Hildon Core Reference¶

Typical main function for a Hildon application¶

import gtk
import hildon

def main():
  # Create the main window
  mainwin = hildon.StackableWindow()

  # Set up our GUI elements
 ...

  # Show the application window
  mainwin.show_all()

  # Enter the main event loop, and wait for user interaction
  gtk.main()

if __name__ == "__main__":
  main()

Details¶

hildon.hildon_init()¶

Initializes the hildon library. Call this function after calling gtk_init() and before using any hildon or GTK+ functions in your program.

New in version 2.2.

hildon.hildon_gtk_init(argc, argv)¶

Convenience function to initialize the GTK+ and hildon libraries. Use this function to replace a call to gtk_init() and also initialize the hildon library. See hildon_init() and gtk_init() for details.

Parameters:	argc – Address of the argc parameter of your main() function. Changed if any arguments were handled. argv – Address of the argv parameter of main() . Any parameters understood by gtk_init() are stripped before return.

Details¶

hildon.hildon_gtk_menu_new()¶

This is a convenience function to create a gtk.Menu setting its widget name to allow Hildon specific styling.

Returns:	A newly created gtk.Menu widget.

hildon.hildon_gtk_button_new(size)¶

This is a convenience function to create a GtkButton setting its size to one of the pre-defined Hildon sizes.

Buttons created with this function also override the “gtk-button-images” setting. Images set using gtk_button_set_image() are always shown.

Buttons created using this function have “focus-on-click” set to False by default.

Parameter:	size – Flags indicating the size of the new button
Returns:	A newly created GtkButton widget.

hildon.hildon_gtk_toggle_button_new(size)¶

This is a convenience function to create a GtkToggleButton setting its size to one of the pre-defined Hildon sizes.

Buttons created with this function also override the “gtk-button-images” setting. Images set using gtk_button_set_image() are always shown.

Buttons created using this function have “focus-on-click” set to False by default.

Parameter:	size – Flags indicating the size of the new button
Returns:	A newly created GtkToggleButton widget.

hildon.hildon_gtk_radio_button_new(size, group)¶

This is a convenience function to create a gtk.RadioButton setting its size to one of the pre-defined Hildon sizes.

Buttons created with this function also override the “gtk-button-images” setting. Images set using gtk_button_set_image() are always shown.

Buttons created using this function have “focus-on-click” set to False by default.

Parameters:	size – Flags indicating the size of the new button group – An existing radio button group, or None if you are creating a new group
Returns:	A newly created gtk.RadioButton widget.

hildon.hildon_gtk_radio_button_new_from_widget(size, radio_group_member)¶

This is a convenience function to create a gtk.RadioButton setting its size to one of the pre-defined Hildon sizes.

Buttons created with this function also override the “gtk-button-images” setting. Images set using gtk_button_set_image() are always shown.

Buttons created using this function have “focus-on-click” set to False by default.

Parameters:	size – Flags indicating the size of the new button radio_group_member – widget to get radio group from or None
Returns:	A newly created gtk.RadioButton widget.

hildon.hildon_gtk_tree_view_new(mode)¶

Creates a new gtk.TreeView widget with the Hildon UI mode set to mode

Parameter:	mode – the Hildon UI mode
Returns:	A newly created gtk.TreeView widget.

hildon.hildon_gtk_tree_view_new_with_model(mode, model)¶

Creates a new gtk.TreeView widget with the Hildon UI mode set to mode and the model initialized to model.

Parameters:	mode – the Hildon UI mode model – the model.
Returns:	A newly created gtk.TreeView widget.

hildon.hildon_gtk_tree_view_set_ui_mode(treeview, mode)¶

Sets the UI mode of treeview to mode.

Parameters:	treeview – A gtk.TreeView mode – The new hildon.UIMode

hildon.hildon_gtk_icon_view_new(mode)¶

Creates a new gtk.IconView widget with the Hildon UI mode set to mode

Parameter:	mode – the Hildon UI mode
Returns:	A newly created gtk.IconView widget

hildon.hildon_gtk_icon_view_new_with_model(mode, model)¶

Creates a new gtk.IconView widget with the Hildon UI mode set to mode and the model intitialized to model.

Parameters:	mode – the Hildon UI mode model – The model.
Returns:	A newly created gtk.IconView widget.

hildon.hildon_gtk_icon_view_set_ui_mode(iconview, mode)¶

Sets the UI mode of iconview to mode.

Parameters:	iconview – A gtk.IconView mode – The new hildon.UIMode

hildon.hildon_gtk_window_set_progress_indicator(window, state)¶

This functions tells the window manager to show/hide a progress indicator in the window title. It applies to hildon.Dialog and hildon.Window (including subclasses).

