class Dialog

Defined in: C4Dialog.h

A Dialog class encapsulates a basic dialog box.

Definition

class Dialog : public Window, public Completable<Dialog>

Member Functions

Dialog::GetDialogStatus Returns the status of a dialog box.

Constructor

Dialog(const Vector2D& size, const char *title, const char *okayText,

const char *cancelText = nullptr, const char *ignoreText = nullptr);

Parameters

`size`	The size of the dialog window.
`title`	The dialog window's displayed title.
`okayText`	The text to be displayed in the okay button. This should not be `nullptr`.
`cancelText`	The text to be displayed in the cancel button. This can be `nullptr`.
`ignoreText`	The text to be displayed in the ignore button. This can be `nullptr`.

Description

The Dialog class provides a convenient way to display a basic dialog box. Between one and three buttons, having the semantic meanings “okay”, “cancel”, and “ignore”, are displayed at the bottom of the dialog box. Other interface widgets can be added by creating them separately and then calling Tree::AddSubnode to add them to the window.

The okayText parameter specifies the text that is displayed in the okay button. The okay button is triggered if the user presses the Enter key (or the Return key on the Mac). If there is no cancel button, then the Escape key also triggers the okay button.

If the cancelText parameter is not nullptr, then a cancel button is displayed with the text it specifies. The cancel button is triggered if the user presses the Escape key.

If the ignoreText parameter is not nullptr, then a button is displayed on the left side of the window with the text it specifies. No keys trigger the ignore button.

Once a dialog box has been created, it can be displayed by calling the InterfaceMgr::AddWidget function. If a dialog box is added to an existing window using the Window::AddSubwindow function, then it becomes a modal dialog for that window.

When the user clicks a button or presses a key that triggers a button, the dialog box is dismissed. Before the Dialog object destroys itself, it records which button was triggered and calls its completion procedure. The completion procedure can call the Dialog::GetDialogStatus function to determine which button was triggered to dismiss the dialog.

Base Classes

`Window`	The `Dialog` class is a specific type of window.
`Completable<Dialog>`	The completion procedure is called when the dialog is dismissed.