Hildon::TouchSelector Class Reference
[Widgets]

A selector widget with several columns. More...

Inheritance diagram for Hildon::TouchSelector:

List of all members.

Public Types

typedef TouchSelectorColumn Column

typedef TouchSelectorSelectionMode SelectionMode

Public Member Functions

virtual ~TouchSelector ()

HildonTouchSelector * gobj ()

Provides access to the underlying C GtkObject.

const HildonTouchSelector * gobj () const

Provides access to the underlying C GtkObject.

TouchSelector ()

Glib::RefPtr< TouchSelectorColumn > append_text_column (const Glib::RefPtr< Gtk::TreeModel > &model, bool center=false)

Equivalent to append_column(), but using a default text cell renderer.

template<class ColumnType>

Glib::RefPtr< TouchSelectorColumn > append_text_column (const Glib::RefPtr< Gtk::TreeModel > &model, const Gtk::TreeModelColumn< ColumnType > &model_column, bool center=false)

Glib::RefPtr< TouchSelectorColumn > append_column (const Glib::RefPtr< Gtk::TreeModel > &model, Gtk::CellRenderer &cell_renderer)

This functions adds a new column to the widget, whose data will be obtained from the model.

Glib::RefPtr< TouchSelectorColumn > append_column (const Glib::RefPtr< Gtk::TreeModel > &model)

bool remove_column (int column=0)

Removes a column from selector.

int get_num_columns () const

Gets the number of columns in the Hildon::TouchSelector.

void set_column_selection_mode (TouchSelectorSelectionMode mode)

Sets the selection mode for selector.

TouchSelectorSelectionMode get_column_selection_mode () const

Gets the selection mode of selector.

Glib::RefPtr< TouchSelectorColumn > get_column (int column=0)

Use this method to retrieve a Hildon::TouchSelectorColumn.

Glib::RefPtr< const
TouchSelectorColumn > get_column (int column=0) const

Use this method to retrieve a Hildon::TouchSelectorColumn.

void set_selected (int column, int index)

Sets the active item of the Hildon::TouchSelector to index.

void set_selected (int column, const Gtk::TreeModel::iterator &iter)

int get_selected_row_number (int column=0) const

Returns: an integer which is the index of the currently active.

Gtk::TreeModel::iterator get_selected (int column=0)

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.

void select_iter (int column, const Gtk::TreeModel::iterator &iter, bool scroll_to)

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

void unselect_iter (int column, const Gtk::TreeModel::iterator &iter)

Unselect the item pointed by iter in the column column.

void unselect_all (int column=0)

Unselects all the selected items in the column column.

Gtk::TreeSelection::ListHandle_Path get_selected_rows (int column=0) const

Creates a list of Gtk::TreePaths of all selected rows in a column.

void set_model (int column, const Glib::RefPtr< Gtk::TreeModel > &model)

Sets the Gtk::TreeModel for a particular column in model.

Glib::RefPtr< Gtk::TreeModel > get_model (int column=0)

Gets the model of a column of selector.

Glib::RefPtr< const
Gtk::TreeModel > get_model (int column=0) const

Gets the model of a column of selector.

Glib::ustring get_current_text () const

Returns: a newly allocated string.

void set_print_func (const sigc::slot< Glib::ustring > &func)

Sets the function to be used by get_current_text().

void unset_print_func ()

Causes no custom TouchSelectorPrintFunc to be active.

bool has_multiple_selection () const

Determines whether selector is complex enough to actually require an extra selection step than only picking an item.

void center_on_selected ()

Ensures all the columns in a Hildon::TouchSelector show a selected item.

Glib::SignalProxy1< void, int > signal_changed ()

Glib::SignalProxy0< void > signal_columns_changed ()

Related Functions

(Note that these are not member functions.)

Hildon::TouchSelector * wrap (HildonTouchSelector *object, bool take_copy=false)

A Glib::wrap() method for this object.

Detailed Description

A selector widget with several columns.

Hildon::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 individually pannable columns.

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

The composition of each column in the selector is represented by a Gtk::TreeModel. To add a new column to a Hildon::TouchSelector, use Hildon::TouchSelector::append_column(). If you want to add a text-only column, without special attributes, use Hildon::TouchSelector::append_text_column().

It is highly recommended that you use only one-column Hildon::TouchSelectors. If you only need a text-only, one column selector, you can use the simpler TouchSelectorText class.

If you need a selector widget that also accepts user inputs, you can use Hildon::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 Hildon::TouchSelectorColumn::property_text_column().

