<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" >
<head><meta content="text/html;charset=&quot;utf-8&quot;" http-equiv="Content-type"/><link href="faldoc.css" rel="stylesheet" type="text/css"/><title> - Class GtkComboBox</title></head><body class="faldoc"><ul class="navi_top"><li class="top"><a href="index.html">Top: Table of contents</a></li>
<li class="up"><a href="gtk.html">Up: The Falcon GTK Binding module</a></li>
<li class="prev"><a href="gtk_GtkColorSelectionDialog.html">Previous: Class GtkColorSelectionDialog</a></li>
<li class="next"><a href="gtk_GtkComboBoxEntry.html">Next: Class GtkComboBoxEntry</a></li>
<li class="clear"></li>
</ul><div id="page_body"><h1><span class="toc_number">10.49</span>Class GtkComboBox</h1><p class="brief">A widget used to choose from a list of items </p>
<pre class="prototype">Class GtkComboBox</pre>
<p>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. </p>
<p>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. </p>
<p>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(). </p>
<table class="members">
<tbody><tr class="member_type"><td class="member_type" colspan="2">Methods</td></tr>
<tr><td><a href="#append_text">append_text</a></td><td>Appends string to the list of strings stored in combo_box. </td></tr>
<tr><td><a href="#get_active">get_active</a></td><td>Returns the index of the currently active item, or -1 if there's no active item. </td></tr>
<tr><td><a href="#get_active_text">get_active_text</a></td><td>Returns the currently active string in combo_box or NULL if none is selected. </td></tr>
<tr><td><a href="#get_add_tearoffs">get_add_tearoffs</a></td><td>Gets the current value of the :add-tearoffs property. </td></tr>
<tr><td><a href="#get_button_sensitivity">get_button_sensitivity</a></td><td>Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model. </td></tr>
<tr><td><a href="#get_column_span_column">get_column_span_column</a></td><td>Returns the column with column span information for combo_box. </td></tr>
<tr><td><a href="#get_focus_on_click">get_focus_on_click</a></td><td>Returns whether the combo box grabs focus when it is clicked with the mouse. </td></tr>
<tr><td><a href="#get_row_span_column">get_row_span_column</a></td><td>Returns the column with row span information for combo_box. </td></tr>
<tr><td><a href="#get_title">get_title</a></td><td>Gets the current title of the menu in tearoff mode. </td></tr>
<tr><td><a href="#insert_text">insert_text</a></td><td>Inserts string at position in the list of strings stored in combo_box. </td></tr>
<tr><td><a href="#new_text">new_text</a></td><td>Convenience function which constructs a new text combo box, which is a GtkComboBox just displaying strings. </td></tr>
<tr><td><a href="#popdown">popdown</a></td><td>Hides the menu or dropdown list of combo_box. </td></tr>
<tr><td><a href="#popup">popup</a></td><td>Pops up the menu or dropdown list of combo_box. </td></tr>
<tr><td><a href="#prepend_text">prepend_text</a></td><td>Prepends string to the list of strings stored in combo_box. </td></tr>
<tr><td><a href="#remove_text">remove_text</a></td><td>Removes the string at position from combo_box. </td></tr>
<tr><td><a href="#set_active">set_active</a></td><td>Sets the active item of combo_box to be the item at index. </td></tr>
<tr><td><a href="#set_add_tearoffs">set_add_tearoffs</a></td><td>Sets whether the popup menu should have a tearoff menu item. </td></tr>
<tr><td><a href="#set_button_sensitivity">set_button_sensitivity</a></td><td>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). </td></tr>
<tr><td><a href="#set_column_span_column">set_column_span_column</a></td><td>Sets the column with column span information for combo_box to be column_span. </td></tr>
<tr><td><a href="#set_focus_on_click">set_focus_on_click</a></td><td>Sets whether the combo box will grab focus when it is clicked with the mouse. </td></tr>
<tr><td><a href="#set_row_span_column">set_row_span_column</a></td><td>Sets the column with row span information for combo_box to be row_span. </td></tr>
<tr><td><a href="#set_title">set_title</a></td><td>Sets the menu's title in tearoff mode. </td></tr>
<tr><td><a href="#set_wrap_width">set_wrap_width</a></td><td>Sets the wrap width of combo_box to be width. </td></tr>
<tr><td><a href="#signal_changed">signal_changed</a></td><td>Connect a VMSlot to the combo box changed signal and return it </td></tr>
<tr><td><a href="#signal_move_active">signal_move_active</a></td><td>Connect a VMSlot to the combo box move-active signal and return it </td></tr>
<tr><td><a href="#signal_popdown">signal_popdown</a></td><td>Connect a VMSlot to the combo box popdown signal and return it </td></tr>
<tr><td><a href="#signal_popup">signal_popup</a></td><td>Connect a VMSlot to the combo box popup signal and return it </td></tr>
</tbody>
</table>
<h2>Methods</h2><h3><a name="append_text">append_text</a></h3><p class="brief">Appends string to the list of strings stored in combo_box. </p>
<pre class="prototype">GtkComboBox.append_text( text )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">text</td><td class="content"> a string </td></tr>
</tbody>
</table>
<p>Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text(). </p>
<h3><a name="get_active">get_active</a></h3><p class="brief">Returns the index of the currently active item, or -1 if there's no active item. </p>
<pre class="prototype">GtkComboBox.get_active()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">An integer which is the index of the currently active item, or -1 if there's no active item. </td></tr>
</tbody>
</table>
<p>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. </p>
<h3><a name="get_active_text">get_active_text</a></h3><p class="brief">Returns the currently active string in combo_box or NULL if none is selected. </p>
<pre class="prototype">GtkComboBox.get_active_text()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">the currently active text </td></tr>
</tbody>
</table>
<p>Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text() and with GtkComboBoxEntrys. </p>
<h3><a name="get_add_tearoffs">get_add_tearoffs</a></h3><p class="brief">Gets the current value of the :add-tearoffs property. </p>
<pre class="prototype">GtkComboBox.get_add_tearoffs()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">the current value of the :add-tearoffs property. </td></tr>
</tbody>
</table>
<h3><a name="get_button_sensitivity">get_button_sensitivity</a></h3><p class="brief">Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model. </p>
<pre class="prototype">GtkComboBox.get_button_sensitivity()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">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. </td></tr>
</tbody>
</table>
<h3><a name="get_column_span_column">get_column_span_column</a></h3><p class="brief">Returns the column with column span information for combo_box. </p>
<pre class="prototype">GtkComboBox.get_column_span_column()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">the column span column </td></tr>
</tbody>
</table>
<h3><a name="get_focus_on_click">get_focus_on_click</a></h3><p class="brief">Returns whether the combo box grabs focus when it is clicked with the mouse. </p>
<pre class="prototype">GtkComboBox.get_focus_on_click()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">TRUE if the combo box grabs focus when it is clicked with the mouse. </td></tr>
</tbody>
</table>
<h3><a name="get_row_span_column">get_row_span_column</a></h3><p class="brief">Returns the column with row span information for combo_box. </p>
<pre class="prototype">GtkComboBox.get_row_span_column()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">the row span column. </td></tr>
</tbody>
</table>
<h3><a name="get_title">get_title</a></h3><p class="brief">Gets the current title of the menu in tearoff mode. </p>
<pre class="prototype">GtkComboBox.get_title()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">the menu's title in tearoff mode. </td></tr>
</tbody>
</table>
<h3><a name="insert_text">insert_text</a></h3><p class="brief">Inserts string at position in the list of strings stored in combo_box. </p>
<pre class="prototype">GtkComboBox.insert_text( position, text )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">position</td><td class="content"> An index to insert text </td></tr>
<tr class="param"><td class="name">text</td><td class="content"> A string </td></tr>
</tbody>
</table>
<p>Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text(). </p>
<h3><a name="new_text">new_text</a></h3><p class="brief">Convenience function which constructs a new text combo box, which is a GtkComboBox just displaying strings. </p>
<pre class="prototype">GtkComboBox.new_text()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">A new text combo box </td></tr>
</tbody>
</table>
<p>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(). </p>
<h3><a name="popdown">popdown</a></h3><p class="brief">Hides the menu or dropdown list of combo_box. </p>
<pre class="prototype">GtkComboBox.popdown()</pre>
<p>This function is mostly intended for use by accessibility technologies; applications should have little use for it. </p>
<h3><a name="popup">popup</a></h3><p class="brief">Pops up the menu or dropdown list of combo_box. </p>
<pre class="prototype">GtkComboBox.popup()</pre>
<p>This function is mostly intended for use by accessibility technologies; applications should have little use for it. </p>
<h3><a name="prepend_text">prepend_text</a></h3><p class="brief">Prepends string to the list of strings stored in combo_box. </p>
<pre class="prototype">GtkComboBox.prepend_text( text )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">text</td><td class="content"> A string </td></tr>
</tbody>
</table>
<p>Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text(). </p>
<h3><a name="remove_text">remove_text</a></h3><p class="brief">Removes the string at position from combo_box. </p>
<pre class="prototype">GtkComboBox.remove_text( position )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">position</td><td class="content"> Index of the item to remove </td></tr>
</tbody>
</table>
<p>Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text(). </p>
<h3><a name="set_active">set_active</a></h3><p class="brief">Sets the active item of combo_box to be the item at index. </p>
<pre class="prototype">GtkComboBox.set_active( index )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">index</td><td class="content"> An index in the model passed during construction, or -1 to have no active item </td></tr>
</tbody>
</table>
<h3><a name="set_add_tearoffs">set_add_tearoffs</a></h3><p class="brief">Sets whether the popup menu should have a tearoff menu item. </p>
<pre class="prototype">GtkComboBox.set_add_tearoffs( add_tearoffs )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">add_tearoffs</td><td class="content"> true to add tearoff menu items </td></tr>
</tbody>
</table>
<h3><a name="set_button_sensitivity">set_button_sensitivity</a></h3><p class="brief">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). </p>
<pre class="prototype">GtkComboBox.set_button_sensitivity( sensitivity )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">sensitivity</td><td class="content"> (GtkSensitivityType) specify the sensitivity of the dropdown button </td></tr>
</tbody>
</table>
<h3><a name="set_column_span_column">set_column_span_column</a></h3><p class="brief">Sets the column with column span information for combo_box to be column_span. </p>
<pre class="prototype">GtkComboBox.set_column_span_column( column_span )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">column_span</td><td class="content"> A column in the model passed during construction </td></tr>
</tbody>
</table>
<p>The column span column contains integers which indicate how many columns an item should span. </p>
<h3><a name="set_focus_on_click">set_focus_on_click</a></h3><p class="brief">Sets whether the combo box will grab focus when it is clicked with the mouse. </p>
<pre class="prototype">GtkComboBox.set_focus_on_click( focus_on_click )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">focus_on_click</td><td class="content"> whether the combo box grabs focus when clicked with the mouse </td></tr>
</tbody>
</table>
<p>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. </p>
<h3><a name="set_row_span_column">set_row_span_column</a></h3><p class="brief">Sets the column with row span information for combo_box to be row_span. </p>
<pre class="prototype">GtkComboBox.set_row_span_column( row_span )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">row_span</td><td class="content"> A column in the model passed during construction. </td></tr>
</tbody>
</table>
<p>The row span column contains integers which indicate how many rows an item should span. </p>
<h3><a name="set_title">set_title</a></h3><p class="brief">Sets the menu's title in tearoff mode. </p>
<pre class="prototype">GtkComboBox.set_title( title )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">title</td><td class="content"> a title for the menu in tearoff mode </td></tr>
</tbody>
</table>
<h3><a name="set_wrap_width">set_wrap_width</a></h3><p class="brief">Sets the wrap width of combo_box to be width. </p>
<pre class="prototype">GtkComboBox.set_wrap_width( width )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">width</td><td class="content"> 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. </td></tr>
</tbody>
</table>
<h3><a name="signal_changed">signal_changed</a></h3><p class="brief">Connect a VMSlot to the combo box changed signal and return it </p>
<pre class="prototype">GtkComboBox.signal_changed()</pre>
<p>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. </p>
<h3><a name="signal_move_active">signal_move_active</a></h3><p class="brief">Connect a VMSlot to the combo box move-active signal and return it </p>
<pre class="prototype">GtkComboBox.signal_move_active()</pre>
<p>The move-active signal is a keybinding signal which gets emitted to move the active selection. </p>
<p>The callback function is passed a GtkScrollType as argument. </p>
<h3><a name="signal_popdown">signal_popdown</a></h3><p class="brief">Connect a VMSlot to the combo box popdown signal and return it </p>
<pre class="prototype">GtkComboBox.signal_popdown()</pre>
<p>The popdown signal is a keybinding signal which gets emitted to popdown the combo box list. </p>
<p>The default bindings for this signal are Alt+Up and Escape. </p>
<h3><a name="signal_popup">signal_popup</a></h3><p class="brief">Connect a VMSlot to the combo box popup signal and return it </p>
<pre class="prototype">GtkComboBox.signal_popup()</pre>
<p>The popup signal is a keybinding signal which gets emitted to popup the combo box list. </p>
<p>The default binding for this signal is Alt+Down. </p>
</div><ul class="navi_bottom"><li class="top"><a href="index.html">Top: Table of contents</a></li>
<li class="up"><a href="gtk.html">Up: The Falcon GTK Binding module</a></li>
<li class="prev"><a href="gtk_GtkColorSelectionDialog.html">Previous: Class GtkColorSelectionDialog</a></li>
<li class="next"><a href="gtk_GtkComboBoxEntry.html">Next: Class GtkComboBoxEntry</a></li>
<li class="clear"></li>
</ul><div class="signature">Made with <a href="faldoc 3.0">http://www.falconpl.org</a></div></body></html>
