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

# GnomeAppBar

## Name

GnomeAppBar -- Statusbar/Progress/Minibuffer widget

## Synopsis

    #include <gnome.h>

    struct      GnomeAppBar;
    #define     GNOME_APPBAR_HAS_STATUS         (appbar)
    #define     GNOME_APPBAR_HAS_PROGRESS       (appbar)
    struct      GnomeAppBarMsg;
    #define     GNOME_APPBAR_INTERACTIVE        (ab)
    GtkWidget*  gnome_appbar_new                (gboolean has_progress,
                                                 gboolean has_status,
                                                 GnomePreferencesType interactivity);
    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_set_progress       (GnomeAppBar *appbar,
                                                 gfloat percentage);
    GtkProgress* gnome_appbar_get_progress      (GnomeAppBar *appbar);
    void        gnome_appbar_refresh            (GnomeAppBar *appbar);
    void        gnome_appbar_set_prompt         (GnomeAppBar *appbar,
                                                 const gchar *prompt,
                                                 gboolean modal);
    void        gnome_appbar_clear_prompt       (GnomeAppBar *appbar);
    gchar*      gnome_appbar_get_response       (GnomeAppBar *appbar);
    void        gnome_appbar_construct          (GnomeAppBar *ab,
                                                 gboolean has_progress,
                                                 gboolean has_status,
                                                 GnomePreferencesType interactivity);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkBox
                         +----GtkHBox
                               +----GnomeAppBar

## Description

A bar that GNOME applications put on the bottom of the windows to display status, progress, hints for menu items or a minibuffer for getting some sort of response. It has a stack for status messages

## Details

### struct GnomeAppBar

    struct GnomeAppBar;

### GNOME_APPBAR_HAS_STATUS()

    #define GNOME_APPBAR_HAS_STATUS(appbar) (GNOME_APPBAR(appbar)->status != NULL)

Returns whether the appbar contains a statusbar widget. For internal use. Don't use.

`appbar` : | appbar to check

### GNOME_APPBAR_HAS_PROGRESS()

    #define GNOME_APPBAR_HAS_PROGRESS(appbar) (GNOME_APPBAR(appbar)->progress != NULL)

Returns whether the appbar has a progress widget. For internal use. Don't use.

`appbar` : | appbar to check

### struct GnomeAppBarMsg

    struct GnomeAppBarMsg;

### GNOME_APPBAR_INTERACTIVE()

    #define GNOME_APPBAR_INTERACTIVE(ab) ((ab) ? (ab)->interactive : FALSE)

Returns whether the appbar has a minibuffer-style interactive status display. For internal use. Don't use.

`ab` : | appbar to check

### gnome_appbar_new ()

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

Create a new GNOME application status bar. If `has_progress` is `TRUE`, a small progress bar widget will be created, and placed on the left side of the appbar. If `has_status` is `TRUE`, a status bar, possibly an editable one, is created.

`interactivity` determines whether the appbar is an interactive "minibuffer" or just a status bar. If it is set to `GNOME_PREFERENCES_NEVER`, it is never interactive. If it is set to `GNOME_PREFERENCES_USER` we respect user preferences from ui-properties. If it's `GNOME_PREFERENCES_ALWAYS` we are interactive whether the user likes it or not. Basically, if your app supports both interactive and not (for example, if you use the gnome-app-util interfaces), you should use `GNOME_PREFERENCES_USER`. Otherwise, use the setting you support. Please note that "interactive" mode is not functional now; GtkEntry is inadequate and so a custom widget will be written eventually.

`has_progress` : | `TRUE` if appbar needs progress bar widget, `FALSE` if not
`has_status` : | `TRUE` if appbar needs status bar widget, `FALSE` if not
`interactivity` : | Level of user activity required
Returns : | Pointer to new GNOME appbar widget.

### gnome_appbar_set_status ()

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

Sets the status label without changing widget state; next set or push will destroy this permanently.

`appbar` : | Pointer to GNOME appbar object.
`status` : | Text to which status label will be set.

### gnome_appbar_set_default ()

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

What to show when showing nothing else; defaults to nothing.

`appbar` : | Pointer to GNOME appbar object
`default_status` : | Text for status label

### gnome_appbar_push ()

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

Push a new status message onto the status bar stack, and display it.

`appbar` : | Pointer to GNOME appbar object
`status` : | Text of status message.

### gnome_appbar_pop ()

    void        gnome_appbar_pop                (GnomeAppBar *appbar);

Remove current status message, and display previous status message, if any. It is OK to call this with an empty stack.

`appbar` : | Pointer to GNOME appbar object

### gnome_appbar_clear_stack ()

    void        gnome_appbar_clear_stack        (GnomeAppBar *appbar);

Remove all status messages from appbar, and display default status message (if present).

`appbar` : | Pointer to GNOME appbar object

### gnome_appbar_set_progress ()

    void        gnome_appbar_set_progress       (GnomeAppBar *appbar,
                                                 gfloat percentage);

Sets progress bar to the given percentage. Pure sugar - with a bad name, in light of the get_progress name which is not the opposite of set_progress. Maybe this function should die.

`appbar` : | Pointer to GNOME appbar object
`percentage` : | Percentage to which progress bar should be set.

### gnome_appbar_get_progress ()

    GtkProgress* gnome_appbar_get_progress      (GnomeAppBar *appbar);

Returns &GtkProgress widget pointer, so that the progress bar may be manipulated further.

`appbar` : | Pointer to GNOME appbar object
Returns : | Pointer to appbar's progress bar object. May be NULL if the appbar has no progress object.

### gnome_appbar_refresh ()

    void        gnome_appbar_refresh            (GnomeAppBar *appbar);

Reflect the current state of stack/default. Useful to force a set_status to disappear.

`appbar` : | Pointer to GNOME appbar object

### gnome_appbar_set_prompt ()

    void        gnome_appbar_set_prompt         (GnomeAppBar *appbar,
                                                 const gchar *prompt,
                                                 gboolean modal);

Put a prompt in the appbar and wait for a response. When the user responds or cancels, a user_response signal is emitted.

`appbar` : | Pointer to GNOME appbar object.
`prompt` : | Text of the prompt message.
`modal` : | If `TRUE`, grabs input.

### gnome_appbar_clear_prompt ()

    void        gnome_appbar_clear_prompt       (GnomeAppBar *appbar);

Remove any prompt.

`appbar` : | Pointer to GNOME appbar object

### gnome_appbar_get_response ()

    gchar*      gnome_appbar_get_response       (GnomeAppBar *appbar);

Get the response to the prompt, if any. Result must be g_free'd.

`appbar` : | Pointer to GNOME appbar object
Returns : | Text from appbar entry widget, as entered by user.

### gnome_appbar_construct ()

    void        gnome_appbar_construct          (GnomeAppBar *ab,
                                                 gboolean has_progress,
                                                 gboolean has_status,
                                                 GnomePreferencesType interactivity);

For use to bindings in languages other than C. Don't use.

`ab` : | Pointer to GNOME appbar object.
`has_progress` : | `TRUE` if appbar needs progress bar widget.
`has_status` : | `TRUE` if appbar needs status bar widget.
`interactivity` : | See gnome_appbar_new() explanation.

## See Also

GnomeApp

<<< Previous Page | Home | Up | Next Page >>>
GnomeApp | GnomeCalculator