org.gnome.gtk

## Class ComboBox

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.Widget
        - - org.gnome.gtk.Container
          - - org.gnome.gtk.Bin
            - - org.gnome.gtk.ComboBox

- All Implemented Interfaces:
    CellEditable, CellLayout
  Direct Known Subclasses:
    ComboBoxText

      public class ComboBox
      extends Bin
      implements CellEditable, CellLayout

  A Widget used to choose from a list of items.

  Internally, ComboBox uses a TreeModel to store the items, giving you the same MVC power of GTK's TreeView/TreeModel system. There is also an alternative API which can be used to create and manipulate ComboBoxes which are comprised only of text. If that is your requirement, see `TextComboBox`.

  ComboBox is a CellLayout, that is, it possesses many of the same aspects as a TreeViewColumn, and, along with being backed by a TreeModel, is used in much the same way as a TreeView: create a ListStore or TreeStore then build the GUI side by creating CellRenderers against the ComboBox.

  An abbreviated example of using this follows; assuming a ListStore `model` with at least DataColumnString `column` in it,

       combo = new ComboBox(model);
       renderer = new CellRendererText(combo);
       renderer.setText(column);

  and that's it. While conceptually straight forward, it turns out to be a lot of work if all you're doing is a single column of DataColumnString. But the ability to also have a DataColumnReference in your model means you can get a link back the object that is being represented by the "mere" text label being displayed to the user, and this can be very powerful. Likewise, you can build ComboBoxes with more complicated layouts, for example having with several verticals of text and perhaps an image packed into the ComboBox as well. Finally, don't forget that you can use several different views against one TreeModel, so a TreeModel that is in use somewhere else in your app can also be the source data for your ComboBox.

  The underlying `GtkComboBox` is actually presents two different APIs that are essentially mutually exclusive, which is why we have split this into two public classes.

  Since:
    4.0.3
  Author:
    Sebastian Mancke, Andrew Cowie

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `ComboBox.Changed` This signal emitted whenever a different item is selected by the user.

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.Widget

      `Widget.ButtonPressEvent, Widget.ButtonReleaseEvent, Widget.Destroy, Widget.Draw, Widget.EnterNotifyEvent, Widget.FocusInEvent, Widget.FocusOutEvent, Widget.Hide, Widget.KeyPressEvent, Widget.KeyReleaseEvent, Widget.LeaveNotifyEvent, Widget.MapEvent, Widget.MotionNotifyEvent, Widget.PopupMenu, Widget.ScrollEvent, Widget.SizeAllocate, Widget.UnmapEvent, Widget.VisibilityNotifyEvent`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ComboBox(TreeModel model)` Construct a new full-power TreeModel-backed ComboBox.
    `ComboBox(TreeModel model, Entry entry)` Construct a new full-power TreeModel-backed ComboBox which also has a supporting Entry.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connect(ComboBox.Changed handler)` Hook up a `ComboBox.Changed` handler to the Widget.
    `int` | `getActive()` Returns the index of the active item in the ComboBox.
    `TreeIter` | `getActiveIter()` Get a TreeIter pointing at the currently selected row.
    `void` | `popdown()` Programmatically tell the ComboBox popup to go away.
    `void` | `popup()` Cause the popup part of the ComboBox to raise and present itself.
    `void` | `setActive(int active)` Change the active item within this ComboBox to be the one at the supplied index.
    `void` | `setActiveIter(TreeIter row)` Set the ComboBox to be pointing at the row nominated by the TreeIter argument.
    `void` | `setModel(TreeModel model)` Set or change the TreeModel from which this ComboBox draws its data.

    - ### Methods inherited from class org.gnome.gtk.Bin

      `getChild`

    - ### Methods inherited from class org.gnome.gtk.Container

      `add, getChildren, remove, setBorderWidth`

    - ### Methods inherited from class org.gnome.gtk.Widget

      `activate, addEvents, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, destroy, getAllocatedHeight, getAllocatedWidth, getAllocation, getCanDefault, getCanFocus, getHasFocus, getName, getParent, getPreferredHeightForWidthMinimum, getPreferredHeightForWidthNatural, getPreferredHeightMinimum, getPreferredHeightNatural, getPreferredWidthForHeightMinimum, getPreferredWidthForHeightNatural, getPreferredWidthMinimum, getPreferredWidthNatural, getRequestMode, getRequisition, getSensitive, getStyleContext, getToplevel, getWindow, grabAdd, grabDefault, grabFocus, grabRemove, hide, isSensitive, overrideBackground, overrideColor, overrideFont, queueDraw, queueDrawArea, realize, setAlignHorizontal, setAlignVertical, setCanDefault, setCanFocus, setEvents, setExpandHorizontal, setExpandVertical, setName, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText, show, showAll`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ComboBox

          public ComboBox(TreeModel model)

      Construct a new full-power TreeModel-backed ComboBox.

      If subclassing ComboBox, use the `protected` `<init>()` no-arg constructor and then set the Model later with `setModel()`.

      Since:
        4.0.3

    - #### ComboBox

          public ComboBox(TreeModel model,
                  Entry entry)

      Construct a new full-power TreeModel-backed ComboBox which also has a supporting Entry.
      Since:
        4.1.1

  - ### Method Detail

    - #### connect

          public void connect(ComboBox.Changed handler)

      Hook up a `ComboBox.Changed` handler to the Widget. since 4.0.3

    - #### getActive

          public int getActive()

      Returns the index of the active item in the ComboBox. This counts from a zero origin, so a return value of `2` means the third item in the list is currently the active item.

      This will return `-1` if there is no active item.

      Since:
        4.0.6

    - #### getActiveIter

          public TreeIter getActiveIter()

      Get a TreeIter pointing at the currently selected row. If no row is currently active then `null` will be returned.
      Since:
        4.0.6

    - #### popdown

          public void popdown()

      Programmatically tell the ComboBox popup to go away.
      Since:
        4.0.14

    - #### popup

          public void popup()

      Cause the popup part of the ComboBox to raise and present itself. You don't tend to need this (after all it's the user who clicks on the ComboBox to cause the popup to present). The ComboBox must already have been realized to the screen before you will be able to use this.
      Since:
        4.0.6

    - #### setActive

          public void setActive(int active)

      Change the active item within this ComboBox to be the one at the supplied index. Items are numbered from `0`.
      Since:
        4.0.6

    - #### setActiveIter

          public void setActiveIter(TreeIter row)

      Set the ComboBox to be pointing at the row nominated by the TreeIter argument.
      Since:
        4.0.6

    - #### setModel

          public void setModel(TreeModel model)

      Set or change the TreeModel from which this ComboBox draws its data.
      Since:
        4.0.6