gtk2/docs/reference/gtk/migrating-GtkComboBox.sgml

214 lines
8.2 KiB
Plaintext
Raw Normal View History

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<chapter id="gtk-migrating-GtkComboBox">
2005-05-16 19:34:39 +00:00
<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
2005-05-16 19:34:39 +00:00
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
2005-05-16 19:34:39 +00:00
#GtkComboBox for the non-editable case and #GtkComboBoxEntry for the
editable case.
The selection of the display style &mdash; menu or list &mdash;
is no longer done at the API level, but has been made themeable via
the style property #GtkComboBox:appearance.
</para>
<section id="migrating-GtkOptionMenu">
<title>Migrating from GtkOptionMenu to GtkComboBox</title>
<para>
Here is an example of a simple, but typical use of
2005-05-16 19:34:39 +00:00
#GtkOptionMenu:
<informalexample><programlisting>
GtkWidget *option_menu, *menu, *menu_item;
2005-05-16 19:34:39 +00:00
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"
2005-05-16 19:34:39 +00:00
signal on the option menu and use gtk_option_menu_get_history()
to retrieve the index of the selected item.
</para>
<para>
2005-05-16 19:34:39 +00:00
And here is how it would be done with a #GtkComboBox:
<informalexample><programlisting>
GtkWidget *combo_box;
2005-05-16 19:34:39 +00:00
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
#GtkComboBox::changed signal 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;
2005-05-16 19:34:39 +00:00
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>
2005-05-16 19:34:39 +00:00
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, &amp;iter);
gtk_list_store_set (store, &amp;iter, 0, pixbuf1, 1, "First Item", -1);
gtk_list_store_append (store, &amp;iter);
gtk_list_store_set (store, &amp;iter, 0, pixbuf2, 1, "Second Item", -1);
gtk_list_store_append (store, &amp;iter);
gtk_list_store_set (store, &amp;iter, 0, pixbuf3, 1, "Third Item", -1);
combo_box = gtk_combo_box_new_with_model (GTK_TREE_MODEL (store));
2005-05-16 19:34:39 +00:00
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);
2005-05-16 19:34:39 +00:00
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>
2005-05-16 19:34:39 +00:00
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");
2005-05-16 19:34:39 +00:00
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>
2005-05-16 19:34:39 +00:00
And here is how it would be done using #GtkComboBoxEntry:
<informalexample><programlisting>
2005-05-16 19:34:39 +00:00
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
2005-05-16 19:34:39 +00:00
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
2005-05-16 19:34:39 +00:00
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>
2005-05-16 19:34:39 +00:00
<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
2005-05-16 19:34:39 +00:00
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
2005-05-16 19:34:39 +00:00
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:
-->