GnomeDialog

## GnomeDialog GnomeDialog — Create generic dialog boxes. |

## Synopsis

    #include <libgnomeui/libgnomeui.h>

                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,
                                                 GCallback callback,
                                                 gpointer data);
    void        gnome_dialog_button_connect_object
                                                (GnomeDialog *dialog,
                                                 gint button,
                                                 GCallback 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_grab_focus         (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 *button_name);
    void        gnome_dialog_append_buttonsv    (GnomeDialog *dialog,
                                                 const gchar **buttons);
    void        gnome_dialog_append_button_with_pixmap
                                                (GnomeDialog *dialog,
                                                 const gchar *button_name,
                                                 const gchar *pixmap_name);
    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);
    #define     GNOME_STOCK_BUTTON_OK
    #define     GNOME_STOCK_BUTTON_CANCEL
    #define     GNOME_STOCK_BUTTON_YES
    #define     GNOME_STOCK_BUTTON_NO
    #define     GNOME_STOCK_BUTTON_CLOSE
    #define     GNOME_STOCK_BUTTON_APPLY
    #define     GNOME_STOCK_BUTTON_HELP
    #define     GNOME_STOCK_BUTTON_NEXT
    #define     GNOME_STOCK_BUTTON_PREV
    #define     GNOME_STOCK_BUTTON_UP
    #define     GNOME_STOCK_BUTTON_DOWN
    #define     GNOME_STOCK_BUTTON_FONT

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkWindow
                                     +----GnomeDialog
                                           +----GnomeMessageBox
                                           +----GnomePropertyBox

## Implemented Interfaces

GnomeDialog implements AtkImplementorIface.

## Signal Prototypes

    "clicked"   void        user_function      (GnomeDialog *dialog,
                                                gint arg1,
                                                gpointer user_data);
    "close"     gboolean    user_function      (GnomeDialog *dialog,
                                                gpointer user_data);

## Description

## Details

### GnomeDialog

    typedef struct {
      GtkWidget * vbox;
    } GnomeDialog;

### Warning

`GnomeDialog` is deprecated and should not be used in newly-written code.

Client code can pack widgets (for example, text or images) into `vbox`.

GtkWidget *`vbox`; | The middle portion of the dialog box.

### gnome_dialog_new ()

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

### Warning

`gnome_dialog_new` is deprecated and should not be used in newly-written code.

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.
Returns : | The new GnomeDialog.

### gnome_dialog_newv ()

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

### Warning

`gnome_dialog_newv` is deprecated and should not be used in newly-written code.

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

`title` : | Title of the dialog.
`buttons` : | NULL-terminated vector of buttons names.
Returns : | The new GnomeDialog.

### gnome_dialog_set_parent ()

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

### Warning

`gnome_dialog_set_parent` is deprecated and should not be used in newly-written code.

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).

`dialog` : | GnomeDialog to set the parent of.
`parent` : | Parent GtkWindow.

### gnome_dialog_button_connect ()

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

### Warning

`gnome_dialog_button_connect` is deprecated and should not be used in newly-written code.

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

`dialog` : | GnomeDialog to affect.
`button` : | Button number.
`callback` : | A standard Gtk callback.
`data` : | Callback data.

### gnome_dialog_button_connect_object ()

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

### Warning

`gnome_dialog_button_connect_object` is deprecated and should not be used in newly-written code.

`g_signal_connect_swapped()` to the "clicked" signal of the given button.

`dialog` : | GnomeDialog to affect.
`button` : | Button to connect to.
`callback` : | Callback.
`obj` : | As for `g_signal_connect_swapped()`.

### gnome_dialog_run ()

    gint        gnome_dialog_run                (GnomeDialog *dialog);

### Warning

