GnomeAppBar

GnomeAppBar

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
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBox
                                 +----GtkHBox
                                       +----GnomeAppBar

Implemented Interfaces

GnomeAppBar implements AtkImplementorIface, GtkBuildable and GtkOrientable.

Properties

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

Signals

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

Description

Details

GNOME_APPBAR_HAS_STATUS()

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

GNOME_APPBAR_HAS_PROGRESS()

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

GNOME_APPBAR_INTERACTIVE()

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

struct GnomeAppBar

struct GnomeAppBar;

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.

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"            GnomePreferencesType  : Read / Write / Construct

Level of user activity required.

Default value: GNOME_PREFERENCES_NEVER

Signal Details

The "clear-prompt" signal

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

The "user-response" signal

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