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

<?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">

  <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 &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 
      #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 
      #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;

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, &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));

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:
-->