ComboBox

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 Windows-style combo box.

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.

To allow the user to enter values not in the model, the “has-entry” property allows the GtkComboBox to contain a #GtkEntry. This entry can be accessed by calling gtk.bin.Bin.getChild on the combo box.

For a simple list of textual choices, the model-view API of GtkComboBox can be a bit overwhelming. In this case, #GtkComboBoxText offers a simple alternative. Both GtkComboBox and #GtkComboBoxText can contain an entry.

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 GtkComboBox 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.

class ComboBox : Bin , CellEditable , CellLayout {

this(void* ptr, Flag!"Take" take);

static GType _getGType();

GType _gType [@property getter];

ComboBox self();

static ComboBoxGidBuilder builder();

int active [@property getter];

int active [@property setter];

string activeId [@property getter];

string activeId [@property setter];

bool addTearoffs [@property getter];

bool addTearoffs [@property setter];

gtk.types.SensitivityType buttonSensitivity [@property getter];

gtk.types.SensitivityType buttonSensitivity [@property setter];

gtk.cell_area.CellArea cellArea [@property getter];

int columnSpanColumn [@property getter];

int columnSpanColumn [@property setter];

int entryTextColumn [@property getter];

int entryTextColumn [@property setter];

bool hasEntry [@property getter];

bool hasFrame [@property getter];

bool hasFrame [@property setter];

int idColumn [@property getter];

int idColumn [@property setter];

gtk.tree_model.TreeModel model [@property getter];

gtk.tree_model.TreeModel model [@property setter];

bool popupFixedWidth [@property getter];

bool popupFixedWidth [@property setter];

bool popupShown [@property getter];

int rowSpanColumn [@property getter];

int rowSpanColumn [@property setter];

string tearoffTitle [@property getter];

string tearoffTitle [@property setter];

int wrapWidth [@property getter];

int wrapWidth [@property setter];

static gtk.combo_box.ComboBox newWithArea(gtk.cell_area.CellArea area);

static gtk.combo_box.ComboBox newWithAreaAndEntry(gtk.cell_area.CellArea area);

static gtk.combo_box.ComboBox newWithEntry();

static gtk.combo_box.ComboBox newWithModel(gtk.tree_model.TreeModel model);

static gtk.combo_box.ComboBox newWithModelAndEntry(gtk.tree_model.TreeModel model);

int getActive();

string getActiveId();

bool getActiveIter(gtk.tree_iter.TreeIter iter);

bool getAddTearoffs();

gtk.types.SensitivityType getButtonSensitivity();

int getColumnSpanColumn();

int getEntryTextColumn();

bool getFocusOnClick();

bool getHasEntry();

int getIdColumn();

gtk.tree_model.TreeModel getModel();

atk.object.ObjectWrap getPopupAccessible();

bool getPopupFixedWidth();

int getRowSpanColumn();

string getTitle();

int getWrapWidth();

void popdown();

void popup();

void popupForDevice(gdk.device.Device device);

void setActive(int index);

bool setActiveId(string activeId);

void setActiveIter(gtk.tree_iter.TreeIter iter);

void setAddTearoffs(bool addTearoffs);

void setButtonSensitivity(gtk.types.SensitivityType sensitivity);

void setColumnSpanColumn(int columnSpan);

void setEntryTextColumn(int textColumn);

void setFocusOnClick(bool focusOnClick);

void setIdColumn(int idColumn);

void setModel(gtk.tree_model.TreeModel model);

void setPopupFixedWidth(bool fixed);

void setRowSeparatorFunc(gtk.types.TreeViewRowSeparatorFunc func);

void setRowSpanColumn(int rowSpan);

void setTitle(string title);

void setWrapWidth(int width);

gulong connectChanged(T callback, Flag!"After" after);

gulong connectFormatEntryText(T callback, Flag!"After" after);

gulong connectMoveActive(T callback, Flag!"After" after);

gulong connectPopdown(T callback, Flag!"After" after);

gulong connectPopup(T callback, Flag!"After" after);

}

Constructors

this this(void* ptr, Flag!"Take" take)
this this(): Creates a new empty #GtkComboBox.

Members

Functions