You can get this string representation using Hildon::TouchSelector::get_current_text(). You can configure how the selection is printed with Hildon::TouchSelector::set_print_func(), that sets the current hildon touch selector print function. The widget has a default print function, that uses the Hildon::TouchSelectorColumn::property_text_column() on each Hildon::TouchSelectorColumn to compose the final representation.

Member Typedef Documentation

typedef TouchSelectorColumn Hildon::TouchSelector::Column

typedef TouchSelectorSelectionMode Hildon::TouchSelector::SelectionMode

Constructor & Destructor Documentation

virtual Hildon::TouchSelector::~TouchSelector ( ) [virtual]

Hildon::TouchSelector::TouchSelector ( )

Member Function Documentation

HildonTouchSelector* Hildon::TouchSelector::gobj ( ) [inline]

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::VBox.

Reimplemented in Hildon::DateSelector, Hildon::TimeSelector, and Hildon::TouchSelectorEntry.

const HildonTouchSelector* Hildon::TouchSelector::gobj ( ) const [inline]

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::VBox.

Reimplemented in Hildon::DateSelector, Hildon::TimeSelector, and Hildon::TouchSelectorEntry.

Glib::RefPtr<TouchSelectorColumn> Hildon::TouchSelector::append_text_column	(	const Glib::RefPtr< Gtk::TreeModel > &	model,
		bool	center = `false`
	)

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, 0 otherwise.

{2,2}.

template<class ColumnType>

Glib::RefPtr< TouchSelectorColumn > Hildon::TouchSelector::append_text_column	(	const Glib::RefPtr< Gtk::TreeModel > &	model,
		const Gtk::TreeModelColumn< ColumnType > &	model_column,
		bool	center = `false`
	)			`[inline]`

