A widget used to choose from a list of items
Class GtkComboBox
A GtkComboBox is a widget that allows the user to choose from a list of valid choices. The GtkComboBox displays the selected choice. When activated, the GtkComboBox 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 GtkOptionMenu, or similar to a Windows-style combo box.
Unlike its predecessors GtkCombo and GtkOptionMenu, 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 GtkCellLayout 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.
In addition to the model-view API, GtkComboBox offers a simple API which is suitable for text-only combo boxes, and hides the complexity of managing the data in a model. It consists of the functions new_text(), append_text(), insert_text(), prepend_text(), remove_text() and get_active_text().
| Methods | |
| append_text | Appends string to the list of strings stored in combo_box. |
| get_active | Returns the index of the currently active item, or -1 if there's no active item. |
| get_active_text | Returns the currently active string in combo_box or NULL if none is selected. |
| get_add_tearoffs | Gets the current value of the :add-tearoffs property. |
| get_button_sensitivity | Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model. |
| get_column_span_column | Returns the column with column span information for combo_box. |
| get_focus_on_click | Returns whether the combo box grabs focus when it is clicked with the mouse. |
| get_row_span_column | Returns the column with row span information for combo_box. |
| get_title | Gets the current title of the menu in tearoff mode. |
| insert_text | Inserts string at position in the list of strings stored in combo_box. |
| new_text | Convenience function which constructs a new text combo box, which is a GtkComboBox just displaying strings. |
| popdown | Hides the menu or dropdown list of combo_box. |
| popup | Pops up the menu or dropdown list of combo_box. |
| prepend_text | Prepends string to the list of strings stored in combo_box. |
| remove_text | Removes the string at position from combo_box. |
| set_active | Sets the active item of combo_box to be the item at index. |
| set_add_tearoffs | Sets whether the popup menu should have a tearoff menu item. |
| set_button_sensitivity | Sets whether the dropdown button of the combo box should be always sensitive (GTK_SENSITIVITY_ON), never sensitive (GTK_SENSITIVITY_OFF) or only if there is at least one item to display (GTK_SENSITIVITY_AUTO). |
| set_column_span_column | Sets the column with column span information for combo_box to be column_span. |
| set_focus_on_click | Sets whether the combo box will grab focus when it is clicked with the mouse. |
| set_row_span_column | Sets the column with row span information for combo_box to be row_span. |
| set_title | Sets the menu's title in tearoff mode. |
| set_wrap_width | Sets the wrap width of combo_box to be width. |
| signal_changed | Connect a VMSlot to the combo box changed signal and return it |
| signal_move_active | Connect a VMSlot to the combo box move-active signal and return it |
| signal_popdown | Connect a VMSlot to the combo box popdown signal and return it |
| signal_popup | Connect a VMSlot to the combo box popup signal and return it |
Appends string to the list of strings stored in combo_box.
GtkComboBox.append_text( text )
| text | a string |
Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text().
Returns the index of the currently active item, or -1 if there's no active item.
GtkComboBox.get_active()
| Return | An integer which is the index of the currently active item, or -1 if there's no 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 GtkTreePath of the active item.
Returns the currently active string in combo_box or NULL if none is selected.
GtkComboBox.get_active_text()
| Return | the currently active text |
Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text() and with GtkComboBoxEntrys.
Gets the current value of the :add-tearoffs property.
GtkComboBox.get_add_tearoffs()
| Return | the current value of the :add-tearoffs property. |
Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model.
GtkComboBox.get_button_sensitivity()
| Return | 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. |
Returns the column with column span information for combo_box.
GtkComboBox.get_column_span_column()
| Return | the column span column |
Returns whether the combo box grabs focus when it is clicked with the mouse.
GtkComboBox.get_focus_on_click()
| Return | TRUE if the combo box grabs focus when it is clicked with the mouse. |
Returns the column with row span information for combo_box.
GtkComboBox.get_row_span_column()
| Return | the row span column. |
Gets the current title of the menu in tearoff mode.
GtkComboBox.get_title()
| Return | the menu's title in tearoff mode. |
Inserts string at position in the list of strings stored in combo_box.
GtkComboBox.insert_text( position, text )
| position | An index to insert text |
| text | A string |
Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text().
Convenience function which constructs a new text combo box, which is a GtkComboBox just displaying strings.
GtkComboBox.new_text()
| Return | A new text combo box |
If you use this function to create a text combo box, you should only manipulate its data source with the following convenience functions: append_text(), insert_text(), prepend_text() and remove_text().
Hides the menu or dropdown list of combo_box.
GtkComboBox.popdown()
This function is mostly intended for use by accessibility technologies; applications should have little use for it.
Pops up the menu or dropdown list of combo_box.
GtkComboBox.popup()
This function is mostly intended for use by accessibility technologies; applications should have little use for it.
Prepends string to the list of strings stored in combo_box.
GtkComboBox.prepend_text( text )
| text | A string |
Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text().
Removes the string at position from combo_box.
GtkComboBox.remove_text( position )
| position | Index of the item to remove |
Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text().
Sets the active item of combo_box to be the item at index.
GtkComboBox.set_active( index )
| index | An index in the model passed during construction, or -1 to have no active item |
Sets whether the popup menu should have a tearoff menu item.
GtkComboBox.set_add_tearoffs( add_tearoffs )
| add_tearoffs | true to add tearoff menu items |
Sets whether the dropdown button of the combo box should be always sensitive (GTK_SENSITIVITY_ON), never sensitive (GTK_SENSITIVITY_OFF) or only if there is at least one item to display (GTK_SENSITIVITY_AUTO).
GtkComboBox.set_button_sensitivity( sensitivity )
| sensitivity | (GtkSensitivityType) specify the sensitivity of the dropdown button |
Sets the column with column span information for combo_box to be column_span.
GtkComboBox.set_column_span_column( column_span )
| column_span | A column in the model passed during construction |
The column span column contains integers which indicate how many columns an item should span.
Sets whether the combo box will grab focus when it is clicked with the mouse.
GtkComboBox.set_focus_on_click( focus_on_click )
| focus_on_click | whether the combo box grabs focus when clicked with the mouse |
Making mouse clicks not grab focus is useful in places like toolbars where you don't want the keyboard focus removed from the main area of the application.
Sets the column with row span information for combo_box to be row_span.
GtkComboBox.set_row_span_column( row_span )
| row_span | A column in the model passed during construction. |
The row span column contains integers which indicate how many rows an item should span.
Sets the menu's title in tearoff mode.
GtkComboBox.set_title( title )
| title | a title for the menu in tearoff mode |
Sets the wrap width of combo_box to be width.
GtkComboBox.set_wrap_width( width )
| width | Preferred number of columns The wrap width is basically the preferred number of columns when you want the popup to be layed out in a table. |
Connect a VMSlot to the combo box changed signal and return it
GtkComboBox.signal_changed()
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 gtk_combo_box_set_active_iter(). It will also be emitted while typing into a GtkComboBoxEntry, as well as when selecting an item from the GtkComboBoxEntry's list.
Connect a VMSlot to the combo box move-active signal and return it
GtkComboBox.signal_move_active()
The move-active signal is a keybinding signal which gets emitted to move the active selection.
The callback function is passed a GtkScrollType as argument.
Connect a VMSlot to the combo box popdown signal and return it
GtkComboBox.signal_popdown()
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.
Connect a VMSlot to the combo box popup signal and return it
GtkComboBox.signal_popup()
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.