GnomeDruid

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.

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 ()

void        gnome_druid_prepend_page        (GnomeDruid *druid,
                                             GnomeDruidPage *page);

This will prepend a GnomeDruidPage into the internal list of pages that the druid has.

gnome_druid_insert_page ()

void        gnome_druid_insert_page         (GnomeDruid *druid,
                                             GnomeDruidPage *back_page,
                                             GnomeDruidPage *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 ()

void        gnome_druid_append_page         (GnomeDruid *druid,
                                             GnomeDruidPage *page);

This will append page onto the end of the internal list.

gnome_druid_set_page ()

void        gnome_druid_set_page            (GnomeDruid *druid,
                                             GnomeDruidPage *page);

This will make page the currently showing page in the druid. page must already be in the druid.