# GnomeAppBar

## Name

GnomeAppBar -- An application status and progress bar widget

## Synopsis

    #include <libgnomeui/libgnomeui.h>

    #define     GNOME_APPBAR_HAS_STATUS         (appbar)
    #define     GNOME_APPBAR_HAS_PROGRESS       (appbar)
    #define     GNOME_APPBAR_INTERACTIVE        (ab)
    struct      GnomeAppBar;
    GtkWidget*  gnome_appbar_new                (gboolean has_progress,
                                                 gboolean has_status,
                                                 GnomePreferencesType interactivity);
    void        gnome_appbar_set_status         (GnomeAppBar *appbar,
                                                 const gchar *status);
    GtkWidget*  gnome_appbar_get_status         (GnomeAppBar *appbar);
    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_percentage
                                                (GnomeAppBar *appbar,
                                                 gfloat percentage);
    GtkProgressBar* 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);

## Object Hierarchy

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

## Implemented Interfaces

GnomeAppBar implements AtkImplementorIface.

## Properties

      "has-progress"         gboolean             : Read / Write / Construct
      "has-status"           gboolean             : Read / Write / Construct
      "interactivity"        GnomePreferencesType : Read / Write / Construct

## Signal Prototypes

    "clear-prompt"
                void        user_function      (GnomeAppBar *appbar,
                                                gpointer user_data);
    "user-response"
                void        user_function      (GnomeAppBar *appbar,
                                                gpointer user_data);

## Description

A GnomeAppBar widget sits (usually) at the bottom of an application window and contains a progress bar (for indicating time consuming tasks and their completion status) and/or a status bar for sending short one-line message to the user. It is also possible (in theory) for the user to edit the contents of the status bar, should the application developer choose to allow that, however note that this is not really working in the present implementation, so developers are recommended to avoid using interactive status bars and use proper editable widgets instead.

## Details

### GNOME_APPBAR_HAS_STATUS()

    #define GNOME_APPBAR_HAS_STATUS(appbar) (gnome_appbar_get_status(GNOME_APPBAR(appbar)) != NULL)

Whether or not the application bar contains a status box.

`appbar` : | A GnomeAppBar instance.
Returns : | `TRUE` is a status box is contained in the appbar.

### GNOME_APPBAR_HAS_PROGRESS()

    #define GNOME_APPBAR_HAS_PROGRESS(appbar) (gnome_appbar_get_progress(GNOME_APPBAR(appbar)) != NULL)

Whether or not the application bar contains a status box.

`appbar` : | A GnomeAppBar instance.
Returns : | `TRUE` is a status box is contained in the appbar.

### GNOME_APPBAR_INTERACTIVE()

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

Whether or not the user can edit the text in the statusbar portion of a GnomeAppBar instance.

`ab` : | A GnomeAppBar instance.
Returns : | `TRUE` if the user can edit the statusbar text.

### struct GnomeAppBar

    struct GnomeAppBar;

This widget contains the status bar and progress bar (if they are requested). After creating a GnomeAppBar widget (via gnome_appbar_new(), for example), it can then be passed to gnome_app_set_statusbar() to add it to the main application window.

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

The `interactivity` parameter 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 GnomeAppBar widget.

### gnome_appbar_set_status ()

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

Sets the status label without changing widget state; next call to gnome_appbar_set_status() or gnome_appbar_push() will destroy this permanently.

`appbar` : | A GnomeAppBar instance.
`status` : | Text to which status label will be set.

### gnome_appbar_get_status ()

    GtkWidget*  gnome_appbar_get_status         (GnomeAppBar *appbar);

Retrieves the statusbar widget.

`appbar` : | A GnomeAppBar instance.
Returns : | A pointer to the statusbar widget.

### gnome_appbar_set_default ()

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

What to show when showing nothing else is on the stack; defaults to the empty string.

`appbar` : | A GnomeAppBar instance.
`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` : | A GnomeAppBar instance.
`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 fine to call this with an empty stack.

`appbar` : | A GnomeAppBar instance.

### 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` : | A GnomeAppBar instance.

### gnome_appbar_set_progress_percentage ()

    void        gnome_appbar_set_progress_percentage
                                                (GnomeAppBar *appbar,
                                                 gfloat percentage);

Sets progress bar to `percentage`.

`appbar` : | A GnomeAppBar instance.
`percentage` : | Percentage to which progress bar should be set.

### gnome_appbar_get_progress ()

    GtkProgressBar* gnome_appbar_get_progress   (GnomeAppBar *appbar);

Retrieves the progress bar widget for further manipulation.

`appbar` : | A GnomeAppBar instance.
Returns : | A GtkProgressBar widget which is `appbar`'s progress bar, or `NULL` if `appbar` has no progress bar.

### gnome_appbar_refresh ()

    void        gnome_appbar_refresh            (GnomeAppBar *appbar);

Refresh the status message bar by redrawing the item on the top of the stack, or the default value if the stack is empty.. Useful to force the message from a previous call to gnome_appbar_set_status() to disappear.

`appbar` : | A GnomeAppBar instance.

### 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` : | A GnomeAppBar instance.
`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 from the status message bar.

`appbar` : | A GnomeAppBar instance.

### gnome_appbar_get_response ()

    gchar*      gnome_appbar_get_response       (GnomeAppBar *appbar);

Get the response to the prompt, if any.

`appbar` : | A GnomeAppBar instance.
Returns : | Text from `appbar` entry widget, as entered by user. This string should be freed by the caller (using gfree()) when no longer required.

## Properties

"`has-progress`" (gboolean : Read / Write / Construct) |
"`has-status`" (gboolean : Read / Write / Construct) |
"`interactivity`" (GnomePreferencesType : Read / Write / Construct) |

## Signals

### The "clear-prompt" signal

    void        user_function                  (GnomeAppBar *appbar,
                                                gpointer user_data);

`appbar` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "user-response" signal

    void        user_function                  (GnomeAppBar *appbar,
                                                gpointer user_data);

`appbar` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.