HildonTouchSelector

HildonTouchSelector — A selector widget with several columns.

Synopsis

gchar*              (*HildonTouchSelectorPrintFunc)     (HildonTouchSelector *selector);
                    HildonTouchSelector;
enum                HildonTouchSelectorSelectionMode;
GtkWidget*          hildon_touch_selector_new           (void);
GtkWidget*          hildon_touch_selector_new_text      (void);
void                hildon_touch_selector_append_text   (HildonTouchSelector *selector,
                                                         const gchar *text);
void                hildon_touch_selector_prepend_text  (HildonTouchSelector *selector,
                                                         const gchar *text);
void                hildon_touch_selector_insert_text   (HildonTouchSelector *selector,
                                                         gint position,
                                                         const gchar *text);
HildonTouchSelectorColumn* hildon_touch_selector_append_text_column
                                                        (HildonTouchSelector *selector,
                                                         GtkTreeModel *model,
                                                         gboolean center);
HildonTouchSelectorColumn* hildon_touch_selector_append_column
                                                        (HildonTouchSelector *selector,
                                                         GtkTreeModel *model,
                                                         GtkCellRenderer *cell_renderer,
                                                         ...);
void                hildon_touch_selector_set_column_attributes
                                                        (HildonTouchSelector *selector,
                                                         gint num_column,
                                                         GtkCellRenderer *cell_renderer,
                                                         ...);
gboolean            hildon_touch_selector_remove_column (HildonTouchSelector *selector,
                                                         gint column);
gint                hildon_touch_selector_get_num_columns
                                                        (HildonTouchSelector *selector);
void                hildon_touch_selector_set_column_selection_mode
                                                        (HildonTouchSelector *selector,
                                                         HildonTouchSelectorSelectionMode mode);
HildonTouchSelectorSelectionMode hildon_touch_selector_get_column_selection_mode
                                                        (HildonTouchSelector *selector);
HildonTouchSelectorColumn* hildon_touch_selector_get_column
                                                        (HildonTouchSelector *selector,
                                                         gint column);
void                hildon_touch_selector_set_active    (HildonTouchSelector *selector,
                                                         gint column,
                                                         gint index);
gint                hildon_touch_selector_get_active    (HildonTouchSelector *selector,
                                                         gint column);
gboolean            hildon_touch_selector_get_selected  (HildonTouchSelector *selector,
                                                         gint column,
                                                         GtkTreeIter *iter);
void                hildon_touch_selector_select_iter   (HildonTouchSelector *selector,
                                                         gint column,
                                                         GtkTreeIter *iter,
                                                         gboolean scroll_to);
void                hildon_touch_selector_unselect_iter (HildonTouchSelector *selector,
                                                         gint column,
                                                         GtkTreeIter *iter);
GList*              hildon_touch_selector_get_selected_rows
                                                        (HildonTouchSelector *selector,
                                                         gint column);
void                hildon_touch_selector_set_model     (HildonTouchSelector *selector,
                                                         gint column,
                                                         GtkTreeModel *model);
GtkTreeModel*       hildon_touch_selector_get_model     (HildonTouchSelector *selector,
                                                         gint column);
gchar*              hildon_touch_selector_get_current_text
                                                        (HildonTouchSelector *selector);
void                hildon_touch_selector_set_print_func
                                                        (HildonTouchSelector *selector,
                                                         HildonTouchSelectorPrintFunc func);
HildonTouchSelectorPrintFunc hildon_touch_selector_get_print_func
                                                        (HildonTouchSelector *selector);
gboolean            hildon_touch_selector_has_multiple_selection
                                                        (HildonTouchSelector *selector);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBox
                                 +----GtkVBox
                                       +----HildonTouchSelector
                                             +----HildonTouchSelectorEntry
                                             +----HildonTimeSelector
                                             +----HildonDateSelector

Implemented Interfaces

HildonTouchSelector implements AtkImplementorIface and GtkBuildable.

Properties

  "has-multiple-selection"   gboolean              : Read
  "initial-scroll"           gboolean              : Read / Write / Construct

Signals

  "changed"                                        : Run Last
  "columns-changed"                                : Run Last

Description

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

Normally, you would use HildonTouchSelector together with a HildonPickerDialog activated from a button. For the most common cases, you should use HildonPickerButton.

The composition of each column in the selector is represented by a GtkTreeModel. To add a new column to a HildonTouchSelector, 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 HildonTouchSelectors. 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 HildonTouchSelectorEntry.

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 HildonTouchSelectorColumn property "text-column"

You can get this string representation using hildon_touch_selector_get_current_text(). You can configure how the selection is printed with hildon_touch_selector_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 HildonTouchSelectorColumn 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 hildon_touch_selector_new(), 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.

Example 14. Creating a HildonTouchSelector

void
selection_changed (HildonTouchSelector * selector,
                   gpointer *user_data)
{
  gchar *current_selection = NULL;

  current_selection = hildon_touch_selector_get_current_text (selector);
  g_debug ("Current selection : %s", current_selection);
}

