About all my projects
Gnome::Gtk4::ComboBox

Gnome::Gtk4::ComboBox

Description

A Gnome::Gtk4::ComboBox is a widget that allows the user to choose from a list of valid choices.

No caption

The Gnome::Gtk4::ComboBox displays the selected choice; when activated, the Gnome::Gtk4::ComboBox displays a popup which allows the user to make a new choice.

The Gnome::Gtk4::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 Gnome::Gtk4::ComboBox implements the Gnome::Gtk4::R-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 has-entry property allows the Gnome::Gtk4::ComboBox to contain a Gnome::Gtk4::Entry. This entry can be accessed by calling .get-child() on the combo box.

For a simple list of textual choices, the model-view API of Gnome::Gtk4::ComboBox can be a bit overwhelming. In this case, Gnome::Gtk4::ComboBoxText offers a simple alternative. Both Gnome::Gtk4::ComboBox and Gnome::Gtk4::ComboBoxText can contain an entry.

CSS nodes

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.

A Gnome::Gtk4::ComboBox 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

Gnome::Gtk4::ComboBox uses the GTK_ACCESSIBLE_ROLE_COMBO_BOX role.

Class initialization

Note: The native version of this class is deprecated in gtk4-lib() since version 4.10

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-combobox

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Creates a new empty Gnome::Gtk4::ComboBox.

method new-combobox ( --> Gnome::Gtk4::ComboBox \)

new-with-entry

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Creates a new empty Gnome::Gtk4::ComboBox 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 .set-entry-text-column().

method new-with-entry ( --> Gnome::Gtk4::ComboBox \)

new-with-model

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Creates a new Gnome::Gtk4::ComboBox with a model.

method new-with-model ( N-Object() $model --> Gnome::Gtk4::ComboBox \)

  • $model; a Gnome::Gtk4::R-TreeModel.

new-with-model-and-entry

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Creates a new empty Gnome::Gtk4::ComboBox with an entry and a model.

See also .new-with-entry().

method new-with-model-and-entry ( N-Object() $model --> Gnome::Gtk4::ComboBox \)

  • $model; A Gnome::Gtk4::R-TreeModel.

Methods

get-active

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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 Gnome::Gtk4::N-TreePath of the active item.

method get-active (--> Int )

Return value; An integer which is the index of the currently active item, or -1 if there’s no active item.

get-active-id

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Returns the ID of the active row of $combo-box.

