MateAppBar

## MateAppBar MateAppBar — An application status and progress bar widget |

## Synopsis

    #include <libmateui/libmateui.h>

    #define             MATE_APPBAR_HAS_STATUS             (appbar)
    #define             MATE_APPBAR_HAS_PROGRESS           (appbar)
    #define             MATE_APPBAR_INTERACTIVE            (ab)
    struct              MateAppBar;
    GtkWidget *         mate_appbar_new                    (gboolean has_progress,
                                                             gboolean has_status,
                                                             MatePreferencesType interactivity);
    void                mate_appbar_set_status             (MateAppBar *appbar,
                                                             const gchar *status);
    GtkWidget *         mate_appbar_get_status             (MateAppBar *appbar);
    void                mate_appbar_set_default            (MateAppBar *appbar,
                                                             const gchar *default_status);
    void                mate_appbar_push                   (MateAppBar *appbar,
                                                             const gchar *status);
    void                mate_appbar_pop                    (MateAppBar *appbar);
    void                mate_appbar_clear_stack            (MateAppBar *appbar);
    void                mate_appbar_set_progress_percentage
                                                            (MateAppBar *appbar,
                                                             gfloat percentage);
    GtkProgressBar *    mate_appbar_get_progress           (MateAppBar *appbar);
    void                mate_appbar_refresh                (MateAppBar *appbar);
    void                mate_appbar_set_prompt             (MateAppBar *appbar,
                                                             const gchar *prompt,
                                                             gboolean modal);
    void                mate_appbar_clear_prompt           (MateAppBar *appbar);
    gchar *             mate_appbar_get_response           (MateAppBar *appbar);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBox
                                     +----GtkHBox
                                           +----MateAppBar

## Implemented Interfaces

MateAppBar implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## Properties

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

## Signals

      "clear-prompt"                                   : Run Last
      "user-response"                                  : Run Last

## Description

A MateAppBar 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

### MATE_APPBAR_HAS_STATUS()

    #define MATE_APPBAR_HAS_STATUS(appbar) (mate_appbar_get_status(MATE_APPBAR(appbar)) != NULL)

Whether or not the application bar contains a status box.

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

### MATE_APPBAR_HAS_PROGRESS()

    #define MATE_APPBAR_HAS_PROGRESS(appbar) (mate_appbar_get_progress(MATE_APPBAR(appbar)) != NULL)

Whether or not the application bar contains a status box.

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

### MATE_APPBAR_INTERACTIVE()

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

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

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

### struct MateAppBar

    struct MateAppBar;

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

### mate_appbar_new ()

    GtkWidget *         mate_appbar_new                    (gboolean has_progress,
                                                             gboolean has_status,
                                                             MatePreferencesType interactivity);

Create a new MATE 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 MATE_PREFERENCES_NEVER, it is never interactive. If it is set to MATE_PREFERENCES_USER we respect user preferences from ui-properties. If it's MATE_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 mate-app-util interfaces), you should use MATE_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 MateAppBar widget.

### mate_appbar_set_status ()

    void                mate_appbar_set_status             (MateAppBar *appbar,
                                                             const gchar *status);

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

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

### mate_appbar_get_status ()

    GtkWidget *         mate_appbar_get_status             (MateAppBar *appbar);

Retrieves the statusbar widget.

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

### mate_appbar_set_default ()

    void                mate_appbar_set_default            (MateAppBar *appbar,
                                                             const gchar *default_status);

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

`appbar` : | A MateAppBar instance.
`default_status` : | Text for status label.

### mate_appbar_push ()

    void                mate_appbar_push                   (MateAppBar *appbar,
                                                             const gchar *status);

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

`appbar` : | A MateAppBar instance.
`status` : | Text of status message.

### mate_appbar_pop ()

    void                mate_appbar_pop                    (MateAppBar *appbar);

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

`appbar` : | A MateAppBar instance.

### mate_appbar_clear_stack ()

    void                mate_appbar_clear_stack            (MateAppBar *appbar);

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

`appbar` : | A MateAppBar instance.

### mate_appbar_set_progress_percentage ()

    void                mate_appbar_set_progress_percentage
                                                            (MateAppBar *appbar,
                                                             gfloat percentage);

Sets progress bar to `percentage`.

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

### mate_appbar_get_progress ()

    GtkProgressBar *    mate_appbar_get_progress           (MateAppBar *appbar);

Retrieves the progress bar widget for further manipulation.

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

### mate_appbar_refresh ()

    void                mate_appbar_refresh                (MateAppBar *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 `mate_appbar_set_status()` to disappear.

`appbar` : | A MateAppBar instance.

### mate_appbar_set_prompt ()

    void                mate_appbar_set_prompt             (MateAppBar *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 MateAppBar instance.
`prompt` : | Text of the prompt message.
`modal` : | If `TRUE`, grabs input.

### mate_appbar_clear_prompt ()

    void                mate_appbar_clear_prompt           (MateAppBar *appbar);

Remove any prompt from the status message bar.

`appbar` : | A MateAppBar instance.

### mate_appbar_get_response ()

    gchar *             mate_appbar_get_response           (MateAppBar *appbar);

Get the response to the prompt, if any.

`appbar` : | A MateAppBar 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.

## Property Details

### The `"has-progress"` property

      "has-progress"             gboolean              : Read / Write / Construct

Create a progress widget.

Default value: FALSE

### The `"has-status"` property

      "has-status"               gboolean              : Read / Write / Construct

Create a status widget.

Default value: FALSE

### The `"interactivity"` property

      "interactivity"            MatePreferencesType  : Read / Write / Construct

Level of user activity required.

Default value: MATE_PREFERENCES_NEVER

## Signal Details

### The `"clear-prompt"` signal

    void                user_function                      (MateAppBar *appbar,
                                                            gpointer     user_data)      : Run Last

`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                      (MateAppBar *appbar,
                                                            gpointer     user_data)      : Run Last

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