GnomeDialog

Name

GnomeDialog -- Transient ("popup") dialogs.

Synopsis


#include <gnome.h>


struct      GnomeDialog;
GtkWidget*  gnome_dialog_new                (const gchar *title,
                                             ...);
GtkWidget*  gnome_dialog_newv               (const gchar *title,
                                             const gchar **buttons);
void        gnome_dialog_set_parent         (GnomeDialog *dialog,
                                             GtkWindow *parent);
void        gnome_dialog_button_connect     (GnomeDialog *dialog,
                                             gint button,
                                             GtkSignalFunc callback,
                                             gpointer data);
void        gnome_dialog_button_connect_object
                                            (GnomeDialog *dialog,
                                             gint button,
                                             GtkSignalFunc callback,
                                             GtkObject *obj);
gint        gnome_dialog_run                (GnomeDialog *dialog);
gint        gnome_dialog_run_and_close      (GnomeDialog *dialog);
void        gnome_dialog_set_default        (GnomeDialog *dialog,
                                             gint button);
void        gnome_dialog_set_sensitive      (GnomeDialog *dialog,
                                             gint button,
                                             gboolean setting);
void        gnome_dialog_set_accelerator    (GnomeDialog *dialog,
                                             gint button,
                                             const guchar accelerator_key,
                                             guint8 accelerator_mods);
void        gnome_dialog_close              (GnomeDialog *dialog);
void        gnome_dialog_close_hides        (GnomeDialog *dialog,
                                             gboolean just_hide);
void        gnome_dialog_set_close          (GnomeDialog *dialog,
                                             gboolean click_closes);
void        gnome_dialog_editable_enters    (GnomeDialog *dialog,
                                             GtkEditable *editable);
void        gnome_dialog_append_buttons     (GnomeDialog *dialog,
                                             const gchar *first,
                                             ...);
void        gnome_dialog_append_button      (GnomeDialog *dialog,
                                             const gchar *name);
void        gnome_dialog_append_buttonsv    (GnomeDialog *dialog,
                                             const gchar **buttons);
void        gnome_dialog_append_button_with_pixmap
                                            (GnomeDialog *dialog,
                                             const gchar *name,
                                             const gchar *pixmap);
void        gnome_dialog_append_buttons_with_pixmaps
                                            (GnomeDialog *dialog,
                                             const gchar **names,
                                             const gchar **pixmaps);
void        gnome_dialog_construct          (GnomeDialog *dialog,
                                             const gchar *title,
                                             va_list ap);
void        gnome_dialog_constructv         (GnomeDialog *dialog,
                                             const gchar *title,
                                             const gchar **buttons);

Object Hierarchy


  GtkObject
   +----GtkWidget
         +----GtkContainer
               +----GtkBin
                     +----GtkWindow
                           +----GnomeDialog

Description

GnomeDialog gives dialogs a consistent look and feel, while making them more convenient to program. GnomeDialog makes it easy to use stock buttons, makes it easier to handle delete_event, and adds some cosmetic touches (such as a separator above the buttons, and a bevel around the edge of the window).

Details

struct GnomeDialog

struct GnomeDialog;

struct _GnomeDialog { GtkWindow window; GtkWidget * vbox; GtkWidget * action_area; /* A button box, not an hbox */ GList *buttons; GtkAccelGroup * accelerators; unsigned int click_closes : 1; unsigned int just_hide : 1; gpointer padding; };

Only vbox should be accessed directly.


gnome_dialog_new ()

GtkWidget*  gnome_dialog_new                (const gchar *title,
                                             ...);

Creates a new GnomeDialog, with the given title, and any button names in the arg list. Buttons can be simple names, such as _("My Button"), or gnome-stock defines such as GNOME_STOCK_BUTTON_OK, etc. The last argument should be NULL to terminate the list.

Buttons passed to this function are numbered from left to right, starting with 0. So the first button in the arglist is button 0, then button 1, etc. These numbers are used throughout the GnomeDialog API.


gnome_dialog_newv ()

GtkWidget*  gnome_dialog_newv               (const gchar *title,
                                             const gchar **buttons);

See gnome_dialog_new(), this function is identical but does not use varargs.


gnome_dialog_set_parent ()

void        gnome_dialog_set_parent         (GnomeDialog *dialog,
                                             GtkWindow *parent);

Dialogs have "parents," usually the main application window which spawned them. This function will let the window manager know about the parent-child relationship. Usually this means the dialog must stay on top of the parent, and will be minimized when the parent is. Gnome also allows users to request dialog placement above the parent window (vs. at the mouse position, or at a default window manger location).


gnome_dialog_button_connect ()

void        gnome_dialog_button_connect     (GnomeDialog *dialog,
                                             gint button,
                                             GtkSignalFunc callback,
                                             gpointer data);

Simply gtk_signal_connect() to the "clicked" signal of the specified button.


gnome_dialog_button_connect_object ()

void        gnome_dialog_button_connect_object
                                            (GnomeDialog *dialog,
                                             gint button,
                                             GtkSignalFunc callback,
                                             GtkObject *obj);

gtk_signal_connect_object() to the "clicked" signal of the given button.


gnome_dialog_run ()

gint        gnome_dialog_run                (GnomeDialog *dialog);

