Hildon Widgets and Objects¶

Object Hierarchy¶

Implemented Interfaces¶

Window implements atk.ImplementorIface and gtk.Buildable .

Signals¶

clipboard-operation                            : Run First

Description¶

Window is a GTK widget which represents a top-level window in the Hildon framework. It is derived from gtk.Window and provides additional commodities specific to the Hildon framework.

Window s can have a menu attached, which is toggled with a hardware key or by tapping on the window frame. This menu can be either a gtk.Menu or a AppMenu (set with Window.set_main_menu() and Window.set_app_menu() respectively). Only one type of menu can be used at the same time. In Hildon 2.2, AppMenu is the recommended menu to use.

Similarly, a Window can have several toolbars attached. These can be added with Window.add_toolbar() . In addition to those, a Window can also have a EditToolbar . To add it to the window use Window.set_edit_toolbar() .

Creating a Window¶

import gtk
import hildon

window = hildon.Window()
toolbar = create_toolbar()
menu = create_menu()

icon_pixbuf = create_icon()

window.set_app_menu(menu)

window.add_toolbar(toolbar)

window.fullscreen()

window.set_urgency_hint(True)

window.set_icon(window, icon_pixbuf)

Details¶

hildon.WindowClipboardOperation¶

class hildon.Window¶

__init__(self)¶

Creates a new Window .

Returns:	A newly created Window .

add_with_scrollbar(child)¶

Adds child to the Window and creates a scrollbar for it. Similar to adding first a GtkScrolledWindow and then child to it.

Parameter:	child – gtk.Widget

set_main_menu(menu)¶

Sets the menu to be used for this window. This menu overrides a program-wide menu that may have been set with HildonProgram.set_common_menu() . Pass None to remove the current menu. Window takes ownership of the passed menu and you’re not supposed to free it yourself anymore.

Note that if you’re using a AppMenu rather than a gtk.Menu you should use Window.set_app_menu() instead.

Parameter:	menu – The gtk.Menu to be used for this Window

get_main_menu()¶

Gets the gtk.Menu assigned to the HildonAppview . Note that the window is still the owner of the menu.

Note that if you’re using a AppMenu rather than a gtk.Menu you should use Window.get_app_menu() instead.

Returns:	The gtk.Menu assigned to this application view.

set_app_menu(menu)¶

Sets the menu to be used for this window. Pass None to remove the current menu. Any reference to a previous menu will be dropped. Window takes ownership of the passed menu and you’re not supposed to free it yourself anymore.

Note that if you’re using a gtk.Menu rather than a AppMenu you should use Window.set_main_menu() instead.

Parameter:	menu – a AppMenu to be used for this window

get_app_menu()¶

Returns the AppMenu assigned to self, or None if it’s unset. Note that the window is still the owner of the menu.

Note that if you’re using a gtk.Menu rather than a AppMenu you should use Window.get_main_menu() instead.

Returns:	a AppMenu

set_menu(menu)¶

Warning

Window.set_menu() is deprecated and should not be used in newly-written code. Hildon 2.2: use Window.set_main_menu()

Sets the menu to be used for this window. This menu overrides a program-wide menu that may have been set with HildonProgram.set_common_menu() . Pass None to remove the current menu. Window takes ownership of the passed menu and you’re not supposed to free it yourself anymore.

Note: Window.set_menu() calls GtkWidget.show_all() for the gtk.Menu . To pass control about visibility to the application developer, Window.set_main_menu() was introduced, which doesn’t do this.

Parameter:	menu – The gtk.Menu to be used for this Window

get_menu()¶

Warning

Window.get_menu() is deprecated and should not be used in newly-written code. In Hildon 2.2 this function has been renamed to Window.get_main_menu() for consistency

Returns:	a gtk.Menu

add_toolbar(toolbar)¶

Adds a toolbar to the window. Note that the toolbar is not automatically shown. You need to call GtkWidget.show_all() on it to make it visible. It’s also possible to hide the toolbar (without removing it) by calling GtkWidget.hide()

Parameter:	toolbar – A gtk.Toolbar to add to the Window

remove_toolbar(toolbar)¶

Removes a toolbar from the window. Note that this decreases the refference count on the widget. If you want to keep the toolbar alive call GObject.ref() before calling this function.

Parameter:	toolbar – A gtk.Toolbar to remove from the Window

set_edit_toolbar(toolbar)¶

Adds a EditToolbar to the window. Note that the toolbar is not automatically shown. You need to call gtk.Widget.show() on it to make it visible. It’s also possible to hide the toolbar (without removing it) by calling gtk.Widget.hide() .

A window can only have at most one edit toolbar at a time, so the previous toolbar (if any) is replaced after calling this function.

Parameter:	toolbar – A EditToolbar , or None to remove the current one.

get_is_topmost()¶

Returns whether the Window is currenty activated by the window manager.

Returns:	True self is currently activated, False otherwise.

set_markup(markup)¶

Sets the marked up title of window. The accepted format is the one used in Pango (see PangoMarkupFormat ) with the exception of span.

Note that you need support from the window manager for this title to be used. See gtk.Window.set_title() for the standard way of setting the title of a window.

Parameter:	markup – the marked up title of the window, or None to unset the current one

hildon_window_get_markup()¶

Gets the marked up title of the window title. See Window.set_markup()

Returns:	the marked up title of the window, or None if none has been set explicitely. The returned string is owned by the widget and must not be modified or freed.

Properties¶

Style Properties¶

Signal Details¶

The clipboard-operation signal.

hildon.user_function(hildon_window, arg1, user_data)¶

Parameters:	hildon_window – the object which received the signal. operation – the operation that happened user_data – user data set when the signal handler was connected.

See Also¶

Program StackableWindow

Object Hierarchy¶

Implemented Interfaces¶

StackableWindow implements atk.ImplementorIface and gtk.Buildable .

Description¶

The StackableWindow is a GTK+ widget which represents a top-level window in the Hildon framework. It is derived from Window . Applications that use stackable windows are organized in a hierarchical way so users can go from any window back to the application’s root window.

The user can only see and interact with the window on top of the stack. Although all other windows are mapped and visible, they are obscured by the topmost one so in practice they appear as if they were hidden.

To add a window to the stack, just use gtk.Widget.show_all() . The previous one will be obscured by the new one. When the new window is destroyed, the previous one will appear again.

Alternatively, you can remove a window from the top of the stack without destroying it by using WindowStack.pop(). The window will be automatically hidden and the previous one will appear.

For advanced details on stack handling, see WindowStack

Basic StackableWindow example¶

import gtk
import hildon

def show_new_window(widget):
  win = hildon.StackableWindow()
  # ... configure new window
  win.show_all()

def main():
  program = hildon.hildon_program_get_instance()

  win = hildon.StackableWindow()
  win.set_title("Main window")

  # ... add some widgets to the window

  button.connect("clicked", show_new_window, None);
  win.connect("destroy", gtk.main_quit, None)

  # This call show the window and also add the window to the stack
  win.show_all()
  gtk.main()

if __name__ == "__main__":
  main()

Details¶

class hildon.StackableWindow¶

__init__()¶

Creates a new StackableWindow .

Returns:	A StackableWindow

get_stack()¶

Returns the stack where window self is on, or None if the window is not stacked.

Returns:	a WindowStack , or None

set_main_menu(menu)¶

Warning

StackableWindow.set_main_menu() is deprecated and should not be used in newly-written code. Hildon 2.2: use Window.set_app_menu()

Parameter:	menu – a AppMenu to be used for this window

See Also¶

WindowStack Program Window

Object Hierarchy¶

Description¶

The WindowStack is an object used to represent a stack of windows in the Hildon framework.

Stacks contain all StackableWindow s that are being shown. The user can only interact with the topmost window from each stack (as it covers all the others), but all of them are mapped and visible from the Gtk point of view.

Each window can only be in one stack at a time. All stacked windows are visible and all visible windows are stacked.

Each application has a default stack, and windows are automatically added to it when they are shown with gtk.Widget.show_all() .

