HildonNote

HildonNote — A widget to ask confirmation from the user.

Synopsis

                    HildonNote;
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_confirmation_with_icon_name
                                                        (GtkWindow *parent,
                                                         const gchar *description,
                                                         const gchar *icon_name);
GtkWidget*          hildon_note_new_cancel_with_progress_bar
                                                        (GtkWindow *parent,
                                                         const gchar *description,
                                                         GtkProgressBar *progressbar);
GtkWidget*          hildon_note_new_information         (GtkWindow *parent,
                                                         const gchar *description);
GtkWidget*          hildon_note_new_information_with_icon_name
                                                        (GtkWindow *parent,
                                                         const gchar *description,
                                                         const gchar *icon_name);
void                hildon_note_set_button_text         (HildonNote *note,
                                                         const gchar *text);
void                hildon_note_set_button_texts        (HildonNote *note,
                                                         const gchar *text_ok,
                                                         const gchar *text_cancel);
enum                HildonNoteType;

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkWindow
                                       +----GtkDialog
                                             +----HildonNote

Implemented Interfaces

HildonNote implements AtkImplementorIface and GtkBuildable.

Properties

  "description"              gchar*                : Read / Write
  "icon"                     gchar*                : Read / Write
  "note-type"                HildonNoteType        : Read / Write / Construct
  "progressbar"              GtkProgressBar*       : Read / Write
  "stock-icon"               gchar*                : Read / Write

Description

HildonNote is a convenient way to prompt users for a small amount of input. A simple note contains an information text and, in case of confirmation notes, it shows buttons to confirm or cancel. It also can include a progress bar.

This widget provides convenient functions to create either information notes, confirmation notes or cancel notes, which are useful to show the progress of a requested task allowing the user to cancel it.

To create information notes you can use hildon_note_new_information(). hildon_note_new_confirmation() creates a note with a text and two buttons to confirm or cancel. Note that it is possible to create a confirmation note with customized buttons by using hildon_note_new_confirmation_add_buttons().

To create a note with a text, a progress bar and cancel button, hildon_note_new_cancel_with_progress_bar() can be used.

Example 24. HildonNote example


gboolean
show_confirmation_note (GtkWindow *parent)
{
  gint retcode;
  GtkWidget *note;
  note = hildon_note_new_confirmation (parent, "Confirmation message...");

  retcode = gtk_dialog_run (GTK_DIALOG (note));
  gtk_widget_destroy (note);

  if (retcode == GTK_RESPONSE_OK) {
       g_debug ("User pressed 'OK' button'");
       return TRUE;
  } else {
       g_debug ("User pressed 'Cancel' button");
       return FALSE;
  }
}


Details

HildonNote

typedef struct _HildonNote HildonNote;

hildon_note_new_confirmation ()

GtkWidget*          hildon_note_new_confirmation        (GtkWindow *parent,
                                                         const gchar *description);

Create a new confirmation note. Confirmation note has a text (description) that you specify and two buttons.

parent : the parent window. The X window ID of the parent window has to be the same as the X window ID of the application. This is important so that the window manager could handle the windows correctly. In GTK the X window ID can be checked using GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
description : the message to confirm
Returns : a GtkWidget pointer of the note

hildon_note_new_confirmation_add_buttons ()

GtkWidget*          hildon_note_new_confirmation_add_buttons
                                                        (GtkWindow *parent,
                                                         const gchar *description,
                                                         ...);

Create a new confirmation note with custom buttons. Confirmation note has a text and any number of buttons. It's important to note that even though the name of the function might suggest, the default ok/cancel buttons are not appended but you have to provide all of the buttons.

FIXME: This doc seems to be wrong, the two buttons aren't added so it would only contain the "additional" buttons? However, changing this would break those applications that rely on current behaviour.

parent : the parent window. The X window ID of the parent window has to be the same as the X window ID of the application. This is important so that the window manager could handle the windows correctly. In GTK the X window ID can be checked using GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
description : the message to confirm
... : arguments pairs for new buttons(label and return value). Terminate the list with NULL value.
Returns : A GtkWidget pointer of the note

hildon_note_new_confirmation_with_icon_name ()

GtkWidget*          hildon_note_new_confirmation_with_icon_name
                                                        (GtkWindow *parent,
                                                         const gchar *description,
                                                         const gchar *icon_name);

Warning

