forked from AuroraMiddleware/gtk
211 lines
8.1 KiB
Plaintext
211 lines
8.1 KiB
Plaintext
<chapter id="gtk-migrating-GtkComboBox">
|
|
|
|
<title>Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and
|
|
GtkComboBoxEntry</title>
|
|
|
|
<para>
|
|
Prior to 2.4, GTK+ offered two widgets for the task of selecting one
|
|
item from a list of options. #GtkOptionMenu presents the list of
|
|
options as a menu while #GtkCombo presents them in a Windows-style list
|
|
popup. The only difference between the two is that a #GtkCombo allows to
|
|
manually edit the selected value, while the #GtkOptionMenu does not.
|
|
</para>
|
|
<para>
|
|
In GTK+ 2.4, a unified API for list selection was introduced, with
|
|
#GtkComboBox for the non-editable case and #GtkComboBoxEntry for the
|
|
editable case.
|
|
The selection of the display style — menu or list —
|
|
is no longer done at the API level, but has been made themeable via
|
|
the style property
|
|
<link linkend="GtkComboBox--appearance">GtkComboBox::appearance</link>.
|
|
</para>
|
|
|
|
<section id="migrating-GtkOptionMenu">
|
|
<title>Migrating from GtkOptionMenu to GtkComboBox</title>
|
|
|
|
<para>
|
|
Here is an example of a simple, but typical use of
|
|
#GtkOptionMenu:
|
|
<informalexample><programlisting>
|
|
GtkWidget *option_menu, *menu, *menu_item;
|
|
|
|
option_menu = gtk_option_menu_new (<!-- -->);
|
|
menu = gtk_menu_new (<!-- -->);
|
|
|
|
menu_item = gtk_menu_item_new_with_label ("First Item");
|
|
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
|
|
gtk_widget_show (menu_item);
|
|
menu_item = gtk_menu_item_new_with_label ("Second Item");
|
|
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
|
|
gtk_widget_show (menu_item);
|
|
menu_item = gtk_menu_item_new_with_label ("Third Item");
|
|
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
|
|
gtk_widget_show (menu_item);
|
|
|
|
gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu);
|
|
</programlisting></informalexample>
|
|
In order to react to the user's selection, connect to the "changed"
|
|
signal on the option menu and use gtk_option_menu_get_history()
|
|
to retrieve the index of the selected item.
|
|
</para>
|
|
<para>
|
|
And here is how it would be done with a #GtkComboBox:
|
|
<informalexample><programlisting>
|
|
GtkWidget *combo_box;
|
|
|
|
combo_box = gtk_combo_box_new_text (<!-- -->);
|
|
|
|
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item");
|
|
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item");
|
|
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item");
|
|
</programlisting></informalexample>
|
|
In order to react to the user's selection, connect to the "changed"
|
|
signal on the combo box and use gtk_combo_box_get_active()
|
|
to retrieve the index of the selected item.
|
|
</para>
|
|
|
|
<para>
|
|
A slightly more complex example involving images:
|
|
<informalexample><programlisting>
|
|
GtkWidget *option_menu, *menu, *menu_item;
|
|
|
|
option_menu = gtk_option_menu_new (<!-- -->);
|
|
menu = gtk_menu_new (<!-- -->);
|
|
|
|
menu_item = gtk_image_menu_item_new_with_label ("First Item");
|
|
gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf1));
|
|
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
|
|
gtk_widget_show (menu_item);
|
|
menu_item = gtk_image_menu_item_new_with_label ("Second Item");
|
|
gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf2));
|
|
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
|
|
gtk_widget_show (menu_item);
|
|
menu_item = gtk_image_menu_item_new_with_label ("Third Item");
|
|
gtk_image_menu_item_set_image (gtk_image_new_from_pixbuf (pixbuf3));
|
|
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
|
|
gtk_widget_show (menu_item);
|
|
|
|
gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu);
|
|
</programlisting></informalexample>
|
|
</para>
|
|
<para>
|
|
can be done using a #GtkComboBox as follows:
|
|
<informalexample><programlisting>
|
|
GtkListStore *store;
|
|
GtkTreeIter iter;
|
|
GtkCellRenderer *renderer;
|
|
GtkWidget *combo_box;
|
|
|
|
store = gtk_list_store_new (2, GDK_TYPE_PIXBUF, G_TYPE_STRING);
|
|
|
|
gtk_list_store_append (store, &iter);
|
|
gtk_list_store_set (store, &iter, 0, pixbuf1, 1, "First Item", -1);
|
|
gtk_list_store_append (store, &iter);
|
|
gtk_list_store_set (store, &iter, 0, pixbuf2, 1, "Second Item", -1);
|
|
gtk_list_store_append (store, &iter);
|
|
gtk_list_store_set (store, &iter, 0, pixbuf3, 1, "Third Item", -1);
|
|
|
|
combo_box = gtk_combo_box_new_with_model (GTK_TREE_MODEL (store));
|
|
|
|
renderer = gtk_cell_renderer_pixbuf_new (<!-- -->);
|
|
gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo_box), renderer, FALSE);
|
|
gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer,
|
|
"pixbuf", 0,
|
|
NULL);
|
|
|
|
renderer = gtk_cell_renderer_text_new (<!-- -->);
|
|
gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo_box), renderer, TRUE);
|
|
gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo_box), renderer,
|
|
"text", 1,
|
|
NULL);
|
|
</programlisting></informalexample>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="migrating-GtkCombo">
|
|
<title>Migrating from GtkCombo to GtkComboBoxEntry</title>
|
|
|
|
<para>
|
|
Here is an example of a simple, but typical use of a #GtkCombo:
|
|
<informalexample><programlisting>
|
|
GtkWidget *combo;
|
|
GList *items = NULL;
|
|
|
|
items = g_list_append (items, "First Item");
|
|
items = g_list_append (items, "Second Item");
|
|
items = g_list_append (items, "Third Item");
|
|
|
|
combo = gtk_combo_new (<!-- -->);
|
|
gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
|
|
</programlisting></informalexample>
|
|
In order to react to the user's selection, connect to the "changed"
|
|
signal on the combo and use
|
|
<literal>gtk_entry_get_text (GTK_ENTRY (combo->entry))</literal>
|
|
to retrieve the selected text.
|
|
</para>
|
|
<para>
|
|
And here is how it would be done using #GtkComboBoxEntry:
|
|
<informalexample><programlisting>
|
|
combo_box = gtk_combo_box_entry_new_text (<!-- -->);
|
|
|
|
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "First Item");
|
|
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item");
|
|
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item");
|
|
</programlisting></informalexample>
|
|
In order to react to the user's selection, connect to the "changed"
|
|
signal on the combo and use
|
|
<literal>gtk_entry_get_text (GTK_ENTRY (GTK_BIN (combo_box)->child))</literal>
|
|
to retrieve the selected text.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="new-features-GtkComboBox">
|
|
<title>New features</title>
|
|
|
|
<para>
|
|
The new widgets have more to offer than a mere combination of the
|
|
features of #GtkOptionMenu and #GtkCombo. Notable new features
|
|
include:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Grid mode</term>
|
|
<listitem><para>Sometimes it is preferable to display the available
|
|
options not in a linear list, but in a grid. A typical example
|
|
would be a "color combo" where the individual items are small
|
|
square color swatches. The new widgets support gridded display
|
|
with the functions
|
|
gtk_combo_box_set_wrap_width(),
|
|
gtk_combo_box_set_row_span_column() and
|
|
gtk_combo_box_set_column_span_column().
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Display of icons</term>
|
|
<listitem><para>An often-heard complaint about #GtkOptionMenu is that
|
|
the icons which appear in the image menu items in its menu are not
|
|
displayed in the button showing the selected item. This limitation
|
|
has been removed in #GtkComboBox; the selected item appears in the
|
|
same way as the options in the popup.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Full tree model power</term>
|
|
<listitem><para>
|
|
Since the new widgets are built around the same models that are
|
|
used for #GtkTreeView, all of the powerful machinery of tree models
|
|
and cell renderers can be used.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</section>
|
|
|
|
</chapter>
|
|
|
|
<!--
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
|
|
End:
|
|
-->
|