Gtk+/Gnome Application Development
Prev	Home	Next

Adding a Status Bar

Adding a status bar is simple enough. Simply call the aptly-named gnome_app_set_statusbar function (Figure 5) with your statusbar widget as the second argument.

However, there are some additional things to keep in mind. First, you can use either GtkStatusbar or GnomeAppBar as a statusbar. Second, you probably want to use the statusbar to display help about menu items as the user moves over them; Gnome comes with convenience functions to do this. This section describes the two status bar widgets; the section called Online Help discusses using the statusbar to display menu item help.

#include <libgnomeui/gnome-app.h>

void gnome_app_set_statusbar(GnomeApp* app, GtkWidget* statusbar);

Figure 5. Installing a Statusbar

`GnomeAppBar`

There's no real reason to prefer GnomeAppBar or GtkStatusbar; they simply have different APIs. The GnomeAppBar widget was written later, with several goals in mind:

To simplify the GtkStatusbar API.
To support an optional progress bar next to the status bar, similar to Netscape's.
Eventual support for "interactive" use in the tradition of the Emacs "minibuffer." This is unfinished in Gnome 1.0, however.

To create a GnomeAppBar, use gnome_appbar_new() (Figure 6). The constructor lets you configure the capabilities of GnomeAppBar: it can have a progress bar (or not), have a status text area (or not), and be interactive (or not). You must have either a status text area or a progress bar. GnomePreferencesType is a kind of extended boolean value:

GNOME_PREFERENCES_NEVER means the bar is never interactive.
GNOME_PREFERENCES_USER means the bar is interactive if the user has activated that feature as a Gnome-wide preference.
GNOME_PREFERENCES_ALWAYS means the bar is always interactive.

In Gnome 1.0, interactivity is incompletely implemented; so avoid GNOME_PREFERENCES_ALWAYS. There are some experimental Gnome functions which provide an abstraction of certain user interactions, allowing users to choose between dialogs and the Emacs-style minibuffer approach; when these are more developed, GNOME_PREFERENCES_USER will make sense even if you don't explicitly use the interactivity. So GNOME_PREFERENCES_USER is the recommended setting.

#include <libgnomeui/gnome-appbar.h>

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

Figure 6. GnomeAppBar Constructor

Using a GnomeAppBar is simple. The progress-bar element presents a GtkProgress interface; to use it, simply extract the GtkProgress with gnome_appbar_get_progress() (Figure 7) and use the GtkProgress functions. Note that you should not make assumptions about the particular subclass of GtkProgress; in particular, do not cast it to GtkProgressBar.

#include <libgnomeui/gnome-appbar.h>

GtkProgress* gnome_appbar_get_progress(GnomeAppBar* appbar);

Figure 7. Extracting GtkProgress

Status texts are stored in a stack; when the bar is refreshed, the top item of the stack is displayed. The bar is refreshed anytime you manipulate the stack. So pushing some text onto the status stack will display that text.

There are two other sources for the status text. You can set some "default" text; this is displayed if the stack is empty. The default default text is "". You can also set the status text without changing the stack; this "transient" text is immediately displayed, but not stored. On the next refresh (the next time you push, pop, or set the default), the text disappears forever, replaced by the top of the stack.

Figure 8 lists the functions to manipulate the status text. gnome_appbar_set_status() is used to set the transient status text; gnome_appbar_refresh() forces a refresh without changing the stack---this is useful to be sure any transient text has been cleared. The other functions should be obvious.

Note that you can use the GnomeAppBar as a simple label---one message at a time, always replacing the previous message---just stick to either setting the default or setting the transient text, and never use the stack.

#include <libgnomeui/gnome-appbar.h>

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

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

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

void gnome_appbar_pop(GnomeAppBar* appbar);

void gnome_appbar_clear_stack(GnomeAppBar* appbar);

void gnome_appbar_refresh(GnomeAppBar* appbar);

Figure 8. Setting GnomeAppBar Text

Gtk+/Gnome Application Development
Prev	Home	Next