Whole document tree
| Gnome Developers' Information | ||
|---|---|---|
| Prev | Chapter 9. Talking to the user: GnomeDialog, GnomeMessageBox, GnomeAppBar, and utility functions. | Next |
9.2. Using GnomeAppBar directly
9.2.1. Creating an AppBar
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.
9.2.2. 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.
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.
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.
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.)
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.
9.2.3. 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.