## Xfce Dialogs

Xfce Dialogs — Common used dialogs to interact with the user.

## Synopsis

    #include <libxfce4ui/libxfce4ui.h>

    GtkWidget *         xfce_message_dialog_new             (GtkWindow *parent,
                                                             const gchar *title,
                                                             const gchar *stock_id,
                                                             const gchar *primary_text,
                                                             const gchar *secondary_text,
                                                             const gchar *first_button_text,
                                                             ...);
    GtkWidget *         xfce_message_dialog_new_valist      (GtkWindow *parent,
                                                             const gchar *title,
                                                             const gchar *icon_stock_id,
                                                             const gchar *primary_text,
                                                             const gchar *secondary_text,
                                                             const gchar *first_button_text,
                                                             va_list args);
    gint                xfce_message_dialog                 (GtkWindow *parent,
                                                             const gchar *title,
                                                             const gchar *stock_id,
                                                             const gchar *primary_text,
                                                             const gchar *secondary_text,
                                                             const gchar *first_button_text,
                                                             ...);
    void                xfce_dialog_show_help               (GtkWindow *parent,
                                                             const gchar *application,
                                                             const gchar *page,
                                                             const gchar *offset);
    void                xfce_dialog_show_info               (GtkWindow *parent,
                                                             const gchar *secondary_text,
                                                             const gchar *primary_format,
                                                             ...);
    void                xfce_dialog_show_warning            (GtkWindow *parent,
                                                             const gchar *secondary_text,
                                                             const gchar *primary_format,
                                                             ...);
    void                xfce_dialog_show_error              (GtkWindow *parent,
                                                             const GError *error,
                                                             const gchar *primary_format,
                                                             ...);
    gboolean            xfce_dialog_confirm                 (GtkWindow *parent,
                                                             const gchar *stock_id,
                                                             const gchar *confirm_label,
                                                             const gchar *secondary_text,
                                                             const gchar *primary_format,
                                                             ...);

    #define             XFCE_BUTTON_TYPE_MIXED
    #define             XFCE_BUTTON_TYPE_PIXBUF

## Description

Useful convientent function to interact with the user using a GtkMessageDialog.

## Details

### xfce_message_dialog_new ()

    GtkWidget *         xfce_message_dialog_new             (GtkWindow *parent,
                                                             const gchar *title,
                                                             const gchar *stock_id,
                                                             const gchar *primary_text,
                                                             const gchar *secondary_text,
                                                             const gchar *first_button_text,
                                                             ...);

`xfce_message_dialog_new()` allows you to easily create Gtk+ message dialogs. It accepts GTK+ stock buttons, mixed buttons (using XFCE_BUTTON_TYPE_MIXED) or buttons with a GdkPixbuf (using XFCE_BUTTON_TYPE_PIXBUF).

The buttons are defined by `first_button_text` and the next arguments in the following format `type`, `param1`[, `param2`, `param3`].

`XFCE_BUTTON_TYPE_MIXED` | This allows you to easily create mixed buttons in a dialog. `param1` is used for the stock_id, `param2` for the label and `param3` for the response_id. See also `xfce_gtk_button_new_mixed()`.
`XFCE_BUTTON_TYPE_PIXBUF` | Creates a button with the GdkPixbuf as button icon. `param1` is the GdkPixuf, `param2` for the label and `param3` for the response_id.
Stock Buttons | When the variables above were not matched, the button type will be a stock button. `type` will be the stock id, `param1` is used for the response_id.

To clarify this behaviour see the example below. We create a dialog with two stock buttons, a GdkPixbuf button and a mixed button.

Example 2. Creating a Xfce Message Dialog

    GdkPixbuf *pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 24, 24);

    GtkWidget *dialog = xfce_message_dialog (parent, "Question",
                                             GTK_STOCK_DIALOG_QUESTION,
                                             "There are unsaved modifications",
                                             "The menu has been modified, do you want to save it before quitting?",
                                             GTK_STOCK_SAVE, GTK_RESPONSE_YES,
                                             XFCE_BUTTON_TYPE_MIXED, GTK_STOCK_DELETE, "Forget modifications", GTK_RESPONSE_APPLY,
                                             XFCE_BUTTON_TYPE_PIXBUF, pixbuf, "Quit", GTK_RESPONSE_NO,
                                             GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
                                             NULL);

    g_object_unref (G_OBJECT (pixbuf));

`parent` : | transient parent of the dialog, or `NULL`.
`title` : | title of the dialog, or `NULL`.
`stock_id` : | gtk stock icon name to show in the dialog.
`primary_text` : | primary text shown in large bold font.
`secondary_text` : | secondary text shown in normal font.
`first_button_text` : | text for the first button.
`...` : | `NULL` terminated list of parameters.
Returns : | A new GtkMessageDialog.

### xfce_message_dialog_new_valist ()

    GtkWidget *         xfce_message_dialog_new_valist      (GtkWindow *parent,
                                                             const gchar *title,
                                                             const gchar *icon_stock_id,
                                                             const gchar *primary_text,
                                                             const gchar *secondary_text,
                                                             const gchar *first_button_text,
                                                             va_list args);