static GtkWidget *
create_customized_selector ()
{
  GtkWidget *selector = NULL;
  GSList *icon_list = NULL;
  GtkListStore *store_icons = NULL;
  GSList *item = NULL;
  GtkCellRenderer *renderer = NULL;
  HildonTouchSelectorColumn *column = NULL;

  selector = hildon_touch_selector_new ();

  icon_list = gtk_stock_list_ids ();

  store_icons = gtk_list_store_new (1, G_TYPE_STRING);
  for (item = icon_list; item; item = g_slist_next (item)) {
    GtkTreeIter iter;
    gchar *label = item->data;

    gtk_list_store_append (store_icons, &iter);
    gtk_list_store_set (store_icons, &iter, 0, label, -1);
    g_free (label);
  }
  g_slist_free (icon_list);

  renderer = gtk_cell_renderer_pixbuf_new ();
  gtk_cell_renderer_set_fixed_size (renderer, -1, 100);

  column = hildon_touch_selector_append_column (HILDON_TOUCH_SELECTOR (selector),
                                                GTK_TREE_MODEL (store_icons),
                                                renderer, "stock-id", 0, NULL);

  g_object_set (G_OBJECT (column), "text-column", 0, NULL);

  hildon_touch_selector_set_column_selection_mode (HILDON_TOUCH_SELECTOR (selector),
                                                   HILDON_TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE);

  g_signal_connect (G_OBJECT (selector), "changed",
                    G_CALLBACK (selection_changed), NULL);

  return selector;
}

static GtkWidget *
create_simple_selector ()
{
  GtkWidget *selector = NULL;
  gint i;

  selector = hildon_touch_selector_new_text ();
  hildon_touch_selector_set_column_selection_mode (HILDON_TOUCH_SELECTOR (selector),
                                                   HILDON_TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE);

  g_signal_connect (G_OBJECT (selector), "changed",
                    G_CALLBACK (selection_changed), NULL);

  for (i = 1; i <= 10 ; i++) {
    gchar *label = g_strdup_printf ("Item &percnt;d", i);

    hildon_touch_selector_append_text (HILDON_TOUCH_SELECTOR (selector),
                                       label);

    g_free (label);
  }

  return selector;
}


Details

HildonTouchSelectorPrintFunc ()

gchar*              (*HildonTouchSelectorPrintFunc)     (HildonTouchSelector *selector);

selector :
Returns :

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_SELECTION_MODE_SINGLE Users can select one item
HILDON_TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE Users can select one to many items

hildon_touch_selector_new ()

GtkWidget*          hildon_touch_selector_new           (void);

Creates a new empty HildonTouchSelector.

Returns : a new 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().

Returns : A new HildonTouchSelector

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().

selector : A HildonTouchSelector.
text : a non NULL text string.

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().

selector : A HildonTouchSelector.
text : a non NULL text string.

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 particular position of a HildoTouchSelector created with hildon_touch_selector_new_text().

selector : a HildonTouchSelector.
position : the position to insert text.
text : A non NULL text string.

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.

selector : a HildonTouchSelector
model : a GtkTreeModel with data for the column
center : whether to center the text on the column
Returns : the new column added, NULL otherwise.

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, i.e., the print function, the "changed" signal, etc.

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.

There is a prerequisite to be considered on models used: text data must be in the first column.

This method basically adds a GtkTreeView to the widget, using the model and the data received.

selector : a HildonTouchSelector
model : the GtkTreeModel with the data of the column
cell_renderer : The GtkCellRenderer where to draw each row contents.
... : a NULL-terminated pair of attributes and column numbers.
Returns : the new column added added, NULL otherwise.

Since 2.2


hildon_touch_selector_set_column_attributes ()

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

Warning

hildon_touch_selector_set_column_attributes is deprecated and should not be used in newly-written code. HildonTouchSelectorColumn implements GtkCellLayout, use this interface instead. See hildon_touch_selector_get_column().

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.

selector : a HildonTouchSelector
num_column : the number of the column whose attributes we're setting
cell_renderer : the GtkCellRendere we're setting the attributes of
... : A NULL-terminated list of attributes.

Since 2.2


hildon_touch_selector_remove_column ()

gboolean            hildon_touch_selector_remove_column (HildonTouchSelector *selector,
                                                         gint column);

Removes a column from selector.

selector : a HildonTouchSelector
column : the position of the column to be removed
Returns : TRUE if the column was removed, FALSE otherwise

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.

selector : a HildonTouchSelector
Returns : the number of columns in selector.

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.

selector : a HildonTouchSelector
mode : the HildonTouchSelectorMode for selector

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.

selector : a HildonTouchSelector
Returns : one of HildonTouchSelectorSelectionMode

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.

selector : A HildonTouchSelector
column : a column number
Returns : the column-th HildonTouchSelectorColumn in selector

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

selector : a HildonTouchSelector
column : column number
index : the index of the item to select, or -1 to have no active item

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

selector : a HildonTouchSelector
column : column number
Returns : an integer which is the index of the currently active item, or -1 if there's no active item.

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.

selector : a HildonTouchSelector
column : the column number we want to get the element
iter : GtkTreeIter currently selected
Returns : TRUE if iter was correctly set, FALSE otherwise

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.

selector : a HildonTouchSelector
column : the column to selects
iter : the GtkTreeIter to be selected
scroll_to : whether to smoothly scroll to the item

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

selector : a HildonTouchSelector
column : the column to unselects from
iter : the GtkTreeIter to be unselected

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.

selector : a HildonTouchSelector
column : the position of the column to get the selected rows from
Returns : A new GList containing a GtkTreePath for each selected row in the column column.

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.

selector : a HildonTouchSelector
column : the position of the column to set the model to
model : a GtkTreeModel

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.

selector : a HildonTouchSelector
column : the position of the column in selector
Returns : the GtkTreeModel for the column 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().

selector : a HildonTouchSelector
Returns : a newly allocated string.

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() 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.

selector : a HildonTouchSelector
func : a HildonTouchSelectorPrintFunc function

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().

selector : a HildonTouchSelector
Returns : a HildonTouchSelectorPrintFunc or NULL if the default one is currently used.

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.

selector : A HildonTouchSelector
Returns : TRUE if selector requires multiple selection steps.

Since 2.2

Property Details

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 "initial-scroll" property

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

Whether to scroll to thecurrent selection whenthe selector is firstshown.

Default value: TRUE

Signal Details

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.

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

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.

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