Gnome User Interface Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GnomeDruid

## Name

GnomeDruid -- The main widget of the GNOME druid system.

## Synopsis

    #include <gnome.h>

    GtkWidget*  gnome_druid_new                 (void);
    void        gnome_druid_set_buttons_sensitive
                                                (GnomeDruid *druid,
                                                 gboolean back_sensitive,
                                                 gboolean next_sensitive,
                                                 gboolean cancel_sensitive);
    void        gnome_druid_set_show_finish     (GnomeDruid *druid,
                                                 gboolean show_finish);
    void        gnome_druid_prepend_page        (GnomeDruid *druid,
                                                 GnomeDruidPage *page);
    void        gnome_druid_insert_page         (GnomeDruid *druid,
                                                 GnomeDruidPage *back_page,
                                                 GnomeDruidPage *page);
    void        gnome_druid_append_page         (GnomeDruid *druid,
                                                 GnomeDruidPage *page);
    void        gnome_druid_set_page            (GnomeDruid *druid,
                                                 GnomeDruidPage *page);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GnomeDruid

## 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);

Returns : |

### 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.

`druid` : | A Druid.
`back_sensitive` : | The sensitivity of the back button.
`next_sensitive` : | The sensitivity of the next button.
`cancel_sensitive` : | The sensitivity of the cancel button.

### 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".

`druid` : | A Druid widget. # `show_finish`: If TRUE, then the "Cancel" button is changed to be "Finish"
`show_finish` : |

### 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.

`druid` : | A Druid widget.
`page` : | The page to be inserted.

### 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.

`druid` : | A Druid widget.
`back_page` : | The page prior to the page to be inserted.
`page` : | The page to insert.

### gnome_druid_append_page ()

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

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

`druid` : | A Druid widget.
`page` : | The page to be appended.

### 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.

`druid` : | A Druid widget.
`page` : | The page to be brought to the foreground.

## See Also

GnomeDruidPage, GnomeDruidPageStart, GnomeDruidPageStandard, GnomeDruidPageFinish

<<< Previous Page | Home | Up | Next Page >>>
GnomeDock | GnomeDruidPage