HildonTouchSelectorPrintFunc ()

gchar*              (*HildonTouchSelectorPrintFunc)     (HildonTouchSelector *selector,
                                                         gpointer user_data);

HildonTouchSelector

typedef struct _HildonTouchSelector HildonTouchSelector;

enum HildonTouchSelectorSelectionMode

typedef enum
{
  HILDON_TOUCH_SELECTOR_SELECTION_MODE_SINGLE,
  HILDON_TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE
} HildonTouchSelectorSelectionMode;

Describes the selection mode of a HildonTouchSelector.

hildon_touch_selector_new ()

GtkWidget*          hildon_touch_selector_new           (void);

Creates a new empty HildonTouchSelector.

Since 2.2

hildon_touch_selector_new_text ()

GtkWidget*          hildon_touch_selector_new_text      (void);

Creates a HildonTouchSelector with a single text column that can be populated conveniently through hildon_touch_selector_append_text(), hildon_touch_selector_prepend_text(), hildon_touch_selector_insert_text().

Since 2.2

hildon_touch_selector_append_text ()

void                hildon_touch_selector_append_text   (HildonTouchSelector *selector,
                                                         const gchar *text);

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

Since 2.2

hildon_touch_selector_prepend_text ()

void                hildon_touch_selector_prepend_text  (HildonTouchSelector *selector,
                                                         const gchar *text);

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

Since 2.2

hildon_touch_selector_insert_text ()

void                hildon_touch_selector_insert_text   (HildonTouchSelector *selector,
                                                         gint position,
                                                         const gchar *text);

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

Since 2.2

hildon_touch_selector_append_text_column ()

HildonTouchSelectorColumn* hildon_touch_selector_append_text_column
                                                        (HildonTouchSelector *selector,
                                                         GtkTreeModel *model,
                                                         gboolean center);

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

Note that this call adds a reference to model, so you must unref it afterwards if you are not going to use it anymore.

Since 2.2

hildon_touch_selector_append_column ()

