libgtk2-perl-doc 2:1.2499-1 / usr / share / perl5 / Gtk2 / ComboBox.pod

=head1 NAME

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

=cut

=for position SYNOPSIS

=head1 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;

=cut



=for position DESCRIPTION

=head1 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 C<new_text>, C<append_text>,
C<insert_text>, C<prepend_text>, C<remove_text> and C<get_active_text>.

=cut



=head1 HIERARCHY

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



=cut

=head1 INTERFACES

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



=cut

=for object Gtk2::ComboBox - A widget used to choose from a list of items

=cut




=head1 METHODS

=head2 widget = Gtk2::ComboBox-E<gt>B<new> ($model=undef)

=over

=item * $model (Gtk2::TreeModel) 

=back

=head2 widget = Gtk2::ComboBox-E<gt>B<new_text> 

=head2 widget = Gtk2::ComboBox-E<gt>B<new_with_model> ($model=undef)

=over

=item * $model (Gtk2::TreeModel) 

=back

=head2 integer = $combo_box-E<gt>B<get_active> 

=head2 treeiter = $combo_box-E<gt>B<get_active_iter> 

=head2 $combo_box-E<gt>B<set_active_iter> ($iter)

=over

=item * $iter (Gtk2::TreeIter or undef) 

=back

=head2 $combo_box-E<gt>B<set_active> ($index)

=over

=item * $index (integer) 

=back

=head2 string = $combo_box-E<gt>B<get_active_text> 

Since: gtk+ 2.6

=head2 boolean = $combo_box-E<gt>B<get_add_tearoffs> 

Since: gtk+ 2.6

=head2 $combo_box-E<gt>B<set_add_tearoffs> ($add_tearoffs)

=over

=item * $add_tearoffs (boolean) 

=back

Since: gtk+ 2.6

=head2 $combo_box-E<gt>B<append_text> ($text)

=over

=item * $text (string) 

=back

=head2 sensitivitytype = $combo_box-E<gt>B<get_button_sensitivity> 

Since: gtk+ 2.14

=head2 $combo_box-E<gt>B<set_button_sensitivity> ($sensitivity)

=over

=item * $sensitivity (Gtk2::SensitivityType) 

=back

Since: gtk+ 2.14

=head2 integer = $combo_box-E<gt>B<get_column_span_column> 

Since: gtk+ 2.6

=head2 $combo_box-E<gt>B<set_column_span_column> ($column_span)

=over

=item * $column_span (integer) 

=back

=head2 boolean = $combo_box-E<gt>B<get_focus_on_click> 

Since: gtk+ 2.6

=head2 $combo_box-E<gt>B<set_focus_on_click> ($focus_on_click)

=over

=item * $focus_on_click (boolean) 

=back

Since: gtk+ 2.6

=head2 $combo_box-E<gt>B<insert_text> ($position, $text)

=over

=item * $position (integer) 

=item * $text (string) 

=back

=head2 treemodel = $combo_box-E<gt>B<get_model> 

=head2 $combo_box-E<gt>B<set_model> ($model)

=over

=item * $model (Gtk2::TreeModel or undef) 

=back

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

=head2 $combo_box-E<gt>B<popdown> 

=head2 $combo_box-E<gt>B<popup> 

=head2 $combo_box-E<gt>B<prepend_text> ($text)

=over

=item * $text (string) 

=back

=head2 $combo_box-E<gt>B<remove_text> ($position)

=over

=item * $position (integer) 

=back

=head2 $combo_box-E<gt>B<set_row_separator_func> ($func, $data=undef)

=over

=item * $func (scalar) 

=item * $data (scalar) 

=back

Since: gtk+ 2.6

=head2 integer = $combo_box-E<gt>B<get_row_span_column> 

Since: gtk+ 2.6

=head2 $combo_box-E<gt>B<set_row_span_column> ($row_span)

=over

=item * $row_span (integer) 

=back

=head2 string = $combo_box-E<gt>B<get_title> 

Since: gtk+ 2.10

=head2 $combo_box-E<gt>B<set_title> ($title)

=over

=item * $title (string) 

=back

Since: gtk+ 2.10

