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.
Example 1. Using GnomeDialog to implement yes/no/cancel
include
/*
* This function demostrates how to use the GnomeDialog in
* modal mode to request a yes/no from the user.
*
* It sets the title to title and inserts the message in message.
*
* If main_window is not NULL, it also binds the dialog to that
* window (so if you minimize the main window, this dialog also
* gets minimized).
*/
int
yes_no (GtkWindow *main_window, char *title, char *message)
{
GtkWidget *dialog, *label;
int button;
dialog = gnome_dialog_new (
title,
GNOME_STOCK_BUTTON_YES,
GNOME_STOCK_BUTTON_NO,
NULL);
if (main_window)
gnome_dialog_set_parent (GNOME_DIALOG (dialog), main_window);
label = gtk_label_new (message);
gtk_box_pack_start (GTK_BOX (GNOME_DIALOG (dialog)->vbox), label, TRUE, TRUE, 0);
/*
* Run the dialog and wait for the user to select yes or no.
* If the user closes the window with the window manager, we
* will get a -1 return value
*/
button = gnome_dialog_run_and_close (GNOME_DIALOG (dialog));
return button;
}
int
main (int argc, char **argv)
{
int button;
gnome_init ("SampleProgram", "1.0", argc, argv);
button = yes_no ("Question?", "Do you like the Bonobos?");
switch (button){
case 0:
printf ("User selected yes\n");
break;
case 1:
printf ("User selected no\n");
break;
case -1:
printf ("User closed the window with the window manager\n");
break;
}
return 0;
}
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.
title :
The title of the dialog; appears in window titlebar.
... :
NULL-terminated varargs list of button names or GNOME_STOCK_BUTTON_* defines.
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).
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().
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.
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.
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.
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.
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.
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.
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.
