gtk2/docs/reference/gtk/migrating-GtkAssistant.sgml
Stefan Kost 804a06b859 Bug 540967 – docs build slowly because of entities
* gtk/building.sgml:
	* gtk/changes-1.2.sgml:
	* gtk/changes-2.0.sgml:
	* gtk/compiling.sgml:
	* gtk/directfb.sgml:
	* gtk/glossary.xml:
	* gtk/gtk-docs.sgml:
	* gtk/gtk-query-immodules-2.0.xml:
	* gtk/gtk-update-icon-cache.xml:
	* gtk/migrating-GtkAboutDialog.sgml:
	* gtk/migrating-GtkAction.sgml:
	* gtk/migrating-GtkAssistant.sgml:
	* gtk/migrating-GtkBuilder.sgml:
	* gtk/migrating-GtkColorButton.sgml:
	* gtk/migrating-GtkComboBox.sgml:
	* gtk/migrating-GtkFileChooser.sgml:
	* gtk/migrating-GtkIconView.sgml:
	* gtk/migrating-GtkLinkButton.sgml:
	* gtk/migrating-GtkRecentChooser.sgml:
	* gtk/migrating-GtkTooltip.sgml:
	* gtk/migrating-checklist.sgml:
	* gtk/osx.sgml:
	* gtk/other_software.sgml:
	* gtk/question_index.sgml:
	* gtk/resources.sgml:
	* gtk/running.sgml:
	* gtk/text_widget.sgml:
	* gtk/tree_widget.sgml:
	* gtk/visual_index.xml:
	* gtk/windows.sgml:
	* gtk/x11.sgml:
	  Use xi:include to speed up doc-build. Remove some unused entities.


svn path=/trunk/; revision=20812
2008-07-10 03:27:56 +00:00

179 lines
5.7 KiB
XML

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