*/
/**
- * SECTION:hildon-banner
- * @short_description: A widget used to display timed notifications.
+ * SECTION:hildon-banner
+ * @short_description: A widget used to display timed notifications.
*
* #HildonBanner is a small, pop-up window that can be used to display
* a short, timed notification or information to the user. It can
* hildon_gtk_window_set_progress_indicator() for the preferred way of
* showing progress notifications in Hildon 2.2.
*
- * Information banners dissapear automatically after a certain
+ * Information banners are automatically destroyed after a certain
* period. This is stored in the #HildonBanner:timeout property (in
* miliseconds), and can be changed using hildon_banner_set_timeout().
*
* Note that #HildonBanner<!-- -->s should only be used to display
* non-critical pieces of information.
+ *
+ * <example>
+ * <title>Using the HildonBanner widget</title>
+ * <programlisting>
+ * 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;
+ * }
+ * </programlisting>
+ * </example>
*/
#ifdef HAVE_CONFIG_H
#undef HILDON_DISABLE_DEPRECATED
#include "hildon-banner.h"
-#include "hildon-banner-private.h"
#include "hildon-defines.h"
#include "hildon-gtk.h"
/* max widths */
-#define HILDON_BANNER_PROGRESS_WIDTH 104
-
#define HILDON_BANNER_LABEL_MAX_TIMED \
(gdk_screen_width() - ((HILDON_MARGIN_TRIPLE) * 2))
const gchar *text,
gboolean override_dnd);
-
G_DEFINE_TYPE (HildonBanner, hildon_banner, GTK_TYPE_WINDOW)
+typedef struct _HildonBannerPrivate HildonBannerPrivate;
+
+#define HILDON_BANNER_GET_PRIVATE(obj) \
+ (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
+ HILDON_TYPE_BANNER, HildonBannerPrivate));
+
+struct _HildonBannerPrivate
+{
+ GtkWidget *main_item;
+ GtkWidget *alignment;
+ GtkWidget *label;
+ GtkWidget *layout;
+ GtkWindow *parent;
+ guint timeout;
+ guint timeout_id;
+ guint is_timed : 1;
+ guint has_been_wrapped : 1;
+ guint has_been_truncated : 1;
+ guint require_override_dnd : 1;
+ guint overrides_dnd : 1;
+};
+
static GQuark
hildon_banner_timed_quark (void)
{
/**
* HildonBanner:timeout:
*
- * The time before making the banner banner go away. This needs
+ * The time before destroying the banner. This needs
* to be adjusted before the banner is mapped to the screen.
*
*/
priv->require_override_dnd = FALSE;
/* Initialize the common layout inside banner */
+ priv->alignment = gtk_alignment_new (0.5, 0.5, 0, 0);
priv->layout = gtk_hbox_new (FALSE, HILDON_MARGIN_DEFAULT);
priv->label = g_object_new (GTK_TYPE_LABEL, NULL);
gtk_label_set_line_wrap_mode (GTK_LABEL (priv->label), PANGO_WRAP_WORD_CHAR);
gtk_container_set_border_width (GTK_CONTAINER (priv->layout), HILDON_MARGIN_DEFAULT);
- gtk_container_add (GTK_CONTAINER (self), priv->layout);
- gtk_box_pack_start (GTK_BOX (priv->layout), priv->label, TRUE, TRUE, 0);
+ gtk_container_add (GTK_CONTAINER (self), priv->alignment);
+ gtk_container_add (GTK_CONTAINER (priv->alignment), priv->layout);
+ gtk_box_pack_start (GTK_BOX (priv->layout), priv->label, FALSE, FALSE, 0);
gtk_window_set_accept_focus (GTK_WINDOW (self), FALSE);
/* Use user provided widget or create a new one */
priv->main_item = widget = user_widget ?
user_widget : GTK_WIDGET (g_object_new_valist(type, first_property, args));
- gtk_box_pack_start (GTK_BOX (priv->layout), widget, TRUE, TRUE, 0);
+ gtk_box_pack_start (GTK_BOX (priv->layout), widget, FALSE, FALSE, 0);
}
/* We make sure that the widget exists in desired position. Different
* any value that you pass will be ignored
* @text: Text to display
*
- * 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.
+ * 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.
*
* Returns: The newly created banner
*
* @widget: the #GtkWidget that is the owner of the banner
* @text: Text to display
*
- * Equivalent to hildon_banner_show_information() but it overrides the do not
- * disturb flag, in the special cases that could be needed. It is required
- * because this method calls internally gtk_widget_show before returns the banner,
- * but the do not disturb flag is checked on the mapping of the widget
- *
+ * Equivalent to hildon_banner_show_information(), but overriding the
+ * "do not disturb" flag.
*
* Returns: The newly created banner
*
* @format: a printf-like format string
* @Varargs: arguments for the format string
*
- * A helper function for #hildon_banner_show_information with
+ * A helper function for hildon_banner_show_information() with
* string formatting.
*
* Returns: the newly created banner
* any value that you pass will be ignored
* @markup: a markup string to display (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
*
- * 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.
+ * 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.
*
* Returns: the newly created banner
*
* 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
+ * 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 both
- * gtk_widget_destroy() followed by g_object_unref() (in this order).
+ * being finalized). In this case you have to call
+ * gtk_widget_destroy() followed by g_object_unref().
*
* Returns: a #HildonBanner widget. You must call gtk_widget_destroy()
* once you are done with the banner.
* any value that you pass will be ignored
* @text: text to display.
*
- * Shows progress notification. See #hildon_banner_show_animation
+ * Shows progress notification. See hildon_banner_show_animation()
* for more information.
*
* Returns: a #HildonBanner widget. You must call #gtk_widget_destroy
* @timeout: timeout to set in miliseconds.
*
* 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
+ * 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
projects / hildon / blobdiff