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, 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 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, 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));

Parameters

parent

transient parent of the dialog, or NULL.

[allow-none]

title

title of the dialog, or NULL.

[allow-none]

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 full]


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.

[allow-none]

title

title of the dialog, or NULL.

[allow-none]

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 full]


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.

[allow-none]

title

title of the dialog, or NULL.

[allow-none]

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.

[allow-none]

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.

[allow-none]

page

subpage of the component on the website or NULL.

[allow-none]

offset

anchor offset in page or NULL.

[allow-none]

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.

Appart from the component , page and offset the following information is also send 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.

[allow-none]

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.

[allow-none]

page

subpage of the component on the website or NULL.

[allow-none]

offset

anchor offset in page or NULL.

[allow-none]

version

alternative version, or NULL to use xfce_version_string().

[allow-none]

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.

[allow-none]

secondary_text

secondary text of the dialog or NULL.

[allow-none]

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.

[allow-none]

secondary_text

secondary text of the dialog or NULL.

[allow-none]

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.

[allow-none]

error

a GError, which gives a more precise description of the problem or NULL.

[allow-none]

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.

[allow-none]

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.

[allow-none]

secondary_text

secondary text in the dialog.

[allow-none]

primary_format

the printf()-style format for the dialog question.

[allow-none]

...

argument list for the primary_format .

[allow-none]

Returns

TRUE if the user confirms, else FALSE.

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 GdkPixuf, param2 for the label and param3 for the response_id.