Glib::RefPtr<TouchSelectorColumn> Hildon::TouchSelector::append_column	(	const Glib::RefPtr< Gtk::TreeModel > &	model,
		Gtk::CellRenderer &	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 Hildon::TouchSelector::changed signal, etc. Internally, a Gtk::TreeView will be added to the widget, using model as the data source.

You can optionally pass a Gtk::CellRenderer in cell_renderer, together with a 0-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 0 to cell_renderer and use the Gtk::CellLayout interface on the returned Hildon::TouchSelectorColumn to set your renderers. Please note that the returned Hildon::TouchSelectorColumn is owned by selector, you shouldn't unref it after setting it up.

Initially, the returned Hildon::TouchSelectorColumn will have its Hildon::TouchSelectorColumn:text-column property unset. You should set it to a column in model with type TYPE_STRING. See Hildon::TouchSelectorColumn::set_text_column().

This method could change the current Hildon::TouchSelector: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::TouchSelector:hildon-ui-mode will change to Hildon::UI_MODE_EDIT.

Parameters:

	model	The Gtk::TreeModel with the data of the column.
	cell_renderer	The Gtk::CellRenderer where to draw each row contents.
	Varargs	A `0`-terminated pair of attributes and column numbers.

Returns:: The new column added added, 0 otherwise.

{2,2}.

Glib::RefPtr<TouchSelectorColumn> Hildon::TouchSelector::append_column ( const Glib::RefPtr< Gtk::TreeModel > & model )

bool Hildon::TouchSelector::remove_column ( int column = 0 )

Removes a column from selector.

Parameters:

column

The position of the column to be removed.

Returns:: true if the column was removed, false otherwise

{2,2}.

int Hildon::TouchSelector::get_num_columns ( ) const

Gets the number of columns in the Hildon::TouchSelector.

Returns:: The number of columns in selector.

{2,2}.

void Hildon::TouchSelector::set_column_selection_mode ( TouchSelectorSelectionMode mode )

Sets the selection mode for selector.

See Hildon::TouchSelectorSelectionMode.

The new mode will be set, but take into into account that the Hildon::TouchSelectorSelectionMode is ignored if the selector Hildon::TouchSelector:hildon-ui-mode property is set to Hildon::UI_MODE_NORMAL

{2,2}

Parameters:

mode

The Hildon::TouchSelectorMode for selector.

TouchSelectorSelectionMode Hildon::TouchSelector::get_column_selection_mode ( ) const

Gets the selection mode of selector.

Returns:: One of Hildon::TouchSelectorSelectionMode

{2,2}.

Glib::RefPtr<TouchSelectorColumn> Hildon::TouchSelector::get_column ( int column = 0 )

Use this method to retrieve a Hildon::TouchSelectorColumn.

Then, you can use the Gtk::CellLayout interface to set up the layout of the column.

Parameters:

column

A column number.

Returns:: The column-th Hildon::TouchSelectorColumn in selector

{2,2}.

Glib::RefPtr<const TouchSelectorColumn> Hildon::TouchSelector::get_column ( int column = 0 ) const

Use this method to retrieve a Hildon::TouchSelectorColumn.

Then, you can use the Gtk::CellLayout interface to set up the layout of the column.

Parameters:

column

A column number.

Returns:: The column-th Hildon::TouchSelectorColumn in selector

{2,2}.

void Hildon::TouchSelector::set_selected	(	int	column,
		int	index
	)

Sets the active item of the Hildon::TouchSelector to index.

The column number is taken from column.

selector must be in Hildon::TOUCH_SELECTOR_SELECTION_MODE_SINGLE

{2,2}

Parameters:

	column	Column number.
	index	The index of the item to select, or -1 to have no active item.

void Hildon::TouchSelector::set_selected	(	int	column,
		const Gtk::TreeModel::iterator &	iter
	)

int Hildon::TouchSelector::get_selected_row_number ( int column = 0 ) const

Returns: an integer which is the index of the currently active.

Parameters:

column

Column number.

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

{2,2}.

Gtk::TreeModel::iterator Hildon::TouchSelector::get_selected ( int column = 0 )

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

Parameters:

	column	The column number we want to get the element.
	iter	Gtk::TreeIter currently selected.

Returns:: true if iter was correctly set, false otherwise

{2,2}.

void Hildon::TouchSelector::select_iter	(	int	column,
		const Gtk::TreeModel::iterator &	iter,
		bool	scroll_to
	)

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

{2,2}

Parameters:

	column	The column to selects.
	iter	The Gtk::TreeIter to be selected.
	scroll_to	Whether to smoothly scroll to the item.

void Hildon::TouchSelector::unselect_iter	(	int	column,
		const Gtk::TreeModel::iterator &	iter
	)

Unselect the item pointed by iter in the column column.

{2,2}

Parameters:

	column	The column to unselects from.
	iter	The Gtk::TreeIter to be unselected.

void Hildon::TouchSelector::unselect_all ( int column = 0 )

Unselects all the selected items in the column column.

{2,2}

Parameters:

column

The position of the column to get the selected rows from.

Gtk::TreeSelection::ListHandle_Path Hildon::TouchSelector::get_selected_rows ( int column = 0 ) const

Creates a list of Gtk::TreePaths 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.

Parameters:

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.

{2,2}.

void Hildon::TouchSelector::set_model	(	int	column,
		const Glib::RefPtr< Gtk::TreeModel > &	model
	)

Sets the Gtk::TreeModel for a particular column in model.

{2,2}

Parameters:

	column	The position of the column to set the model to.
	model	A Gtk::TreeModel.

Glib::RefPtr<Gtk::TreeModel> Hildon::TouchSelector::get_model ( int column = 0 )

Gets the model of a column of selector.

Parameters:

column

The position of the column in selector.

Returns:: The Gtk::TreeModel for the column column of selector.

{2,2}.

Glib::RefPtr<const Gtk::TreeModel> Hildon::TouchSelector::get_model ( int column = 0 ) const

Gets the model of a column of selector.

Parameters:

column

The position of the column in selector.

Returns:: The Gtk::TreeModel for the column column of selector.

{2,2}.

Glib::ustring Hildon::TouchSelector::get_current_text ( ) const

Returns: a newly allocated string.

Returns:: A newly allocated string.

{2,2}.

void Hildon::TouchSelector::set_print_func ( const sigc::slot< Glib::ustring > & func )

Sets the function to be used by get_current_text().

See set_print_func_full().

{2,2}

Parameters:

func

A Hildon::TouchSelectorPrintFunc function.

void Hildon::TouchSelector::unset_print_func ( )

Causes no custom TouchSelectorPrintFunc to be active.

: set_print_func()

bool Hildon::TouchSelector::has_multiple_selection ( ) const

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 Hildon::TouchSelectorEntry.

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

Returns:: true if selector requires multiple selection steps.

{2,2}.

void Hildon::TouchSelector::center_on_selected ( )

Ensures all the columns in a Hildon::TouchSelector 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 Hildon::TouchSelector: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 Hildon::TouchSelector:initial-scroll property in order to get centered on the proper element.

{2,2}

Glib::SignalProxy1< void,int > Hildon::TouchSelector::signal_changed ( )

Prototype:: void on_my_changed(int column)

Glib::SignalProxy0< void > Hildon::TouchSelector::signal_columns_changed ( )

Prototype:: void on_my_columns_changed()

Friends And Related Function Documentation

Hildon::TouchSelector * wrap	(	HildonTouchSelector *	object,
		bool	take_copy = `false`
	)			`[related]`

A Glib::wrap() method for this object.

Parameters:

	object	The C instance.
	take_copy	False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:: A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

touch-selector.h


Public Types
typedef TouchSelectorColumn	Column
typedef TouchSelectorSelectionMode	SelectionMode
Public Member Functions
virtual	~TouchSelector ()
HildonTouchSelector *	gobj ()
	Provides access to the underlying C GtkObject.
const HildonTouchSelector *	gobj () const
	Provides access to the underlying C GtkObject.
	TouchSelector ()
Glib::RefPtr< TouchSelectorColumn >	append_text_column (const Glib::RefPtr< Gtk::TreeModel > &model, bool center=false)
	Equivalent to append_column(), but using a default text cell renderer.
template<class ColumnType>
Glib::RefPtr< TouchSelectorColumn >	append_text_column (const Glib::RefPtr< Gtk::TreeModel > &model, const Gtk::TreeModelColumn< ColumnType > &model_column, bool center=false)
Glib::RefPtr< TouchSelectorColumn >	append_column (const Glib::RefPtr< Gtk::TreeModel > &model, Gtk::CellRenderer &cell_renderer)
	This functions adds a new column to the widget, whose data will be obtained from the model.
Glib::RefPtr< TouchSelectorColumn >	append_column (const Glib::RefPtr< Gtk::TreeModel > &model)
bool	remove_column (int column=0)
	Removes a column from selector.
int	get_num_columns () const
	Gets the number of columns in the Hildon::TouchSelector.
void	set_column_selection_mode (TouchSelectorSelectionMode mode)
	Sets the selection mode for selector.
TouchSelectorSelectionMode	get_column_selection_mode () const
	Gets the selection mode of selector.
Glib::RefPtr< TouchSelectorColumn >	get_column (int column=0)
	Use this method to retrieve a Hildon::TouchSelectorColumn.
Glib::RefPtr< const TouchSelectorColumn >	get_column (int column=0) const
	Use this method to retrieve a Hildon::TouchSelectorColumn.
void	set_selected (int column, int index)
	Sets the active item of the Hildon::TouchSelector to index.
void	set_selected (int column, const Gtk::TreeModel::iterator &iter)
int	get_selected_row_number (int column=0) const
	Returns: an integer which is the index of the currently active.
Gtk::TreeModel::iterator	get_selected (int column=0)
	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.
void	select_iter (int column, const Gtk::TreeModel::iterator &iter, bool scroll_to)
	Sets the currently selected item in the column column to the one pointed by iter, optionally smoothly scrolling to it.
void	unselect_iter (int column, const Gtk::TreeModel::iterator &iter)
	Unselect the item pointed by iter in the column column.
void	unselect_all (int column=0)
	Unselects all the selected items in the column column.
Gtk::TreeSelection::ListHandle_Path	get_selected_rows (int column=0) const
	Creates a list of Gtk::TreePaths of all selected rows in a column.
void	set_model (int column, const Glib::RefPtr< Gtk::TreeModel > &model)
	Sets the Gtk::TreeModel for a particular column in model.
Glib::RefPtr< Gtk::TreeModel >	get_model (int column=0)
	Gets the model of a column of selector.
Glib::RefPtr< const Gtk::TreeModel >	get_model (int column=0) const
	Gets the model of a column of selector.
Glib::ustring	get_current_text () const
	Returns: a newly allocated string.
void	set_print_func (const sigc::slot< Glib::ustring > &func)
	Sets the function to be used by get_current_text().
void	unset_print_func ()
	Causes no custom TouchSelectorPrintFunc to be active.
bool	has_multiple_selection () const
	Determines whether selector is complex enough to actually require an extra selection step than only picking an item.
void	center_on_selected ()
	Ensures all the columns in a Hildon::TouchSelector show a selected item.
Glib::SignalProxy1< void, int >	signal_changed ()
Glib::SignalProxy0< void >	signal_columns_changed ()
Related Functions
(Note that these are not member functions.)
Hildon::TouchSelector *	wrap (HildonTouchSelector *object, bool take_copy=false)
	A Glib::wrap() method for this object.

Hildon::TouchSelector Class Reference [Widgets]

Public Types

Public Member Functions

Related Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Hildon::TouchSelector Class Reference
[Widgets]