|
Graphics.UI.Gtk.MenuComboToolbar.ComboBox | Portability | portable (depends on GHC) | Stability | provisional | Maintainer | gtk2hs-users@lists.sourceforge.net |
|
|
|
|
|
Description |
A widget used to choose from a list of items.
- Module available since Gtk+ version 2.4
|
|
Synopsis |
|
|
|
|
Detail
|
|
A ComboBox is a widget that allows the user to choose from a list of
valid choices. The ComboBox displays the selected choice. When activated,
the ComboBox 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
OptionMenu, or similar to a Windows-style combo box.
Unlike its predecessors Combo and OptionMenu, the 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 ComboBox implements the 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.
In addition to the general model-view API, ComboBox offers the function
comboBoxNewText which creates a text-only combo box.
|
|
Class Hierarchy
|
|
| GObject
| +----Object
| +----Widget
| +----Container
| +----Bin
| +----ComboBox
| +----ComboBoxEntry
|
|
Types
|
|
|
|
|
|
|
|
|
|
|
|
|
Constructors
|
|
|
Creates a new empty ComboBox.
|
|
|
Convenience function which constructs a new text combo box that is a
ComboBox just displaying strings. This function internally calls
comboBoxSetModelText after creating a new combo box.
|
|
|
|
|
Methods
|
|
Simple Text API
|
|
|
Create a combo box that holds strings.
This function stores a Graphics.UI.Gtk.ModelView.ListStore with the
widget and sets the model to the list store. The widget can contain only
strings. The model can be retrieved with comboBoxGetModel. The list
store can be retrieved with comboBoxGetModelText.
Any exisiting model or renderers are removed before setting the new text
model.
Note that the functions comboBoxAppendText, comboBoxInsertText,
comboBoxPrependText, comboBoxRemoveText and comboBoxGetActiveText
can be called on a combo box only once comboBoxSetModelText is called.
|
|
|
Retrieve the model that was created with comboBoxSetModelText.
|
|
|
Appends string to the list of strings stored in comboBox. Note that
you can only use this function with combo boxes constructed with
comboBoxNewText. Returns the index of the appended text.
|
|
|
:: ComboBoxClass self | | => self | position - An index to insert text.
| -> Int | text - A string.
| -> String | | -> IO () | | Inserts string at position in the list of strings stored in
comboBox. Note that you can only use this function with combo boxes
constructed with comboBoxNewText.
|
|
|
|
Prepends string to the list of strings stored in comboBox. Note that
you can only use this function with combo boxes constructed with
comboBoxNewText.
|
|
|
:: ComboBoxClass self | | => self | position - Index of the item to remove.
| -> Int | | -> IO () | | Removes the string at position from comboBox. Note that you can only
use this function with combo boxes constructed with comboBoxNewText.
|
|
|
|
Returns the currently active string in comboBox or Nothing if none is
selected. Note that you can only use this function with combo boxes
constructed with comboBoxNewText.
|
|
Standard API
|
|
|
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.
- Available since Gtk+ version 2.6
|
|
|
Sets the wrap width of the combo box to be width. The wrap width is
basically the preferred number of columns when you want the popup to be
laid out in a table.
|
|
|
Gets the column with row span information for comboBox.
- Available since Gtk+ version 2.6
|
|
|
Sets the column with row span information for comboBox to be rowSpan.
The row span column contains integers which indicate how many rows an item
should span.
|
|
|
Gets the source of the column span information for the combo box.
- Available since Gtk+ version 2.6
|
|
|
Sets the source of the column span information for the combo box. The
column span source contains integers which indicate how many columns an
item should span.
|
|
|
:: ComboBoxClass self | | => self | returns An integer which is the index of the currently active
item, or -1 if there's no active item.
| -> IO Int | | Returns the index of the currently active item, or -1 if there is 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
treePathGetIndices path !! 0, where path is the TreePath of the
active item.
|
|
|
|
:: ComboBoxClass self | | => self | index - An index in the model passed during construction, or -1
to have no active item.
| -> Int | | -> IO () | | Sets the active item of comboBox to be the item at index.
|
|
|
|
Returns a TreeIter that points to the current active item, if it
exists, or Nothing if there is no current active item.
|
|
|
:: ComboBoxClass self | | => self | iter - The TreeIter.
| -> TreeIter | | -> IO () | | Sets the current active item to be the one referenced by iter. iter
must correspond to a path of depth one.
|
|
|
|
|
|
|
Sets the model used by comboBox to be model. Will unset a previously
set model (if applicable). If model is Nothing, then it will unset the
model.
Note that this function does not clear the cell renderers, you have to call
comboBoxCellLayoutClear yourself if you need to set up different cell
renderers for the new model.
|
|
|
Pops up the menu or dropdown list of the combo box.
This function is mostly intended for use by accessibility technologies;
applications should have little use for it.
|
|
|
Hides the menu or dropdown list of comboBox.
This function is mostly intended for use by accessibility technologies;
applications should have little use for it.
|
|
comboBoxSetRowSeparatorSource | Source |
|
:: (ComboBoxClass self, TreeModelClass (model row), TypedTreeModelClass model) | | => self | The model and a function to extract a Boolean from it.
| -> Maybe (model row, row -> Bool) | | -> IO () | | Installs a mapping from the model to a row separator flag, which is used
to determine whether a row should be drawn as a separator. If the row
separator mapping is Nothing, no separators are drawn. This is the
default value.
- Available since Gtk+ version 2.6
|
|
|
|
:: ComboBoxClass self | | => self | addTearoffs - True to add tearoff menu items
| -> Bool | | -> IO () | | Sets whether the popup menu should have a tearoff menu item.
- Available since Gtk+ version 2.6
|
|
|
|
Gets the current value of the :add-tearoffs property.
|
|
|
:: ComboBoxClass self | | => self | title - a title for the menu in tearoff mode.
| -> String | | -> IO () | | Sets the menu's title in tearoff mode.
- Available since Gtk+ version 2.10
|
|
|
|
|
|
|
:: ComboBoxClass self | | => self | focusOnClick - whether the combo box grabs focus when clicked
with the mouse
| -> Bool | | -> IO () | | 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.
- Available since Gtk+ version 2.6
|
|
|
|
:: ComboBoxClass self | | => self | returns True if the combo box grabs focus when it is
clicked with the mouse.
| -> IO Bool | | Returns whether the combo box grabs focus when it is clicked with the
mouse. See comboBoxSetFocusOnClick.
- Available since Gtk+ version 2.6
|
|
|
Attributes
|
|
|
The model from which the combo box takes the values shown in the list.
|
|
|
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
|
|
|
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.
Default value: invalidColumnId
- Available since Gtk+ version 2.6
|
|
|
The values of that column are used to determine how many columns a value
in the list will span.
Default value: invalidColumnId
- Available since Gtk+ version 2.6
|
|
|
The item which is currently active. This value only makes sense for
a list model.
|
|
|
The add-tearoffs property controls whether generated menus have tearoff
menu items.
Note that this only affects menu style combo boxes.
Default value: False
- Available since Gtk+ version 2.6
|
|
|
The has-frame property controls whether a frame is drawn around the
entry.
Default value: True
- Available since Gtk+ version 2.6
|
|
|
Whether the combo box grabs focus when it is clicked with the mouse.
Default value: True
|
|
|
A title that may be displayed by the window manager when the popup is
torn-off.
Default value: ""
- Available since Gtk+ version 2.10
|
|
|
Whether the combo boxes dropdown is popped up. Note that this property is
mainly useful because it allows you to connect to notify::popup-shown.
Default value: False
- Available since Gtk+ version 2.10
|
|
|
'title' property. See comboBoxGetTitle and comboBoxSetTitle
- Available since Gtk+ version 2.10
|
|
Signals
|
|
|
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 comboBoxSetActiveIter. It will also be emitted while typing into a
ComboBoxEntry, as well as when selecting an item from the
ComboBoxEntry's list.
|
|
|
The combo box was dropped down or collapsed.
|
|
Deprecated
|
|
|
|
|
|
Produced by Haddock version 2.6.0 |