HildonTouchSelectorColumn* hildon_touch_selector_append_column
                                                        (HildonTouchSelector *selector,
                                                         GtkTreeModel *model,
                                                         GtkCellRenderer *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, the print function, the "changed" signal, etc. Internally, a GtkTreeView will be added to the widget, using model as the data source. This will add a reference to model, so you must unref it after calling this function if you are not going to use it anymore.

You can optionally pass a GtkCellRenderer in cell_renderer, together with a NULL-terminated list of pairs property/value, in the same way you would use gtk_tree_view_column_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 NULL to cell_renderer and use the GtkCellLayout interface on the returned HildonTouchSelectorColumn to set your renderers. Please note that the returned HildonTouchSelectorColumn is owned by selector, you shouldn't unref it after setting it up.

Initially, the returned HildonTouchSelectorColumn will have its "text-column" property unset. You should set it to a column in model with type G_TYPE_STRING. See hildon_touch_selector_column_set_text_column().

This method could change the current "hildon-ui-mode". HILDON_UI_MODE_NORMAL is only allowed with one column, so if the selector is in this mode, and a additional column is added, "hildon-ui-mode" will change to HILDON_UI_MODE_EDIT.

Since 2.2

hildon_touch_selector_set_column_attributes ()

void                hildon_touch_selector_set_column_attributes
                                                        (HildonTouchSelector *selector,
                                                         gint num_column,
                                                         GtkCellRenderer *cell_renderer,
                                                         ...);

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

Since 2.2

hildon_touch_selector_remove_column ()

gboolean            hildon_touch_selector_remove_column (HildonTouchSelector *selector,
                                                         gint column);

Removes a column from selector.

Since 2.2

hildon_touch_selector_get_num_columns ()

gint                hildon_touch_selector_get_num_columns
                                                        (HildonTouchSelector *selector);

Gets the number of columns in the HildonTouchSelector.

Since 2.2

hildon_touch_selector_set_column_selection_mode ()

void                hildon_touch_selector_set_column_selection_mode
                                                        (HildonTouchSelector *selector,
                                                         HildonTouchSelectorSelectionMode mode);

Sets the selection mode for selector. See HildonTouchSelectorSelectionMode.

The new mode will be set, but take into into account that the HildonTouchSelectorSelectionMode is ignored if the selector "hildon-ui-mode" property is set to HILDON_UI_MODE_NORMAL

Since 2.2

hildon_touch_selector_get_column_selection_mode ()

HildonTouchSelectorSelectionMode hildon_touch_selector_get_column_selection_mode
                                                        (HildonTouchSelector *selector);

Gets the selection mode of selector.

Since 2.2

hildon_touch_selector_get_column ()

HildonTouchSelectorColumn* hildon_touch_selector_get_column
                                                        (HildonTouchSelector *selector,
                                                         gint column);

Use this method to retrieve a HildonTouchSelectorColumn. Then, you can use the GtkCellLayout interface to set up the layout of the column.

Since 2.2

hildon_touch_selector_set_active ()

void                hildon_touch_selector_set_active    (HildonTouchSelector *selector,
                                                         gint column,
                                                         gint index);

Sets the active item of the HildonTouchSelector to index. The column number is taken from column.

selector must be in HILDON_TOUCH_SELECTOR_SELECTION_MODE_SINGLE

Since 2.2

hildon_touch_selector_get_active ()

gint                hildon_touch_selector_get_active    (HildonTouchSelector *selector,
                                                         gint 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 HILDON_TOUCH_SELECTOR_SELECTION_MODE_SINGLE

Since 2.2

hildon_touch_selector_get_selected ()

gboolean            hildon_touch_selector_get_selected  (HildonTouchSelector *selector,
                                                         gint column,
                                                         GtkTreeIter *iter);

Sets iter to the currently selected node on the nth-column, if selection is set to HILDON_TOUCH_SELECTOR_SINGLE or HILDON_TOUCH_SELECTOR_MULTIPLE with a column different that the first one. iter may be NULL if you just want to test if selection has any selected items.

This function will not work if selection is in HILDON_TOUCH_SELECTOR_MULTIPLE mode and the column is the first one.

See gtk_tree_selection_get_selected() for more information.

Since 2.2

hildon_touch_selector_center_on_selected ()

void                hildon_touch_selector_center_on_selected
                                                        (HildonTouchSelector *selector);

Ensures all the columns in a HildonTouchSelector show a selected item. If one of the columns is in HILDON_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.

The "initial-scroll" property configure the widget in order to use this function at the first show.

Take into account that the element is not centered until the widget is realized. If the widget is not realized when the function is called, it will be postponed. If you call this functions several times before the widgets is realized, only the last one will be used.

This behaviour includes any call to hildon_touch_selector_center_on_index(), so take care calling this functions, or with the "initial-scroll" property in order to get centered on the proper element.

Since 2.2

hildon_touch_selector_center_on_index ()

void                hildon_touch_selector_center_on_index
                                                        (HildonTouchSelector *selector,
                                                         gint column,
                                                         gint index);

Ensures that the column number column shows the element index

This is similar to hildon_touch_selector_center_on_selected() but with the difference that allows to center on a column item not selected.

Take into account that the element is not centered until the widget is realized. If the widget is not realized when the function is called, it will be postponed. If you call this function several times before the widget is realized, only the last one will be used.

This behaviour includes any call to hildon_touch_selector_center_on_selected(). Check this function for more tips.

Since 2.2

hildon_touch_selector_get_hildon_ui_mode ()

HildonUIMode        hildon_touch_selector_get_hildon_ui_mode
                                                        (HildonTouchSelector *selector);

Gets the current hildon-ui-mode, see HildonUIMode for more information

Since 2.2

hildon_touch_selector_set_hildon_ui_mode ()

gboolean            hildon_touch_selector_set_hildon_ui_mode
                                                        (HildonTouchSelector *selector,
                                                         HildonUIMode mode);

Sets the value of the property "hildon-ui-mode" to be mode, see HildonUIMode for more information

Note that the HILDON_UI_MODE_NORMAL can be only used when the selector has one column, use the return value to check if the change was effective.

Since 2.2

hildon_touch_selector_get_last_activated_row ()

GtkTreePath*        hildon_touch_selector_get_last_activated_row
                                                        (HildonTouchSelector *selector,
                                                         gint column);

Gets a GtkTreePath of the last row activated in a column (the last row that emitted a "row-activated" signal). This is mainly useful if the selector "hildon-ui-mode" in set to HILDON_UI_MODE_NORMAL, as using this state there is no real selection, so a method like hildon_touch_selector_get_selected_rows() will return always a empty selection.

Anyway, this method works as well on HILDON_UI_MODE_EDIT, but in this case is better, and more useful, to get the current selection.

Since 2.2

hildon_touch_selector_select_iter ()

void                hildon_touch_selector_select_iter   (HildonTouchSelector *selector,
                                                         gint column,
                                                         GtkTreeIter *iter,
                                                         gboolean scroll_to);

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

Since 2.2

hildon_touch_selector_unselect_iter ()

void                hildon_touch_selector_unselect_iter (HildonTouchSelector *selector,
                                                         gint column,
                                                         GtkTreeIter *iter);

Unselect the item pointed by iter in the column column

Since 2.2

hildon_touch_selector_unselect_all ()

void                hildon_touch_selector_unselect_all  (HildonTouchSelector *selector,
                                                         gint column);

Unselects all the selected items in the column column.

Since 2.2

hildon_touch_selector_get_selected_rows ()

GList*              hildon_touch_selector_get_selected_rows
                                                        (HildonTouchSelector *selector,
                                                         gint column);

Creates a list of GtkTreePaths 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_tree_row_reference_new().

See gtk_tree_selection_get_selected_rows() for more information.

Since 2.2

hildon_touch_selector_set_model ()

void                hildon_touch_selector_set_model     (HildonTouchSelector *selector,
                                                         gint column,
                                                         GtkTreeModel *model);

Sets the GtkTreeModel for a particular column in model.

Note that this call adds a reference to model, so you must unref it afterwards if you are not going to use it anymore.

Since 2.2

hildon_touch_selector_get_model ()

GtkTreeModel*       hildon_touch_selector_get_model     (HildonTouchSelector *selector,
                                                         gint column);

Gets the model of a column of selector.

Since 2.2

hildon_touch_selector_get_current_text ()

gchar*              hildon_touch_selector_get_current_text
                                                        (HildonTouchSelector *selector);

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

Since 2.2

hildon_touch_selector_set_print_func ()

void                hildon_touch_selector_set_print_func
                                                        (HildonTouchSelector *selector,
                                                         HildonTouchSelectorPrintFunc func);

Sets the function to be used by hildon_touch_selector_get_current_text(). See hildon_touch_selector_set_print_func_full().

Since 2.2

hildon_touch_selector_get_print_func ()

HildonTouchSelectorPrintFunc hildon_touch_selector_get_print_func
                                                        (HildonTouchSelector *selector);

Gets the HildonTouchSelectorPrintFunc currently used. See hildon_touch_selector_set_print_func().

hildon_touch_selector_set_print_func_full ()

void                hildon_touch_selector_set_print_func_full
                                                        (HildonTouchSelector *selector,
                                                         HildonTouchSelectorPrintFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy_func);

Sets the function to be used by hildon_touch_selector_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.

Since 2.2

hildon_touch_selector_has_multiple_selection ()

gboolean            hildon_touch_selector_has_multiple_selection
                                                        (HildonTouchSelector *selector);

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 HildonTouchSelectorEntry.

This information is useful for widgets containing a HildonTouchSelector, like HildonPickerDialog, that could need a "Done" button, in case that its internal HildonTouchSelector has multiple columns, for instance.

Since 2.2

hildon_touch_selector_optimal_size_request ()

void                hildon_touch_selector_optimal_size_request
                                                        (HildonTouchSelector *selector,
                                                         GtkRequisition *requisition);

Gets the optimal size request of the touch selector. This function is mostly intended for dialog implementations that include a HildonTouchSelector and want to optimize the screen real state, for example, when you want a dialog to show as much of the selector, avoiding any extra empty space below the selector.

See HildonPickerDialog implementation for an example.

This function is oriented to be used in the size_request of a dialog or window, if you are not sure do not use it.

There is a precondition to this function: Since this function does not call the "size_request" method, it can only be used when you know that gtk_widget_size_request() has been called since the last time a resize was queued.

Since 2.2

The "has-multiple-selection" property

  "has-multiple-selection"   gboolean              : Read

Whether the widget has multiple selection (like multiple columns, multiselection mode, or multiple internal widgets) and therefore it may need a confirmation button, for instance.

Default value: FALSE

The "hildon-ui-mode" property

  "hildon-ui-mode"           HildonUIMode          : Read / Write

Specifies which UI mode to use in the internal treeviews. A setting of HILDON_UI_MODE_NORMAL will cause these tree view to disable selections and emit row-activated as soon as a row is pressed (unless it is pressed to drag the pannable area where the treeview is). You can use the method hildon_touch_selector_get_last_activated_row() to get it. When HILDON_UI_MODE_EDIT is set, selections can be made according to the setting of the mode on GtkTreeSelection.

Toggling this property will cause the tree view to select an appropriate selection mode if not already done.

Default value: HILDON_UI_MODE_EDIT

Since Hildon 2.2

The "initial-scroll" property

  "initial-scroll"           gboolean              : Read / Write / Construct

Whether to scroll to thecurrent selection whenthe selector is firstshown.

Default value: TRUE

The "changed" signal

void                user_function                      (HildonTouchSelector *widget,
                                                        gint                 column,
                                                        gpointer             user_data)      : Run Last

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 hildon_touch_selector_select_iter() on one of the columns.

Since 2.2

The "columns-changed" signal

void                user_function                      (HildonTouchSelector *selector,
                                                        gpointer             user_data)      : Run Last

The "columns-changed" signal is emitted when the number of columns in the HildonTouchSelector change.

Since 2.2