connectChanged gulong connectChanged(T callback, Flag!"After" after): Connect to Changed signal.
connectFormatEntryText gulong connectFormatEntryText(T callback, Flag!"After" after): Connect to FormatEntryText signal.
connectMoveActive gulong connectMoveActive(T callback, Flag!"After" after): Connect to MoveActive signal.
connectPopdown gulong connectPopdown(T callback, Flag!"After" after): Connect to Popdown signal.
connectPopup gulong connectPopup(T callback, Flag!"After" after): Connect to Popup signal.
getActive int getActive(): Returns 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.
getActiveId string getActiveId(): Returns the ID of the active row of combo_box. This value is taken from the active row and the column specified by the #GtkComboBox:id-column property of combo_box (see gtk.combo_box.ComboBox.setIdColumn).
getActiveIter bool getActiveIter(gtk.tree_iter.TreeIter iter): Sets iter to point to the currently active item, if any item is active. Otherwise, iter is left unchanged.
getAddTearoffs bool getAddTearoffs(): Gets the current value of the :add-tearoffs property.
getButtonSensitivity gtk.types.SensitivityType getButtonSensitivity(): Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model.
getColumnSpanColumn int getColumnSpanColumn(): Returns the column with column span information for combo_box.
getEntryTextColumn int getEntryTextColumn(): Returns the column which combo_box is using to get the strings from to display in the internal entry.
getFocusOnClick bool getFocusOnClick(): Returns whether the combo box grabs focus when it is clicked with the mouse. See gtk.combo_box.ComboBox.setFocusOnClick.
getHasEntry bool getHasEntry(): Returns whether the combo box has an entry.
getIdColumn int getIdColumn(): Returns the column which combo_box is using to get string IDs for values from.
getModel gtk.tree_model.TreeModel getModel(): Returns the #GtkTreeModel which is acting as data source for combo_box.
getPopupAccessible atk.object.ObjectWrap getPopupAccessible(): Gets the accessible object corresponding to the combo box’s popup.
getPopupFixedWidth bool getPopupFixedWidth(): Gets whether the popup uses a fixed width matching the allocated width of the combo box.
getRowSpanColumn int getRowSpanColumn(): Returns the column with row span information for combo_box.
getTitle string getTitle(): Gets the current title of the menu in tearoff mode. See gtk.combo_box.ComboBox.setAddTearoffs.
getWrapWidth int getWrapWidth(): Returns the wrap width which is used to determine the number of columns for the popup menu. If the wrap width is larger than 1, the combo box is in table mode.
popdown void popdown(): Hides the menu or dropdown list of combo_box.
popup void popup(): Pops up the menu or dropdown list of combo_box.
popupForDevice void popupForDevice(gdk.device.Device device): Pops up the menu or dropdown list of combo_box, the popup window will be grabbed so only device and its associated pointer/keyboard are the only #GdkDevices able to send events to it.
self ComboBox self(): Returns this, for use in with statements.
setActive void setActive(int index): Sets the active item of combo_box to be the item at index.
setActiveId bool setActiveId(string activeId): Changes the active row of combo_box to the one that has an ID equal to active_id, or unsets the active row if active_id is null. Rows having a null ID string cannot be made active by this function.
setActiveIter void setActiveIter(gtk.tree_iter.TreeIter iter): Sets the current active item to be the one referenced by iter, or unsets the active item if iter is null.
setAddTearoffs void setAddTearoffs(bool addTearoffs): Sets whether the popup menu should have a tearoff menu item.
setButtonSensitivity void setButtonSensitivity(gtk.types.SensitivityType sensitivity): Sets whether the dropdown button of the combo box should be always sensitive (gtk.types.SensitivityType.On), never sensitive (gtk.types.SensitivityType.Off) or only if there is at least one item to display (gtk.types.SensitivityType.Auto).
setColumnSpanColumn void setColumnSpanColumn(int columnSpan): Sets the column with column span information for combo_box to be column_span. The column span column contains integers which indicate how many columns an item should span.
setEntryTextColumn void setEntryTextColumn(int textColumn): Sets the model column which combo_box should use to get strings from to be text_column. The column text_column in the model of combo_box must be of type G_TYPE_STRING.
setFocusOnClick void setFocusOnClick(bool focusOnClick): Sets whether the combo box will grab focus when it is 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.
setIdColumn void setIdColumn(int idColumn): 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.
setModel void setModel(gtk.tree_model.TreeModel model): Sets the model used by combo_box to be model. Will unset a previously set model (if applicable). If model is null, then it will unset the model.
setPopupFixedWidth void setPopupFixedWidth(bool fixed): Specifies whether the popup’s width should be a fixed width matching the allocated width of the combo box.
setRowSeparatorFunc void setRowSeparatorFunc(gtk.types.TreeViewRowSeparatorFunc func): 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 null, no separators are drawn. This is the default value.
setRowSpanColumn void setRowSpanColumn(int rowSpan): Sets the column with row span information for combo_box to be row_span. The row span column contains integers which indicate how many rows an item should span.
setTitle void setTitle(string title): Sets the menu’s title in tearoff mode.
setWrapWidth void setWrapWidth(int width): Sets the wrap width of combo_box to be width. The wrap width is basically the preferred number of columns when you want the popup to be layed out in a table.

