gtk.ComboBox
gtk.ComboBox — a widget used to choose from a list of items (new in PyGTK 2.4)
Synopsis
class gtk.ComboBox(gtk.Bin, gtk.CellLayout): |
Functions
def gtk.combo_box_new_text()
Ancestry
+--gobject.GObject +-- gtk.Object +-- gtk.Widget +-- gtk.Container +-- gtk.Bin +-- gtk.ComboBox
Implemented Interfaces
gtk.ComboBox
implements
gtk.Buildable
atk.ImplementorIFace
gtk.CellEditable
gtk.CellLayout
gtk.ComboBox Properties
|
gtk.ComboBox Style Properties
|
gtk.ComboBox Signal Prototypes
gtk.Container Signal Prototypes
gtk.CellEditable Signal Prototypes
"changed" | def callback( |
def callback( | |
"popdown" | def callback( |
"popup" | def callback( |
Description
Note
This widget is available in GTK+ 2.4 and PyGTK 2.4 and above.
The gtk.ComboBox
is a replacement for the gtk.OptionMenu
. The
gtk.ComboBox
implements the gtk.CellLayout
interface that provides a number of useful methods for managing the
contents. A gtk.ComboBox
is created with the gtk.ComboBox() constructor that
is associated with the optional gtk.TreeModel
. If
no gtk.TreeModel
is specified it can be added later with the set_model
()
method.
Alternatively, the gtk.combo_box_new_text
()
function creates a simple gtk.ComboBox
and associated gtk.ListStore
model. A gtk.CellRendererText
is also created and packed in the new combo box. In this simple combo
box each list item is a text string that can be selected. The
convenience methods append_text
(),
prepend_text
(),
insert_text
()
and remove_text
()
can be used to manage the contents of the gtk.ComboBox
. Using
the gtk.combo_box_new_text
()
function is equivalent to:
liststore = gtk.ListStore(gobject.TYPE_STRING) combobox = gtk.ComboBox(liststore) cell = gtk.CellRendererText() combobox.pack_start(cell, True) combobox.add_attribute(cell, 'text', 0)
Constructor
gtk.ComboBox(model
=None)
| A valid gtk.TreeModel . |
Returns : | A new gtk.ComboBox . |
Note
This constructor is available in PyGTK 2.4 and above.
Creates a new gtk.ComboBox
associated with the optional gtk.TreeModel
specified by model
. If
model
is not specified the combo box will not
have an associated tree model.
Methods
gtk.ComboBox.get_has_entry
def get_has_entry()
Returns : | Whether there is an entry in the combo box. |
Note
This method is available in PyGTK 2.24 and above.
The get_has_entry
() method returns
whether the combo box has an entry.
gtk.ComboBox.get_entry_text_column
def get_entry_text_column()
Returns : | A column in the data source model of the combo box. |
Note
This method is available in PyGTK 2.24 and above.
The get_entry_text_column
() method returns
the columns which the combo box is using to get the strings
from to display in the internal entry.
gtk.ComboBox.set_entry_text_column
def set_entry_text_column(text_column
)
| A column in the data source model to get the strings from for the internal entry. |
Note
This method is available in PyGTK 2.24 and above.
The set_entry_text_column
() method sets the model column
which the 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.
gtk.ComboBox.get_wrap_width
def get_wrap_width()
Returns : | The wrap width. |
Note
This method is available in PyGTK 2.6 and above.
The get_wrap_width
() method returns the
value of the "wrap-width" property of the combo box as set by the set_wrap_width
()
method. The wrap width is basically the preferred number of columns to use
to lay out the popup i.e. lays out the popup items in a table with
width
columns.
gtk.ComboBox.set_wrap_width
def set_wrap_width(width
)
| The preferred number of columns of width. |
Note
This method is available in PyGTK 2.4 and above.
The set_wrap_width
() method sets the
wrap width (and the "wrap-width" property) of the combo box to the value
specified by width
. The wrap width is basically the
preferred number of columns to use to lay out the popup i.e. lays out the
popup items in a table with width
columns.
gtk.ComboBox.get_row_span_column
def get_row_span_column()
Returns : | The row span column. |
Note
This method is available in PyGTK 2.6 and above.
The get_row_span_column
() method
returns the value of the "row-span-column" property. The "row-span-column"
property indicates the column in the associated gtk.TreeModel
row
that contains an integer that indicates how many rows the item should
span.
gtk.ComboBox.set_row_span_column
def set_row_span_column(row_span
)
| A column in the model passed during construction. |
Note
This method is available in PyGTK 2.4 and above.
The set_row_span_column
() method sets
the "row-span-column" property to the value specified by
row_span
. The "row-span-column" property indicates
the column in the associated gtk.TreeModel
row
that contains an integer that indicates how many rows the item should
span.
gtk.ComboBox.get_column_span_column
def get_column_span_column()
Returns : | The column span column. |
Note
This method is available in PyGTK 2.6 and above.
The get_column_span_column
() method
returns the value of the "column-span-column" property. The
"column-span-column" property indicates the column in the associated gtk.TreeModel
row
that contains an integer that indicates how many columns the item should
span.
gtk.ComboBox.set_column_span_column
def set_column_span_column(column_span
)
| A column in the model passed during construction. |
Note
This method is available in PyGTK 2.4 and above.
The set_column_span_column
() method
sets the "column-span-column" property to the value specified by
column_span
. The "column-span-column" property
indicates the column in the associated gtk.TreeModel
row
that contains an integer that indicates how many columns the item should
span.
gtk.ComboBox.get_button_sensitivity
def get_button_sensitivity()
Returns : | 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. |
Note
This method is available in PyGTK 2.14 and above.
The get_button_sensitivity
() method returns whether
the combo box sets the dropdown button sensitive or not when there are no items in the model.
gtk.ComboBox.set_button_sensitivity
def set_button_sensitivity(sensitivity
)
| specify the sensitivity of the dropdown button. |
Note
This method is available in PyGTK 2.14 and above.
The set_button_sensitivity
() method 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).
gtk.ComboBox.get_active
def get_active()
Returns : | An integer which is the model index of the currently active item, or -1 if there's no active item. |
Note
This method is available in PyGTK 2.4 and above.
The get_active
() method returns the
value of the "active" property which is the index in the model 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 method returns the first path index of
the active item. For example if the path of the active item is (1, 0,
2) this method will return 1.
gtk.ComboBox.set_active
def set_active(index
)
| An index in the model passed during construction, or -1 to have no active item. |
Note
This method is available in PyGTK 2.4 and above.
The set_active
() method sets the active
item of the combo_box to the item with the model index specified by
index
. If index
is -1 the
combo box will have no active item. The "active" property is also set to the
value of index
.
gtk.ComboBox.get_active_iter
def get_active_iter()
Returns : | A gtk.TreeIter
that points at the active item or None if there
is no active item. |
Note
This method is available in PyGTK 2.4 and above.
The get_active_iter
() method returns a
gtk.TreeIter
that points to the current active item or None
if
there is no active item.
gtk.ComboBox.set_active_iter
def set_active_iter(iter
)
| A valid gtk.TreeIter
pointing at an item in the associated gtk.TreeModel . |
Note
This method is available in PyGTK 2.4 and above.
The set_active_iter
() method sets the
current active item to be the one referenced by iter
in the associated gtk.TreeModel
.
iter
must correspond to a path of depth one. The
"active" property is also set by this method.
gtk.ComboBox.set_model
def set_model(model
=None)
| A gtk.TreeModel . |
Note
This method is available in PyGTK 2.4 and above.
The set_model
() method sets the model
used by the combo box to the value specified by
model
. The "model" property will also be set to the
value of model
. A previously set model will be
unset. If model
is None
or not
specified, the old model will be unset.
Note
In PyGTK 2.4.0 the model could not be None
and did not default to None
.
gtk.ComboBox.get_model
def get_model()
Returns : | A gtk.TreeModel
or None . |
Note
This method is available in PyGTK 2.4 and above.
The get_model
() method returns the
value of the "model" property which contains the gtk.TreeModel
that is acting as data source for the combo_box or None
if no gtk.TreeModel
is
associated with the combo box.
gtk.ComboBox.append_text
def append_text(text
)
| A string. |
Note
This method is available in PyGTK 2.4 and above.
Warning
This method is deprecated since PyGTK 2.24 and should not be used in newly-written code.
Use gtk.ComboBoxText
instead.
The append_text
() method appends the
string specified by text
to the list of strings
stored in the combo box gtk.ListStore
. Note
that you can only use this method with combo boxes constructed with the
gtk.combo_box_new_text
()
function.
gtk.ComboBox.insert_text
def insert_text(position
, text
)
| A model index where the
text should be
inserted. |
| A string. |
Note
This method is available in PyGTK 2.4 and above.
Warning
This method is deprecated since PyGTK 2.24 and should not be used in newly-written code.
Use gtk.ComboBoxText
instead.
The insert_text
() method inserts the
string specified by text
in the combo box gtk.ListStore
at
the index specified by position
. Note that you can
only use this method with combo boxes constructed with the gtk.combo_box_new_text
()
function.
gtk.ComboBox.prepend_text
def prepend_text(text
)
| A string. |
Note
This method is available in PyGTK 2.4 and above.
Warning
This method is deprecated since PyGTK 2.24 and should not be used in newly-written code.
Use gtk.ComboBoxText
instead.
The prepend_text
() method prepends the
string specified by text
to the list of strings
stored in the gtk.ListStore
associated with the combo_box. Note that you can only use this method with
combo boxes constructed with the gtk.combo_box_new_text
()
function.
gtk.ComboBox.remove_text
def remove_text(position
)
| Index of the item to remove. |
Note
This method is available in PyGTK 2.4 and above.
Warning
This method is deprecated since PyGTK 2.24 and should not be used in newly-written code.
Use gtk.ComboBoxText
instead.
The remove_text
() method removes the
string at the index specified by position
in the
associated gtk.ListStore
. Note
that you can only use this function with combo boxes constructed with the
gtk.combo_box_new_text
()
function.
gtk.ComboBox.get_active_text
def get_active_text()
Returns : | The currently active text. |
Note
This method is available in PyGTK 2.6 and above.
Warning
This method is deprecated since PyGTK 2.24 and should not be used in newly-written code.
Use gtk.ComboBoxText
instead.
The get_active_text
() method returns
the currently active string or None
if no entry is
selected. Note that you can only use this function with combo boxes
constructed with the gtk.combo_box_new_text
()
function.
gtk.ComboBox.popup
def popup()
Note
This method is available in PyGTK 2.4 and above.
The popup
() method pops up the menu or
dropdown list of the combo box. This method is mostly intended for use
by accessibility technologies; applications should have little use for
it.
gtk.ComboBox.popdown
def popdown()
Note
This method is available in PyGTK 2.4 and above.
The popdown
() method hides the menu or
dropdown list of the combo box. This method is mostly intended for use by
accessibility technologies; applications should have little use for
it.
gtk.ComboBox.get_popup_accessible
def get_popup_accessible()
Returns : | the accessible object corresponding to the popup. |
Note
This method is available in PyGTK 2.6 and above.
The get_popup_accessible
() method gets
the accessible object corresponding to the popup. This method is mostly
intended for use by accessibility technologies; applications should have
little use for it.
gtk.ComboBox.set_row_separator_func
def set_row_separator_func(func
=None, data
=None)
| a function or
None |
| user data to pass to
func |
Note
This method is available in PyGTK 2.6 and above.
The set_row_separator_func
() method
sets the row separator function to func
, which is
used to determine if a row should be drawn as a separator. If func is
None
, no separators are drawn. This is the default
value.
The signature of func
is:
def func(model, iter, user_data):
where model
is the gtk.TreeModel
used by the combo box, iter
is a gtk.TreeIter
pointing at a row in model
and
user_data
is
data
. func
returns
True
if the row is a separator. A common way to implement
func
is to have a boolean column in
model
, that indicates if the row is a
separator.
gtk.ComboBox.get_add_tearoffs
def get_add_tearoffs()
Returns : | True if menus should have a
tearoff menuitem. |
Note
This method is available in PyGTK 2.6 and above.
The get_add_tearoffs
() method returns the
value of the "add-tearoffs" property.
gtk.ComboBox.set_add_tearoffs
def set_add_tearoffs(add_tearoffs
)
| if True add tearoff menu items |
Note
This method is available in PyGTK 2.6 and above.
The set_add_tearoffs
() method sets the
"add-tearoffs" property to the value of
add_tearoffs
. If add_tearoffs
is True
, the popup menu should have a tearoff menu
item.
gtk.ComboBox.get_focus_on_click
def get_focus_on_click()
Returns : | True if the combo box grabs
focus when it is clicked with the mouse. |
Note
This method is available in PyGTK 2.6 and above.
The get_focus_on_click
() method returns
the value of the "focus-on-click" property.
gtk.ComboBox.set_focus_on_click
def set_focus_on_click(focus_on_click
)
| if True the combo box grabs
focus when clicked with the mouse. |
Note
This method is available in PyGTK 2.6 and above.
The set_focus_on_click
() method sets the
value of the "focus-on-click" property to the value of
focus_on_click
. If
focus_on_click
is True
the combo
box grabs focus when clicked with the mouse.
gtk.ComboBox.get_title
def get_title()
Returns : | the menu's title in tearoff mode.. |
Note
This method is available in PyGTK 2.10 and above.
The get_title
() method returns the
value of the "tearoff-title" property that contains the current title
of the menu in tearoff mode. See the set_add_tearoffs()
method for more information.
Functions
gtk.combo_box_new_text
def gtk.combo_box_new_text()
Returns : | A new gtk.ComboBox
for text items. |
Note
This function is available in PyGTK 2.4 and above.
Warning
This function is deprecated since PyGTK 2.24 and should not be used in newly-written code.
Use gtk.ComboBoxText
instead.
The gtk.combo_box_new_text
() function is a
convenience function that constructs a new text combo box, which is a gtk.ComboBox
just
displaying strings. If you use this function to create a text combo box, you
should only manipulate its data source with the following convenience
methods: append_text
(),
insert_text
(),
prepend_text
()
and remove_text
().
Signals
The "changed" gtk.ComboBox Signal
def callback(combobox
, user_param1
, ...
)
| the combo box that received the signal |
| the first user parameter (if any) specified
with the connect () |
| additional user parameters (if any) |
Note
This signal is available in PyGTK 2.4 and above.
The "changed" signal is emitted when a new item in the combo box is selected.
The "move-active" gtk.ComboBox Signal
def callback(combobox
, scroll_type
, user_param1
, ...
)
| the combo box that received the signal |
| a GTK Scroll Type Constants |
| the first user parameter (if any) specified
with the connect () |
| additional user parameters (if any) |
Note
This signal is available in PyGTK 2.12 and above.
The "move-active" signal is a keybinding signal which gets emitted to move the active selection.
The "popdown" gtk.ComboBox Signal
def callback(combobox
, user_param1
, ...
)
| the combo box that received the signal |
| the first user parameter (if any) specified
with the connect () |
| additional user parameters (if any) |
Note
This signal is available in PyGTK 2.12 and above.
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.
The "popup" gtk.ComboBox Signal
def callback(combobox
, user_param1
, ...
)
| the combo box that received the signal |
| the first user parameter (if any) specified
with the connect () |
| additional user parameters (if any) |
Note
This signal is available in PyGTK 2.12 and above.
The "popup" signal is a keybinding signal which gets emitted to popup the combo box list. The default bindings for this signal are Alt+Down.