Class DropDown

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.DropDown
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Proxy
@Generated("org.javagi.JavaGI") public class DropDown extends Widget implements Accessible, Buildable, ConstraintTarget

Allows the user to choose an item from a list of options.

An example GtkDropDown

The GtkDropDown displays the Gtk.DropDown:selected choice.

The options are given to GtkDropDown in the form of GListModel and how the individual options are represented is determined by a ListItemFactory. The default factory displays simple strings, and adds a checkmark to the selected item in the popup.

To set your own factory, use setFactory(ListItemFactory). It is possible to use a separate factory for the items in the popup, with setListFactory(ListItemFactory).

GtkDropDown knows how to obtain strings from the items in a StringList; for other models, you have to provide an expression to find the strings via setExpression(Expression).

GtkDropDown can optionally allow search in the popup, which is useful if the list of options is long. To enable the search entry, use setEnableSearch(boolean).

Here is a UI definition example for GtkDropDown with a simple model:

<object class="GtkDropDown">
  <property name="model">
    <object class="GtkStringList">
      <items>
        <item translatable="yes">Factory</item>
        <item translatable="yes">Home</item>
        <item translatable="yes">Subway</item>
      </items>
    </object>
  </property>
</object>

If a GtkDropDown is created in this manner, or with fromStrings(String[]), for instance, the object returned from getSelectedItem() will be a StringObject.

To learn more about the list widget framework, see the overview.

CSS nodes

GtkDropDown has a single CSS node with name dropdown, with the button and popover nodes as children.

Accessibility

GtkDropDown uses the Gtk.AccessibleRole.combo_box role.

  • Constructor Details

    • DropDown

      public DropDown(MemorySegment address)
      Create a DropDown instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • DropDown

      public DropDown(@Nullable ListModel model, @Nullable Expression expression)

      Creates a new GtkDropDown.

      You may want to call setFactory(ListItemFactory) to set up a way to map its items to widgets.

      Parameters:
      model - the model to use
      expression - the expression to use

    • DropDown

      public DropDown()
      Create a new DropDown.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the DropDown class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected DropDown asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • fromStrings

      public static DropDown fromStrings(@Nullable String @Nullable [] strings)
      Creates a new GtkDropDown that is populated with the strings.
      Parameters:
      strings - The strings to put in the dropdown
      Returns:
      a new GtkDropDown

    • getEnableSearch

      public boolean getEnableSearch()
      Returns whether search is enabled.
      Returns:
      true if the popup includes a search entry

    • getExpression

      public @Nullable Expression getExpression()

      Gets the expression set that is used to obtain strings from items.

      See setExpression(Expression).

      Returns:
      a GtkExpression

    • getFactory

      public @Nullable ListItemFactory getFactory()

      Gets the factory that's currently used to populate list items.

      The factory returned by this function is always used for the item in the button. It is also used for items in the popup if Gtk.DropDown:list-factory is not set.

      Returns:
      The factory in use

    • getHeaderFactory

      public @Nullable ListItemFactory getHeaderFactory()
      Gets the factory that's currently used to create header widgets for the popup.
      Returns:
      The factory in use
      Since:
      4.12

    • getListFactory

      public @Nullable ListItemFactory getListFactory()
      Gets the factory that's currently used to populate list items in the popup.
      Returns:
      The factory in use

    • getModel

      public @Nullable ListModel getModel()
      Gets the model that provides the displayed items.
      Returns:
      The model in use

    • getSearchMatchMode

      public StringFilterMatchMode getSearchMatchMode()
      Returns the match mode that the search filter is using.
      Returns:
      the match mode of the search filter
      Since:
      4.12

    • getSelected

      public int getSelected()
      Gets the position of the selected item.
      Returns:
      the position of the selected item, or GTK_INVALID_LIST_POSITION if no item is selected

    • getSelectedItem

      public @Nullable GObject getSelectedItem()
      Gets the selected item. If no item is selected, null is returned.
      Returns:
      The selected item

    • getShowArrow

      public boolean getShowArrow()
      Returns whether to show an arrow within the widget.
      Returns:
      true if an arrow will be shown.
      Since:
      4.6

    • setEnableSearch

      public void setEnableSearch(boolean enableSearch)

      Sets whether a search entry will be shown in the popup that allows to search for items in the list.

      Note that Gtk.DropDown:expression must be set for search to work.

      Parameters:
      enableSearch - whether to enable search

    • setExpression

      public void setExpression(@Nullable Expression expression)

      Sets the expression that gets evaluated to obtain strings from items.

      This is used for search in the popup. The expression must have a value type of G_TYPE_STRING.

      Parameters:
      expression - a GtkExpression

    • setFactory

      public void setFactory(@Nullable ListItemFactory factory)
      Sets the GtkListItemFactory to use for populating list items.
      Parameters:
      factory - the factory to use

    • setHeaderFactory

      public void setHeaderFactory(@Nullable ListItemFactory factory)
      Sets the GtkListItemFactory to use for creating header widgets for the popup.
      Parameters:
      factory - the factory to use
      Since:
      4.12

    • setListFactory

      public void setListFactory(@Nullable ListItemFactory factory)
      Sets the GtkListItemFactory to use for populating list items in the popup.
      Parameters:
      factory - the factory to use

    • setModel

      public void setModel(@Nullable ListModel model)
      Sets the GListModel to use.
      Parameters:
      model - the model to use

    • setSearchMatchMode

      public void setSearchMatchMode(StringFilterMatchMode searchMatchMode)
      Sets the match mode for the search filter.
      Parameters:
      searchMatchMode - the new match mode
      Since:
      4.12

    • setSelected

      public void setSelected(int position)
      Selects the item at the given position.
      Parameters:
      position - the position of the item to select, or GTK_INVALID_LIST_POSITION

    • setShowArrow

      public void setShowArrow(boolean showArrow)
      Sets whether an arrow will be displayed within the widget.
      Parameters:
      showArrow - whether to show an arrow within the widget
      Since:
      4.6

    • onActivate

      public SignalConnection<DropDown.ActivateCallback> onActivate(DropDown.ActivateCallback handler)

      Emitted to when the drop down is activated.

      The ::activate signal on GtkDropDown is an action signal and emitting it causes the drop down to pop up its dropdown.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      4.6
      See Also:

    • emitActivate

      public void emitActivate()
      Emits the "activate" signal. See onActivate(DropDown.ActivateCallback).

    • builder

      public static DropDown.Builder<? extends DropDown.Builder> builder()
      A DropDown.Builder object constructs a DropDown with the specified properties. Use the various set...() methods to set properties, and finish construction with DropDown.Builder.build().
      Returns:
      the builder object