Properties

_gType GType _gType [@property getter]
active int active [@property getter]: Get active property.
active int active [@property setter]: Set active property.
activeId string activeId [@property getter]: Get activeId property.
activeId string activeId [@property setter]: Set activeId property.
addTearoffs bool addTearoffs [@property getter]: Get addTearoffs property.
addTearoffs bool addTearoffs [@property setter]: Set addTearoffs property.
buttonSensitivity gtk.types.SensitivityType buttonSensitivity [@property getter]: Get buttonSensitivity property.
buttonSensitivity gtk.types.SensitivityType buttonSensitivity [@property setter]: Set buttonSensitivity property.
cellArea gtk.cell_area.CellArea cellArea [@property getter]: Get cellArea property.
columnSpanColumn int columnSpanColumn [@property getter]: Get columnSpanColumn property.
columnSpanColumn int columnSpanColumn [@property setter]: Set columnSpanColumn property.
entryTextColumn int entryTextColumn [@property getter]: Get entryTextColumn property.
entryTextColumn int entryTextColumn [@property setter]: Set entryTextColumn property.
hasEntry bool hasEntry [@property getter]: Get hasEntry property.
hasFrame bool hasFrame [@property getter]: Get hasFrame property.
hasFrame bool hasFrame [@property setter]: Set hasFrame property.
idColumn int idColumn [@property getter]: Get idColumn property.
idColumn int idColumn [@property setter]: Set idColumn property.
model gtk.tree_model.TreeModel model [@property getter]: Get model property.
model gtk.tree_model.TreeModel model [@property setter]: Set model property.
popupFixedWidth bool popupFixedWidth [@property getter]: Get popupFixedWidth property.
popupFixedWidth bool popupFixedWidth [@property setter]: Set popupFixedWidth property.
popupShown bool popupShown [@property getter]: Get popupShown property.
rowSpanColumn int rowSpanColumn [@property getter]: Get rowSpanColumn property.
rowSpanColumn int rowSpanColumn [@property setter]: Set rowSpanColumn property.
tearoffTitle string tearoffTitle [@property getter]: Get tearoffTitle property.
tearoffTitle string tearoffTitle [@property setter]: Set tearoffTitle property.
wrapWidth int wrapWidth [@property getter]: Get wrapWidth property.
wrapWidth int wrapWidth [@property setter]: Set wrapWidth property.

Static functions

_getGType GType _getGType()
builder ComboBoxGidBuilder builder(): Get builder for gtk.combo_box.ComboBox
newWithArea gtk.combo_box.ComboBox newWithArea(gtk.cell_area.CellArea area): Creates a new empty #GtkComboBox using area to layout cells.
newWithAreaAndEntry gtk.combo_box.ComboBox newWithAreaAndEntry(gtk.cell_area.CellArea area): Creates a new empty #GtkComboBox with an entry.
newWithEntry gtk.combo_box.ComboBox newWithEntry(): Creates a new empty #GtkComboBox with an entry.
newWithModel gtk.combo_box.ComboBox newWithModel(gtk.tree_model.TreeModel model): Creates a new #GtkComboBox with the model initialized to model.
newWithModelAndEntry gtk.combo_box.ComboBox newWithModelAndEntry(gtk.tree_model.TreeModel model): Creates a new empty #GtkComboBox with an entry and with the model initialized to model.

Mixed In Members

From `mixin CellEditableT!()`

