Editing Legacy Maemo 5 Documentation/Graphical UI Tutorial/Controls (section)

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

Learn more about Contributing to the wiki.

==Notification widgets ==

To cover the main use cases regarding notification of users, Hildon provides banners and notes. Banner widgets display a text information during a certain period of time. Notes are specialized <code>GtkDialog</code>s that need a small amount of input from the user.

===Banners===

A <code>HildonBanner</code> is useful to display information which does not need any user response. This widget automatically disappears after a certain time period.

To create and show a banner, use the following function:

<source lang="c">
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);
</source>

All functions above require a widget as an argument that must be a pointer to the owner widget of the banner. Usually, the owner is the window that represents the currently displayed view.

Function <code>hildon_banner_show_information()</code> shows a banner with the given text.

Function <code>hildon_banner_show_informationf()</code> shows a banner which displays the text given by the printf-like formated string applied to the parameters that the rest of the function's arguments represent.

You can also apply a Pango markup and add some attributes to the displayed text. To do that, either use <code>hildon_banner_show_information_with_markup()</code> to create the banner or setup the markup by calling <code>hildon_banner_set_markup()</code> after the initialization. [@@COMMENT@@ LINK TO PANGO MARKUP]

===Warning===

Currently, icons are not displayed in banners, so any value that you pass as the <code>icon_name</code> is ignored.

The period of time after the banner automatically disappear is stored in the property "<code>timeout</code>" (in miliseconds). A convenience function to set this property is provided:

<source lang="c">
void        hildon_banner_set_timeout       (HildonBanner *self,
                                             guint timeout);
</source>

Here is a simple example showing how to setup and show an informational banner.

'''Example 7.5. Setting up an informational banner'''

<source lang="c">
GtkWidget* banner;
/* Create a banner with a markup */
banner = hildon_banner_show_information_with_markup (widget,
                                                     NULL,
                                                     "<b>Information banner</b>");
hildon_banner_set_timeout (HILDON_BANNER (banner), 9000);
</source>

===Note===

Only one timed banner can exist for each window in your application. If you spawn a new banner before the previous one has timed out, the first one is replaced.

====Notes====

<code>HildonNote</code>s are <code>GtkDialog</code>s designed to request a small amount of input from users. Usually, notes show an information text and buttons to confirm and cancel, for example, according to their type.

Unlike banners, notes always need a user action, that is, notes do not disappear automatically after a period of time.

The <code>HildonNote</code> widget provides functions to create and show different types of notes: information notes, confirmation notes and cancel notes.

<source lang="c">
GtkWidget*  hildon_note_new_information     (GtkWindow *parent,
                                             const gchar *description);
GtkWidget*  hildon_note_new_confirmation    (GtkWindow *parent,
                                             const gchar *description);
GtkWidget*  hildon_note_new_confirmation_add_buttons
                                            (GtkWindow *parent,
                                             const gchar *description,
                                             ...);
GtkWidget*  hildon_note_new_cancel_with_progress_bar
                                            (GtkWindow *parent,
                                             const gchar *description,
                                             GtkProgressBar *progressbar);
</source>

Every function to create notes receives as a parameter the parent window of the newly created note. This is important in order to allow the window manager to handle the windows properly.

====Information Notes====

Information notes are used to show an information to the users. This note disappears when user taps outside the note's area. Otherwise the note remains visible.

Here is an example of how to show an information note and handle the user's answer.

'''Example 7.6. Example of a Hildon information note'''

<source lang="c">
static void
show_information_note                          (GtkWidget *parent)
{
  GtkWidget *window, *note;
  gint response;
  note = hildon_note_new_information (NULL,
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    "Maecenas tristique dictum est. Aenean rhoncus aliquam mi."
    "In hac habitasse platea dictumst.");
  response = gtk_dialog_run (GTK_DIALOG (note));
  if (response == GTK_RESPONSE_DELETE_EVENT)
    g_debug ("%s: GTK_RESPONSE_DELETE_EVENT", __FUNCTION__);
  gtk_object_destroy (GTK_OBJECT (note));
}
</source>

====Confirmation Notes====

Confirmation notes show an information text that is usually a question and two buttons labelled "Yes" and "No".

To create a confirmation note with the text you specify and two buttons labelled "Yes"/"No", use <code>hildon_note_new_confirmation()</code> as follows:

'''Example 7.7. Example of a Hildon confirmation note'''

<source lang="c">
static void
show_confirmation_note                          (GtkWidget *parent)
{
    GtkWidget *note;
    gint response;
    note = hildon_note_new_confirmation (parent,
                                         "Do you want foo ?");
    response = gtk_dialog_run (GTK_DIALOG (note));
    if (response == GTK_RESPONSE_DELETE_EVENT)
      g_debug ("%s: GTK_RESPONSE_DELETE_EVENT", __FUNCTION__);
    gtk_object_destroy (GTK_OBJECT (note));
}
</source>

Alternatively, you can use <code>hildon_note_new_confirmation_add_buttons()</code> to create a confirmation note with custom buttons.

'''Example 7.8. Example of a Hildon confirmation note with custom buttons'''

<source lang="c">
static void
show_confirmation_note                          (GtkWidget *parent)
{
    GtkWidget *note;
    gint response;
    note = hildon_note_new_confirmation_add_buttons(parent,
                                                    "Do you want foo?",
                                                    "ACCEPT", GTK_RESPONSE_OK,
                                                    "CANCEL", GTK_RESPONSE_CANCEL,
                                                    "DELETE", GTK_RESPONSE_DELETE_EVENT,
                                                    NULL);
    response = gtk_dialog_run (GTK_DIALOG (note));
    if (response == GTK_RESPONSE_DELETE_EVENT)
      g_debug ("%s: GTK_RESPONSE_DELETE_EVENT", __FUNCTION__);
    gtk_object_destroy (GTK_OBJECT (note));
}
</source>

'''Cancel Notes'''

A cancel note displays a text, a Cancel button and a progress bar. They are useful to tell users that a long task is in progress. Also, cancel notes allow users to cancel the task in progress.

Next example shows how to create a cancel note with a progress bar. Note that to control the progress bar, additional code is needed.

'''Example 7.9. Example of a Hildon cancel note with a progress bar'''

<source lang="c">
static void
show_information_note                          (GtkWidget *parent)
{
  GtkWidget *note
  GtkProgressBar *progressbar
  gint response;
  progressbar = gtk_progress_bar_new()
  note = hildon_note_new_cancel_with_progress_bar (parent,
                                                  "A large task is happening"
                                                  progressbar);
  response = gtk_dialog_run (GTK_DIALOG (note));
  if (response == GTK_RESPONSE_DELETE_EVENT)
    g_debug ("%s: GTK_RESPONSE_DELETE_EVENT", __FUNCTION__);
  gtk_object_destroy (GTK_OBJECT (note));
}
</source>

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Retrieved from "http://wiki.maemo.org/Legacy_Maemo_5_Documentation/Graphical_UI_Tutorial/Controls"

Personal tools

Navigation

Views

Editing Legacy Maemo 5 Documentation/Graphical UI Tutorial/Controls (section)