Additional stacks can be created at any time using WindowStack() . To add a window to a specific stack, use WindowStack.push_1() (remember that, for the default stack, gtk.Widget.show_all() can be used instead).

To remove a window from a stack use WindowStack.pop_1() , or simply gtk.Widget.hide() .

For more complex layout changes, applications can push and/or pop several windows at the same time in a single step. See WindowStack.push() , WindowStack.pop() and WindowStack.pop_and_push() for more details.

Details¶

class hildon.WindowStack¶

get_default()¶

Returns the default window stack. This stack always exists and doesn’t need to be created by the application.

Returns:	the default WindowStack

__init__()¶

Creates a new WindowStack . The stack is initially empty.

Returns:	a new WindowStack

size()¶

Returns the number of windows in stack

Returns:	Number of windows in stack

get_windows()¶

Returns the list of windows on this stack (topmost first). The widgets in the list are not individually referenced.

Returns:	a newly-allocated list of StackableWindow s

peek()¶

Returns the window on top of stack. The stack is never modified.

Returns:	the window on top of the stack, or None if the stack is empty.

push(win1, ...)¶

Pushes all windows to the top of stack, and shows them. Everything is done in a single transition, so the user will only see the last window. None of the windows must be already stacked.

Parameters:	win1 – The first window to push ... – A None -terminated list of additional StackableWindow s to push.

push_list(list)¶

Pushes all windows in list to the top of stack, and shows them. Everything is done in a single transition, so the user will only see the last window in list during this operation. None of the windows must be already stacked.

Parameter:	list – A list of HildonStackableWindow s to push

push_1(win)¶

Adds win to the top of stack, and shows it. The window must not be already stacked.

win: A StackableWindow

pop(nwindows, popped_windows)¶

Pops nwindows windows from stack, and hides them. Everything is done in a single transition, so the user will not see any of the windows being popped in this operation.

If popped_windows is not None , the list of popped windows is stored there (ordered bottom-up). That list must be freed by the user.

nwindows: Number of windows to pop

popped_windows: if non-None , the list of popped windows is stored here

pop_1()¶

Removes the window on top of stack, and hides it. If the stack is empty nothing happens.

Returns:	the window on top of the stack, or None if the stack is empty.

pop_and_push(nwindows, popped_windows, win1, ...)¶

Pops nwindows windows from stack (and hides them), then pushes all passed windows (and shows them). Everything is done in a single transition, so the user will only see the last pushed window. None of the pushed windows must be already stacked.

If popped_windows is not None , the list of popped windows is stored there (ordered bottom-up). That list must be freed by the user.

nwindows: Number of windows to pop.

popped_windows: if non-None , the list of popped windows is stored here

win1: The first window to push

...: A None -terminated list of additional StackableWindow s to push.

pop_and_push_list(nwindows, popped_windows, list)¶

Pops nwindows windows from stack (and hides them), then pushes all windows in list (and shows them). Everything is done in a single transition, so the user will only see the last window from list. None of the pushed windows must be already stacked.

If popped_windows is not None , the list of popped windows is stored there (ordered bottom-up). That list must be freed by the user.

nwindows: Number of windows to pop.

popped_windows: if non-None , the list of popped windows is stored here

list: A list of StackableWindow s to push

Properties¶

The window-group property

GtkWindowGroup that all windows on this stack belong to.

See Also¶

StackableWindow

Object Hierarchy¶

Implemented Interfaces¶

Button implements atk.ImplementorIface and gtk.Buildable .

Description¶

The Button is a GTK widget which represents a clickable button. It is derived from the GtkButton widget and provides additional commodities specific to the Hildon framework.

The height of a Button can be set to either “finger” height or “thumb” height. It can also be configured to use halfscreen or fullscreen width. Alternatively, either dimension can be set to “auto” so it behaves like a standard GtkButton .

The Button can hold any valid child widget, but it usually contains two labels, named title and value, and it can also contain an image. The contents of the button are packed together inside a gtk.Alignment and they do not expand by default (they don’t use the full space of the button).

To change the alignment of both labels, use gtk.Button.set_alignment().

To make them expand and use the full space of the button, use Button.set_alignment() .

To change the relative alignment of each label, use Button.set_title_alignment() and Button.set_value_alignment() .

In hildon-button-example.c included in the Hildon distribution you can see examples of how to create the most common button layouts.

If only one label is needed, GtkButton can be used as well, see also GtkButton.

Creating a Button¶

def button_clicked(button, user_data=None):
    title = button.get_title()
    value = button.get_value()

    print "Button clicked with title %s and value %s" % (title, value)

def create_button():
    button = hildon.Button(gtk.HILDON_SIZE_AUTO_WIDTH | gtk.HILDON_SIZE_FINGER_HEIGHT,
                           hildon.BUTTON_ARRANGEMENT_VERTICAL)
    button.set_text("Some title", "some value")

    image = gtk.image_new_from_stock(gtk.STOCK_INFO, gtk.ICON_SIZE_BUTTON)
    button.set_image(image)
    button.set_image_position(gtk.POS_RIGHT)

    button.set_alignment(button, 0.0, 0.5)

    button.connect("clicked", button_clicked)

    return button

Details¶

class hildon.Button¶

ButtonArrangement¶

Value	Meaning
BUTTON_ARRANGEMENT_HORIZONTAL	Labels are arranged from left to right
BUTTON_ARRANGEMENT_VERTICAL	Labels are arranged from top to bottom

Describes the arrangement of labels inside a Button

ButtonStyle¶

Value	Meaning
BUTTON_STYLE_NORMAL	The button will look like a Button
BUTTON_STYLE_PICKER	The button will look like a PickerButton

Describes the visual style of a Button

__init__(size, arrangement, title=None, value=None)¶

Creates a new Button with two labels, title and value.

If you just don’t want to use one of the labels, set it to None . You can set it to a non-None value at any time later using Button.set_title() or Button.set_value() .

Parameters:	size – Flags to set the size of the button. arrangement – How the labels must be arranged. title – Title of the button (main label), or None
Parma value:	Value of the button (secondary label), or None
Returns:	a new Button

set_title(title)¶

Sets the title (main label) of button to title.

This will clear any previously set title.

If title is set to None , the title label will be hidden and the value label will be realigned.

Parameter:	title – a new title (main label) for the button, or None

set_value(value)¶

Sets the value (secondary label) of button to value.

This will clear any previously set value.

If value is set to None , the value label will be hidden and the title label will be realigned.

Parameter:	value – a new value (secondary label) for the button, or None

get_title()¶

Fetches the text from the main label (title) of button, as set by Button.set_title() or Button.set_text() . If the label text has not been set the return value will be None . This will be the case if you create an empty button to use as a container.

Returns:	The text of the title label. This string is owned by the widget and must not be modified or freed.

get_value()¶

Fetches the text from the secondary label (value) of button, as set by Button.set_value() or Button.set_text() . If the label text has not been set the return value will be None . This will be the case if you create an empty button to use as a container.

Returns:	The text of the value label. This string is owned by the widget and must not be modified or freed.

set_text(title, value)¶

Convenience function to change both labels of a Button

Parameters:	title – new text for the button title (main label) value – new text for the button value (secondary label)

set_image(image)¶

Sets the image of button to the given widget. The previous image (if any) will be removed.

Parameter:	image – a widget to set as the button image

get_image()¶

Gets the widget that is currenty set as the image of button, previously set with Button.set_image()

Returns:	a gtk.Widget or None in case there is no image

set_image_position(position)¶

Sets the position of the image inside button. Only gtk.POS_LEFT and gtk.POS_RIGHT are currently supported.

Parameter:	position – the position of the image (gtk.POS_LEFT or gtk.POS_RIGHT)

set_alignment(xalign, yalign, xscale, yscale)¶

Sets the alignment of the contents of the widget. If you don’t need to change xscale or yscale you can just use gtk.Button.set_alignment() instead.

