XfceDialogs: libxfce4ui Reference Manual

## XfceDialogs XfceDialogs — A collection of helper dialogs |

## Stability Level

Stable, unless otherwise indicated

## Functions

GtkWidget * | xfce_message_dialog_new ()
GtkWidget * | xfce_message_dialog_new_valist ()
gint | xfce_message_dialog ()
void | xfce_dialog_show_help ()
void | xfce_dialog_show_help_with_version ()
void | xfce_dialog_show_info ()
void | xfce_dialog_show_warning ()
void | xfce_dialog_show_error ()
gboolean | xfce_dialog_confirm ()
gint | xfce_dialog_confirm_close_tabs ()

## Types and Values

#define | XFCE_BUTTON_TYPE_MIXED
#define | XFCE_BUTTON_TYPE_PIXBUF

## Includes

    #include <libxfce4ui/libxfce4ui.h>

## Description

Xfce-dialogs are a collection of helper dialogs to display the help dialog with link to the docs website, warning, info, and error dialogs and more.

## Functions

### 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 (deprecated), 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 icon name, `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 GdkPixbuf, `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 3. Creating a Xfce Message Dialog

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    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, "edit-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));

The caller is responsible for destroying the dialog with `gtk_widget_destroy()` when it is no longer required.

#### Parameters

parent | transient parent of the dialog, or `NULL`. | [nullable]
title | title of the dialog, or `NULL`. | [nullable]
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.

[transfer none]

### 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.

#### Parameters

parent | transient parent of the dialog, or `NULL`. | [nullable]
title | title of the dialog, or `NULL`. | [nullable]
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.

[transfer none]

### 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.

#### Parameters

parent | transient parent of the dialog, or `NULL`. | [nullable]
title | title of the dialog, or `NULL`. | [nullable]
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 *component,
                           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()`.

See also: `xfce_dialog_show_help_with_version()`.

#### Parameters

parent | transient parent of the dialog, or `NULL`. | [nullable]
component | name of the component opening the help page or `NULL`. If the value is `NULL` the target will be the main page of the documentation website. | [nullable]
page | subpage of the `component` on the website or `NULL`. | [nullable]
offset | anchor offset in `page` or `NULL`. | [nullable]

Since: 4.10

### xfce_dialog_show_help_with_version ()

    void
    xfce_dialog_show_help_with_version (GtkWindow *parent,
                                        const gchar *component,
                                        const gchar *page,
                                        const gchar *offset,
                                        const gchar *version);

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

Apart from the `component` , `page` and `offset` the following information is also sent to the server: user language and the `xfce_version_string()` or `version` if set.

See also: `xfce_dialog_show_help()`.

#### Parameters

parent | transient parent of the dialog, or `NULL`. | [nullable]
component | name of the component opening the help page or `NULL`. If the value is `NULL` the target will be the main page of the documentation website. | [nullable]
page | subpage of the `component` on the website or `NULL`. | [nullable]
offset | anchor offset in `page` or `NULL`. | [nullable]
version | alternative version, or `NULL` to use `xfce_version_string()`. | [nullable]

Since: 4.12

### 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.

#### Parameters

parent | transient parent of the dialog, or `NULL`. | [nullable]
secondary_text | secondary text of the dialog or `NULL`. | [nullable]
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.

#### Parameters

parent | transient parent of the dialog, or `NULL`. | [nullable]
secondary_text | secondary text of the dialog or `NULL`. | [nullable]
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.

#### Parameters

parent | transient parent of the dialog, or `NULL`. | [nullable]
error | a GError, which gives a more precise description of the problem or `NULL`. | [nullable]
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.

#### Parameters

parent | transient parent of the dialog, or `NULL`. | [nullable]
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. | [nullable]
secondary_text | secondary text in the dialog. | [nullable]
primary_format | the `printf()`-style format for the dialog question. | [nullable]
... | argument list for the `primary_format` . | [nullable]

#### Returns

TRUE if the user confirms, else FALSE.

### xfce_dialog_confirm_close_tabs ()

    gint
    xfce_dialog_confirm_close_tabs (GtkWindow *parent,
                                    gint num_tabs,
                                    gboolean show_confirm_box,
                                    gboolean *confirm_box_checked);

Runs a dialog to ask the user whether they want to close the whole window, close the current tab, or cancel.

If `num_tabs` is non-negative, the message to the user will state that there are `num_tabs` open tabs. If `num_tabs` is negative, then the message to the user will state simply that there are "multiple open tabs".

If `show_confirm_box` is `TRUE` a checkbox is added to the dialog to allow the user to set whether they wish to see this dialog in future. The initial state of the checkbox is determined by the value stored at `confirm_box_checked` and the value at `confirm_box_checked` after returning records the state of the checkbox. If `show_confirm_box` is `FALSE`, `confirm_box_checked` is ignored and may be `NULL`.

#### Parameters

parent | transient parent of the dialog, or `NULL`. | [nullable]
num_tabs | the number of open tabs for display to user |
show_confirm_box | whether to ask the user if this confirmation shall be shown in the future |
confirm_box_checked | state of confirmation checkbox. | [nullable]

#### Returns

GTK_RESPONSE_CANCEL if cancelled, GTK_RESPONSE_YES if the user wants to close the window, GTK_RESPONSE_CLOSE if the user wants to close the tab, and GTK_RESPONSE_NONE for an error.

Since: 4.16

## Types and Values

### XFCE_BUTTON_TYPE_MIXED

    #define XFCE_BUTTON_TYPE_MIXED  "button-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

    #define XFCE_BUTTON_TYPE_PIXBUF "button-pixbuf"

Creates a button with the GdkPixbuf as button icon. param1 is the GdkPixbuf, param2 for the label and param3 for the response_id.