Blocks until the user clicks a button, or closes the dialog with the window manager's close decoration (or by pressing Escape).

You need to set up the dialog to do the right thing when a button is clicked or delete_event is received; you must consider both of those possibilities so that you know the status of the dialog when gnome_dialog_run() returns. A common mistake is to forget about Escape and the window manager close decoration; by default, these call gnome_dialog_close(), which by default destroys the dialog. If your button clicks do not destroy the dialog, you don't know whether the dialog is destroyed when gnome_dialog_run() returns. This is bad.

So you should either close the dialog on button clicks as well, or change the gnome_dialog_close() behavior to hide instead of destroy. You can do this with gnome_dialog_close_hides().


gnome_dialog_run_and_close ()

gint        gnome_dialog_run_and_close      (GnomeDialog *dialog);

See gnome_dialog_run(). The only difference is that this function calls gnome_dialog_close() before returning, if the dialog was not already closed.


gnome_dialog_set_default ()

void        gnome_dialog_set_default        (GnomeDialog *dialog,
                                             gint button);

The default button will be activated if the user just presses return. Usually you should make the least-destructive button the default. Otherwise, the most commonly-used button.


gnome_dialog_set_sensitive ()

void        gnome_dialog_set_sensitive      (GnomeDialog *dialog,
                                             gint button,
                                             gboolean setting);

Calls gtk_widget_set_sensitive() on the specified button number.


gnome_dialog_set_accelerator ()

void        gnome_dialog_set_accelerator    (GnomeDialog *dialog,
                                             gint button,
                                             const guchar accelerator_key,
                                             guint8 accelerator_mods);


gnome_dialog_close ()

void        gnome_dialog_close              (GnomeDialog *dialog);

See also gnome_dialog_close_hides(). This function emits the "close" signal, which either hides or destroys the dialog (destroy by default). If you connect to the "close" signal, and your callback returns TRUE, the hide or destroy will be blocked. You can do this to avoid closing the dialog if the user gives invalid input, for example.

Using gnome_dialog_close() in place of gtk_widget_hide() or gtk_widget_destroy() allows you to easily catch all sources of dialog closure, including delete_event and button clicks, and handle them in a central location.


gnome_dialog_close_hides ()

void        gnome_dialog_close_hides        (GnomeDialog *dialog,
                                             gboolean just_hide);

Some dialogs are expensive to create, so you want to keep them around and just gtk_widget_show() them when they are opened, and gtk_widget_hide() them when they're closed. Other dialogs are expensive to keep around, so you want to gtk_widget_destroy() them when they're closed. It's a judgment call you will need to make for each dialog.


gnome_dialog_set_close ()

void        gnome_dialog_set_close          (GnomeDialog *dialog,
                                             gboolean click_closes);

This is a convenience function so you don't have to connect callbacks to each button just to close the dialog. By default, GnomeDialog has this parameter set the FALSE and it will not close on any click. (This was a design error.) However, almost all the GnomeDialog subclasses, such as GnomeMessageBox and GnomePropertyBox, have this parameter set to TRUE by default.


gnome_dialog_editable_enters ()

void        gnome_dialog_editable_enters    (GnomeDialog *dialog,
                                             GtkEditable *editable);

Normally if there's an editable widget (such as GtkEntry) in your dialog, pressing Enter will activate the editable rather than the default dialog button. However, in most cases, the user expects to type something in and then press enter to close the dialog. This function enables that behavior.


gnome_dialog_append_buttons ()

void        gnome_dialog_append_buttons     (GnomeDialog *dialog,
                                             const gchar *first,
                                             ...);

This function is mostly for internal library use. You should use gnome_dialog_new() instead. See that function for a description of the button arguments.


gnome_dialog_append_button ()

void        gnome_dialog_append_button      (GnomeDialog *dialog,
                                             const gchar *name);

This function is mostly for internal library use. You should use gnome_dialog_new() instead. See that function for a description of the button argument.


gnome_dialog_append_buttonsv ()

void        gnome_dialog_append_buttonsv    (GnomeDialog *dialog,
                                             const gchar **buttons);

For internal use, language bindings, etc. Use gnome_dialog_new() instead.


gnome_dialog_append_button_with_pixmap ()

void        gnome_dialog_append_button_with_pixmap
                                            (GnomeDialog *dialog,
                                             const gchar *name,
                                             const gchar *pixmap);

gnome_dialog_new() does not permit custom buttons with pixmaps, so if you want one of those you need to use this function.


gnome_dialog_append_buttons_with_pixmaps ()

void        gnome_dialog_append_buttons_with_pixmaps
                                            (GnomeDialog *dialog,
                                             const gchar **names,
                                             const gchar **pixmaps);

Simply calls gnome_dialog_append_button_with_pixmap() repeatedly.


gnome_dialog_construct ()

void        gnome_dialog_construct          (GnomeDialog *dialog,
                                             const gchar *title,
                                             va_list ap);

See gnome_dialog_new().


gnome_dialog_constructv ()

void        gnome_dialog_constructv         (GnomeDialog *dialog,
                                             const gchar *title,
                                             const gchar **buttons);

See gnome_dialog_new().

See Also

GnomeAbout GnomePropertyBox GnomeMessageBox GnomeScores