Note that for this method to work properly the, child widget of button must be a gtk.Alignment . That’s what Button uses by default, so this function will work unless you add a custom widget to button.

Parameters:	xalign – the horizontal alignment of the contents, from 0 (left) to 1 (right). yalign – the vertical alignment of the contents, from 0 (top) to 1 (bottom). xscale – the amount that the child widget expands horizontally to fill up unused space, from 0 to 1 yscale – the amount that the child widget expands vertically to fill up unused space, from 0 to 1

set_title_alignment(xalign, yalign)¶

Sets the alignment of the title label. See also Button.set_alignment() to set the alignment of the whole contents of the button.

Parameters:	xalign – the horizontal alignment of the title label, from 0 (left) to 1 (right). yalign – the vertical alignment of the title label, from 0 (top) to 1 (bottom).

set_value_alignment(xalign, yalign)¶

Sets the alignment of the value label. See also Button.set_alignment() to set the alignment of the whole contents of the button.

Parameters:	xalign – the horizontal alignment of the value label, from 0 (left) to 1 (right). yalign – the vertical alignment of the value label, from 0 (top) to 1 (bottom).

set_image_alignment(xalign, yalign)¶

Sets the alignment of the image. See also Button.set_alignment() to set the alignment of the whole contents of the button.

Parameters:	xalign – the horizontal alignment of the image, from 0 (left) to 1 (right). yalign – the vertical alignment of the image, from 0 (top) to 1 (bottom).

add_title_size_group(group)¶

Adds the title label of button to size_group.

Parameter:	group – A gtk.SizeGroup for the button title (main label)

add_value_size_group(group)¶

Adds the value label of button to size_group.

Parameter:	group – A gtk.SizeGroup for the button value (secondary label)

add_image_size_group(size_group)¶

Adds the image of button to size_group. You must add an image using Button.set_image() before calling this function.

Parameter:	size_group – A gtk.SizeGroup for the button image

add_size_groups(title_size_group, value_size_group, image_size_group)¶

Convenience function to add title, value and image to size groups. None size groups will be ignored.

Parameters:	title_size_group – A gtk.SizeGroup for the button title (main label), or None value_size_group – A gtk.SizeGroup group for the button value (secondary label), or None image_size_group – A gtk.SizeGroup group for the button image, or None

set_style(style)¶

Sets the style of button to style. This changes the visual appearance of the button (colors, font sizes) according to the particular style chosen, but the general layout is not altered.

Use BUTTON_STYLE_NORMAL to make it look like a normal Button , or BUTTON_STYLE_PICKER to make it look like a PickerButton .

Parameter:	style – A ButtonStyle for button.

get_style()¶

Gets the visual style of the button.

Returns:	a ButtonStyle

Properties¶

Style Properties¶

Object Hierarchy¶

Implemented Interfaces¶

CheckButton implements atk.ImplementorIface and gtk.Buildable .

Description¶

HildonCheckButton is a button containing a label and a check box which will remain ‘pressed-in’ when clicked. Clicking again will make the check box toggle its state.

The state of a HildonCheckButton can be set using hildon.check_button_set_active() , and retrieved using hildon.check_button_get_active() . The label can be set using gtk.Button.set_label() and retrieved using gtk.Button.get_label() .

Using a Hildon check button¶

def button_toggled(checkbutton):
    if (checkbutton.get_active()):
        print "Button is active"
    else:
        print "Button is not active"

def create_check_button():
    button = hildon.CheckButton(gtk.HILDON_SIZE_AUTO)
    button.set_label("Click me")
    button.connect("toggled", button_toggled)
    return button

Details¶

class hildon.HildonCheckButton¶

__init__(size)¶

Creates a new HildonCheckButton .

Parameter:	size – Flags indicating the size of the new button
Returns:	A newly created HildonCheckButton

set_active(is_active)¶

Sets the status of a HildonCheckButton . Set to True if you want button to be ‘pressed-in’, and False to raise it. This action causes the “toggled” signal to be emitted.

Parameter:	is_active – new state for the button

get_active()¶

Gets the current state of button.

Returns:	True if button is active, False otherwise.

toggled()¶

Emits the “toggled” signal on the HildonCheckButton . There is no good reason for an application ever to call this function.

Style Properties¶

The checkbox-size style property

Signal Details¶

The toggled signal

hildon.user_function(user_data)

Emitted when the HildonCheckButton ‘s state is changed.

Parameter:	user_data – user data set when the signal handler was connected.

Object Hierarchy¶

Implemented Interfaces¶

HildonPickerButton implements atk.ImplementorIface and gtk.Buildable .

Description¶

PickerButton is a widget that lets the user select a particular item from a list. Visually, it’s a button with title and value labels that brings up a PickerDialog . The user can then use this dialog to choose an item, which will be displayed in the value label of the button.

You should create your own TouchSelector at convenience and set it to the PickerButton with PickerButton.set_selector() . For the common use cases of buttons to select date and time, you can use DateButton and TimeButton .

Details¶

class hildon.HildonPickerButton¶

__init__(size, arrangement)¶

Creates a new HildonPickerButton . See hildon.Button() for details on the parameters.

Parameters:	size – One of HildonSizeType , specifying the size of the new button. arrangement – one of ButtonArrangement , specifying the placement of the labels.
Returns:	a newly created HildonPickerButton

set_selector(selector)¶

Sets selector as the TouchSelector to be shown in the PickerDialog that button brings up.

Parameter:	selector – a TouchSelector

get_selector()¶

Retrieves the TouchSelector associated to button.

Returns:	a TouchSelector

set_active(index)¶

Sets the active item of the TouchSelector associated to button to index. If the selector has several columns, only the first one is used.

Parameter:	index – the index of the item to select, or -1 to have no active item

get_active()¶

Returns the index of the currently active item, or -1 if there’s no active item. If the selector has several columns, only the first one is used.

Returns:	an integer which is the index of the currently active item, or -1 if there’s no active item.

get_done_button_text()¶

Gets the text used in the PickerDialog that is launched by button. If no custom text is set, then None is returned.

Returns:	the custom string to be used, or None if the default “done-button-text” is to be used.

set_done_button_text(done_button_text)¶

Sets a custom string to be used in the “done” button in PickerDialog . If unset, the default “done-button-text” property value will be used.

Parameter:	done_button_text – a string

value_changed()¶

Emits a “value-changed” signal to the given HildonPickerButton

Properties¶

Signal Details¶

The value-changed signal

hildon.user_function(widget, user_data)

The ::value-changed signal is emitted each time the user chooses a different item from the TouchSelector related, and the value label gets updated.

Parameters:	widget – the widget that received the signal user_data – user data set when the signal handler was connected.

See Also¶

TouchSelector PickerDialog

Object Hierarchy¶

Implemented Interfaces¶

HildonDateButton implements atk.ImplementorIface and gtk.Buildable .

Description¶

HildonDateButton is a widget that shows a text label and a date, and allows the user to select a different date. Visually, it’s a button that, once clicked, presents a PickerDialog containing a HildonDateSelector . Once the user selects a different date from the selector, this will be shown in the button.

Details¶

class hildon.HildonDateButton¶

__init__(size, arrangement)¶

Creates a new HildonDateButton . See hildon_button_new() for details on the parameters.

Parameters:	size – One of HildonSizeType arrangement – one of ButtonArrangement
Returns:	a new HildonDateButton

new_with_year_range(size, arrangement, min_year, max_year)¶

Creates a new HildonDateButton with a specific valid range of years. See hildon.DateSelector.new_with_year_range() for details on the range.

Parameters:	size – One of HildonSizeType arrangement – one of ButtonArrangement min_year – the minimum available year or -1 to ignore max_year – the maximum available year or -1 to ignore
Returns:	a new HildonDateButton

get_date(year, month, day)¶

Retrieves currently selected date from button.

Parameters:	year – return location for the selected year month – return location for the selected month day – return location for the selected day

hildon_date_button_set_date(year, month, day)¶