hildon_note_new_confirmation_with_icon_name is deprecated and should not be used in newly-written code. Since 2.2, icons are not shown in confirmation notes. Icons set with this function will be ignored. Use hildon_note_new_confirmation() instead.

Create a new confirmation note. Confirmation note has a text (description) that you specify and two buttons.

parent : the parent window. The X window ID of the parent window has to be the same as the X window ID of the application. This is important so that the window manager could handle the windows correctly. In GTK the X window ID can be checked using GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
description : the message to confirm
icon_name : icon to be displayed. If NULL, default icon is used.
Returns : a GtkWidget pointer of the note

hildon_note_new_cancel_with_progress_bar ()

GtkWidget*          hildon_note_new_cancel_with_progress_bar
                                                        (GtkWindow *parent,
                                                         const gchar *description,
                                                         GtkProgressBar *progressbar);

Create a new cancel note with a progress bar. Cancel note has text(description) that you specify, a Cancel button and a progress bar.

parent : the parent window. The X window ID of the parent window has to be the same as the X window ID of the application. This is important so that the window manager could handle the windows correctly. In GTK the X window ID can be checked using GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
description : the action to cancel
progressbar : a pointer to GtkProgressBar to be filled with the progressbar assigned to this note. Use this to set the fraction of progressbar done. This parameter can be NULL as well, in which case plain text cancel note appears.
Returns : a GtkDialog. Use this to get rid of this note when you no longer need it.

hildon_note_new_information ()

GtkWidget*          hildon_note_new_information         (GtkWindow *parent,
                                                         const gchar *description);

Create a new information note. Information note has a text (description) that you specify and an OK button.

parent : the parent window. The X window ID of the parent window has to be the same as the X window ID of the application. This is important so that the window manager could handle the windows correctly. In GTK the X window ID can be checked using GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
description : the message to confirm
Returns : a GtkWidget pointer of the note

hildon_note_new_information_with_icon_name ()

GtkWidget*          hildon_note_new_information_with_icon_name
                                                        (GtkWindow *parent,
                                                         const gchar *description,
                                                         const gchar *icon_name);

Warning

hildon_note_new_information_with_icon_name is deprecated and should not be used in newly-written code. Since 2.2, icons are not shown in confirmation notes. Icons set with this function will be ignored. Use hildon_note_new_information() instead.

Create a new information note. Information note has text(description) that you specify, an OK button and an icon.

parent : the parent window. The X window ID of the parent window has to be the same as the X window ID of the application. This is important so that the window manager could handle the windows correctly. In GTK the X window ID can be checked using GDK_WINDOW_XID(GTK_WIDGET(parent)->window).
description : the message to confirm
icon_name : icon to be displayed. If NULL, default icon is used.
Returns : a GtkWidget pointer of the note

hildon_note_set_button_text ()

void                hildon_note_set_button_text         (HildonNote *note,
                                                         const gchar *text);

Sets the button text to be used by the hildon_note widget.

note : a HildonNote
text : sets the button text and if there is two buttons in dialog, the button texts will be <text>, "Cancel".

hildon_note_set_button_texts ()

void                hildon_note_set_button_texts        (HildonNote *note,
                                                         const gchar *text_ok,
                                                         const gchar *text_cancel);

Sets the button texts to be used by this hildon_note widget.

note : a HildonNote
text_ok : the new text of the default OK button
text_cancel : the new text of the default cancel button

enum HildonNoteType

typedef enum
{
    HILDON_NOTE_TYPE_CONFIRMATION = 0,
    HILDON_NOTE_TYPE_CONFIRMATION_BUTTON,
    HILDON_NOTE_TYPE_INFORMATION,
    HILDON_NOTE_TYPE_INFORMATION_THEME,
    HILDON_NOTE_TYPE_PROGRESSBAR
}                                               HildonNoteType;

Property Details

The "description" property

  "description"              gchar*                : Read / Write

Description for the note.

Default value: ""

The "icon" property

  "icon"                     gchar*                : Read / Write

Icon for the note.

Default value: ""

The "note-type" property

  "note-type"                HildonNoteType        : Read / Write / Construct

The type of the note dialog.

Default value: HILDON_NOTE_TYPE_CONFIRMATION

The "progressbar" property

  "progressbar"              GtkProgressBar*       : Read / Write

Progressbar for the note (if any).

The "stock-icon" property

  "stock-icon"               gchar*                : Read / Write

Stock icon name for the note.

Default value: ""

Generated by GTK-Doc V1.10