Since dialogs in plain GTK+ are painstakingly constructed
from scratch, there are at least as many ways to write a
dialog as there are programmers. The programmer must
decide where to place the dialog on the screen, how much
padding to have, whether to put a separator above the
buttons, what container to put the buttons in, what the
keyboard shortcuts are, and so on. The premise of GnomeDialog is that the programmer
should not have to care about these things; if they're
variable at all, the user should configure them the way
they want. From the programmer's perspective, dialogs
"just work."
A GnomeDialog is easy to
create. Here's a summary of the basic steps, more
detail follows:
-
Read the section
called Special Dialog Types and decide
whether one of the special dialog subclasses is
appropriate. If so, skip the below steps and create
that subclass instead.
-
Create the widget with
gnome_dialog_new(). Pass this function the
title of the dialog (displayed by the window
manager) and the name of each button you'd like to
have.
-
Populate
GNOME_DIALOG(dialog)->vbox with the
contents of your dialog.
-
Plan how your dialog will work. You can connect to
the "close" or "clicked" signals, as
appropriate. You can have the dialog hide or
destroy itself when closed. You can also have the
dialog automatically close when clicked, or handle
this yourself. There are a number of ways the user
can interact with a dialog, so it's important to be
sure the combination of settings you choose will
work no matter what the user does.
To create a dialog, use
gnome_dialog_new(), shown in Figure 1. The
argument list is a
NULL-terminated list of buttons to insert in the
dialog. For example, you might say:
GtkWidget* dialog;
dialog = gnome_dialog_new(_("My Dialog Title"),
_("OK"),
_("Cancel"),
NULL);
|
This creates a dialog titled "My Dialog Title" with an
OK and a Cancel button; the strings are marked for
translation with the _()
macro. The OK button will be the leftmost button in the
dialog.
The GnomeDialog API numbers
the buttons you add starting with 0; you use these
numbers to refer to the buttons later, since you don't
have a pointer to the automatically-created button
widgets. In this case, the OK button is button 0, and
the Cancel button is button 1. (Note that this is
standard Gnome practice---OK or Yes goes first, then
Cancel or No. In fact
libgnomeui/gnome-uidefs.h contains the macros GNOME_YES,
GNOME_OK, GNOME_NO, and
GNOME_CANCEL which represent
the dialog button numbers for these items in a
two-button dialog.)
The above example, which specifies buttons called "OK"
and "Cancel," is not quite correct for production code.
Gnome provides a set of "stock buttons" for common
button names. These ensure everyone uses "OK" instead
of "Ok" or "OK!"; they allow translators to translate
common strings only once; and they often insert icons
in the buttons, making them more attractive and
recognizable to users. You should always use stock
buttons if possible.
You can use stock buttons in
gnome_dialog_new(). Simply substitute the stock
button macros for the button names:
dialog = gnome_dialog_new(_("My Dialog Title"),
GNOME_STOCK_BUTTON_OK,
GNOME_STOCK_BUTTON_CANCEL,
NULL);
|
Gnome includes many stock buttons, stock menu items,
and stock pixmaps---it's a good idea to check these out
so you don't reinvent the wheel. There's a complete
list in
libgnomeui/gnome-stock.h.
