[Home]  [Prev]  [Next]    Guide for building well-designed cross-platform applications

5. Dialogs and Panels

5.1 Modal/modeless dialogs

Dialogs are a somewhat controversial especially their use as modal or modeless. It does not matter much if a dialog is or is not modal but a dialog has to "vanish" from the display when its action is finished, possibly leaving the dialog in a hidden state. Modal or modeless can be used as guidance for the user to achieve the right order of action.

Dialogs should only be used for small tasks where it isn't necessary to be shown all the time. Usually an application should have an ordinary frame window as its main window. Only application which e.g. just change some settings/preferences should use a dialog as the main window.

For users it's much easier to understand and use modal dialogs. This is yet another reason to use a frame instead of none modal dialogs. Of course modal dialogs have their limitation when they aren't implemented correct. A modal dialog should only block all the upper level windows up to the top level window but not further. Unfortunately this implementation is very common. To overcome this situation either live with modal dialogs or use none modal but block all the upper windows yourself.

Below is a sample of a modal dialog which lives through a session. This has the advantage that the data in the dialog persist which still be a simple modal dialog.

Sample code: Session long modal dialog

class Demo: public wxPanel {
    void OnSampleDlg (wxCommandEvent &event);
    void OnSampleDlgUI (wxUpdateUIEvent &event);
    SampleDlg *m_SampleDlg;

    EVT_MENU (myID_SAMPLEDLG,        Demo::OnSampleDlg)
    EVT_UPDATE_UI (myID_SAMPLEDLG,   Demo::OnSampleDlgUI)
Demo::Demo (wxWindow *parent, wxWindowID id,
    m_SampleDlg = new SampleDlg (this, m_text);

Demo::~Demo () {
    if (m_SampleDlg) delete m_SampleDlg;

void Demo::OnSampleDlg (wxCommandEvent &WXUNUSED(event)) {
    m_SampleDlg->SetText (_("This is a text."));
    if (!m_text.IsEmpty()) {
        // nothing so far

void Demo::OnSampleDlgUI (wxUpdateUIEvent &event) {
    event.Enable (true);

The sample dialog code itself can be looked up in the dialogs.cpp, dialogs.h sources of the demo application.

5.2 Close box on dialogs

A dialog may have a close box which always has the effect of cancelling the dialog even if there isn't a cancel button. Like the cancel button, the ESC key can be used to activate the close box, therefore a cancel.

Using the ESC key is sometimes difficult since because it should be handled by the framework but isn't. wxWidgets does it only for items marked with wxID_CANCEL.

Sample code: ESC key for OK-button

BEGIN_EVENT_TABLE (..., wxDialog)
    EVT_BUTTON (wxID_CANCEL, ...::OnOkay)
    wxButton *okButton = new wxButton (this, wxID_CANCEL, _("OK"));

5.3 Buttons in dialogs

Usually all buttons of a dialog are equally sized and equally spaced, except otherwise mentioned. If this isn't possible the sizes should be increases by defined multiples (e.g. 1.5, 2, 2.5 times) of the minimal size.

Buttons are the usual way to start a command in a dialog. They are usually located left-to-right on the bottom or top-down on the right side of a dialog, depending on the size restrictions of the dialog.

The normal action button (usually "OK") is located in the "middle" of the left-to-right order or on the top in the top-down order and always ends a dialog (hides it). The normal action button usually is also the default button.

An optional apply action button may follow the normal action button on the right or down. An apply action does invoke a task but never leaves the dialog. It always acts as if the dialog is ended with the normal action button but just called again.

The cancel action button is always located on the right or lowest position of any button. It always cancels a task leaving anything in a state as if the dialog wasn't called. If this isn't possible any task has to be handled like a delete action and the cancel button has to be removed or disabled after a non cancel able state is reached. The cancel button may never be the default button.

An optional help button may be located in the left most position of the left-to-right order, most of the time separated in space from the other buttons. The absence of a help button may not mean the absence of the help, it may be invoked by other means.

Optional special action buttons may be located left or below of the normal action button.

5.4 Message box

If a message dialog shows a questions its buttons should not be labelled "OK" and "cancel" instead of "yes" and "no" or better use verbs which describes the chosen actions as "do" and "don't". If your message box shows two buttons make sure your question can only be understand it this two ways.

5.5 Panels (windows)

Panels are rather similar to dialogs, they look almost the same. Panels don't vanish they always are displayed and they can have menus. Panels are mostly used for forms.