editingCanceled bool editingCanceled [@property getter]: Get editingCanceled property.
editingCanceled bool editingCanceled [@property setter]: Set editingCanceled property.
editingDone void editingDone(): Emits the #GtkCellEditable::editing-done signal.
removeWidget void removeWidget(): Emits the #GtkCellEditable::remove-widget signal.
startEditing void startEditing(gdk.event.Event event): Begins editing on a cell_editable.
connectEditingDone gulong connectEditingDone(T callback, Flag!"After" after): Connect to EditingDone signal.
connectRemoveWidget gulong connectRemoveWidget(T callback, Flag!"After" after): Connect to RemoveWidget signal.

From `mixin CellLayoutT!()`

addAttribute void addAttribute(gtk.cell_renderer.CellRenderer cell, string attribute, int column): Adds an attribute mapping to the list in cell_layout.
clear void clear(): Unsets all the mappings on all renderers on cell_layout and removes all renderers from cell_layout.
clearAttributes void clearAttributes(gtk.cell_renderer.CellRenderer cell): Clears all existing attributes previously set with gtk.cell_layout.CellLayout.setAttributes.
getArea gtk.cell_area.CellArea getArea(): Returns the underlying #GtkCellArea which might be cell_layout if called on a #GtkCellArea or might be null if no #GtkCellArea is used by cell_layout.
getCells gtk.cell_renderer.CellRenderer[] getCells(): Returns the cell renderers which have been added to cell_layout.
packEnd void packEnd(gtk.cell_renderer.CellRenderer cell, bool expand): Adds the cell to the end of cell_layout. If expand is false, then the cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is true.
packStart void packStart(gtk.cell_renderer.CellRenderer cell, bool expand): Packs the cell into the beginning of cell_layout. If expand is false, then the cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is true.
reorder void reorder(gtk.cell_renderer.CellRenderer cell, int position): Re-inserts cell at position.
setCellDataFunc void setCellDataFunc(gtk.cell_renderer.CellRenderer cell, gtk.types.CellLayoutDataFunc func): Sets the #GtkCellLayoutDataFunc to use for cell_layout.

Inherited Members

From Bin

_getGType GType _getGType()
_gType GType _gType [@property getter]
self Bin self(): Returns this, for use in with statements.
builder BinGidBuilder builder(): Get builder for gtk.bin.Bin
getChild gtk.widget.Widget getChild(): Gets the child of the #GtkBin, or null if the bin contains no child widget. The returned widget does not have a reference added, so you do not need to unref it.

From CellEditable

_getGType GType _getGType()
editingCanceled bool editingCanceled [@property getter]: Get editingCanceled property.
editingCanceled bool editingCanceled [@property setter]: Set editingCanceled property.
editingDone void editingDone(): Emits the #GtkCellEditable::editing-done signal.
removeWidget void removeWidget(): Emits the #GtkCellEditable::remove-widget signal.
startEditing void startEditing(gdk.event.Event event): Begins editing on a cell_editable.
connectEditingDone gulong connectEditingDone(T callback, Flag!"After" after): Connect to EditingDone signal.
connectRemoveWidget gulong connectRemoveWidget(T callback, Flag!"After" after): Connect to RemoveWidget signal.

From CellLayout

_getGType GType _getGType()
addAttribute void addAttribute(gtk.cell_renderer.CellRenderer cell, string attribute, int column): Adds an attribute mapping to the list in cell_layout.
clear void clear(): Unsets all the mappings on all renderers on cell_layout and removes all renderers from cell_layout.
clearAttributes void clearAttributes(gtk.cell_renderer.CellRenderer cell): Clears all existing attributes previously set with gtk.cell_layout.CellLayout.setAttributes.
getArea gtk.cell_area.CellArea getArea(): Returns the underlying #GtkCellArea which might be cell_layout if called on a #GtkCellArea or might be null if no #GtkCellArea is used by cell_layout.
getCells gtk.cell_renderer.CellRenderer[] getCells(): Returns the cell renderers which have been added to cell_layout.
packEnd void packEnd(gtk.cell_renderer.CellRenderer cell, bool expand): Adds the cell to the end of cell_layout. If expand is false, then the cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is true.
packStart void packStart(gtk.cell_renderer.CellRenderer cell, bool expand): Packs the cell into the beginning of cell_layout. If expand is false, then the cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is true.
reorder void reorder(gtk.cell_renderer.CellRenderer cell, int position): Re-inserts cell at position.
setCellDataFunc void setCellDataFunc(gtk.cell_renderer.CellRenderer cell, gtk.types.CellLayoutDataFunc func): Sets the #GtkCellLayoutDataFunc to use for cell_layout.

gtk combo_box classes