gtk2/docs/reference/gtk/migrating-GtkAssistant.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-GtkAssistant">
  <chapterinfo>
    <author>
      <firstname>Carlos</firstname>
      <surname>Garnacho</surname>
      <affiliation>
	<address>
	  <email>carlosg@gnome.org</email>
	</address>
      </affiliation>
    </author>
  </chapterinfo>

  <title>Migrating from GnomeDruid to GtkAssistant</title>

  <para>
    Since version 2.10, GTK+ provides the GtkAssistant widget as a replacement
    for the <structname>GnomeDruid</structname> widget in the libgnomeui 
    library.
  </para>

  <para>
    Conceptually, both <structname>GtkAssistant</structname> and
    <structname>GnomeDruid</structname> do the same task, but there are 
    several areas where the API has been completely redesigned, so this 
    chapter covers the main changes between both widgets.
  </para>

  <section id="inserting-pages">
    <title>Inserting pages</title>

    <para>
      <structname>GnomeDruid</structname> was implemented as a container for
	 <structname>GnomeDruidPage</structname> abstract objects, which are
         implemented by the <structname>GnomeDruidPageEdge</structname> and 
         <structname>GnomeDruidPageStandard</structname> widgets. Instead, 
         <structname>GtkAssistant</structname> allows any widget to be a page, 
         and implements per-page settings (such as page type or title) as 
         child properties. So instead of:
    </para>

    <programlisting>
/* Page 1 */
page = gnome_druid_page_edge_new (GNOME_EDGE_START);
gnome_druid_page_edge_set_test (GNOME_DRUID_PAGE_EDGE (page),
                                "Welcome to the assistant, it will make your life easier");
gtk_widget_show (page);
gnome_druid_append_page (GNOME_DRUID (druid), GNOME_DRUID_PAGE (page));

/* Page 2 */
page = gnome_druid_page_standard_new ();
gtk_container_add (GTK_CONTAINER (GNOME_DRUID_PAGE_STANDARD (page)->vbox,
                   create_page1 ());
gtk_widget_show_all (page);
gnome_druid_append_page (GNOME_DRUID (druid), GNOME_DRUID_PAGE (page));

/* Page 3 */
page = gnome_druid_page_edge_new (GNOME_EDGE_FINISH);
gnome_druid_page_edge_set_test (GNOME_DRUID_PAGE_EDGE (page),
                                "Now you are done, your life is easier");
gtk_widget_show (page);
gnome_druid_append_page (GNOME_DRUID (druid), GNOME_DRUID_PAGE (page));
    </programlisting>

    <para>
      You have to write:
    </para>

    <programlisting>
gtk_assistant_append_page (GTK_ASSISTANT (assistant),
                           gtk_label_new ("Welcome to the assistant, it will make your life easier"));
gtk_assistant_append_page (GTK_ASSISTANT (assistant),
                           create_page1 ());
gtk_assistant_append_page (GTK_ASSISTANT (assistant),
                           gtk_label_new ("Now you are done, your life is easier");
    </programlisting>
  </section>

  <section id="decorating-the-assistant-pages">
    <title>Decorating the assistant pages</title>

    <para>
      To decorate your assistant pages, <structname>GtkAssistant</structname> provides similar functions
	 to <structname>GnomeDruid</structname>, so you have to transform code like this:
    </para>

    <programlisting>
gnome_druid_page_edge_set_title (GNOME_DRUID_PAGE_EDGE (page), "Welcome");
gnome_druid_page_edge_set_logo (GNOME_DRUID_PAGE_EDGE (page), logo_pixbuf);
gnome_druid_page_edge_set_watermark (GNOME_DRUID_PAGE_EDGE (page), watermark_pixbuf);
    </programlisting>

    <para>
    Into this:
    </para>

    <programlisting>
gtk_assistant_set_page_title (GTK_ASSISTANT (assistant), page_widget, "Welcome");
gtk_assistant_set_page_header_image (GTK_ASSISTANT (assistant), page_widget, logo_pixbuf);
gtk_assistant_set_page_side_image (GTK_ASSISTANT (assistant), page_widget, watermark_pixbuf);
    </programlisting>

    <para>
      Where page_widget is the widget used as a page.
    </para>
  </section>

  <section id="setting-the-page-flow">
    <title>Setting the page flow</title>

    <para>
      Here is the area where <structname>GtkAssistant</structname> and <structname>GnomeDruid</structname>
	 differ the most. While <structname>GnomeDruid</structname> used the "next" and "back" signals from the 
	 <structname>GnomeDruidPage</structname>, <structname>GtkAssistant</structname> uses the following
	 techniques:
    </para>

    <itemizedlist>
      <listitem>
	   <para>gtk_assistant_set_forward_page_func (): Allows to define a GtkAssistantPageFunc to let the
	   assistant know which will be the following page given the current page.</para>
      </listitem>
      <listitem>
	   <para>gtk_assistant_set_page_complete (): Lets the assistant know whether the specified page is complete
	   or not, updating buttons state accordingly.</para>
      </listitem>
      <listitem>
	   <para>gtk_assistant_set_page_type (): Lets the assistant know the page role and update the buttons
	   state accordingly. Pages can have the following roles:</para>
	   <simplelist>
	     <member>Intro</member>
		<member>Content</member>
		<member>Progress</member>
		<member>Confirmation</member>
		<member>Summary</member>
	   </simplelist>
      </listitem>
    </itemizedlist>

    <para>
      A sample GtkAssistantPageFunc could look like this:
    </para>

    <programlisting>
static gint
forward_page_function (gint     current_page,
                       gpointer data)
{
  switch (current_page)
    {
    case 0:
      return 1;
    case 1:
      if (check_page1_data ())
	   return 2;
	 else
	   return 3;
    case 2:
      return 3;
    default:
      return -1;
    }
}
    </programlisting>

  </section>
</chapter>

<!--
Local variables:
mode: sgml
sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
End:
-->