Package: gtk

Class gtk-combo-box

Superclasses

Documented Subclasses

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 gtk_tree_path_get_indices (path)[0], where path is the gtk-tree-path 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)
The add-tearoffs property controls whether generated menus have tearoff menu items. Note that this only affects menu style combo boxes.
Warning: add-tearoffs has been deprecated since version 3.10 and should not be used in newly-written code.
Default value: nil
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 gtk-cell-area used to layout cell renderers for this combo box. If no area is specified when creating the combo box with the gtk-combo-box-new-with-area a horizontally oriented gtk-cell-area-box 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 +g-type-int+ in the model. The values of that column are used to determine how many columns a value in the list will span.
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 has-entry = true.
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: nil
has-frame
The has-frame property of type :boolean (Read / Write)
The has-frame property 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 != -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.
popup-fixed-width
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
popup-shown
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: nil
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 +g-type-int+ 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 wrap-width.
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: tearoff-title 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 is a widget that allows the user to choose from a list of valid choices. The gtk-combo-box displays the selected choice. When activated, the gtk-combo-box 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 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 gtk-combo-box 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 to contain a gtk-entry. This entry can be accessed by calling the gtk-bin-get-child function on the combo box.

For a simple list of textual choices, the model-view API of gtk-combo-box can be a bit overwhelming. In this case, gtk-combo-box-text offers a simple alternative. Both gtk-combo-box and gtk-combo-box-text 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 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: nil{
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: arrow-scaling 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,2]
Default value: 1
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: arrow-size 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: shadow-type 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 (widget)    : Run Last      
The changed 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 gtk-combo-box-set-active-iter function. It will also be emitted while typing into the entry of a combo box with an entry.
widget
The object which received the signal.
The "format-entry-text" signal
 lambda (combo path)    : Run Last      
For combo boxes that are created with an entry. See the has-entry property. 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.
 static gchar*
 format_entry_text_callback (GtkComboBox *combo,
                             const gchar *path,
                             gpointer     user_data)
 {
   GtkTreeIter iter;
   GtkTreeModel model;
   gdouble      value;

model = gtk_combo_box_get_model (combo);

gtk_tree_model_get_iter_from_string (model, &iter, path); gtk_tree_model_get (model, &iter, THE_DOUBLE_VALUE_COLUMN, &value, -1);

return g_strdup_printf ("%g", value); }
combo
The object which received the signal.
path
The gtk-tree-path object string from the combo box's current model to format text for.
Returns
A newly allocated string representing path for the current gtk-combo-box model.
The "move-active" signal
 lambda (widget scroll-type)    : Action      
The "move-active" signal is a keybinding signal which gets emitted to move the active selection.
widget
The object that received the signal.
scroll-type
A gtk-scroll-type.
The "popdown" signal
 lambda (button)    : Action      
The "popdown" signal is a keybinding signal which gets emitted to popdown the combo box list. The default bindings for this signal are Alt+Up and Escape.
button
The object which received the signal.
The "popup" signal
 lambda (widget)    : Action      
The "popup" signal is a keybinding signal which gets emitted to popup the combo box list. The default binding for this signal is Alt+Down.
widget
The object that received the signal.
 

Slot Access Functions

Inherited Slot Access Functions

2013-5-31