Sets the date in button. The date set will be displayed and will be the default selected option on the shown HildonDateSelector .

Parameters:	year – the year to set. month – the month number to set. day – the day of the month to set.

See Also¶

PickerButton TimeButton

Object Hierarchy¶

Implemented Interfaces¶

HildonTimeButton implements atk.ImplementorIface and gtk.Buildable .

Description¶

HildonTimeButton is a widget that shows a text label and a time, and allows the user to select a different time. Visually, it’s a button that, once clicked, presents a PickerDialog containing a HildonTimeSelector . Once the user selects a different time from the selector, this will be shown in the button.

Details¶

class hildon.HildonTimeButton¶

__init__(size, param)¶

Creates a new HildonTimeButton . See hildon.Button() for details on the parameters.

Parameters:	size – One of HildonSizeType arrangement – one of ButtonArrangement
Returns:	a new HildonTimeButton

new_step(size, arrangement, minutes_step)¶

Creates a new HildonTimeButton . See hildon.Button() for details on the parameters.

Parameters:	size – One of HildonSizeType arrangement – one of ButtonArrangement minutes_step – step between the minutes in the selector options
Returns:	a new HildonTimeButton

get_time(hours, minutes)¶

Retrieves the time from button.

Parameters:	hours – return location for the hours of the time selected minutes – return location for the minutes of the time selected

set_time(hours, minutes)¶

Sets the time to be displayed in button. This time will be selected by default on the HildonTimeSelector .

Parameters:	hours – the hours to be set minutes – the time to be set

See Also¶

PickerButton DateButton

Object Hierarchy¶

Implemented Interfaces¶

Caption implements atk.ImplementorIface and gtk.Buildable .

Description¶

Caption is a single-child container widget that precedes the contained widget with a field label and an optional icon. It allows grouping of several controls together. When a captioned widget has focus, both widget and caption label are displayed with active focus.

Details¶

hildon.CaptionStatus¶

Keys to set the Caption to be optional or mandatory.

hildon.CaptionIconPosition¶

Keys to set the icon placement in Caption .

class hildon.Caption¶

__init__(group, value, control, icon, flag)¶

Creates a new instance of hildon_caption widget, with a specific control and image. Note: Clicking on a focused caption will trigger the activate signal. The default behaviour for the caption’s activate signal is to call gtk.Widget.activate on it’s control.

Parameters:	group – a gtk.SizeGroup for controlling the size of related captions, Can be None value – the caption text to accompany the text entry. The widget makes a copy of this text. control – the control that is to be captioned icon – an icon to accompany the label - can be None in which case no icon is displayed flag – indicates whether this captioned control is mandatory or optional
Returns:	a GtkWidget pointer of Caption

get_size_group()¶

Query given captioned control for the gtk.SizeGroup assigned to it.

Returns:	a gtk.SizeGroup

set_size_group(new_group)¶

Sets a gtk.SizeGroup of a given captioned control.

Parameter:	new_group – a gtk.SizeGroup

is_mandatory()¶

Query Caption whether this captioned control is a mandatory one.

Returns:	is this captioned control a mandatory one?

set_status(flag)¶

Sets Caption status.

Parameter:	flag – one of the values from CaptionStatus

get_status()¶

Gets Caption status.

Returns:	one of the values from CaptionStatus

set_icon_position(pos)¶

Sets Caption icon position.

Parameter:	pos – one of the values from CaptionIconPosition

get_icon_position()¶

Gets Caption icon position.

Returns:	one of the values from CaptionIconPosition .

set_icon_image(icon)¶

Sets the icon image widget to be used by this hildon_caption widget.

Parameter:	icon – the GtkImage to use as the icon. calls gtk.Widget.show on the icon if it is not visible

get_icon_image()¶

Gets icon of Caption

Returns:	the GtkImage widget that is being used as the icon by the hildon_caption, or None if no icon image is in use.

set_label(label)¶

Sets the label text that appears before the control. Separator character is added to the end of the label string. By default the separator is “:”.

Parameter:	label – the text to use

get_label()¶

Gets label of Caption

Returns:	the text currently being used as the label of the caption control. The string is owned by the label and the caller should never free or modify this value.

set_separator(separator)¶

Sets the separator character that appears after the label. The default seaparator character is “:” separately.

Parameter:	separator – the separator to use

get_separator()¶

Gets separator string of Caption

Returns:	the text currently being used as the separator of the caption control. The string is owned by the caption control and the caller should never free or modify this value.

set_label_alignment(alignment)¶

Sets the vertical alignment to be used for the text part of the caption. Applications need to align the child control themselves.

Parameter:	alignment – new vertical alignment

get_label_alignment()¶

Gets current vertical alignment for the text part.

Returns:	vertical alignment

set_child_expand(expand)¶

Sets child expandability.

Parameter:	expand – bool to determine if the child is expandable

get_child_expand()¶

Gets childs expandability.

Returns:	wheter the child is expandable or not.

set_label_markup(markup)¶

Sets the label markup text that appears before the control. It acts like hildon_caption_set_label but is using the markup text that allows to specify text properties such as bold or italic.

Parameter:	markup – the markup text to use

Properties¶

Child Properties¶

Signal Details¶

The activate signal

hildon.user_function(Caption, user_data)

Parameters:	Caption – the object which received the signal. user_data – user data set when the signal handler was connected.

Object Hierarchy¶

Implemented Interfaces¶

Banner implements atk.ImplementorIface and gtk.Buildable .

Description¶

Banner is a small, pop-up window that can be used to display a short, timed notification or information to the user. It can communicate that a task has been finished or that the application state has changed.

Hildon provides convenient funtions to create and show banners. To create and show information banners you can use hildon_banner_show_information() , hildon_banner_show_informationf() or hildon_banner_show_information_with_markup() .

Two more kinds of banners are maintained for backward compatibility but are no longer recommended in Hildon 2.2. These are the animated banner (created with hildon_banner_show_animation() ) and the progress banner (created with hildon_banner_show_progress() ). See hildon_gtk_window_set_progress_indicator() for the preferred way of showing progress notifications in Hildon 2.2.

Information banners dissapear automatically after a certain period. This is stored in the “timeout” property (in miliseconds), and can be changed using set_timeout() .

Note that Banner s should only be used to display non-critical pieces of information.

Details¶

hildon.hildon_banner_new_information(widget, icon_name, text)¶

This function creates and displays an information banner that automatically goes away after certain time period. For each window in your application there can only be one timed banner, so if you spawn a new banner before the earlier one has timed out, the previous one will be replaced.

Parameters:	widget – the gtk.Widget that is the owner of the banner icon_name – since Hildon 2.2 this parameter is not used anymore and any value that you pass will be ignored text – text to display
Returns:	the newly created Banner

hildon.hildon_banner_show_information_with_markup(widget, icon_name, markup)¶

This function creates and displays an information banner that automatically goes away after certain time period. For each window in your application there can only be one timed banner, so if you spawn a new banner before the earlier one has timed out, the previous one will be replaced.

Parameters:	widget – the gtk.Widget that wants to display banner icon_name – since Hildon 2.2 this parameter is not used anymore and any value that you pass will be ignored text – a markup string to display (see Pango markup format)
Returns:	the newly created Banner

hildon.hildon_banner_show_animation(widget, animation_name, text)¶

Shows an animated progress notification. It’s recommended not to try to show more than one progress notification at a time, since they will appear on top of each other. You can use progress notifications with timed banners. In this case the banners are located so that you can somehow see both.

Please note that banners are destroyed automatically once the window they are attached to is closed. The pointer that you receive with this function does not contain additional references, so it can become invalid without warning (this is true for all toplevel windows in gtk). To make sure that the banner does not disappear automatically, you can separately ref the return value (this doesn’t prevent the banner from disappearing, just the object from being finalized).

Parameters:	widget – the gtk.Widget that wants to display banner animation_name – since Hildon 2.2 this parameter is not used anymore and any value that you pass will be ignored text – text to display
Returns:	the newly created Banner

Warning

