forked from AuroraMiddleware/gtk
324b853954
2007-05-26 Matthias Clasen <mclasen@redhat.com> * gtk/migrating*.sgml: Some cleanups svn path=/trunk/; revision=17948
175 lines
5.6 KiB
Plaintext
175 lines
5.6 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:
|
|
-->
|