Note that window must be realized for this to work.

Parameters:	window – a gtk.Window. state – The state we want to set: 1 -> show progress indicator, 0 -> hide progress indicator.

hildon.hildon_gtk_hscale_new()¶

Creates a new horizontal scale widget that lets the user select a value. The value is technically a double between 0.0 and 1.0. See gtk_adjustment_configure() for reconfiguring the adjustment.

The scale is hildonized, which means that a click or tap immediately jumps to the desired position, see gtk_range_set_jump_to_position() . Further more the value is not displayed, see gtk_scale_set_draw_value() .

Returns:	a new hildonized GtkHScale

hildon.hildon_gtk_vscale_new()¶

Creates a new vertical scale widget that lets the user select a value. The value is technically a double between 0.0 and 1.0. See gtk_adjustment_configure() for reconfiguring the adjustment.

The scale is hildonized, which means that a click or tap immediately jumps to the desired position, see gtk_range_set_jump_to_position() . Further more the value is not displayed, see gtk_scale_set_draw_value() .

Returns:	a new hildonized gtk.VScale

See Also¶

hildon.Button hildon.CheckButton

Description¶

Hildon provides some helper functions that can be used for commonly performed tasks and functionality blocks. This includes operations on widget styles and probing functions for touch events.

Details¶

hildon.hildon_helper_set_logical_font(widget, logicalfontname)¶

This function assigns a defined logical font to the widget and all its child widgets. it also connects to the “style_set” signal which will retrieve assign the new font for the given logical name each time the theme is changed The returned signal id can be used to disconnect the signal. When calling multiple times the previous signal (obtained by calling this function) is disconnected automatically and should not be used.

Parameters:	widget – a gtk.Widget to assign this logical font for. logicalfontname – a str with the logical font name to assign to the widget.
Returns:	the signal id that is triggered every time theme is changed. 0 if font set failed.

hildon.hildon_helper_set_logical_color(widget, rcflags, state, logicalcolorname)¶

This function assigns a defined logical color to the widget and all it’s child widgets. It also connects to the “style_set” signal which will retrieve assign the new color for the given logical name each time the theme is changed. The returned signal id can be used to disconnect the signal. When calling multiple times the previous signal (obtained by calling this function) is disconnected automatically and should not be used.

Example: If the style you want to modify is bg[NORMAL] then set rcflags to GTK_RC_BG and state to GTK_STATE_NORMAL.

Parameters:	widget – A gtk.Widget to assign this logical font for. rcflags – GtkRcFlags enumeration defining whether to assign to FG, BG, TEXT or BASE style. state – GtkStateType indicating to which state to assign the logical color logicalcolorname – A string with the logical font name to assign to the widget.
Returns:	The signal id that is triggered every time theme is changed. 0 if color set failed.

hildon.hildon_helper_event_button_is_finger(event)¶

Checks if the given button event is a finger event.

Parameter:	event – A GtkEventButton to check
Returns:	True if the event is a finger event.

hildon.hildon_helper_set_insensitive_message(widget, message)¶

Warning

hildon_helper_set_insensitive_message() is deprecated and should not be used in newly-written code. As of hildon 2.2, it is strongly discouraged to use insensitive messages.

This function assigns an insensitive message to a widget. When the widget is in an insensitive state and the user activates it, the message will be displayed using a standard hildon.Banner.

Parameters:	widget – A gtk.Widget to assign a banner to message – A message to display to the user

hildon.hildon_helper_set_insensitive_messagef(widget, format, ...)¶

Warning

hildon_helper_set_insensitive_messagef() is deprecated and should not be used in newly-written code. As of hildon 2.2, it is strongly discouraged to use insensitive messages.

A version of hildon_helper_set_insensitive_message with string formatting.

Parameters:	widget – A gtk.Widget to assign a banner to format – a printf-like format string ... – arguments for the format string

hildon.hildon_helper_set_thumb_scrollbar(win, thumb)¶

This function enables a thumb scrollbar on a given scrolled window. It’ll convert the existing normal scrollbar into a larger, finger-usable scrollbar that works without a stylus. As fingerable list rows are fairly high, consider using the whole available vertical space of your application for the content in order to have as many rows as possible visible on the screen at once.

Finger-Sized scrollbar should always be used together with finger-sized content.

Parameters:	win – A GtkScrolledWindow to use as target thumb – True to enable the thumb scrollbar, False to disable

Details¶

hildon.hildon_play_system_sound(sample)¶

Plays the given sample using libcanberra. Volume level is received from gconf.

Parameter:	sample – sound file to play

Object Hierarchy¶

GObject
 +----Program

Description¶

Program is an object used to represent an application running in the Hildon framework.

