gtk2/docs/reference/gtk/migrating-GtkAssistant.sgml
Matthias Clasen 017a5e3d5b More work on GtkAssistant by Carlos Garnacho:
2006-01-28  Matthias Clasen  <mclasen@redhat.com>

	More work on GtkAssistant by Carlos Garnacho:

	* demos/gtk-demo/Makefile.am:
	* demos/gtk-demo/assistant.c: Add a  GtkAssistant demo.

	* gtk/gtkassistant.c: Handle focus, several small fixes to the
	flow computations.
2006-01-28 06:03:50 +00:00

171 lines
5.5 KiB
Plaintext

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