Description
The GNOME druid is a system for assisting the user with installing a
service. It is roughly equivalent in functionality to the
"Wizards" available in Windows.
There are two major parts of the druid, the GnomeDruid widget, and
the set of GnomeDruidPage widgets. The GnomeDruid widget is the
main widget that interacts with the user. It has a Next, a
Prev, and a Cancel button, and acts as a container for the pages.
It is not a top-level window, so it needs to be put in a
GtkWindow in almost all cases. The GnomeDruidPage is a virtual
widget, from which all of the actual content of the page inherits
from. There are currently three of these available within
gnome-libs.
Creating a druid
GNOME druids are fairly simple to program with. You start by
creating a GnomeDruid into which you put all of your pages.
This widget will handle the presentation of the GnomeDruidPage
widgets.
You then create all appropriate GnomeDruidPage widgets. There
are three implementations of these in libgnomeui, although there
is no reason why more couldn't be written. They are the
GnomeDruidPageStart, the GnomeDruidPageStandard, and the
GnomeDruidPageFinish. The GnomeDruidPageStandard acts as a
GtkContainer, and is probably the most commonly used druid page.
The other ones, as their names might suggest, are used at the
endpoints of the druid. More information on the specific
properties of these widgets can be found on their respective
pages.
You will need to add the pages to the druid in order for them to
appear. The druid itself keeps an internal list of all pages, and
using the gnome_druid_prepend_page(), gnome_druid_append_page(),
and gnome_druid_insert_page() will place them into it.
Managing the control-flow in a druid
The control-flow in a druid is managed at the GnomeDruidPage
level, and is a little complex. The signals available are "back",
"next", "finish", "cancel" and "prepare", and all but the last are
triggered when their respective buttons are pressed. In the
absence of anything connected to these signals, the druid will
cycle through the pages in the order of the internal list, so for
a simple druid, just adding the pages in order is sufficient.
If the druid has some branching code, then it will be handled at
the point of the branch. The current page will emit the
appropriate "next" or "back" signal in this case. It is up to the
druid author to trap this signal when necessary and call
gnome_druid_set_page() in the handler to go to the correct page.
In addition, they will want to return TRUE to let the druid know
that it has handled the page change, and to prevent the druid from
following its list.
Details
gnome_druid_new ()
GtkWidget* gnome_druid_new (void); |
gnome_druid_set_buttons_sensitive ()
void gnome_druid_set_buttons_sensitive
(GnomeDruid *druid,
gboolean back_sensitive,
gboolean next_sensitive,
gboolean cancel_sensitive); |
Sets the sensitivity of the druid's control-buttons. If the
variables are TRUE, then they will be clickable. This function is used
primarily by the actual GnomeDruidPage widgets.
gnome_druid_set_show_finish ()
void gnome_druid_set_show_finish (GnomeDruid *druid,
gboolean show_finish); |
Sets the text on the last button on the druid. If show_finish
is TRUE, then the text becomes "Finish". If show_finish is FALSE, then the
text becomes "Cancel".
gnome_druid_prepend_page ()
This will prepend a GnomeDruidPage into the internal list of
pages that the druid has.
gnome_druid_insert_page ()
This will insert page after back_page into the list of
internal pages that the druid has. If back_page is not present in the list
or NULL, page will be prepended to the list.
gnome_druid_append_page ()
This will append page onto the end of the internal list.
gnome_druid_set_page ()
This will make page the currently showing page in the druid.
page must already be in the druid.