15.1.1. Basic Gtk2::ComboBox Use

The easy way to create and populate a Gtk2::ComboBox is to use the convenience method:

widget = Gtk2::ComboBox->new_text 

This method creates a Gtk2::ComboBox and its associated Gtk2::ListStore and packs it with a Gtk2::CellRendererText. The following convenience methods are used to populate or remove the contents of the Gtk2::ComboBox and its Gtk2::ListStore:

$combo_box->append_text ($text) 
	* $text (string)

$combo_box->insert_text ($position, $text) 
	* $position (integer)
	* $text (string)
	
$combo_box->prepend_text ($text) 
	* $text (string)
	
$combo_box->remove_text ($position) 
	* $position (integer)

In most cases the convenience methods are all you need.

To get the text displayed by the active item:

	
string = $combo_box->get_active_text 

The index of the active item is retrieved using the method:

string = $combo_box->get_active 

The active item can be set using the method:

$combo_box->set_active ($index) 

If index is -1 there is no active item and the Gtk2::ComboBox display will be blank.

You can connect to the "changed" signal of a Gtk2::ComboBox to be notified when the active item has been changed.

The demo program 'gtk2_combo_box_basic.pl' demonstrates the use of the above methods.

15.1.2. Advanced Gtk2::ComboBox Use

Creating a Gtk2::ComboBox using the "new_text" method is roughly equivalent to the following code:

my $list_store = Gtk2::ListStore->new(qw/Glib::String/);
my $combobox = Gtk2::ComboBox->new($list_store);
my $renderer = Gtk2::CellRendererText->new();
$combobox->pack_start($renderer, TRUE);
$combobox->add_attribute($renderer,'text',0);

To make use of the power of the various Gtk2::TreeModel and Gtk2::CellRenderer objects you need to construct a Gtk2::ComboBox using the constructor:

 widget = Gtk2::ComboBox->new ($model=undef) 
 	* $model (Gtk2::TreeModel)

If you create a Gtk2::ComboBox without associating a Gtk2::TreeModel, you can add one later using the method:

$combo_box->set_model ($model) 
	* $model (Gtk2::TreeModel)

The associated Gtk2::TreeModel can be retrieved using the method:

treemodel = $combo_box->get_model 

Some of the things you can do with a Gtk2::ComboBox are:

• Share the same Gtk2::TreeModel with other Gtk2::ComboBoxes and Gtk2::TreeViews.

• Display images and text in the Gtk2::ComboBox list items.

• Use an existing Gtk2::TreeStore or Gtk2::ListStore as the model for the Gtk2::ComboBox list items.

• Use a Gtk2::TreeModelSort to provide a sorted Gtk2::ComboBox list.

• Use a Gtk2::TreeModelFilter to use a subtree of a Gtk2::TreeStore as the source for a Gtk2::ComboBox list items.

• Use a Gtk2::TreeModelFilter to use a subset of the rows in a Gtk2::TreeStore or Gtk2::ListStore as the Gtk2::ComboBox list items.

• Use a cell data function to modify or synthesize the display for list items.

The use of the Gtk2::TreeModel and Gtk2::CellRenderer objects is detailed in Chapter 14

The Gtk2::ComboBox list items can be displayed in a grid if you have a large number of items to display. Otherwise the list will have scroll arrows if the entire list cannot be displayed. The following method is used to set the number of columns to display:

$combo_box->set_wrap_width ($width) 
	* $width (integer)

where $row_span is the number of columns of the grid displaying the list items.For example, the 'gtk2_combo_box_wrap.pl' program displays a list of 50 items in 5 columns.

In addition to the "get_active" method described above, you can retrieve a Gtk2::TreeIter pointing at the active row by using the method:

treeiter = $combo_box->get_active_iter 

You can also set the active list item using a Gtk2::TreeIter with the method:

$combo_box->set_active_iter ($iter) 
	* $iter (Gtk2::TreeIter) 

Since the Gtk2::ComboBox implements the Gtk2::CellLayout interface which has similar capabilities as the Gtk2::TreeViewColumn.Briefly, the interface provides:

$combobox->pack_start($renderer, TRUE);
$combobox->pack_end($renderer, TRUE);
$combobox->clear;

The first two methods pack a Gtk2::CellRenderer into the Gtk2::ComboBox and the clear method clears all attributes from all Gtk2::CellRenderers.

The following methods:

$combobox->add_attribute($renderer, $attribute, $column);

$combobox->set_attributes($renderer,.....);

set attributes for the Gtk2::CellRenderer specified by $renderer. The "add_attribute" method takes a string attribute name (e.g. 'text') and an integer column number of the column in the Gtk2::TreeModel to use to set attribute. The additional arguments to the "set_attributes" method are attribute=column pairs (e.g 'text'=>1).