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

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().

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.

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.