Gnome Developers' Information
Prev | Chapter 9. Talking to the user: GnomeDialog, GnomeMessageBox, GnomeAppBar, and utility functions. | Next

# Using GnomeAppBar directly

## Creating an AppBar

`GtkWidget *gnome_appbar_new` ( gboolean has_progress , gboolean has_status , GnomePreferencesType interactivity );

GnomeAppBar is a progress bar on the left, and a statusbar/minibuffer on the right. It can optionally be only a progress bar (dumb, but you can do it), or only a statusbar/minibuffer (if you have no progress to display).

The statusbar/minibuffer can be an interactive prompt a la Emacs or just a status display. (Eventually, anyway. For now interactive mode is broken.) This is specified with the `interactivity` parameter, which can have three values: GNOME_PREFERENCES_NEVER, GNOME_PREFERENCES_USER, or GNOME_PREFERENCES_ALWAYS. If you specify _NEVER or _ALWAYS, then interactivity will be prohibited or forced. Otherwise, a user setting provided by Gnome will determine interactivity.

## Using a GnomeAppBar to display status

The appbar displays one message at a time. There are three kinds of messages: transient status messages, messages on the stack, and the default message.

- Transient messages are displayed, overriding any other messages, but the appbar retains no knowledge of them; so they disappear forever as soon as the appbar is refreshed. `gnome_appbar_set_status()` creates a transient message.

- If no transient message has overwritten it, the top message on the stack is always displayed. `gnome_appbar_push()`, `gnome_appbar_pop()`, and `gnome_appbar_clear_stack()` manipulate the stack.

- If the stack is empty, the appbar displays the default message (which can be the empty string). The default message is set with `gnome_appbar_set_default()`.

It is possible and even encouraged to use only one of the three kinds of message. You can make the appbar as simple or as complicated as you like; with only `gnome_appbar_set_status()`, it's basically just a GtkLabel.

`void gnome_appbar_set_status` ( GnomeAppBar *appbar , const gchar *status );

Often you want to pop up a message that isn't very important, and you don't want to worry about removing it later. `gnome_appbar_set_status()` does this for you. It sets the message in the appbar until the next time the appbar is changed.

If you want, you can use the appbar with only this function. For simple applications it can be a nice approach.

`void gnome_appbar_set_default` ( GnomeAppBar *appbar , const gchar *default_status );

When there's no special status to display, the appbar is normally empty. However, if you prefer you can set a default message; this is a message that can never be removed from the message stack. To return to an empty appbar, set the default to an empty string.

`void gnome_appbar_push` ( GnomeAppBar *appbar , const gchar *status );

`void gnome_appbar_pop` ( GnomeAppBar *appbar );

`void gnome_appbar_clear_stack` ( GnomeAppBar *appbar );

GnomeAppBar maintains a stack of messages; it always displays the top message on the stack. (There's one exception: `gnome_appbar_set_status()` overrides the current top message temporarily.)

`void gnome_appbar_refresh` ( GnomeAppBar *appbar );

`gnome_appbar_refresh()` updates the appbar to reflect the current saved state. Basically this means any transient messages (created with `gnome_appbar_set_status()`) will disappear, to be replaced by the top of the stack or the default message.

## Using an AppBar to query the user

This doesn't work so well, so it's not documented. Basically you can put up a prompt, and get a signal if the user enters a response or cancels. It's useful to avoid a dialog if you just want to get a string or the like. But someone needs to write the proper widget, perhaps based on GtkEntry.

Prev | Home | Next
Talking to the user: GnomeDialog, GnomeMessageBox, GnomeAppBar, and utility functions. | Up | The abstract message utility functions