hildon_banner_show_animation is deprecated and should not be used in newly-written code. Hildon 2.2: use hildon_gtk_window_set_progress_indicator() instead.

hildon.hildon_banner_show_progress(widget, bar, text)¶

Shows progress notification. See hildon_banner_show_animation for more information.

Parameters:	widget – the gtk.Widget that wants to display banner bar – Progressbar to use. You usually can just pass None , unless you want somehow customized progress bar. text – text to display
Returns:	the newly created Banner

Warning

hildon_banner_show_progress is deprecated and should not be used in newly-written code. Hildon 2.2: use hildon_gtk_window_set_progress_indicator() instead.

class hildon.Banner¶

__init__()¶

Creates a new Banner .

Returns:	A Banner

set_text(text)¶

Sets the text that is displayed in the banner.

Parameter:	text – a new text to display in banner

set_markup(markup)¶

Sets the text with markup that is displayed in the banner.

Parameter:	markup – a new text with Pango markup to display in the banner

set_fraction(fraction)¶

The fraction is the completion of progressbar, the scale is from 0.0 to 1.0. Sets the amount of fraction the progressbar has.

Note that this method only has effect if the banner was created with hildon_banner_show_progress()

Parameter:	fraction – a double

set_icon(icon_name)¶

Sets the icon to be used in the banner.

Parameter:	icon_name – the name of icon to use. Can be None for default icon

Warning

Banner.set_icon is deprecated and should not be used in newly-written code. This function does nothing. As of hildon 2.2, hildon banners don’t allow changing their icons.

set_icon_from_file(icon_file)¶

Sets the icon from its filename to be used in the banner.

Parameter:	icon_file – the filename of icon to use. Can be None for default icon.

Warning

Banner.set_icon_from_file is deprecated and should not be used in newly-written code. This function does nothing. As of hildon 2.2, hildon banners don’t allow changing their icons.

set_timeout(timeout)¶

Sets the timeout on the banner. After the given amount of miliseconds has elapsed the banner will go away. Note that settings this only makes sense on the banners that are timed and that have not been yet displayed on the screen.

Parameter:	timeout – timeout to set in miliseconds.

Note that this method only has effect if the object is an information banner (created using hildon_banner_show_information() and friends).

Properties¶

Object Hierarchy¶

Implemented Interfaces¶

Note implements atk.ImplementorIface and gtk.Buildable .

Description¶

Note is a convenient way to prompt users for a small amount of input. A simple note contains an information text and, in case of confirmation notes, it shows buttons to confirm or cancel. It also can include a gtk.ProgressBar.

This widget provides convenient methods to create either information notes, confirmation notes or cancel notes, which are useful to show the progress of a requested task allowing the user to cancel it.

def show_confirmation_note(parent):
    note = hildon.Note("confirmation", parent, "Confirmation message...")

    retcode = gtk.Dialog.run(note)

    if retcode == gtk.RESPONSE_OK:
        print "User pressed 'OK' button'"
        return True
    else:
        print "User pressed 'Cancel' button"
        return False

Details¶

class hildon.Note¶

__init__(note_type, parent, description, icon_name=None, progressbar=None)¶

Note

Note constructor has changed API since Diablo.

Creates a new Note.

Parameters:

note_type – type of note to be created. Can be one of “confirmation”, “information” and “cancel”. parent – the parent window. The X window ID of the parent window has to be the same as the X window ID of the application. This is important so that the window manager could handle the windows correctly. description – the message to be displayed on the note. icon_name – icon to be displayed. If None, default icon is used. progressbar – a gtk.ProgressBar assigned to this note. Use this to set the fraction of progressbar done. This parameter can be None as well, in which case plain text cancel note appears.

Returns:

A newly created Note.

set_button_text(text)¶

Sets the button text to be used by the hildon_note widget.

Parameters:	note – a Note text – sets the button text and if there is two buttons in dialog, the button texts will be text, “Cancel”.

hildon.set_button_texts(text_ok, text_cancel)¶

Sets the button texts to be used by this hildon_note widget.

Parameters:	note – a Note text_ok – the new text of the default OK button text_cancel – the new text of the default cancel button

hildon.NoteType¶

Name	Meaning
hildon.NOTE_TYPE_CONFIRMATION
hildon.NOTE_TYPE_CONFIRMATION_BUTTON
hildon.NOTE_TYPE_INFORMATION
hildon.NOTE_TYPE_INFORMATION_THEME
hildon.NOTE_TYPE_PROGRESSBAR

Properties¶

Object Hierarchy¶

Implemented Interfaces¶

TouchSelector implements atk.ImplementorIface and gtk.Buildable .

Description¶

TouchSelector is a selector widget, that allows users to select items from one to many predefined lists. It is very similar to gtk.ComboBox , but with several individual pannable columns.

Normally, you would use TouchSelector together with a PickerDialog activated from a button. For the most common cases, you should use PickerButton .

The composition of each column in the selector is represented by a GtkTreeModel . To add a new column to a TouchSelector , use hildon_touch_selector_append_column() . If you want to add a text-only column, without special attributes, use hildon_touch_selector_append_text_column() .

It is highly recommended that you use only one column TouchSelector s. If you only need a text only, one column selector, you can create it with hildon_touch_selector_new_text() and populate with hildon_touch_selector_append_text() , hildon_touch_selector_prepend_text() , and hildon_touch_selector_insert_text() .

If you need a selector widget that also accepts user inputs, you can use TouchSelectorEntry .

The current selection has a string representation. In the most common cases, each column model will contain a text column. You can configure which column in particular using the TouchSelectorColumn property “text-column”

You can get this string representation using get_current_text(). You can configure how the selection is printed with set_print_func(), that sets the current hildon touch selector print function. The widget has a default print function, that uses the “text-column” property on each SelectorColumn to compose the final representation.

If you create the selector using hildon_touch_selector_new_text() you don’t need to take care of this property, as the model is created internally. If you create the selector using __init__() , you need to specify properly the property for your custom model in order to get a non-empty string representation, or define your custom print function.

Creating a TouchSelector¶

def selection_changed(selector, user_data):
    current_selection = selector.get_current_text()
    print "Current selection : %s" % current_selection

def create_customized_selector():
    selector = hildon.TouchSelector()

    icon_list = gtk.stock_list_ids()

    store_icons = gtk.ListStore(gobject.TYPE_STRING);

    for item in icon_list:
        new_iter = store_icons.append()
        store_icons.set(new_iter, 0, item)

    renderer = gtk.CellRendererPixbuf()
    renderer.set_fixed_size(-1, 100)


    # Add the column to the selector
    # FIXME: bug 4646
    #column = selector.append_column(store_icons, renderer, "stock-id", 0)

    selector.set_column_selection_mode(hildon.TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE)

    column.set_property("text-column", 0)

    return selector

Details¶

hildon.TouchSelectorSelectionMode¶

class hildon.TouchSelector¶

__init__()¶

Creates a new empty TouchSelector .

Returns:	a new TouchSelector .

append_text(text)¶

Appends a new entry in a TouchSelector created with hildon_touch_selector_new_text().

Parameter:	text – a non None text string.

prepend_text(text)¶

Prepends a new entry in a TouchSelector created with hildon_touch_selector_new_text().

Parameter:	text – a non None text string.

insert_text(position, text)¶

Inserts a new entry in a particular position of a TouchSelector created with hildon_touch_selector_new_text().

Parameters:	position – the position to insert text. text – A non None text string.

append_text_column(model, center)¶

Equivalent to append_column(), but using a default text cell renderer. This is the most common use case of the widget.

Parameters:	model – a gtk.TreeModel with data for the column center – whether to center the text on the column
Returns:	The new column added, None otherwise.

append_column(model, cell_renderer, ...)¶