This value is taken from the active row and the column specified by the id-column property of $combo-box (see .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 id-column property of $combo-box is not set, or if no row is active, or if the active row has a undefined ID value, then undefined is returned.

method get-active-id (--> Str )

Return value; the ID of the active row.

get-active-iter

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets $iter to point to the currently active item.

If no item is active, $iter is left unchanged.

method get-active-iter ( N-Object $iter --> Bool )

  • $iter; A Gnome::Gtk4::N-TreeIter

Return value; True if $iter was set, False otherwise.

get-button-sensitivity

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model.

method get-button-sensitivity (--> GtkSensitivityType )

Return value; 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..

get-child

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Gets the child widget of $combo-box.

method get-child (--> N-Object )

Return value; the child widget of $combo-box.

get-entry-text-column

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Returns the column which $combo-box is using to get the strings from to display in the internal entry.

method get-entry-text-column (--> Int )

Return value; A column in the data source model of $combo-box..

get-has-entry

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Returns whether the combo box has an entry.

method get-has-entry (--> Bool )

Return value; whether there is an entry in $combo-box..

get-id-column

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Returns the column which $combo-box is using to get string IDs for values from.

method get-id-column (--> Int )

Return value; A column in the data source model of $combo-box..

get-model

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Returns the Gnome::Gtk4::R-TreeModel of $combo-box.

method get-model (--> N-Object )

Return value; A Gnome::Gtk4::R-TreeModel which was passed during construction..

get-popup-fixed-width

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Gets whether the popup uses a fixed width.

method get-popup-fixed-width (--> Bool )

Return value; True if the popup uses a fixed width.

get-row-separator-func

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Returns the current row separator function.

method get-row-separator-func (-->  )

Return value; the current row separator function..

popdown

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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.

method popdown ( )

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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.

method popup ( )

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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.

method popup-for-device ( N-Object() $device )

  • $device; a Gnome::Gdk4::Device.

set-active

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets the active item of $combo-box to be the item at $index.

method set-active ( Int() $index )

  • $index; An index in the model passed during construction, or -1 to have no active item.

set-active-id

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Changes the active row of $combo-box to the one that has an ID equal to $active-id.

If $active-id is undefined, the active row is unset. Rows having a undefined ID string cannot be made active by this function.

If the id-column property of $combo-box is unset or if no row has the given ID then the function does nothing and returns False.

method set-active-id ( Str $active-id --> Bool )

  • $active-id; the ID of the row to select.

Return value; True if a row with a matching ID was found. If a undefined $active-id was given to unset the active row, the function always returns True..

set-active-iter

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets the current active item to be the one referenced by $iter.

If $iter is undefined, the active item is unset.

method set-active-iter ( N-Object $iter )

  • $iter; The Gnome::Gtk4::N-TreeIter

set-button-sensitivity

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets whether the dropdown button of the combo box should update its sensitivity depending on the model contents.

method set-button-sensitivity ( GtkSensitivityType $sensitivity )

  • $sensitivity; specify the sensitivity of the dropdown button.

set-child

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets the child widget of $combo-box.

method set-child ( N-Object() $child )

  • $child; the child widget.

set-entry-text-column

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets the model column which $combo-box should use to get strings from to be $text-column.

For this column no separate Gnome::Gtk4::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 has-entry as True.

method set-entry-text-column ( Int() $text-column )

  • $text-column; A column in $model to get the strings from for the internal entry.

set-id-column

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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.

method set-id-column ( Int() $id-column )

  • $id-column; A column in $model to get string IDs for values from.

set-model

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

Sets the model used by $combo-box to be $model.

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

Note that this function does not clear the cell renderers, you have to call .clear() in class Gnome::Gtk4::R-CellLayout yourself if you need to set up different cell renderers for the new model.

method set-model ( N-Object() $model )

  • $model; A Gnome::Gtk4::R-TreeModel.

set-popup-fixed-width

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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.

method set-popup-fixed-width ( Bool() $fixed )

  • $fixed; whether to use a fixed popup width.

set-row-separator-func This function is not yet available

Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10

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 undefined, no separators are drawn. This is the default value.

method set-row-separator-func ( &func, gpointer $data, … )

  • &func; a Gnome::Gtk4::T-treeview. Tthe function must be specified with following signature; :( N-Object $model, N-Object $iter, gpointer $data -- gboolean )>.

  • $data; user data to pass to $func.

  • destroy; destroy notifier for $data. Note that each argument must be specified as a type followed by its value!

Signals

activate

Emitted to when the combo box is activated.

The `::activate` signal on Gnome::Gtk4::ComboBox is an action signal and emitting it causes the combo box to pop up its dropdown.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::ComboBox :$_widget,
  *C<user>-options
)

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::ComboBox object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

changed

Emitted when the active item is changed.

The can be due to the user selecting a different item from the list, or due to a call to .set-active-iter(). It will also be emitted while typing into the entry of a combo box with an entry.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::ComboBox :$_widget,
  *C<user>-options
)

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::ComboBox object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

format-entry-text

Emitted to allow changing how the text in a combo box's entry is displayed.

See has-entry.

Connect a signal handler which returns an allocated string representing $path. That string will then be used to set the text in the combo box's entry. The default signal handler uses the text from the entry-text-column model column.

Here's an example signal handler which fetches data from the model and displays it in the entry.

method handler (
  Str $path,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::ComboBox :$_widget,
  *C<user>-options
  --> Str
)

  • $path; the Gnome::Gtk4::N-TreePath string from the combo box's current model to format text for.

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::ComboBox object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value; (transfer ownership: full) a newly allocated string representing $path for the current Gnome::Gtk4::ComboBox model.

move-active

Emitted to move the active selection.

This is an [keybinding signal](class.SignalAction.html).

method handler (
   $scroll-type,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::ComboBox :$_widget,
  *C<user>-options
)

  • $scroll-type; a enumeration GtkScrollType defined in Gnome::Gtk4::T-enums.

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::ComboBox object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

popdown

Emitted to popdown the combo box list.

This is an [keybinding signal](class.SignalAction.html).

The default bindings for this signal are Alt+Up and Escape.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::ComboBox :$_widget,
  *C<user>-options
  --> gboolean
)

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::ComboBox object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value;

Emitted to popup the combo box list.

This is an [keybinding signal](class.SignalAction.html).

The default binding for this signal is Alt+Down.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::ComboBox :$_widget,
  *C<user>-options
)

  • $_handle_id; The registered event handler id.

  • $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::ComboBox object.

  • $_widget; The object which registered the signal. User code may have left the object going out of scope.

  • user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.