## Dialogs

Dialogs — user interaction helper functions.

## Synopsis

    #include <libxfcegui4/libxfcegui4.h>

    void        xfce_err                        (const gchar *format,
                                                 ...);
    void        xfce_verr                       (const gchar *format,
                                                 va_list ap);
    void        xfce_warn                       (const gchar *format,
                                                 ...);
    void        xfce_vwarn                      (const gchar *format,
                                                 va_list ap);
    void        xfce_info                       (const gchar *format,
                                                 ...);
    void        xfce_vinfo                      (const gchar *format,
                                                 va_list ap);
    gboolean    xfce_confirm                    (const gchar *text,
                                                 const gchar *stock_id,
                                                 const gchar *action);
    gint        xfce_message_dialog             (GtkWindow *parent,
                                                 const gchar *title,
                                                 const gchar *icon_id,
                                                 const gchar *primary_text,
                                                 const gchar *secondary_text,
                                                 const gchar *first_button_type,
                                                 ...);
    GtkWidget*  xfce_create_header              (GdkPixbuf *icon,
                                                 const gchar *text);
    GtkWidget*  xfce_create_header_with_image   (GtkWidget *image,
                                                 const gchar *text);
    GtkWidget*  xfce_create_mixed_button        (const gchar *stock,
                                                 const gchar *text);
    GtkWidget*  xfce_create_small_label         (const gchar *text);

## Description

Provides simple user interaction functions, like error, warning and confirm dialogs.

## Details

### xfce_err ()

    void        xfce_err                        (const gchar *format,
                                                 ...);

Displays a modal error dialog to the user and blocks until the users clicks the close button.

`format` : | printf-style format string.
`...` : | argument list.

### xfce_verr ()

    void        xfce_verr                       (const gchar *format,
                                                 va_list ap);

Displays a modal error dialog to the user and blocks until the users clicks the close button.

`format` : | printf-style format string.
`ap` : | variable argument list pointer.

### xfce_warn ()

    void        xfce_warn                       (const gchar *format,
                                                 ...);

Displays a modal warning dialog to the user and blocks until the users clicks the close button.

`format` : | printf-style format string.
`...` : | argument list.

### xfce_vwarn ()

    void        xfce_vwarn                      (const gchar *format,
                                                 va_list ap);

Displays a modal warning dialog to the user and blocks until the users clicks the close button.

`format` : | printf-style format string.
`ap` : | variable argument list pointer.

### xfce_info ()

    void        xfce_info                       (const gchar *format,
                                                 ...);

Displays a modal info dialog to the user and blocks until the users clicks the close button.

`format` : | printf-style format string.
`...` : | argument list.

### xfce_vinfo ()

    void        xfce_vinfo                      (const gchar *format,
                                                 va_list ap);

Displays a modal info dialog to the user and blocks until the users clicks the close button.

`format` : | printf-style format string.
`ap` : | variable argument list pointer.

### xfce_confirm ()

    gboolean    xfce_confirm                    (const gchar *text,
                                                 const gchar *stock_id,
                                                 const gchar *action);

Runs a modal confirmation 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.

`text` : | a question text
`stock_id` : | a stock item name
`action` : | if non-NULL, this text is used on the confirm button together with the `stock` icon.
Returns : | TRUE if the user confirms, else FALSE.

### xfce_message_dialog ()

    gint        xfce_message_dialog             (GtkWindow *parent,
                                                 const gchar *title,
                                                 const gchar *icon_id,
                                                 const gchar *primary_text,
                                                 const gchar *secondary_text,
                                                 const gchar *first_button_type,
                                                 ...);

`xfce_message_dialog()` allows you to easily create a dialog respecting GNOME HIG; it accepts gtk stock buttons, or custom buttons using a gtk stock icon and text or a gdkpixbuf and text or just a text. It runs a modal message dialog with transient parent `parent` (or `NULL` for none) and title `title` (or `NULL` for a default title) containing the icon `icon`, large and bolded formatted `primary_text`, normal formatted `secondary_text` and some buttons. The buttons are defined by first_button_type and the next arguments in following format `type`, `param1`[, `param2`, `param3`]; there are four types of button :

- `GTK_STOCK_`* : `param1` is used for the response ID, others aren't used.

- `XFCE_CUSTOM_BUTTON` : `param1` is used for the button text and `param2` for the the response ID, `param3` isn't used.

- `XFCE_CUSTOM_STOCK_BUTTON` : `param1` is used for the button text, `param2` for the gtk stock icon name and `param3` for the response ID.

- `XFCE_CUSTOM_PIXBUF_BUTTON` : `param1` is used for the button text, `param2` for the GdkPixbuf pointer and `param3` for the response ID.

Here's a simple example:

     gint response = xfce_message_dialog (parent, "Question",
                                          GTK_STOCK_DIALOG_QUESTION,
                                          "Do you want to save before closing the menu ?",
                                          "The menu has been modified, do you want to save it before quitting ?",
                                          XFCE_CUSTOM_STOCK_BUTTON, "Forget modifications", GTK_STOCK_QUIT, GTK_RESPONSE_NO,
                                          GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
                                          GTK_STOCK_SAVE, GTK_RESPONSE_YES, NULL);

`parent` : | Transient parent of the dialog, or `NULL`
`title` : | Title of the dialog, or `NULL`
`icon_id` : | Gtk stock icon to show in the dialog
`primary_text` : | Text shown in large and bolded font
`secondary_text` : | Text shown in normal font
`first_button_type` : | Type of the first button, or `NULL`
`...` : | `NULL` ended list of parameters and response ID
Returns : | selected response ID.

### xfce_create_header ()

    GtkWidget*  xfce_create_header              (GdkPixbuf *icon,
                                                 const gchar *text);

Creates a header with an optional `icon` (may be NULL) in larger bold font. Background and foreground colors are taken from Gtk+ style.

`icon` : | a GdkPixbuf or NULL if no icon should be displayed in the header.
`text` : | a text to be displayed in the header.
Returns : | the container widget that contains the header widgets.

### xfce_create_header_with_image ()

    GtkWidget*  xfce_create_header_with_image   (GtkWidget *image,
                                                 const gchar *text);

Creates a header with an optional `image` (may be NULL) in larger bold font. Background and foreground colors are taken from Gtk+ style.

`image` : | a GtkImage or NULL if no image should be displayed in the header.
`text` : | the text to be displayed in the header.
Returns : | the container widget that contains the header widgets.

### xfce_create_mixed_button ()

    GtkWidget*  xfce_create_mixed_button        (const gchar *stock,
                                                 const gchar *text);

Creates a button with both `stock` icon and `text`.

`stock` : | a stock item name.
`text` : | a text to display.
Returns : | the newly created mixed button widget.

### xfce_create_small_label ()

    GtkWidget*  xfce_create_small_label         (const gchar *text);

Creates a small italic label using Gtk's markup functionality.

`text` : | label text.
Returns : | the newly created label.