Gtk2::ComboBox(3)

📦
version 1.24993 · 2 versions
, in fedora 43

✨ NAME ✨

Gtk2::ComboBox — a widget used to choose from a list of items 💖 (it's in the Gtk2::ComboBox(3) manual, bestie, and it's about to be your new fave)

🌸 SYNOPSIS 🌸

okay so here's the easy way first, the one that just works:

  # 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;

and now the full-featured way, the one that eats 💅 — a combo box showing stock ids and their little images:

  # 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 🦋

okay so Gtk2::ComboBox is a widget that lets the user choose from a list of valid choices. it displays the selected choice. and when it gets activated? it pops up a whole popup so the user can pick something new. main character behaviour, honestly.

unlike its predecessors Gtk2::Combo and Gtk2::OptionMenu, Gtk2::ComboBox uses the model-view pattern ✨ — the list of valid choices lives in a tree model, and you adapt how those choices look to the data in the model using cell renderers, exactly like you would in a tree view. this is possible because ComboBox implements the Gtk2::CellLayout interface. and ngl, 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 that tree structure. it's giving range. 🌈

in addition to the model-view API, ComboBox also offers a simple API that's perfect for text-only combo boxes and hides all the complexity of managing data in a model. it consists of the methods new_text, append_text, insert_text, prepend_text, remove_text and get_active_text. periodt. 💅

👑 HIERARCHY 👑

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

look at that lineage. generational talent fr fr. 🧚

💜 INTERFACES 💜

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

🔥 METHODS 🔥

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

  • $model — a Gtk2::TreeModel (optional, defaults to undef)

widget = Gtk2::ComboBox->new_text

no args, no stress, just vibes 🎀

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

  • $model — a Gtk2::TreeModel (optional, defaults to undef)

integer = $combo_box->get_active

treeiter = $combo_box->get_active_iter

$combo_box->set_active_iter ($iter)

  • $iter — a 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 — a 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 — a Gtk2::TreeModel or undef
lowkey important: 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 (optional, defaults to undef)

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 / static-nick / static-blurb) — the item which is currently active ✨
  • 'add-tearoffs' (boolean : default false : readable / writable / private / static-nick / static-blurb) — whether dropdowns should have a tearoff menu item
  • 'button-sensitivity' (Gtk2::SensitivityType : default "auto" : readable / writable / private / static-nick / static-blurb) — whether the dropdown button is sensitive when the model is empty
  • 'column-span-column' (integer : default -1 : readable / writable / private / static-nick / static-blurb) — TreeModel column containing the column span values
  • 'entry-text-column' (integer : default -1 : readable / writable / private / static-nick / static-blurb) — 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 / static-nick / static-blurb) — whether the combo box grabs focus when it is clicked with the mouse
  • 'has-entry' (boolean : default false : readable / writable / construct-only / private / static-nick / static-blurb) — whether combo box has an entry
  • 'has-frame' (boolean : default true : readable / writable / private / static-nick / static-blurb) — whether the combo box draws a frame around the child
  • 'model' (Gtk2::TreeModel : default undef : readable / writable / private / static-nick / static-blurb) — the model for the combo box
  • 'popup-shown' (boolean : default false : readable / private / static-nick / static-blurb) — whether the combo's dropdown is shown
  • 'row-span-column' (integer : default -1 : readable / writable / private / static-nick / static-blurb) — TreeModel column containing the row span values
  • 'tearoff-title' (string : default undef : readable / writable / private / static-nick / static-blurb) — a title that may be displayed by the window manager when the popup is torn-off
  • 'wrap-width' (integer : default 0 : readable / writable / private / static-nick / static-blurb) — wrap width for laying out the items in a grid

💅 STYLE PROPERTIES 💅

  • 'appears-as-list' (boolean : default false : readable / private / static-nick / static-blurb) — whether dropdowns should look like lists rather than menus
  • 'arrow-size' (integer : default 15 : readable / private / static-nick / static-blurb) — the minimum size of the arrow in the combo box
  • 'shadow-type' (Gtk2::ShadowType : default "none" : readable / private / static-nick / static-blurb) — 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

go read the whole family, iykyk 💖

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

this software is licensed under the LGPL. see Gtk2 for a full notice.

and that's the whole page bestie 🎀 no cap, every last detail, all of it. this came out of perl v5.42.0, dated 2025-07-25 — Gtk2::ComboBox(3), user contributed perl documentation, and you're officially obsessed now. slay. 👑✨

📦 where this page comes from