--- name: "Gtk2::ComboBox" section: "3pm" platform: "linux" package: "libgtk2-perl-doc" version: "2:1.24992-1" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/Gtk2::ComboBox" --- # Gtk2::ComboBox(3pm) A widget used to choose from a list of items ## 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) - • `$model` (Gtk2::TreeModel) ### widget = Gtk2::ComboBox-\>new\_text ### widget = Gtk2::ComboBox-\>new\_with\_model ($model=undef) - • `$model` (Gtk2::TreeModel) ### integer = $combo\_box-\>get\_active ### treeiter = $combo\_box-\>get\_active\_iter ### $combo\_box-\>set\_active\_iter ($iter) - • `$iter` (Gtk2::TreeIter or undef) ### $combo\_box-\>set\_active ($index) - • `$index` (integer) ### 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) - • `$add_tearoffs` (boolean) Since: gtk+ 2.6 ### $combo\_box-\>append\_text ($text) - • `$text` (string) ### sensitivitytype = $combo\_box-\>get\_button\_sensitivity Since: gtk+ 2.14 ### $combo\_box-\>set\_button\_sensitivity ($sensitivity) - • `$sensitivity` (Gtk2::SensitivityType) Since: gtk+ 2.14 ### integer = $combo\_box-\>get\_column\_span\_column Since: gtk+ 2.6 ### $combo\_box-\>set\_column\_span\_column ($column\_span) - • `$column_span` (integer) ### boolean = $combo\_box-\>get\_focus\_on\_click Since: gtk+ 2.6 ### $combo\_box-\>set\_focus\_on\_click ($focus\_on\_click) - • `$focus_on_click` (boolean) Since: gtk+ 2.6 ### $combo\_box-\>insert\_text ($position, $text) - • `$position` (integer) - • `$text` (string) ### treemodel = $combo\_box-\>get\_model ### $combo\_box-\>set\_model ($model) - • `$model` (Gtk2::TreeModel or undef) 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) - • `$text` (string) ### $combo\_box-\>remove\_text ($position) - • `$position` (integer) ### $combo\_box-\>set\_row\_separator\_func ($func, $data=undef) - • `$func` (scalar) - • `$data` (scalar) Since: gtk+ 2.6 ### integer = $combo\_box-\>get\_row\_span\_column Since: gtk+ 2.6 ### $combo\_box-\>set\_row\_span\_column ($row\_span) - • `$row_span` (integer) ### string = $combo\_box-\>get\_title Since: gtk+ 2.10 ### $combo\_box-\>set\_title ($title) - • `$title` (string) Since: gtk+ 2.10 ### integer = $combo\_box-\>get\_wrap\_width Since: gtk+ 2.6 ### $combo\_box-\>set\_wrap\_width ($width) - • `$width` (integer) ## 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 - • 'none' / 'GTK\_SCROLL\_NONE' - • 'jump' / 'GTK\_SCROLL\_JUMP' - • 'step-backward' / 'GTK\_SCROLL\_STEP\_BACKWARD' - • 'step-forward' / 'GTK\_SCROLL\_STEP\_FORWARD' - • 'page-backward' / 'GTK\_SCROLL\_PAGE\_BACKWARD' - • 'page-forward' / 'GTK\_SCROLL\_PAGE\_FORWARD' - • 'step-up' / 'GTK\_SCROLL\_STEP\_UP' - • 'step-down' / 'GTK\_SCROLL\_STEP\_DOWN' - • 'page-up' / 'GTK\_SCROLL\_PAGE\_UP' - • 'page-down' / 'GTK\_SCROLL\_PAGE\_DOWN' - • 'step-left' / 'GTK\_SCROLL\_STEP\_LEFT' - • 'step-right' / 'GTK\_SCROLL\_STEP\_RIGHT' - • 'page-left' / 'GTK\_SCROLL\_PAGE\_LEFT' - • 'page-right' / 'GTK\_SCROLL\_PAGE\_RIGHT' - • 'start' / 'GTK\_SCROLL\_START' - • 'end' / 'GTK\_SCROLL\_END' ### enum Gtk2::SensitivityType - • 'auto' / 'GTK\_SENSITIVITY\_AUTO' - • 'on' / 'GTK\_SENSITIVITY\_ON' - • 'off' / 'GTK\_SENSITIVITY\_OFF' ## 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.