HildonBanner

HildonBanner — A widget used to display timed notifications.

Synopsis


#include <hildon/hildon.h>

                    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_information_override_dnd
                                                        (GtkWidget *widget,
                                                         const gchar *text);
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);
GtkWidget*          hildon_banner_show_custom_widget    (GtkWidget *widget,
                                                         GtkWidget *custom_widget);
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 AtkImplementorIface and GtkBuildable.

Properties

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

Description

HildonBanner is a small, pop-up window that can be used to display a short, timed notification or information to the user. It can communicate that a task has been finished or that the application state has changed.

Hildon provides convenient funtions to create and show banners. To create and show information banners you can use hildon_banner_show_information(), hildon_banner_show_informationf() or hildon_banner_show_information_with_markup().

If the application window has set the _HILDON_DO_NOT_DISTURB flag (using hildon_gtk_window_set_do_not_disturb() for example), the banner will not be shown. If you need to override this flag for important information, you can use the method hildon_banner_show_information_override_dnd(). Please, take into account that this is only for important information.

Two more kinds of banners are maintained for backward compatibility but are no longer recommended in Hildon 2.2. These are the animated banner (created with hildon_banner_show_animation()) and the progress banner (created with hildon_banner_show_progress()). See hildon_gtk_window_set_progress_indicator() for the preferred way of showing progress notifications in Hildon 2.2.

Information banners are automatically destroyed after a certain period. This is stored in the "timeout" property (in miliseconds), and can be changed using hildon_banner_set_timeout().

Note that HildonBanners should only be used to display non-critical pieces of information.

Example 8. Using the HildonBanner widget

void show_info_banner (GtkWidget *parent)
{
  GtkWidget *banner;

  banner = hildon_banner_show_information (widget, NULL, "Information banner");
  hildon_banner_set_timeout (HILDON_BANNER (banner), 9000);

  return;
}


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 is automatically destroyed after a certain time period (see hildon_banner_set_timeout()). 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 : since Hildon 2.2 this parameter is not used anymore and any value that you pass will be ignored
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 : since Hildon 2.2 this parameter is not used anymore and any value that you pass will be ignored
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 is automatically destroyed after certain time period (see hildon_banner_set_timeout()). 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 : since Hildon 2.2 this parameter is not used anymore and any value that you pass will be ignored
markup : a markup string to display (see Pango markup format)
Returns : the newly created banner

hildon_banner_show_information_override_dnd ()

GtkWidget*          hildon_banner_show_information_override_dnd
                                                        (GtkWidget *widget,
                                                         const gchar *text);

Equivalent to hildon_banner_show_information(), but overriding the "do not disturb" flag.

widget : the GtkWidget that is the owner of the banner
text : Text to display
Returns : The newly created banner

Since 2.2


hildon_banner_show_animation ()

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

Warning

hildon_banner_show_animation is deprecated and should not be used in newly-written code. Hildon 2.2: use hildon_gtk_window_set_progress_indicator() instead.

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.

Unlike information banners (created with hildon_banner_show_information()), animation banners are not destroyed automatically using a timeout. You have to destroy them yourself.

Please note also that these banners are destroyed automatically if the window they are attached to is closed. The pointer that you receive with this function does 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 does not disappear automatically, you can separately ref the return value (this doesn't prevent the banner from disappearing, just the object from being finalized). In this case you have to call gtk_widget_destroy() followed by g_object_unref().

widget : the GtkWidget that wants to display banner
animation_name : since Hildon 2.2 this parameter is not used anymore and any value that you pass will be ignored
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);

Warning

hildon_banner_show_progress is deprecated and should not be used in newly-written code. Hildon 2.2: use hildon_gtk_window_set_progress_indicator() instead.

Shows progress notification. See hildon_banner_show_animation() for more information.

widget : the GtkWidget that wants to display banner
bar : since Hildon 2.2 this parameter is not used anymore and any value that you pass will be ignored
text : text to display.
Returns : a HildonBanner widget. You must call gtk_widget_destroy once you are done with the banner.

hildon_banner_show_custom_widget ()

GtkWidget*          hildon_banner_show_custom_widget    (GtkWidget *widget,
                                                         GtkWidget *custom_widget);

Shows a banner displaying a user-defined widget.

widget : the GtkWidget that wants to display a banner
custom_widget : a GtkWidget to be placed inside the banner.
Returns : a new HildonBanner

Since 2.2


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);

Warning

hildon_banner_set_fraction is deprecated and should not be used in newly-written code. This function does nothing. As of Hildon 2.2, hildon banners don't have progress bars.

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

Note that this method only has effect if self was created with hildon_banner_show_progress()

self : a HildonBanner widget
fraction : gdouble

hildon_banner_set_icon ()

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

Warning

hildon_banner_set_icon is deprecated and should not be used in newly-written code. This function does nothing. As of hildon 2.2, hildon banners don't allow changing their icons.

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);

Warning

hildon_banner_set_icon_from_file is deprecated and should not be used in newly-written code. This function does nothing. As of hildon 2.2, hildon banners don't allow changing their icons.

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 be destroyed. Setting this only makes sense on banners that are timed and that have not been yet displayed on the screen.

Note that this method only has effect if self is an information banner (created using hildon_banner_show_information() and friends).

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 destroying the banner. This needs to be adjusted before the banner is mapped to the screen.

Allowed values: <= 10000

Default value: 3000