Applications can have one or more hildon.Window s. These can be registered in the Program with Program.add_window() , and can be unregistered similarly with Program.remove_window() .

Program provides the programmer with commodities such as applying a common toolbar and menu to all registered hildon.Window s. This is done with Program.set_common_menu() , Program.set_common_app_menu() and Program.set_common_toolbar().

Program is also used to apply program-wide properties that are specific to the Hildon framework. For instance Program.set_can_hibernate() sets whether or not an application can be set to hibernate by the Hildon task navigator, in situations of low memory.

program = hildon.Program.get_instance()

window1 = hildon.Window()
window2 = hildon.Window()

common_toolbar = create_common_toolbar()
window_specific_toolbar = create_window_specific_toolbar()

menu = create_menu()

program.add_window(window1)
program.add_window(window2)

program.set_common_app_menu (menu)

program.set_common_toolbar (common_toolbar)
window1.add_toolbar (window_specific_toolbar)

program.set_can_hibernate (True)

Details¶

class hildon.Program¶

get_instance()¶

Returns the Program for the current process. The object is created on the first call. Note that you’re not supposed to unref the returned object since it’s not reffed in the first place.

Returns:	the Program .

add_window(window)¶

Registers a hildon.Window as belonging to a given Program . This allows to apply program-wide settings as all the registered windows, such as Program.set_common_menu() , Program.set_common_app_menu() and Program.set_common_toolbar().

Parameter:	window – A hildon.Window to be added

remove_window(window)¶

Used to unregister a window from the program. Subsequent calls to Program.set_common_menu() , Program.set_common_app_menu() and Program.set_common_toolbar() will not affect the window.

Parameter:	window – The hildon.Window to unregister

set_can_hibernate(can_hibernate)¶

Used to set whether or not the Hildon task navigator should be able to set the program to hibernation in case of low memory

Parameter:	can_hibernate – whether or not the Program can hibernate

get_can_hibernate()¶

Returns whether the Program is set to be support hibernation from the Hildon task navigator

Returns:	True if the program can hibernate, False otherwise.

set_common_menu(menu)¶

Sets a gtk.Menu that will appear in all hildon.Window s registered with the Program . Only one common gtk.Menu can be set, further calls will detach the previous common gtk.Menu . A hildon.Window can use its own gtk.Menu with hildon.Window.set_menu()

This method does not support hildon.AppMenu s. See Program.set_common_app_menu() for that.

Parameter:	menu – A gtk.Menu to use as common menu for the program

get_common_menu()¶

Returns the gtk.Menu that was set as common menu for this Program .

Returns:	the gtk.Menu or None of no common menu was set.

set_common_app_menu(menu)¶

Sets a hildon.AppMenu that will appear in all hildon.Window s registered with the Program . Only one common hildon.AppMenu can be set, further calls will detach the previous common hildon.AppMenu . A hildon.Window can use its own hildon.AppMenu with hildon.Window.set_app_menu()

This method does not support gtk.Menu s. See Program.set_common_menu() for that.

Parameter:	menu – A hildon.AppMenu to use as common menu for the program

get_common_app_menu()¶

Returns the hildon.AppMenu that was set as common menu for this Program .

Returns:	the hildon.AppMenu or None of no common app menu was set.

set_common_toolbar(toolbar)¶

Sets a gtk.Toolbar that will appear in all the hildon.Window registered to the Program . Only one common gtk.Toolbar can be set, further call will detach the previous common gtk.Toolbar . A hildon.Window can use its own gtk.Toolbar with hildon.Window.add_toolbar() . Both Program and hildon.Window specific toolbars will be shown

Parameter:	toolbar – A gtk.Toolbar to use as common toolbar for the program

get_common_toolbar()¶

Returns the gtk.Toolbar that was set as common toolbar for this Program .

Returns:	the gtk.Toolbar or None of no common toolbar was set.

get_is_topmost()¶

Returns whether one of the program’s windows or dialogs is currently activated by the window manager.

Returns:	True if a window or dialog is topmost, False otherwise.

pop_window_stack()¶

Warning

Program.pop_window_stack() is deprecated and should not be used in newly-written code. Use hildon.Window.stack_pop() instead

Pops a window from the stack.

Returns:	A hildon.StackableWindow , or None

peek_window_stack()¶

Warning

Program.peek_window_stack() is deprecated and should not be used in newly-written code. Use hildon.Window.stack_peek() instead

Returns:	A hildon.StackableWindow , or None

go_to_root_window()¶

Warning

Program.go_to_root_window() is deprecated and should not be used in newly-written code. See hildon.WindowStack

Goes to the root window of the stack.

Property Details¶

See Also¶

hildon.Window hildon.StackableWindow