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 can also include a GtkProgressBar.

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 9. 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 new HildonNote.

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 new HildonNote.

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 new HildonNote.

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 text (a 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 new HildonNote.

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. An information note has text (a 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, the default icon is used.
Returns : a new HildonNote.

hildon_note_set_button_text ()

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

Sets the text of the button in note.

note : a HildonNote.
text : sets the button text. If there are 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 text for the buttons in note.

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;

Type of a HildonNote, defining its behavior, contents, and theming.

HILDON_NOTE_TYPE_CONFIRMATION Standard confirmation note with 'Yes' and 'No' buttons.
HILDON_NOTE_TYPE_CONFIRMATION_BUTTON Confirmation note with custom buttons.
HILDON_NOTE_TYPE_INFORMATION Information note with an 'OK' button.
HILDON_NOTE_TYPE_INFORMATION_THEME Deprecated information note with a themed icon. Equivalent to HILDON_NOTE_TYPE_INFORMATION.
HILDON_NOTE_TYPE_PROGRESSBAR Note with a GtkProgressBar and an 'OK' button.

Property Details

The "description" property

  "description"              gchar*                : Read / Write

The text that appears in the HildonNote.

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

If set, a GtkProgressBar is displayed in the note.

The "stock-icon" property

  "stock-icon"               gchar*                : Read / Write

Stock icon name for the note.

Default value: ""

Generated by GTK-Doc V1.10