Gtk2::ComboBox(3)

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 / 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

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

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