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.