This functions adds a new column to the widget, whose data will be obtained from the model. Only widgets added this way should used on the selection logic, i.e., the print function, the “changed” signal, etc. You can optionally pass a gtk.CellRenderer in cell_renderer, together with a None -terminated list of pairs property/value, in the same way you would use gtk.TreeViewColumn.set_attributes(). This will pack cell_renderer at the start of the column, expanded by default. If you prefer not to add it this way, you can simply pass None to cell_rendererand use the gtk.CellLayout interface on the returned SelectorColumn to set your renderers. There is a prerequisite to be considered on models used: text data must be in the first column. This method basically adds a gtk.TreeView to the widget, using the model and the data received.

Parameters:	model – the gtk.TreeModel with the data of the column cell_renderer – The gtk.CellRenderer where to draw each row contents.
Returns:	the new column added added, None otherwise.

set_column_attributes(num_column, cell_renderer, ...)¶

Warning

set_column_attributes() is deprecated and should not be used in newly-written code. SelectorColumn implements gtk.CellLayout , use this interface instead. See get_column().

Sets the attributes for the given column. The attributes must be given in attribute/column pairs, just like in set_attributes(). All existing attributes are removed and replaced with the new ones.

Parameters:	num_column – the number of the column whose attributes we’re setting cell_renderer – the gtk.CellRendere we’re setting the attributes of

remove_column(column)¶

Removes a column from selector.

Parameter:	column – the position of the column to be removed
Returns:	True if the column was removed, False otherwise

get_num_columns()¶

Gets the number of columns in the TouchSelector .

Returns:	the number of columns in selector.

set_column_selection_mode(mode)¶

Sets the selection mode for selector. See TouchSelectorSelectionMode .

Parameter:	mode – the TouchSelectorMode for selector

get_column_selection_mode()¶

Gets the selection mode of selector.

Returns:	one of TouchSelectorSelectionMode

get_column(column)¶

Use this method to retrieve a TouchSelectorColumn . Then, you can use the gtk.CellLayout interface to set up the layout of the column.

Parameter:	column – a column number
Returns:	the column-th TouchSelectorColumn in selector

set_active(column, index)¶

Sets the active item of the TouchSelector to index. The column number is taken from column. selector must be in TOUCH_SELECTOR_SELECTION_MODE_SINGLE

Parameters:	column – column number index – the index of the item to select, or -1 to have no active item

get_active(column)¶

Returns the index of the currently active item in column number column, or -1 if there’s no active item. selector must be in TOUCH_SELECTOR_SELECTION_MODE_SINGLE

Parameter:	column – column number
Returns:	an integer which is the index of the currently active item, or -1 if there’s no active item.

get_selected(column)¶

Returns a 2-tuple with a GtkTreeModel and GtkTreIter to the currently selected node on the nth-column, if selection is set to TOUCH_SELECTOR_SINGLE or TOUCH_SELECTOR_MULTIPLE with a column different that the first one. Iterator may be None if you just want to test if selection has any selected items. This function will return None if selection is in TOUCH_SELECTOR_MULTIPLE mode and the column is the first one.

See gtk.TreeSelection.get_selected() for more information.

Parameter:	column – the column number we want to get the element
Returns:	a 2-tuple containing a reference to the GtkTreeModel and a GtkTreeIter pointing to the currently selected node.

center_on_selected()¶