=head2 integer = $combo_box-E<gt>B<get_wrap_width> 

Since: gtk+ 2.6

=head2 $combo_box-E<gt>B<set_wrap_width> ($width)

=over

=item * $width (integer) 

=back



=cut


=head1 PROPERTIES

=over

=item 'active' (integer : default -1 : readable / writable / private)

The item which is currently active

=item 'add-tearoffs' (boolean : default false : readable / writable / private)

Whether dropdowns should have a tearoff menu item

=item 'button-sensitivity' (Gtk2::SensitivityType : default "auto" : readable / writable / private)

Whether the dropdown button is sensitive when the model is empty

=item 'column-span-column' (integer : default -1 : readable / writable / private)

TreeModel column containing the column span values

=item '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

=item 'focus-on-click' (boolean : default true : readable / writable / private)

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

=item 'has-entry' (boolean : default false : readable / writable / construct-only / private)

Whether combo box has an entry

=item 'has-frame' (boolean : default true : readable / writable / private)

Whether the combo box draws a frame around the child

=item 'model' (Gtk2::TreeModel : default undef : readable / writable / private)

The model for the combo box

=item 'popup-shown' (boolean : default false : readable / private)

Whether the combo's dropdown is shown

=item 'row-span-column' (integer : default -1 : readable / writable / private)

TreeModel column containing the row span values

=item 'tearoff-title' (string : default undef : readable / writable / private)

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

=item 'wrap-width' (integer : default 0 : readable / writable / private)

Wrap width for laying out the items in a grid

=back



=cut


=head1 STYLE PROPERTIES

=over

=item 'appears-as-list' (boolean : default false : readable / private)

Whether dropdowns should look like lists rather than menus

=item 'arrow-size' (integer : default 15 : readable / private)

The minimum size of the arrow in the combo box

=item 'shadow-type' (Gtk2::ShadowType : default "none" : readable / private)

Which kind of shadow to draw around the combo box

=back



=cut


=head1 SIGNALS

=over

=item B<changed> (Gtk2::ComboBox)

=item B<move-active> (Gtk2::ComboBox, Gtk2::ScrollType)

=item boolean = B<popdown> (Gtk2::ComboBox)

=item B<popup> (Gtk2::ComboBox)

=back



=cut


=head1 ENUMS AND FLAGS

=head2 enum Gtk2::ScrollType

=over

=item * 'none' / 'GTK_SCROLL_NONE'

=item * 'jump' / 'GTK_SCROLL_JUMP'

=item * 'step-backward' / 'GTK_SCROLL_STEP_BACKWARD'

=item * 'step-forward' / 'GTK_SCROLL_STEP_FORWARD'

=item * 'page-backward' / 'GTK_SCROLL_PAGE_BACKWARD'

=item * 'page-forward' / 'GTK_SCROLL_PAGE_FORWARD'

=item * 'step-up' / 'GTK_SCROLL_STEP_UP'

=item * 'step-down' / 'GTK_SCROLL_STEP_DOWN'

=item * 'page-up' / 'GTK_SCROLL_PAGE_UP'

=item * 'page-down' / 'GTK_SCROLL_PAGE_DOWN'

=item * 'step-left' / 'GTK_SCROLL_STEP_LEFT'

=item * 'step-right' / 'GTK_SCROLL_STEP_RIGHT'

=item * 'page-left' / 'GTK_SCROLL_PAGE_LEFT'

=item * 'page-right' / 'GTK_SCROLL_PAGE_RIGHT'

=item * 'start' / 'GTK_SCROLL_START'

=item * 'end' / 'GTK_SCROLL_END'

=back


=head2 enum Gtk2::SensitivityType

=over

=item * 'auto' / 'GTK_SENSITIVITY_AUTO'

=item * 'on' / 'GTK_SENSITIVITY_ON'

=item * 'off' / 'GTK_SENSITIVITY_OFF'

=back




=cut


=head1 SEE ALSO

L<Gtk2>, L<Glib::Object>, L<Glib::InitiallyUnowned>, L<Gtk2::Object>, L<Gtk2::Widget>, L<Gtk2::Container>, L<Gtk2::Bin>


=cut


=head1 COPYRIGHT

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

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



=cut