Class gtk-combo-box

Package: gtk

Superclasses

gtk-bin, gtk-container, gtk-widget, gtk-buildable, gtk-cell-editable, gtk-cell-layout, g-object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

gtk-app-chooser-button, gtk-combo-box-text

Direct Slots

active

The active property of type :int (Read / Write)
The item which is currently active. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this property has the value (first (gtk-tree-path-indices path)), where path is the gtk-tree-path instance of the active item.
Allowed values: >= -1
Default value: -1

active-id

The active-id property of type :string (Read / Write)
The value of the ID column of the active row.
Default value: nil

add-tearoffs

The add-tearoffs property of type :boolean (Read / Write)
Controls whether generated menus have tearoff menu items. Note that this only affects menu style combo boxes.
Warning: The add-tearoffs property has been deprecated since version 3.10 and should not be used in newly written code.
Default value: false

button-sensitivity

The button-sensitivity property of type gtk-sensitivity-type (Read / Write)
Whether the dropdown button is sensitive when the model is empty.
Default value: :auto

cell-area

The cell-area property of type gtk-cell-area (Read / Write / Construct)
The cell area used to layout cell renderers for this combo box. If no cell area is specified when creating the combo box with the function gtk-combo-box-new-with-area a horizontally oriented gtk-cell-area-box object will be used.

column-span-column

The column-span-column property of type :int (Read / Write)
If this is set to a non-negative value, it must be the index of a column of type "gint" in the model. The value in that column for each item will determine how many columns that item will span in the popup. Therefore, values in this column must be greater than zero, and the sum of an item’s column position + span should not exceed wrap-width.
Allowed values: >= -1
Default value: -1

entry-text-column

The entry-text-column property of type :int (Read / Write)
The column in the combo box's model to associate with strings from the entry if the combo was created with the value true for the has-entry property.
Allowed values: >= -1
Default value: -1

focus-on-click

The focus-on-click property of type :boolean (Read / Write)
Whether the combo box grabs focus when it is clicked with the mouse.
Default value: true

has-entry

The has-entry property of type :boolean (Read / Write / Construct)
Whether the combo box has an entry.
Default value: false

has-frame

The has-frame property of type :boolean (Read / Write)
Controls whether a frame is drawn around the entry.
Default value: true

id-column

The id-column property of type :int (Read / Write)
The column in the combo box's model that provides string IDs for the values in the model, if not equal to -1.
Allowed values: >= -1
Default value: -1

model

The model property of type gtk-tree-model (Read / Write)
The model from which the combo box takes the values shown in the list.

The popup-fixed-width property of type :boolean (Read / Write)
Whether the popup's width should be a fixed width matching the allocated width of the combo box.
Default value: true

The popup-shown property of type :boolean (Read)
Whether the combo boxes dropdown is popped up. Note that this property is mainly useful, because it allows you to connect to the "notify::popup-shown" signal.
Default value: false

row-span-column

The row-span-column property of type :int (Read / Write)
If this is set to a non-negative value, it must be the index of a column of type "gint" in the model. The values of that column are used to determine how many rows a value in the list will span. Therefore, the values in the model column pointed to by this property must be greater than zero and not larger than the wrap-width property.
Allowed values: >= -1
Default value: -1

tearoff-title

The tearoff-title property of type :string (Read / Write)
A title that may be displayed by the window manager when the popup is torn-off.
Warning: The tearoff-title property has been deprecated since version 3.10 and should not be used in newly written code.
Default value: nil

wrap-width

The wrap-width property of type :int (Read / Write)
If wrap-width is set to a positive value, the list will be displayed in multiple columns, the number of columns is determined by wrap-width.
Allowed values: >= 0
Default value: 0

Details

A gtk-combo-box widget allows the user to choose from a list of valid choices. The gtk-combo-box widget displays the selected choice. When activated, the gtk-combo-box widget displays a popup which allows the user to make a new choice. The style in which the selected value is displayed, and the style of the popup is determined by the current theme. It may be similar to a Windows style combo box.

The gtk-combo-box widget 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 the gtk-combo-box class implements the gtk-cell-layout 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 gtk-combo-box widget to contain a gtk-entry widget. This entry can be accessed by calling the function gtk-bin-child on the combo box.

For a simple list of textual choices, the model-view API of the gtk-combo-box widget can be a bit overwhelming. In this case, the gtk-combo-box-text widget offers a simple alternative. Both the gtk-combo-box widget and the gtk-combo-box-text widget can contain an entry.

CSS nodes

 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 gtk-combo-box widget 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.

Style Property Details

appears-as-list: The appears-as-list style property of type :boolean (Read)
Whether dropdowns should look like lists rather than menus.
Default value: false
arrow-scaling: The arrow-scaling style property of :float (Read)
Sets the amount of space used up by the combo box arrow, proportional to the font size.
Warning: The arrow-scaling style property has been deprecated since version 3.20 and should not be used in newly written code. Use the standard min-width/min-height CSS properties on the arrow node. The value of this style property is ignored.
Allowed values: [0.0,2.0]
Default value: 1.0
arrow-size: The arrow-size style property of type :int (Read)
Sets the minimum size of the arrow in the combo box. Note that the arrow size is coupled to the font size, so in case a larger font is used, the arrow will be larger than set by arrow size.
Warning: The arrow-size style property has been deprecated since version 3.20 and should not be used in newly written code. Use the standard min-width/min-height CSS properties on the arrow node. The value of this style property is ignored.
Allowed values: >= 0
Default value: 15
shadow-type: The shadow-type style property of type gtk-shadow-type (Read)
Which kind of shadow to draw around the combo box.
Warning: The shadow-type style property has been deprecated since version 3.20 and should not be used in newly written code. Use CSS styling to change the appearance of the combobox frame. The value of this style property is ignored.
Default value: :none

Signal Details

The "changed" signal

 lambda (combo)    : Run Last

The signal is 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 the function gtk-combo-box-active-iter. It will also be emitted while typing into the entry of a combo box with an entry.

combo: The gtk-combo-box widget that received the signal.

The "format-entry-text" signal

 lambda (combo pathstr)    : Run Last

A signal which allows you to change how the text displayed in a combo box's entry is displayed. 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 property model column. Here is an example signal handler which fetches data from the model and displays it in the entry. For combo boxes that are created with an entry. See the has-entry property.

(defun format-entry-text-callback (combo pathstr)
  (let* ((model (gtk-combo-box-model combo))
         (iter (gtk-tree-model-iter-from-string model pathstr))
         (value (gtk-tree-model-value model iter col-value)))
    (format nil "~a" value)))

combo: The gtk-combo-box widget that received the signal.
pathstr: A string representing the gtk-tree-path instance from the combo box's current model to format text for.
Returns: A string representing the value at pathstr for the current gtk-combo-box model.