`gnome_dialog_run` is deprecated and should not be used in newly-written code.

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()`.

`dialog` : | GnomeDialog to use.
Returns : | If a button was pressed, the button number is returned. If not, -1 is returned.

### gnome_dialog_run_and_close ()

    gint        gnome_dialog_run_and_close      (GnomeDialog *dialog);

### Warning

`gnome_dialog_run_and_close` is deprecated and should not be used in newly-written code.

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

`dialog` : | GnomeDialog to use.
Returns : | If a button was pressed, the button number. Otherwise -1.

### gnome_dialog_set_default ()

    void        gnome_dialog_set_default        (GnomeDialog *dialog,
                                                 gint button);

### Warning

`gnome_dialog_set_default` is deprecated and should not be used in newly-written code.

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.

`dialog` : | GnomeDialog to affect.
`button` : | Number of the default button.

### gnome_dialog_grab_focus ()

    void        gnome_dialog_grab_focus         (GnomeDialog *dialog,
                                                 gint button);

### Warning

`gnome_dialog_grab_focus` is deprecated and should not be used in newly-written code.

The button `button` will grab the focus. Use this for dialogs Where only buttons are displayed and you want to change the default button.

`dialog` : | GnomeDialog to affect.
`button` : | Number of the default button.

### gnome_dialog_set_sensitive ()

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

### Warning

`gnome_dialog_set_sensitive` is deprecated and should not be used in newly-written code.

Calls `gtk_widget_set_sensitive()` on the specified button number.

`dialog` : | GnomeDialog to affect.
`button` : | Which button to affect.
`setting` : | TRUE means it's sensitive.

### gnome_dialog_set_accelerator ()

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

### Warning

`gnome_dialog_set_accelerator` is deprecated and should not be used in newly-written code.

Set an accelerator key for a button.

`dialog` : | GnomeDialog to affect.
`button` : | Button number.
`accelerator_key` : | Key for the accelerator.
`accelerator_mods` : | Modifier.

### gnome_dialog_close ()

    void        gnome_dialog_close              (GnomeDialog *dialog);

### Warning

`gnome_dialog_close` is deprecated and should not be used in newly-written code.

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.

`dialog` : | GnomeDialog to close.

### gnome_dialog_close_hides ()

    void        gnome_dialog_close_hides        (GnomeDialog *dialog,
                                                 gboolean just_hide);

### Warning

`gnome_dialog_close_hides` is deprecated and should not be used in newly-written code.

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.

`dialog` : | GnomeDialog to affect.
`just_hide` : | If TRUE, `gnome_dialog_close()` calls `gtk_widget_hide()` instead of `gtk_widget_destroy()`.

### gnome_dialog_set_close ()

    void        gnome_dialog_set_close          (GnomeDialog *dialog,
                                                 gboolean click_closes);

### Warning

`gnome_dialog_set_close` is deprecated and should not be used in newly-written code.

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.

`dialog` : | GnomeDialog to affect.
`click_closes` : | TRUE if clicking any button should call `gnome_dialog_close()`.

### gnome_dialog_editable_enters ()

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

### Warning

`gnome_dialog_editable_enters` is deprecated and should not be used in newly-written code.

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.

`dialog` : | GnomeDialog to affect.
`editable` : | Editable to affect.

### gnome_dialog_append_buttons ()

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

### Warning

`gnome_dialog_append_buttons` is deprecated and should not be used in newly-written code.

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.

`dialog` : | GnomeDialog to add buttons to.
`first` : | First button to add.
`...` : | varargs list of additional buttons, NULL-terminated.

### gnome_dialog_append_button ()

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

### Warning

`gnome_dialog_append_button` is deprecated and should not be used in newly-written code.

Add a button to a dialog after its initial construction. 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.

`dialog` : | GnomeDialog to add button to.
`button_name` : | Button to add.

### gnome_dialog_append_buttonsv ()

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

### Warning

`gnome_dialog_append_buttonsv` is deprecated and should not be used in newly-written code.

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

`dialog` : | GnomeDialog to append to.
`buttons` : | NULL-terminated vector of buttons to append.

### gnome_dialog_append_button_with_pixmap ()

    void        gnome_dialog_append_button_with_pixmap
                                                (GnomeDialog *dialog,
                                                 const gchar *button_name,
                                                 const gchar *pixmap_name);

### Warning

`gnome_dialog_append_button_with_pixmap` is deprecated and should not be used in newly-written code.

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

`dialog` : | GnomeDialog to add the button to.
`button_name` : | Name of the button, or stock button define.
`pixmap_name` : | Stock pixmap name.

### gnome_dialog_append_buttons_with_pixmaps ()

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

### Warning

`gnome_dialog_append_buttons_with_pixmaps` is deprecated and should not be used in newly-written code.

Simply calls `gnome_dialog_append_button_with_pixmap()` repeatedly.

`dialog` : | GnomeDialog to append to.
`names` : | NULL-terminated vector of button names.
`pixmaps` : | NULL-terminated vector of pixmap names.

### gnome_dialog_construct ()

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

### Warning

`gnome_dialog_construct` is deprecated and should not be used in newly-written code.

See `gnome_dialog_new()`.

`dialog` : | Dialog to construct.
`title` : | Title of the dialog.
`ap` : | va_list of buttons, NULL-terminated.

### gnome_dialog_constructv ()

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

### Warning

`gnome_dialog_constructv` is deprecated and should not be used in newly-written code.

See `gnome_dialog_new()`.

`dialog` : | Dialog to construct.
`title` : | Title of the dialog.
`buttons` : | NULL-terminated array of buttons.

### GNOME_STOCK_BUTTON_OK

    #define GNOME_STOCK_BUTTON_OK     GTK_STOCK_OK

### Warning

`GNOME_STOCK_BUTTON_OK` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_CANCEL

    #define GNOME_STOCK_BUTTON_CANCEL GTK_STOCK_CANCEL

### Warning

`GNOME_STOCK_BUTTON_CANCEL` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_YES

    #define GNOME_STOCK_BUTTON_YES    GTK_STOCK_YES

### Warning

`GNOME_STOCK_BUTTON_YES` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_NO

    #define GNOME_STOCK_BUTTON_NO     GTK_STOCK_NO

### Warning

`GNOME_STOCK_BUTTON_NO` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_CLOSE

    #define GNOME_STOCK_BUTTON_CLOSE  GTK_STOCK_CLOSE

### Warning

`GNOME_STOCK_BUTTON_CLOSE` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_APPLY

    #define GNOME_STOCK_BUTTON_APPLY  GTK_STOCK_APPLY

### Warning

`GNOME_STOCK_BUTTON_APPLY` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_HELP

    #define GNOME_STOCK_BUTTON_HELP   GTK_STOCK_HELP

### Warning

`GNOME_STOCK_BUTTON_HELP` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_NEXT

    #define GNOME_STOCK_BUTTON_NEXT   GTK_STOCK_GO_FORWARD

### Warning

`GNOME_STOCK_BUTTON_NEXT` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_PREV

    #define GNOME_STOCK_BUTTON_PREV   GTK_STOCK_GO_BACK

### Warning

`GNOME_STOCK_BUTTON_PREV` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_UP

    #define GNOME_STOCK_BUTTON_UP     GTK_STOCK_GO_UP

### Warning

`GNOME_STOCK_BUTTON_UP` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_DOWN

    #define GNOME_STOCK_BUTTON_DOWN   GTK_STOCK_GO_DOWN

### Warning

`GNOME_STOCK_BUTTON_DOWN` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

### GNOME_STOCK_BUTTON_FONT

    #define GNOME_STOCK_BUTTON_FONT   GTK_STOCK_SELECT_FONT

### Warning

`GNOME_STOCK_BUTTON_FONT` is deprecated and should not be used in newly-written code.

This button has been replaced by one in GTK+ and new code should use that.

## Signals

### The "clicked" signal

    void        user_function                  (GnomeDialog *dialog,
                                                gint arg1,
                                                gpointer user_data);

`dialog` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "close" signal

    gboolean    user_function                  (GnomeDialog *dialog,
                                                gpointer user_data);

`dialog` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.
Returns : |