Ensures all the columns in a TouchSelector show a selected item. If one of the columns is in `TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE mode, that column will be scrolled to ensure the selected item that is closest to the currently visible area is shown.

select_iter(column, iter, scroll_to)¶

Sets the currently selected item in the column column to the one pointed by iter, optionally smoothly scrolling to it.

Parameters:	column – the column to selects iter – the gtk.TreeIter to be selected scroll_to – whether to smoothly scroll to the item

unselect_iter(column, iter)¶

Unselect the item pointed by iter in the column column

Parameters:	column – the column to unselects from iter – the gtk.TreeIter to be unselected

unselect_all(column)¶

Unselects all the selected items in the column column.

Parameter:	column – the position of the column to get the selected rows from

get_selected_rows(column)¶

Creates a list of gtk.TreePath s of all selected rows in a column. Additionally, if you to plan to modify the model after calling this function, you may want to convert the returned list into a list of GtkTreeRowReferences. To do this, you can use gtk.TreeRowReference.

See gtk.TreeSelection.get_selected_rows() for more information.

Parameter:	column – the position of the column to get the selected rows from
Returns:	A new list containing a gtk.TreePath for each selected row in the column column.

set_model(column, model)¶

Sets the gtk.TreeModel for a particular column in model.

Parameters:	column – the position of the column to set the model to model – a GtkTreeModel

get_model(column)¶

Gets the model of a column of selector.

Parameter:	column – the position of the column in selector
Returns:	the gtk.TreeModel for the column column of selector.

get_current_text()¶

Returns a string representing the currently selected items for each column of selector. See set_print_func().

Returns:	a newly allocated string.

set_print_func(func)¶

Sets the function to be used by get_current_text() to produce a text representation of the currently selected items in selector. The default function will return a concatenation of comma separated items selected in each column in selector. Use this to override this method if you need a particular representation for your application.

Parameter:	func – a callable object

get_print_func()¶

Gets the PrintFunc currently used. See set_print_func().

Returns:	a object or None if the default one is currently used.

has_multiple_selection()¶

Determines whether selector is complex enough to actually require an extra selection step than only picking an item. This is normally True if selector has multiple columns, multiple selection, or when it is a more complex widget, like TouchSelectorEntry . This information is useful for widgets containing a TouchSelector , like PickerDialog , that could need a “Done” button, in case that its internal TouchSelector has multiple columns, for instance.

Returns:	True if selector requires multiple selection steps.

Related Functions¶

function:	hildon_touch_selector_new_text () Creates a TouchSelector with a single text column that can be populated conveniently through append_text(), prepend_text(), insert_text(). returns: A new TouchSelector

Properties¶

Signal Details¶

The changed signal

hildon.user_function(widget, column, user_data)

The “changed” signal is emitted when the active item on any column is changed. This can be due to the user selecting a different item from the list, or due to a call to select_iter() on one of the columns.

Parameters:	widget – the object which received the signal column – the number of the column that has changed user_data – user data set when the signal handler was connected.

The columns-changed signal

hildon.user_function(selector, user_data)

The “columns-changed” signal is emitted when the number of columns in the TouchSelector change.

Parameters:	selector – the object which received the signal user_data – user data set when the signal handler was connected.

Object Hierarchy¶

Implemented Interfaces¶

TouchSelectorColumn implements gtk.CellLayout .

Description¶

TouchSelectorColumn object represents a visible column in TouchSelector . It allows to manage the cell renderers related to each column.

Details¶

class hildon.TouchSelectorColumn¶

Properties¶

Object Hierarchy¶

Implemented Interfaces¶

SelectorEntry implements atk.ImplementorIface and gtk.Buildable .

Description¶

SelectorEntry is a selector widget with a text entry, similar in behaviour to gtk.ComboBoxEntry , that allows user to select an item from a predefined list or to enter a different one in a HildonEntry . Items can also be searched and selected by typing in the entry. For more specific use cases, the HildonEntry can be accessed directly with hildon_touch_selector_get_entry() .

The main difference between the gtk.TreeModel used by HildonTouchSelector and TouchSelectorEntry , is that the latter must always include a text column. You should set it with touch_selector_entry_set_text_column().

Normally, you would use TouchSelectorEntry together with a PickerDialog activated from a button. For the most common cases, you should use PickerButton .

If you only need a text only, one column selector, you can create it with hildon_touch_selector_entry_new_text() and populate it with append_text(), prepend_text(), and insert_text().

Details¶

class hildon.TouchSelectorEntry¶

__init__()¶

Creates a TouchSelectorEntry

Returns:	A new TouchSelectorEntry

set_text_column(text_column)¶

Sets the model column which touch selector box should use to get strings from to be text_column.

Parameter:	text_column – A column in model to get the strings from

get_text_column()¶

Gets the text column that selector is using as a text column.

Returns:	the number of the column used as a text column.

set_input_mode(input_mode)¶

Sets the input mode to be used in the gtk.Entry in selector. See set_input_mode() for details. It must be noted that not all input modes are available for the entry in selector. In particular, GTK_INPUT_MODE_MULTILINE, GTK_INPUT_MODE_INVISIBLE, GTK_INPUT_MODE_DICTIONARY are disabled, since these are irrelevant for TouchSelectorEntry .

Parameter:	input_mode – GtkInputMode mask

get_input_mode()¶

Gets the input mode used in the :class:`gtk.Entry` in ``selector``. See :meth:`get_input_mode` for details.

Returns:	a mask of GtkInputMode

get_entry()¶

Provides access to the Entry in selector. Use to programmatically change the contents in entry or modify its behavior.

Returns:	a Entry .

Related Functions¶

hildon.hildon_touch_selector_entry_new_text()¶

Creates a TouchSelectorEntry with a single text column that can be populated conveniently through append_text(), prepend_text(), insert_text().

Returns:	A new TouchSelectorEntry

Properties¶

See Also¶

TouchSelector PickerButton

Object Hierarchy¶

Implemented Interfaces¶

DateSelector implements atk.ImplementorIface and gtk.Buildable .

Description¶

DateSelector is a date widget with multiple columns. Users can choose a date by selecting values in the day, month and year columns.

The currently selected month and year can be altered with select_month(). The day can be selected from the active month using select_day().

Details¶

class hildon.DateSelector¶

__init__()¶

Creates a new DateSelector

Returns:	a new DateSelector

select_month(month, year)¶

Modify the current month and year on the current active date Ytility function to keep this API similar to the previously existing Calendar widget.

Parameters:	month – the current month (0-11) year – the current year
Returns:	True on success, False otherwise

select_day(day)¶

Modify the current day on the current active date Utility function to keep this API similar to the previously existing Calendar widget.

Parameter:	day – the current day (1-31, 1-30, 1-29, 1-28) depends on the month

select_current_date(year, month, day)¶

Sets the current active date on the DateSelector widget

Parameters:	year – the current year month – the current month (0-11) day – the current day (1-31, 1-30, 1-29, 1-28) depends on the month
Returns:	True on success, False otherwise

get_date()¶

Gets the current active date on the DateSelector widget

Returns:	a tuple with (year, month, day)

Related Functions¶

hildon.hildon_date_selector_new_with_year_range(min_year, max_year)¶

Creates a new DateSelector with a specific year range. If min_year or max_year are set to -1, then the default upper or lower bound will be used, respectively.

Parameters:	min_year – the minimum available year or -1 to ignore max_year – the maximum available year or -1 to ignore
Returns:	a new DateSelector

Properties¶

Object Hierarchy¶

Implemented Interfaces¶

TimeSelector implements atk.ImplementorIface and gtk.Buildable .

Description¶

TimeSelector allows users to choose a time by selecting hour and minute. It also allows choosing between AM or PM format.

The currently selected time can be altered with set_time(), and retrieved using get_time().

Use this widget instead of deprecated HildonTimeEditor widget.

Details¶

class hildon.TimeSelector¶

__init__()¶

Creates a new TimeSelector

Returns:	a new TimeSelector

new_step(minutes_step)¶

Creates a new TimeSelector minutes_step: step between the minutes we are going to show in the selector

Parameter:	minutes_step –
Returns:	a new TimeSelector

set_time(hours, minutes)¶

Sets the current active hour on the TimeSelector widget The format of the hours accepted is always 24h format, with a range (0-23):(0-59).

Parameters:	hours – the current hour (0-23) minutes – the current minute (0-59)
Returns:	True on success, False otherwise

get_time()¶

Gets the current active hour on the TimeSelector widget. This method returns the date always in 24h format, with a range (0-23):(0-59)

Returns:	a tuple with (hours, minutes)

Properties¶

Object Hierarchy¶

Implemented Interfaces¶

PannableArea implements atk.ImplementorIface and gtk.Buildable .

Description¶

PannableArea is a container widget that can be “panned” (scrolled) up and down using the touchscreen with fingers. The widget has no scrollbars, but it rather shows small scroll indicators to give an idea of the part of the content that is visible at a time. The scroll indicators appear when a dragging motion is started on the pannable area.

The scrolling is “kinetic”, meaning the motion can be “flicked” and it will continue from the initial motion by gradually slowing down to an eventual stop. The motion can also be stopped immediately by pressing the touchscreen over the pannable area.

Details¶

hildon.PannableAreaMode¶

hildon.MovementMode¶

Used to control the movement of the pannable, we can allow or disallow horizontal or vertical movement. This way the applications can control the movement using scroll_to and jump_to functions

hildon.MovementDirection¶

Used to point out the direction of the movement

hildon.SizeRequestPolicy¶

Used to control the size request policy of the widget

Ctors:

class hildon.PannableArea¶

__init__()¶

Create a new pannable area widget

add_with_viewport(child)¶

Convenience function used to add a child to a GtkViewport , and add the viewport to the scrolled window.

Parameter:	child – Child widget to add to the viewport

scroll_to(x, y)¶

Smoothly scrolls area to ensure that (x, y) is a visible point on the widget. To move in only one coordinate, you must set the other one to -1. Notice that, in PANNABLE_AREA_MODE_PUSH, this function works just like jump_to().

This function is useful if you need to present the user with a particular element inside a scrollable widget, like GtkTreeView . For instance, the following example shows how to scroll inside a GtkTreeView to make visible an item, indicated by the GtkTreeIter iter.

::

path = model.get_pah(model) rect = treeview.get_background_area(path, None) (x, y) = treeview.convert_bin_window_to_tree_coords(0, rect.y) panarea.scroll_to(-1, y)

If you want to present a child widget in simpler scenarios, use scroll_to_child() instead.

There is a precondition to this function: the widget must be already realized. Check the jump_to_child() for more tips regarding how to call this function during initialization.

Parameters:	x – The x coordinate of the destination point or -1 to ignore this axis. y – The y coordinate of the destination point or -1 to ignore this axis.

jump_to(x, y)¶

Jumps the position of area to ensure that (x, y) is a visible point in the widget. In order to move in only one coordinate, you must set the other one to -1. See scroll_to() function for an example of how to calculate the position of children in scrollable widgets like GtkTreeview . There is a precondition to this function: the widget must be already realized. Check the jump_to_child() for more tips regarding how to call this function during initialization.

Parameters:	x – The x coordinate of the destination point or -1 to ignore this axis. y – The y coordinate of the destination point or -1 to ignore this axis.

scroll_to_child(child)¶

Smoothly scrolls until child is visible inside area. child must be a descendant of area. If you need to scroll inside a scrollable widget, e.g., GtkTreeview , see scroll_to().

There is a precondition to this function: the widget must be already realized. Check the jump_to_child() for more tips regarding how to call this function during initialization.

Parameter:	child – A gtk.Widget , descendant of area.

jump_to_child(child)¶

Jumps to make sure child is visible inside area. child must be a descendant of area. If you want to move inside a scrollable widget, like, GtkTreeview , see scroll_to().

There is a precondition to this function: the widget must be already realized. You can control if the widget is ready with the GTK_WIDGET_REALIZED macro. If you want to call this function during the initialization process of the widget do it inside a callback to the ::realize signal, using g_signal_connect_after() function.

Parameter:	child – A gtk.Widget , descendant of area.

get_child_widget_at(x, y)¶

Get the widget at the point (x, y) inside the pannable area. In case no widget found it returns None.

Parameters:	x – horizontal coordinate of the point y – vertical coordinate of the point
Returns:	the gtk.Widget if we find a widget, NULL in any other case

get_size_request_policy()¶

This function returns the current size request policy of the widget. That policy controls the way the size_request is done in the pannable area. Check set_size_request_policy() for a more detailed explanation.

Returns:	the policy is currently being used in the widget HildonSizeRequestPolicy .

get_hadjustment()¶

Returns the horizontal adjustment. This adjustment is the internal widget adjustment used to control the animations. Do not modify it directly to change the position of the pannable, to do that use the pannable API. If you modify the object directly it could cause artifacts in the animations.

Returns:	The horizontal GtkAdjustment

Functions¶

hildon.hildon_pannable_area_new_full(mode, enabled, vel_min, vel_max, decel, sps)¶

Create a new HildonPannableArea widget and set various properties

Parameters:	mode – HildonPannableAreaMode enabled – Value for the enabled property vel_min – Value for the velocity-min property vel_max – Value for the velocity-max property decel – Value for the deceleration property sps – Value for the sps property
Returns:	the newly create HildonPannableArea

Properties¶

Style Properties¶

Signal Details¶

The horizontal-movement signal

hildon.user_function(hildonpannable, direction, initial_x, initial_y, user_data)

The horizontal-movement signal is emitted when the pannable area starts a horizontal movement.

Parameters:	hildonpannable – the object which received the signal direction – the direction of the movement hildon.MOVEMENT_UP or hildon.MOVEMENT_DOWN initial_x – the x value of the touched point in the area when the motion started initial_y – the y value of the touched point in the area when the motion started user_data – user data set when the signal handler was connected.

The vertical-movement signal

hildon.user_function(hildonpannable, direction, initial_x, initial_y, user_data)

The vertical-movement signal is emitted when the pannable area starts a vertical movement.

Parameters:	hildonpannable – the object which received the signal direction – the direction of the movement hildon.MOVEMENT_LEFT or hildon.MOVEMENT_RIGHT initial_x – the x value when the motion started initial_y – the y value when the motion started user_data – user data set when the signal handler was connected.

See Also¶

gtk.ScrolledWindow

Object Hierarchy¶

Implemented Interfaces¶

Entry implements atk.ImplementorIface , gtk.Buildable , GtkEditable and GtkCellEditable .

Description¶

The Entry is a GTK widget which represents a text entry. It is derived from the gtk.Entry widget and provides additional commodities specific to the Hildon framework.

Besides all the features inherited from gtk.Entry , a Entry can also have a placeholder text. This text will be shown if the entry is empty and doesn’t have the input focus, but it’s otherwise ignored. Thus, calls to Entry.get_text() will never return the placeholder text, not even when it’s being displayed.

Creating a Entry with a placeholder¶

def create_entry():
    entry = hildon.Entry(gtk.HILDON_SIZE_AUTO)
    entry.set_placeholder("First name")
    return entry

Details¶

class hildon.Entry¶

__init__(size = 0)¶

Creates a new entry.

Parameter:	size – The size of the entry
Returns:	a new Entry

set_text(text)¶

Sets the text in entry to text, replacing its current contents. Note that you must never use Entry.set_text() to set the text of a Entry .

Parameter:	text – the new text

get_text()¶

Gets the current text in entry. Note that you must never use get_text() to get the text from a Entry . Also note that placeholder text (set using set_placeholder() is never returned. Only text set by set_text() or typed by the user is considered.

Returns:	the text in entry. This text must not be modified or freed.

set_placeholder(text)¶

Sets the placeholder text in entry to text.

Parameter:	text – the new text

Object Hierarchy¶

Implemented Interfaces¶

TextView implements atk.ImplementorIface and gtk.Buildable .

Description¶

The TextView is a GTK widget which represents a text view. It is derived from the gtk.TextView widget and provides additional commodities specific to the Hildon framework.

Besides all the features inherited from gtk.TextView , a TextView can also have a placeholder text. This text will be shown if the text view is empty and doesn’t have the input focus, but it’s otherwise ignored. Thus, calls to hildon_text_view_get_buffer() will never return the placeholder text, not even when it’s being displayed.

Although TextView is derived from gtk.TextView , get_buffer() and set_buffer() must never be used to get/set the buffer in this widget. get_buffer() and set_buffer() must be used instead.

Creating a TextView with a placeholder¶

def create_text_view ():
    text_view = hildon.TextView()
    text_view.set_placeholder("Type some text here")
    return text_view

Details¶

class hildon.TextView¶

__init__()¶

Creates a new text view.

Returns:	a new TextView

set_buffer(buffer)¶

Sets buffer as the buffer being displayed by text_view. The previous buffer displayed by the text view is unreferenced, and a reference is added to buffer. If you owned a reference to bufferbefore passing it to this function, you must remove that reference yourself Note that you must never use set_buffer() to set the buffer of a TextView .

Parameter:	buffer – a gtk.TextBuffer

get_buffer()¶

Returns the text buffer in text_view. The reference count is not incremented; the caller of this function won’t own a new reference. Note that you must never use get_buffer() to get the buffer from a TextView . Also note that placeholder text (set using set_placeholder() is never contained in this buffer.

Returns:	a gtk.TextBuffer

set_placeholder(text)¶

Sets the placeholder text in text_view to text.

Parameter:	text – the new text

Object Hierarchy¶

Implemented Interfaces¶

AppMenu implements atk.ImplementorIface and gtk.Buildable .

Description¶

The AppMenu is a GTK widget which represents an application menu in the Hildon framework.

This menu opens from the top of the screen and contains a number of entries (gtk.Button ) organized in one or two columns, depending on the size of the screen (the number of columns changes automatically if the screen is resized). Entries are added left to right and top to bottom.

Besides that, the AppMenu can contain a group of filter buttons (gtk.ToggleButton or gtk.RadioButton ).

To use a AppMenu , add it to a Window using Window.set_app_menu() . The menu will appear when the user presses the window title bar. Alternatively, you can show it by hand using popup().

The menu will be automatically hidden when one of its buttons is clicked. Use g_signal_connect_after() when connecting callbacks to buttons to make sure that they’re called after the menu disappears. Alternatively, you can add the button to the menu before connecting any callback.

Although implemented with a gtk.Window , AppMenu behaves like a normal ref-counted widget, so ref(), unref() , ref_sink() and friends will behave just like with any other non-toplevel widget.

Creating a AppMenu¶

win = hildon.StackableWindow()
menu = hildon.AppMenu()

# Create a button and add it to the menu
button = gtk.Button("Menu command one")
button.connect("clicked", button_one_clicked, userdata)
menu.append(button)

# Another button
button = gtk.Button("Menu command two")
button.connect("clicked", button_two_clicked, userdata)
menu.append(button)

# Create a filter and add it to the menu
filter = gtk.RadioButton(None, "Filter one")
filter.set_mode(False)
filter.connect("clicked", filter_one_clicked, userdata)
menu.add_filter(filter)

# Add a new filter
filter = gtk.RadioButton(None, "Filter two")
filter.set_mode(False)
filter.connect("clicked", filter_two_clicked, userdata)
menu.add_filter(filter)

# Show all menu items
menu.show_all()

# Add the menu to the window
window.set_app_menu(menu)

Details¶

class hildon.AppMenu¶

__init_()¶

Creates a new AppMenu .

Returns:	A AppMenu .

append(item)¶

Adds item to the end of the menu’s item list.

Parameter:	item – A gtk.Button to add to the AppMenu

prepend(item)¶

Adds item to the beginning of the menu’s item list.

Parameter:	item – A gtk.Button to add to the AppMenu

menu_insert(item, positon)¶

Adds item to menu at the position indicated by position.

Parameters:	item – A gtk.Button to add to the AppMenu position – The position in the item list where item is added (from 0 to n-1).

reorder_child(item, position)¶

Moves a GtkButton to a new position within AppMenu .

Parameters:	item – A gtk.Button to move position – The new position to place item (from 0 to n-1).

add_filter(filter)¶

Adds the filter to menu.

Parameter:	filter – A gtk.Button to add to the AppMenu .

get_items()¶

Returns a list of all items (regular items, not filters) contained in menu.

Returns:	a newly-allocated list containing the items in menu

get_filters()¶

Returns a list of all filters contained in menu.

Returns:	a newly-allocated list containing the filters in menu

popup(parent_window)¶

Displays a menu on top of a window and makes it available for selection.

Parameter:	parent_window – a gtk.Window