Gtk2::ComboBox

NAME

Gtk2::ComboBox − A widget used to choose from a list of items

SYNOPSIS

# the easy way:
$combobox = Gtk2::ComboBox−>new_text;
foreach (@strings) {
$combobox−>append_text ($_);
}
$combobox−>prepend_text ($another_string);
$combobox−>insert_text ($index, $yet_another_string);
$combobox−>remove_text ($index);
$text = $combobox−>get_active_text;
# the full−featured way.
# a combo box that shows stock ids and their images:
use constant ID_COLUMN => 0;
$model = Gtk2::ListStore−>new ('Glib::String');
foreach (qw(gtk−ok gtk−cancel gtk−yes gtk−no gtk−save gtk−open)) {
$model−>set ($model−>append, ID_COLUMN, $_);
}
$combo_box = Gtk2::ComboBox−>new ($model);
# to display anything, you must pack cell renderers into
# the combobox, which implements the Gtk2::CellLayout interface.
$renderer = Gtk2::CellRendererPixbuf−>new;
$combo_box−>pack_start ($renderer, FALSE);
$combo_box−>add_attribute ($renderer, stock_id => ID_COLUMN);
$renderer = Gtk2::CellRendererText−>new;
$combo_box−>pack_start ($renderer, TRUE);
$combo_box−>add_attribute ($renderer, text => ID_COLUMN);
# select by index
$combo_box−>set_active ($index);
$active_index = $combo_box−>get_active;
# or by iter
$combo_box−>set_active_iter ($iter);
$active_iter = $combo_box−>get_active_iter;

DESCRIPTION

Gtk2::ComboBox is a widget that allows the user to choose from a list of valid choices. The ComboBox displays the selected choice. When activated, the ComboBox displays a popup which allows the user to make a new choice.

Unlike its predecessors Gtk2::Combo and Gtk2::OptionMenu, the Gtk2::ComboBox uses the model-view pattern; the list of valid choices is specified in the form of a tree model, and the display of the choices can be adapted to the data in the model by using cell renderers, as you would in a tree view. This is possible since ComboBox implements the Gtk2::CellLayout interface. The tree model holding the valid choices is not restricted to a flat list; it can be a real tree, and the popup will reflect the tree structure.

In addition to the model-view API, ComboBox offers a simple API which is suitable for text-only combo boxes, and hides the complexity of managing the data in a model. It consists of the methods "new_text", "append_text", "insert_text", "prepend_text", "remove_text" and "get_active_text".

HIERARCHY

Glib::Object
+−−−−Glib::InitiallyUnowned
+−−−−Gtk2::Object
+−−−−Gtk2::Widget
+−−−−Gtk2::Container
+−−−−Gtk2::Bin
+−−−−Gtk2::ComboBox

INTERFACES

Glib::Object::_Unregistered::AtkImplementorIface
Gtk2::Buildable
Gtk2::CellLayout
Gtk2::CellEditable

METHODS

widget = Gtk2::ComboBox−>new ($model=undef)

widget = Gtk2::ComboBox−>new_text
widget = Gtk2::ComboBox−>new_with_model ($model=undef)

integer = $combo_box−>get_active
treeiter = $combo_box−>get_active_iter
$combo_box−>set_active_iter ($iter)

$combo_box−>set_active ($index)

string = $combo_box−>get_active_text
Since: gtk+ 2.6

boolean = $combo_box−>get_add_tearoffs
Since: gtk+ 2.6

$combo_box−>set_add_tearoffs ($add_tearoffs)

Since: gtk+ 2.6

$combo_box−>append_text ($text)

sensitivitytype = $combo_box−>get_button_sensitivity
Since: gtk+ 2.14

$combo_box−>set_button_sensitivity ($sensitivity)

Since: gtk+ 2.14

integer = $combo_box−>get_column_span_column
Since: gtk+ 2.6

$combo_box−>set_column_span_column ($column_span)

boolean = $combo_box−>get_focus_on_click
Since: gtk+ 2.6

$combo_box−>set_focus_on_click ($focus_on_click)

Since: gtk+ 2.6

$combo_box−>insert_text ($position, $text)

treemodel = $combo_box−>get_model
$combo_box−>set_model ($model)

Note that setting "undef" for no model is new in Gtk 2.6. (Both here or via "set_property".)

$combo_box−>popdown
$combo_box−>popup
$combo_box−>prepend_text ($text)

$combo_box−>remove_text ($position)

$combo_box−>set_row_separator_func ($func, $data=undef)

Since: gtk+ 2.6

integer = $combo_box−>get_row_span_column
Since: gtk+ 2.6

$combo_box−>set_row_span_column ($row_span)

string = $combo_box−>get_title
Since: gtk+ 2.10

$combo_box−>set_title ($title)

Since: gtk+ 2.10

integer = $combo_box−>get_wrap_width
Since: gtk+ 2.6

$combo_box−>set_wrap_width ($width)

PROPERTIES

’active’ (integer : default −1 : readable / writable / private)

The item which is currently active

’add−tearoffs’ (boolean : default false : readable / writable /
private)

Whether dropdowns should have a tearoff menu item

’button−sensitivity’ (Gtk2::SensitivityType : default "auto" : readable
/ writable / private)

Whether the dropdown button is sensitive when the model is empty

’column−span−column’ (integer : default −1 : readable / writable /
private)

TreeModel column containing the column span values

’entry−text−column’ (integer : default −1 : readable / writable /
private)

The column in the combo box’s model to associate with strings from the entry if the combo was created with #GtkComboBox:has−entry = %TRUE

’focus−on−click’ (boolean : default true : readable / writable /
private)

Whether the combo box grabs focus when it is clicked with the mouse

’has−entry’ (boolean : default false : readable / writable /
construct-only / private)

Whether combo box has an entry

’has−frame’ (boolean : default true : readable / writable / private)

Whether the combo box draws a frame around the child

’model’ (Gtk2::TreeModel : default undef : readable / writable /
private)

The model for the combo box

’popup−shown’ (boolean : default false : readable / private)

Whether the combo’s dropdown is shown

’row−span−column’ (integer : default −1 : readable / writable /
private)

TreeModel column containing the row span values

’tearoff−title’ (string : default undef : readable / writable /
private)

A title that may be displayed by the window manager when the popup is torn-off

’wrap−width’ (integer : default 0 : readable / writable / private)

Wrap width for laying out the items in a grid

STYLE PROPERTIES

’appears−as−list’ (boolean : default false : readable / private)

Whether dropdowns should look like lists rather than menus

’arrow−size’ (integer : default 15 : readable / private)

The minimum size of the arrow in the combo box

’shadow−type’ (Gtk2::ShadowType : default "none" : readable / private)

Which kind of shadow to draw around the combo box

SIGNALS

changed (Gtk2::ComboBox)
move-active (Gtk2::ComboBox, Gtk2::ScrollType)
boolean = popdown (Gtk2::ComboBox)
popup (Gtk2::ComboBox)

ENUMS AND FLAGS

enum Gtk2::ScrollType

enum Gtk2::SensitivityType

SEE ALSO

Gtk2, Glib::Object, Glib::InitiallyUnowned, Gtk2::Object, Gtk2::Widget, Gtk2::Container, Gtk2::Bin

COPYRIGHT

Copyright (C) 2003−2011 by the gtk2−perl team.

This software is licensed under the LGPL. See Gtk2 for a full notice.