XfceDialogs

XfceDialogs — A collection of helper dialogs

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

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.