HildonBanner

HildonBanner — A widget used to display timed notifications.

Synopsis




            HildonBanner;
GtkWidget*  hildon_banner_show_information  (GtkWidget *widget,
                                             const gchar *icon_name,
                                             const gchar *text);
GtkWidget*  hildon_banner_show_informationf (GtkWidget *widget,
                                             const gchar *icon_name,
                                             const gchar *format,
                                             ...);
GtkWidget*  hildon_banner_show_information_with_markup
                                            (GtkWidget *widget,
                                             const gchar *icon_name,
                                             const gchar *markup);
GtkWidget*  hildon_banner_show_animation    (GtkWidget *widget,
                                             const gchar *animation_name,
                                             const gchar *text);
GtkWidget*  hildon_banner_show_progress     (GtkWidget *widget,
                                             GtkProgressBar *bar,
                                             const gchar *text);
void        hildon_banner_set_text          (HildonBanner *self,
                                             const gchar *text);
void        hildon_banner_set_markup        (HildonBanner *self,
                                             const gchar *markup);
void        hildon_banner_set_fraction      (HildonBanner *self,
                                             gdouble fraction);
void        hildon_banner_set_icon          (HildonBanner *self,
                                             const gchar *icon_name);
void        hildon_banner_set_icon_from_file
                                            (HildonBanner *self,
                                             const gchar *icon_file);
void        hildon_banner_set_timeout       (HildonBanner *self,
                                             guint timeout);

Object Hierarchy


  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkWindow
                                       +----HildonBanner

Implemented Interfaces

HildonBanner implements GtkBuildable and AtkImplementorIface.

Properties


  "is-timed"             gboolean              : Read / Write / Construct Only
  "parent-window"        GtkWindow             : Read / Write / Construct Only
  "timeout"              guint                 : Read / Write / Construct Only

Description

HildonBanner can be used to display a short, timed notification or information to the user. It can communicate that a task has been finished or the application state has changed. Banners should be used only to display non-critical pieces of information.

Details

HildonBanner

typedef struct _HildonBanner HildonBanner;

hildon_banner_show_information ()

GtkWidget*  hildon_banner_show_information  (GtkWidget *widget,
                                             const gchar *icon_name,
                                             const gchar *text);

This function creates and displays an information banner that automatically goes away after certain time period. For each window in your application there can only be one timed banner, so if you spawn a new banner before the earlier one has timed out, the previous one will be replaced.

widget : the GtkWidget that is the owner of the banner
icon_name : the name of icon to use. Can be NULL for default icon
text : Text to display
Returns : The newly created banner

hildon_banner_show_informationf ()

GtkWidget*  hildon_banner_show_informationf (GtkWidget *widget,
                                             const gchar *icon_name,
                                             const gchar *format,
                                             ...);

A helper function for hildon_banner_show_information with string formatting.

widget : the GtkWidget that is the owner of the banner
icon_name : the name of icon to use. Can be NULL for default icon
format : a printf-like format string
... : arguments for the format string
Returns : the newly created banner

hildon_banner_show_information_with_markup ()

GtkWidget*  hildon_banner_show_information_with_markup
                                            (GtkWidget *widget,
                                             const gchar *icon_name,
                                             const gchar *markup);

This function creates and displays an information banner that automatically goes away after certain time period. For each window in your application there can only be one timed banner, so if you spawn a new banner before the earlier one has timed out, the previous one will be replaced.

widget : the GtkWidget that wants to display banner
icon_name : the name of icon to use. Can be NULL for default icon.
markup : a markup string to display (see Pango markup format)
Returns : the newly created banner

hildon_banner_show_animation ()

GtkWidget*  hildon_banner_show_animation    (GtkWidget *widget,
                                             const gchar *animation_name,
                                             const gchar *text);

Shows an animated progress notification. It's recommended not to try to show more than one progress notification at a time, since they will appear on top of each other. You can use progress notifications with timed banners. In this case the banners are located so that you can somehow see both.

Please note that banners are destroyed automatically once the window they are attached to is closed. The pointer that you receive with this function do not contain additional references, so it can become invalid without warning (this is true for all toplevel windows in gtk). To make sure that the banner do not disapear automatically, you can separately ref the return value (this doesn't prevent the banner from disappearing, but the object it just not finalized). In this case you have to call both gtk_widget_destroy followed by g_object_unref (in this order).

widget : the GtkWidget that wants to display banner
animation_name : The progress animation to use. You usually can just pass NULL for the default animation.
text : the text to display.
Returns : a HildonBanner widget. You must call gtk_widget_destroy once you are done with the banner.

hildon_banner_show_progress ()

GtkWidget*  hildon_banner_show_progress     (GtkWidget *widget,
                                             GtkProgressBar *bar,
                                             const gchar *text);

Shows progress notification. See hildon_banner_show_animation for more information.

widget : the GtkWidget that wants to display banner
bar : Progressbar to use. You usually can just pass NULL, unless you want somehow customized progress bar.
text : text to display.
Returns : a HildonBanner widget. You must call gtk_widget_destroy once you are done with the banner.

hildon_banner_set_text ()

void        hildon_banner_set_text          (HildonBanner *self,
                                             const gchar *text);

Sets the text that is displayed in the banner.

self : a HildonBanner widget
text : a new text to display in banner

hildon_banner_set_markup ()

void        hildon_banner_set_markup        (HildonBanner *self,
                                             const gchar *markup);

Sets the text with markup that is displayed in the banner.

self : a HildonBanner widget
markup : a new text with Pango markup to display in the banner

hildon_banner_set_fraction ()

void        hildon_banner_set_fraction      (HildonBanner *self,
                                             gdouble fraction);

The fraction is the completion of progressbar, the scale is from 0.0 to 1.0. Sets the amount of fraction the progressbar has.

self : a HildonBanner widget
fraction : gdouble

hildon_banner_set_icon ()

void        hildon_banner_set_icon          (HildonBanner *self,
                                             const gchar *icon_name);

Sets the icon to be used in the banner.

self : a HildonBanner widget
icon_name : the name of icon to use. Can be NULL for default icon

hildon_banner_set_icon_from_file ()

void        hildon_banner_set_icon_from_file
                                            (HildonBanner *self,
                                             const gchar *icon_file);

Sets the icon from its filename to be used in the banner.

self : a HildonBanner widget
icon_file : the filename of icon to use. Can be NULL for default icon

hildon_banner_set_timeout ()

void        hildon_banner_set_timeout       (HildonBanner *self,
                                             guint timeout);

Sets the timeout on the banner. After the given amount of miliseconds has elapsed the banner will go away. Note that settings this only makes sense on the banners that are timed and that have not been yet displayed on the screen.

self : a HildonBanner widget
timeout : timeout to set in miliseconds.

Property Details

The "is-timed" property

  "is-timed"             gboolean              : Read / Write / Construct Only

Whether the banner is timed and goes away automatically.

Default value: FALSE

The "parent-window" property

  "parent-window"        GtkWindow             : Read / Write / Construct Only

The window for which the banner will be singleton.

The "timeout" property

  "timeout"              guint                 : Read / Write / Construct Only

The time before making the banner banner go away. This needs to be adjusted before the banner is mapped to the screen.

Allowed values: <= 10000

Default value: 3000