Handling GnomeDialog Signals

Now for the tricky part. You have to prepare yourself to handle anything the user might do to your dialog. Here's a brief list of possibilities; it's worth going over the list whenever you create a dialog:

• Closing the dialog by pressing the Escape key

• Closing the dialog by clicking the window manager's close decoration

• Clicking one of the dialog's buttons

• Interacting with the contents of the dialog

• If the dialog is not modal, interacting with other parts of the application

GnomeDialog emits two signals in addition to those it inherits from parent classes. If the user clicks one of the dialog's buttons, a "clicked" signal is emitted. (This is not the "clicked" signal from GtkButton; it's a different signal, emitted by GnomeDialog.) A GnomeDialog"clicked" handler should have three arguments: the dialog emitting the signal, the number of the button clicked, and your callback data.

GnomeDialog also has a "close" signal. It is emitted when gnome_dialog_close() is called; all the built-in event handlers (e.g. for the Escape shortcut) call this function to close the dialog. GnomeDialog's default handler for "close" has two possible behaviors: it can call either gtk_widget_hide() or gtk_widget_destroy() on the dialog. The behavior is configurable by calling gnome_dialog_close_hides(), shown in Figure 3.

       #include <libgnomeui/gnome-dialog.h>
      

By default, "close" destroys the dialog. This is what you usually want; however, if a dialog is noticeably time-consuming to create, you might want to merely hide and re-show it between uses, without ever destroying it. You might also want to hide the dialog from the user, extract the state of any widgets inside it, and then destroy it with gtk_widget_destroy(). The decision depends on the structure of your code. However, in general it is simpler and less error-prone to let the dialog be destroyed when clicked. You can connect to the "clicked" signal if you need to query the state of widgets in the dialog.

If you connect a handler to "close", that handler should return a boolean value. If it returns TRUE, the hide or destroy will not take place. You can use this to keep the user from closing the dialog, for example if they have not filled in all the fields of a form.

The "close" signal is designed to collect several possible user actions into a single handler: it should be emitted when the user presses Escape or the window manager's window close button is clicked. It's often convenient to emit close when the dialog's buttons are clicked as well. You can ask GnomeDialog to emit close whenever a button is clicked with gnome_dialog_set_close() (Figure 3); if its setting argument is TRUE, the dialog will emit "close" in addition to "clicked" if any of its buttons are clicked. By default, this setting is FALSE for GnomeDialog, but for many of the special dialog types the default is TRUE (the inconsistency is an unfortunate misfeature).

Note that the "close" signal is emitted when the dialog receives "delete_event"; this means you only have to write one signal handler to deal with all dialog closings. There is no need to handle "delete_event" as a separate case.