Manual

Gtk2_IndexedComboBox is a Gtk2 widget similar to the HTML select box - it lets you not only store values as the normal GtkComboBox, but associated key/value pairs. Gtk2_IndexedComboBox is meant to be as easy to use as possible, and to have an API similar to the combo boxes created with GtkComboBox::new_text(). You can directly add key/value pairs to the widget instead of using the model (which is possible, too). Retrieving the currently selected key can be done with a single method call. Both keys and values can be strings, thus allowing integers implicitly. This is very useful if you need a widget to select some row ID from a database, but want to display some descriptive string. By default, a single GtkCellRendererText is used as cell renderer.

Simple example

Simple example – To get started easily

Simple example

In this example, we will create a combo box, add an array of key/value pairs and display the currently selected pair in a label.

Simple Gtk2_IndexedComboBox example

<?php
require_once 'Gtk2/IndexedComboBox.php';

//display this data
$arData = array(
    1   => 'Germany',
    2   => 'United Kingdom',
    3   => 'Spain',
    4   => 'France'
);

//Create combo and set the array
$combo = new Gtk2_IndexedComboBox();
$combo->set_array($arData);
//make #2 active
$combo->set_active_key(2);

//trace changes
$combo->connect('changed', 'comboChanged', $lbl);

function comboChanged($combo, $lbl)
{
    $lbl->set_text(
        "Combo changed:\r\n"
        . 'Key: '   . $combo->get_active_key() . "\r\n"
        . 'Value: ' . $combo->get_active_text()
    );
}

//some label to display changes
$lbl = new GtkLabel("Status\r\n\r\n");

//standard stuff
$vbox = new GtkVBox();
$vbox->pack_start($combo);
$vbox->pack_start($lbl);

$wnd = new GtkWindow();
$wnd->connect_simple('destroy', array('Gtk', 'main_quit'));
$wnd->add($vbox);
$wnd->show_all();
Gtk::main();
?>

At first, we create a new combo widget object. You already could pass the array of data in the constructor if you wanted to, but here we use the set_array() method to do this. After providing the data, entry with id 2 is made active/pre-selected.

Whenever the selection changes, the example displays the selected key and value in a label below the combo box. We use get_active_key() to retrieve the key, and get_active_text() to retrieve the value.

Conquering Glade combo boxes

Conquering Glade combo boxes – How to use glade combos with this class

Conquering Glade combo boxes

While designing your user interface with Glade is really convenient and easy, it doesn't allow you to use custom classes as this combo here. Thanks to the MVC model in Gtk2, you still can use this class's power by using the same model as Gtk2_IndexedComboBox uses internally: Gtk2_IndexedComboBox_Model.

Glade file to use

<?xml version="1.0" standalone="no"?> <!--*- mode: xml -*-->
<!DOCTYPE glade-interface SYSTEM "http://glade.gnome.org/glade-2.0.dtd">

<glade-interface>

<widget class="GtkWindow" id="wndTest">
  <property name="visible">True</property>
  <property name="title" translatable="yes">Gtk2_IndexedComboBox_Model test</property>
  <property name="type">GTK_WINDOW_TOPLEVEL</property>
  <property name="window_position">GTK_WIN_POS_NONE</property>
  <property name="modal">False</property>
  <property name="resizable">True</property>
  <property name="destroy_with_parent">False</property>
  <property name="decorated">True</property>
  <property name="skip_taskbar_hint">False</property>
  <property name="skip_pager_hint">False</property>
  <property name="type_hint">GDK_WINDOW_TYPE_HINT_NORMAL</property>
  <property name="gravity">GDK_GRAVITY_NORTH_WEST</property>
  <signal name="destroy" handler="Gtk::main_quit"/>

  <child>
    <widget class="GtkComboBox" id="cmbNormal">
      <property name="visible">True</property>
    </widget>
  </child>
</widget>

</glade-interface>

PHP code

<?php
require_once 'Gtk2/IndexedComboBox/Model.php';

$glade = new GladeXML(dirname(__FILE__) . '/glade.glade');
$glade->signal_autoconnect();

$combo = $glade->get_widget('cmbNormal');
$combo->connect('changed', 'comboChanged');
//show the second column only
$renderer = new GtkCellRendererText();
$combo->pack_start($renderer);
$combo->set_attributes($renderer, 'text', 1);

$mod = new Gtk2_IndexedComboBox_Model();
$combo->set_model($mod);

$mod->append(1, 'One');
$mod->append_array(array(2 => 'Two', 3 => 'Three'));
$mod->prepend(4, 'Four');

function comboChanged($combo)
{
    $nActive = $combo->get_active();
    $iter    = $combo->get_model()->get_iter($nActive);

    $key     = $combo->get_model()->get_key($iter);
    $text    = $combo->get_model()->get_text($iter);

    echo 'Selected: ' . $key . ' => ' . $text . "\r\n";
}

Gtk::main();
?>

The important thing to remember is that you need to setup your own cell renderer, and tell it which column in the model shall be displayed. Beside that, you just do the normal model-creation-and-setting via set_model().

All data manipulation methods of Gtk2_IndexedComboBox you saw in the previous example are available in the model, Gtk2_IndexedComboBox_Model. Only get_active_key() and get_active_text() cannot be used on the model, since this doesn't know anything about selections. Retrieve the selected GtkTreeIter by combining the calls of get_active() and get_iter(), and pass this iter object to get_key() and get_text().

Gtk2_IndexedComboBox

Gtk2_IndexedComboBox – The main class

Gtk2_IndexedComboBox

Gtk2_IndexedComboBox automatically creates the model and sets up the cell renderer when instantiating the widget. You may pass an array of key/value pairs to the constructor if you like to, but also can set them later.

The currently selected (active) key can be retrieved via get_active_key(), the selected (active) value by using get_active_text(). You can preselect a certain key with set_active_key().

If you don't like the renderer or want to change it or its attributes, use get_cell_renderer() and set_cell_renderer().

All other methods to retrieve/store data are convenience methods that act as proxy to the model. For example, Gtk2_IndexedComboBox' method set_array() internally calls the same method on the model, Gtk2_IndexedComboBox_Model. This allows you to quickly add some data to the combo without getting the model first and acting on it.

Gtk2_IndexedComboBox_Model

Gtk2_IndexedComboBox_Model – Model class behind the scenes

Gtk2_IndexedComboBox_Model

The model class is the data storage for your key/value pairs. It contains two columns, both are of type Gtk::TYPE_STRING and can hold text and numbers. The first is used for the keys, the values are stored in the second column.

The class has several method that allow you to store data in the model: The classis set_array() takes an associative array of key/value pairs. Once set, you can use append_array() and prepend_array() to add new data after or before the current values. You also have the possibility to use insert_array() that takes the position as first, and the data array as second parameter.

Beside the *_array methods, you can add single key/value pairs by using append() and prepend() which take the key as first, and the value as second parameter. insert() wants an additional position number as first parameter, and key/value as second and third.

To delete data from the model, use remove_key(). After finishing your data manipulation, you can retrieve the full associative array of key/value pairs via get_array().

To obtain the key or value of a certain GtkTreeIter (that you got e.g. from the model by using get_iter()), use get_key() and get_text().