See `xfce_message_dialog_new()`, this version takes a va_list for language bindings to use.

`parent` : | transient parent of the dialog, or `NULL`.
`title` : | title of the dialog, or `NULL`.
`icon_stock_id` : | gtk stock icon name to show in the dialog.
`primary_text` : | primary text shown in large bold font.
`secondary_text` : | secondary text shown in normal font.
`first_button_text` : | text for the first button.
`args` : | argument list.
Returns : | A new GtkMessageDialog.

### xfce_message_dialog ()

    gint                xfce_message_dialog                 (GtkWindow *parent,
                                                             const gchar *title,
                                                             const gchar *stock_id,
                                                             const gchar *primary_text,
                                                             const gchar *secondary_text,
                                                             const gchar *first_button_text,
                                                             ...);

Create a new dialog as in `xfce_message_dialog_new()`, then runs the dialog using gtk_dialog_run and return the response id selected by the user.

See `xfce_message_dialog_new()` for more information.

`parent` : | transient parent of the dialog, or `NULL`.
`title` : | title of the dialog, or `NULL`.
`stock_id` : | gtk stock icon name to show in the dialog.
`primary_text` : | primary text shown in large bold font.
`secondary_text` : | secondary text shown in normal font.
`first_button_text` : | text for the first button.
`...` : | `NULL` ended list of parameters.
Returns : | the selected response id.

### xfce_dialog_show_help ()

    void                xfce_dialog_show_help               (GtkWindow *parent,
                                                             const gchar *application,
                                                             const gchar *page,
                                                             const gchar *offset);

Asks the user to visit the online documentation. If confirmed, it will open the webbrowser and redirect the user to the correct location.

Appart from the `component`, `page` and `offset` the following information is also send to the server: user language and the `xfce_version_string()`.

Since 4.10

`parent` : | transient parent of the dialog, or `NULL`.
`page` : | subpage of the `component` on the website or `NULL`.
`offset` : | anchor offset in `page` or `NULL`.

### xfce_dialog_show_info ()

    void                xfce_dialog_show_info               (GtkWindow *parent,
                                                             const gchar *secondary_text,
                                                             const gchar *primary_format,
                                                             ...);

Displays an information dialog on `parent` using the `primary_format` as message.

`parent` : | transient parent of the dialog, or `NULL`.
`secondary_text` : | secondary text of the dialog or `NULL`.
`primary_format` : | the `printf()`-style format for the primary problem description.
`...` : | argument list for the `format`.

### xfce_dialog_show_warning ()

    void                xfce_dialog_show_warning            (GtkWindow *parent,
                                                             const gchar *secondary_text,
                                                             const gchar *primary_format,
                                                             ...);

Displays a warning dialog on `parent` using the `primary_format` as message.

`parent` : | transient parent of the dialog, or `NULL`.
`secondary_text` : | secondary text of the dialog or `NULL`.
`primary_format` : | the `printf()`-style format for the primary problem description.
`...` : | argument list for the `format`.

### xfce_dialog_show_error ()

    void                xfce_dialog_show_error              (GtkWindow *parent,
                                                             const GError *error,
                                                             const gchar *primary_format,
                                                             ...);

Displays an error dialog on `parent` using the `primary_format` as primary message and optionally displaying `error` as secondary error text.

`parent` : | transient parent of the dialog, or `NULL`.
`error` : | a GError, which gives a more precise description of the problem or `NULL`.
`primary_format` : | the `printf()`-style format for the primary problem description.
`...` : | argument list for the `primary_format`.

### xfce_dialog_confirm ()

    gboolean            xfce_dialog_confirm                 (GtkWindow *parent,
                                                             const gchar *stock_id,
                                                             const gchar *confirm_label,
                                                             const gchar *secondary_text,
                                                             const gchar *primary_format,
                                                             ...);

Runs a questions dialog, that has a 'Cancel' and a 'Confirm' button. The 'Confirm' button text can be set by `action` if given.

If `stock_id` is equal to GTK_STOCK_YES, the 'Cancel' button becomes a 'No' button.

`parent` : | transient parent of the dialog, or `NULL`.
`stock_id` : | the stock name of the confirm button, for example GTK_STOCK_YES or GTK_STOCK_CLEAR.
`confirm_label` : | if non-`NULL`, this text is used on the confirm button together with the `stock_id` icon.
`secondary_text` : | secondary text in the dialog.
`primary_format` : | the `printf()`-style format for the dialog question.
`...` : | argument list for the `primary_format`.
Returns : | TRUE if the user confirms, else FALSE.

### XFCE_BUTTON_TYPE_MIXED

    #define XFCE_BUTTON_TYPE_MIXED  "button-mixed"

Used to define a mixed button in `xfce_message_dialog_new()` and `xfce_message_dialog_run()`.

### XFCE_BUTTON_TYPE_PIXBUF

    #define XFCE_BUTTON_TYPE_PIXBUF "button-pixbuf"

Used to define a GdkPixuf button in `xfce_message_dialog_new()` and `xfce_message_dialog_run()`.