Dialog boxes are a convenient way to prompt the user for a small amount of input, e.g. to display a message, ask a question, or anything else that does not require extensive effort on the user's part.

Gtk+ treats a dialog as a window split vertically. The top section is a VBox, and is where widgets such as a Label or a Entry should be packed. The bottom area is known as the action_area. This is generally used for packing buttons into the dialog which may perform functions such as cancel, ok, or apply. The two areas are separated by a HSeparator.

Dialog boxes are created with a call to dialogNew or dialogNewWithButtons. dialogNewWithButtons is recommended; it allows you to set the dialog title, some convenient flags, and add simple buttons.

If 'dialog' is a newly created dialog, the two primary areas of the window can be accessed using dialogGetUpper and dialogGetActionArea.

A 'modal' dialog (that is, one which freezes the rest of the application from user input), can be created by calling windowSetModal on the dialog. When using dialogNewWithButtons you can also pass the DialogModal flag to make a dialog modal.

If you add buttons to Dialog using dialogNewWithButtons, dialogAddButton, dialogAddButtons, or dialogAddActionWidget, clicking the button will emit a signal called "response" with a response ID that you specified. Gtk+ will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the ResponseType enumeration (these all have values less than zero). If a dialog receives a delete event, the "response" signal will be emitted with a response ID of ResponseNone.

If you want to block waiting for a dialog to return before returning control flow to your code, you can call dialogRun. This function enters a recursive main loop and waits for the user to respond to the dialog, returning the response ID corresponding to the button the user clicked.

For a simple message box, you probably want to use MessageDialog which provides convenience functions for creating standard dialogs containing simple messages to inform or ask the user.

• Class Hierarchy | | GObject | +----Object | +----Widget | +----Container | +----Bin | +----Window | +----Dialog | +----AboutDialog | +----ColorSelectionDialog | +----FileChooserDialog | +----FileSelection | +----FontSelectionDialog | +----InputDialog | +----MessageDialog

Get the upper part of a dialog.

• The upper part of a dialog window consists of a VBox. Add the required widgets into this box.

Extract the action area of a dialog box.

• This is useful to add some special widgets that cannot be added with dialogAddActionWidget.

Blocks in a recursive main loop until the dialog either emits the response signal, or is destroyed. If the dialog is destroyed during the call to dialogRun, it returns ResponseNone. Otherwise, it returns the response ID from the "response" signal emission. Before entering the recursive main loop, dialogRun calls widgetShow on the dialog for you. Note that you still need to show any children of the dialog yourself.

During dialogRun, the default behavior of "delete_event" is disabled; if the dialog receives "delete_event", it will not be destroyed as windows usually are, and dialogRun will return ResponseDeleteEvent. Also, during dialogRun the dialog will be modal. You can force dialogRun to return at any time by calling dialogResponse to emit the "response" signal. Destroying the dialog during dialogRun is a very bad idea, because your post-run code won't know whether the dialog was destroyed or not. Hence, you should not call widgetDestroy once dialogRun has returned.

After dialogRun returns, you are responsible for hiding or destroying the dialog if you wish to do so.

Note that even though the recursive main loop gives the effect of a modal dialog (it prevents the user from interacting with other windows while the dialog is run), callbacks such as timeouts, IO channel watches, DND drops, etc, will be triggered during a dialogRun call.

Emits the "response" signal with the given response ID. Used to indicate that the user has responded to the dialog in some way; typically either you or dialogRun will be monitoring the "response" signal and take appropriate action.

This function can be used to add a custom widget to the action area that should close the dialog when activated or to close the dialog otherwise.

Sets the last widget in the dialog's action area with the given ResponseId as the default widget for the dialog. Pressing "Enter" normally activates the default widget.

• The default response is reset once it is triggered. Hence, if you hide the dialog (rather than closing it) and re-display it later, you need to call this function again.

The dialog has a separator bar above its buttons.

Default value: True