Xfce Dialogs

Xfce Dialogs — Common used dialogs to interact with the user.

Synopsis

#include <libxfce4ui/libxfce4ui.h>

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,
                                                         ...);
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);
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,
                                                         ...);
void                xfce_dialog_show_help               (GtkWindow *parent,
                                                         const gchar *application,
                                                         const gchar *page,
                                                         const gchar *offset);
void                xfce_dialog_show_info               (GtkWindow *parent,
                                                         const gchar *secondary_text,
                                                         const gchar *primary_format,
                                                         ...);
void                xfce_dialog_show_warning            (GtkWindow *parent,
                                                         const gchar *secondary_text,
                                                         const gchar *primary_format,
                                                         ...);
void                xfce_dialog_show_error              (GtkWindow *parent,
                                                         const GError *error,
                                                         const gchar *primary_format,
                                                         ...);
gboolean            xfce_dialog_confirm                 (GtkWindow *parent,
                                                         const gchar *stock_id,
                                                         const gchar *confirm_label,
                                                         const gchar *secondary_text,
                                                         const gchar *primary_format,
                                                         ...);

#define             XFCE_BUTTON_TYPE_MIXED
#define             XFCE_BUTTON_TYPE_PIXBUF

Description

Useful convientent function to interact with the user using a GtkMessageDialog.

Details

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


parent :

transient parent of the dialog, or NULL.

title :

title of the dialog, or NULL.

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.

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.

parent :

transient parent of the dialog, or NULL.

title :

title of the dialog, or NULL.

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.

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.

parent :

transient parent of the dialog, or NULL.

title :

title of the dialog, or NULL.

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 *application,
                                                         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().

Since 4.10

parent :

transient parent of the dialog, or NULL.

page :

subpage of the component on the website or NULL.

offset :

anchor offset in page or NULL.

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.

parent :

transient parent of the dialog, or NULL.

secondary_text :

secondary text of the dialog or NULL.

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.

parent :

transient parent of the dialog, or NULL.

secondary_text :

secondary text of the dialog or NULL.

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.

parent :

transient parent of the dialog, or NULL.

error :

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

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.

parent :

transient parent of the dialog, or NULL.

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.

secondary_text :

secondary text in the dialog.

primary_format :

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

... :

argument list for the primary_format.

Returns :

TRUE if the user confirms, else FALSE.

XFCE_BUTTON_TYPE_MIXED

#define XFCE_BUTTON_TYPE_MIXED  "button-mixed"

Used to define a mixed button in xfce_message_dialog_new() and xfce_message_dialog_run().


XFCE_BUTTON_TYPE_PIXBUF

#define XFCE_BUTTON_TYPE_PIXBUF "button-pixbuf"

Used to define a GdkPixuf button in xfce_message_dialog_new() and xfce_message_dialog_run().