Package ch.bailu.gtk.gtk

Class ComboBox

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.gobject.Object
ch.bailu.gtk.gobject.InitiallyUnowned
ch.bailu.gtk.gtk.Widget
ch.bailu.gtk.gtk.ComboBox
All Implemented Interfaces:
PointerInterface
Direct Known Subclasses:
ComboBoxText
public class ComboBox extends Widget
A `GtkComboBox` is a widget that allows the user to choose from a list of
valid choices.

![An example GtkComboBox](combo-box.png)

The `GtkComboBox` displays the selected choice; when activated, the
`GtkComboBox` displays a popup which allows the user to make a new choice.

The `GtkComboBox` 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 `GtkComboBox` implements the
[iface@Gtk.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.

To allow the user to enter values not in the model, the
[property@Gtk.ComboBox:has-entry] property allows the `GtkComboBox` to
contain a [class@Gtk.Entry]. This entry can be accessed by calling
[method@Gtk.ComboBox.get_child] on the combo box.

For a simple list of textual choices, the model-view API of `GtkComboBox`
can be a bit overwhelming. In this case, [class@Gtk.ComboBoxText] offers
a simple alternative. Both `GtkComboBox` and `GtkComboBoxText` can contain
an entry.

## CSS nodes

```
combobox
├── box.linked
│ ╰── button.combo
│ ╰── box
│ ├── cellview
│ ╰── arrow
╰── window.popup
```

A normal combobox contains a box with the .linked class, a button
with the .combo class and inside those buttons, there are a cellview and
an arrow.

```
combobox
├── box.linked
│ ├── entry.combo
│ ╰── button.combo
│ ╰── box
│ ╰── arrow
╰── window.popup
```

A `GtkComboBox` with an entry has a single CSS node with name combobox.
It contains a box with the .linked class. That box contains an entry and
a button, both with the .combo class added. The button also contains another
node with name arrow.

# Accessibility

`GtkComboBox` uses the %GTK_ACCESSIBLE_ROLE_COMBO_BOX role.

https://docs.gtk.org/gtk4/class.ComboBox.html

  • Field Details

  • Constructor Details

    • ComboBox

      public ComboBox(PointerContainer pointer)

    • ComboBox

      public ComboBox()
      Creates a new empty `GtkComboBox`.

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • newWithEntryComboBox

      public static ComboBox newWithEntryComboBox()
      Creates a new empty `GtkComboBox` with an entry.

      In order to use a combo box with entry, you need to tell it
      which column of the model contains the text for the entry
      by calling [method@Gtk.ComboBox.set_entry_text_column].
      Returns:
      A new `GtkComboBox`

    • newWithModelComboBox

      public static ComboBox newWithModelComboBox(@Nonnull TreeModel model)
      Creates a new `GtkComboBox` with a model.
      Parameters:
      model - a `GtkTreeModel`
      Returns:
      A new `GtkComboBox`

    • newWithModelAndEntryComboBox

      public static ComboBox newWithModelAndEntryComboBox(@Nonnull TreeModel model)
      Creates a new empty `GtkComboBox` with an entry and a model.

      See also [ctor@Gtk.ComboBox.new_with_entry].
      Parameters:
      model - A `GtkTreeModel`
      Returns:
      A new `GtkComboBox`

    • getActive

      public int getActive()
      Returns the index of the currently active item.

      If the model is a non-flat treemodel, and the active item is not
      an immediate child of the root of the tree, this function returns
      `gtk_tree_path_get_indices (path)[0]`, where `path` is the
      [struct@Gtk.TreePath] of the active item.
      Returns:
      An integer which is the index of the currently active item, or -1 if there’s no active item

    • getActiveId

      public Str getActiveId()
      Returns the ID of the active row of @combo_box.

      This value is taken from the active row and the column specified
      by the [property@Gtk.ComboBox:id-column] property of @combo_box
      (see [method@Gtk.ComboBox.set_id_column]).

      The returned value is an interned string which means that you can
      compare the pointer by value to other interned strings and that you
      must not free it.

      If the [property@Gtk.ComboBox:id-column] property of @combo_box is
      not set, or if no row is active, or if the active row has a %NULL
      ID value, then %NULL is returned.
      Returns:
      the ID of the active row

    • getActiveIter

      public boolean getActiveIter(@Nonnull TreeIter iter)
      Sets @iter to point to the currently active item.

      If no item is active, @iter is left unchanged.
      Parameters:
      iter - A `GtkTreeIter`
      Returns:
      %TRUE if @iter was set, %FALSE otherwise

    • getButtonSensitivity

      public int getButtonSensitivity()
      Returns whether the combo box sets the dropdown button
      sensitive or not when there are no items in the model.
      Returns:
      %GTK_SENSITIVITY_ON if the dropdown button is sensitive when the model is empty, %GTK_SENSITIVITY_OFF if the button is always insensitive or %GTK_SENSITIVITY_AUTO if it is only sensitive as long as the model has one item to be selected.

    • getChild

      public Widget getChild()
      Gets the child widget of @combo_box.
      Returns:
      the child widget of @combo_box

    • getEntryTextColumn

      public int getEntryTextColumn()
      Returns the column which @combo_box is using to get the strings
      from to display in the internal entry.
      Returns:
      A column in the data source model of @combo_box.

    • getHasEntry

      public boolean getHasEntry()
      Returns whether the combo box has an entry.
      Returns:
      whether there is an entry in @combo_box.

    • getIdColumn

      public int getIdColumn()
      Returns the column which @combo_box is using to get string IDs
      for values from.
      Returns:
      A column in the data source model of @combo_box.

    • getModel

      public TreeModel getModel()
      Returns the `GtkTreeModel` of @combo_box.
      Returns:
      A `GtkTreeModel` which was passed during construction.

    • getPopupFixedWidth

      public boolean getPopupFixedWidth()
      Gets whether the popup uses a fixed width.
      Returns:
      %TRUE if the popup uses a fixed width

    • popdown

      public void popdown()
      Hides the menu or dropdown list of @combo_box.

      This function is mostly intended for use by accessibility technologies;
      applications should have little use for it.

    • popup

      public void popup()
      Pops up the menu or dropdown list of @combo_box.

      This function is mostly intended for use by accessibility technologies;
      applications should have little use for it.

      Before calling this, @combo_box must be mapped, or nothing will happen.

    • popupForDevice

      public void popupForDevice(@Nonnull Device device)
      Pops up the menu of @combo_box.

      Note that currently this does not do anything with the device, as it was
      previously only used for list-mode combo boxes, and those were removed
      in GTK 4. However, it is retained in case similar functionality is added
      back later.
      Parameters:
      device - a `GdkDevice`

    • setActive

      public void setActive(int index_)
      Sets the active item of @combo_box to be the item at @index.
      Parameters:
      index_ - An index in the model passed during construction, or -1 to have no active item

    • setActiveId

      public boolean setActiveId(@Nullable Str active_id)
      Changes the active row of @combo_box to the one that has an ID equal to
      @active_id.

      If @active_id is %NULL, the active row is unset. Rows having
      a %NULL ID string cannot be made active by this function.

      If the [property@Gtk.ComboBox:id-column] property of @combo_box is
      unset or if no row has the given ID then the function does nothing
      and returns %FALSE.
      Parameters:
      active_id - the ID of the row to select
      Returns:
      %TRUE if a row with a matching ID was found. If a %NULL @active_id was given to unset the active row, the function always returns %TRUE.

    • setActiveId

      public boolean setActiveId(String active_id)
      Changes the active row of @combo_box to the one that has an ID equal to
      @active_id.

      If @active_id is %NULL, the active row is unset. Rows having
      a %NULL ID string cannot be made active by this function.

      If the [property@Gtk.ComboBox:id-column] property of @combo_box is
      unset or if no row has the given ID then the function does nothing
      and returns %FALSE.
      Parameters:
      active_id - the ID of the row to select
      Returns:
      %TRUE if a row with a matching ID was found. If a %NULL @active_id was given to unset the active row, the function always returns %TRUE.

    • setActiveIter

      public void setActiveIter(@Nullable TreeIter iter)
      Sets the current active item to be the one referenced by @iter.

      If @iter is %NULL, the active item is unset.
      Parameters:
      iter - The `GtkTreeIter`

    • setButtonSensitivity

      public void setButtonSensitivity(int sensitivity)
      Sets whether the dropdown button of the combo box should update
      its sensitivity depending on the model contents.
      Parameters:
      sensitivity - specify the sensitivity of the dropdown button

    • setChild

      public void setChild(@Nullable Widget child)
      Sets the child widget of @combo_box.
      Parameters:
      child - the child widget

    • setEntryTextColumn

      public void setEntryTextColumn(int text_column)
      Sets the model column which @combo_box should use to get strings
      from to be @text_column.

      For this column no separate
      [class@Gtk.CellRenderer] is needed.

      The column @text_column in the model of @combo_box must be of
      type %G_TYPE_STRING.

      This is only relevant if @combo_box has been created with
      [property@Gtk.ComboBox:has-entry] as %TRUE.
      Parameters:
      text_column - A column in @model to get the strings from for the internal entry

    • setIdColumn

      public void setIdColumn(int id_column)
      Sets the model column which @combo_box should use to get string IDs
      for values from.

      The column @id_column in the model of @combo_box must be of type
      %G_TYPE_STRING.
      Parameters:
      id_column - A column in @model to get string IDs for values from

    • setModel

      public void setModel(@Nullable TreeModel model)
      Sets the model used by @combo_box to be @model.

      Will unset a previously set model (if applicable). If model is %NULL,
      then it will unset the model.

      Note that this function does not clear the cell renderers, you have to
      call [method@Gtk.CellLayout.clear] yourself if you need to set up different
      cell renderers for the new model.
      Parameters:
      model - A `GtkTreeModel`

    • setPopupFixedWidth

      public void setPopupFixedWidth(boolean fixed)
      Specifies whether the popup’s width should be a fixed width.

      If @fixed is %TRUE, the popup's width is set to match the
      allocated width of the combo box.
      Parameters:
      fixed - whether to use a fixed popup width

    • setRowSeparatorFunc

      public void setRowSeparatorFunc(ComboBox.OnTreeViewRowSeparatorFunc func, @Nullable Pointer data, ComboBox.OnDestroyNotify destroy)
      Sets the row separator function, which is used to determine
      whether a row should be drawn as a separator.

      If the row separator function is %NULL, no separators are drawn.
      This is the default value.
      Parameters:
      func - a `GtkTreeViewRowSeparatorFunc`
      data - user data to pass to @func
      destroy - destroy notifier for @data

    • onActivate

      public SignalHandler onActivate(ComboBox.OnActivate signal)
      Connect to signal "activate".
      See ComboBox.OnActivate.onActivate() for signal description.
      Field SIGNAL_ON_ACTIVATE contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onChanged

      public SignalHandler onChanged(ComboBox.OnChanged signal)
      Connect to signal "changed".
      See ComboBox.OnChanged.onChanged() for signal description.
      Field SIGNAL_ON_CHANGED contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onFormatEntryText

      public SignalHandler onFormatEntryText(ComboBox.OnFormatEntryText signal)
      Connect to signal "format-entry-text".
      See ComboBox.OnFormatEntryText.onFormatEntryText(ch.bailu.gtk.type.Str) for signal description.
      Field SIGNAL_ON_FORMAT_ENTRY_TEXT contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onMoveActive

      public SignalHandler onMoveActive(ComboBox.OnMoveActive signal)
      Connect to signal "move-active".
      See ComboBox.OnMoveActive.onMoveActive(int) for signal description.
      Field SIGNAL_ON_MOVE_ACTIVE contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onPopdown

      public SignalHandler onPopdown(ComboBox.OnPopdown signal)
      Connect to signal "popdown".
      See ComboBox.OnPopdown.onPopdown() for signal description.
      Field SIGNAL_ON_POPDOWN contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onPopup

      public SignalHandler onPopup(ComboBox.OnPopup signal)
      Connect to signal "popup".
      See ComboBox.OnPopup.onPopup() for signal description.
      Field SIGNAL_ON_POPUP contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • asAccessible

      public Accessible asAccessible()
      Implements interface Accessible. Call this to get access to interface functions.
      Overrides:
      asAccessible in class Widget
      Returns:
      Accessible

    • asBuildable

      public Buildable asBuildable()
      Implements interface Buildable. Call this to get access to interface functions.
      Overrides:
      asBuildable in class Widget
      Returns:
      Buildable

    • asCellEditable

      public CellEditable asCellEditable()
      Implements interface CellEditable. Call this to get access to interface functions.
      Returns:
      CellEditable

    • asCellLayout

      public CellLayout asCellLayout()
      Implements interface CellLayout. Call this to get access to interface functions.
      Returns:
      CellLayout

    • asConstraintTarget

      public ConstraintTarget asConstraintTarget()
      Implements interface ConstraintTarget. Call this to get access to interface functions.
      Overrides:
      asConstraintTarget in class Widget
      Returns:
      ConstraintTarget

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()