tsc_MessageBox

Overview

This class implements a message dialog similar to the standard Windows API MessageBox with the "Application Modal" flag.  Never use the Windows API to display message boxes; the dialog will often end up covered by another Survey Core window, and the user has no way of dismissing the dialog, which effectively locks up the application.  The Survey Core MessageBox on the other hand will remain at the front of all SC windows until dismissed.  It also conforms to Trimble UI design.

The functions are static and are therefore called like: tsc_MessageBox::Show(...);

Dialogs may be dismissed with the Esc key or the Enter key.  The Esc key will return Escape or X_NULL, and the Enter key will select the leftmost button that is present on the dialog.

A simple Ok message box

static void Show (const char* title, const char* message);
static void Show (x_Code title, x_Code message);
These methods display a message dialog with an OK button. The function does not return until the user Okays the dialog.

Standard button combinations

The usual sets of buttons (Ok, Yes, No, Cancel) can be displayed by using these methods. See below for the buttons and result types.

static StdResults Show (const char* title, const char* message, StdButtons buttons);
static StdResults Show (x_Code title, x_Code message, StdButtons buttons);

enum StdButtons { OkCancel, YesNo, YesNoCancel };

The following values may be returned by message boxes with standard buttons:

enum StdResults
{
    Escape = X_NULL,
    Ok     = X_SoftkeyOk,
    Cancel = X_SoftkeyCancel,
    Yes    = X_Yes,
    No     = X_No
};

Dialogs with custom buttons

It is possible to display a modal message dialog with up to four buttons configurable by x_Codes using the following method.  Buttons may be omitted by omitting the corresponsing parameter or by specifying X_NULL

static x_Code Show (const char* title,
                    const char* message,
                    x_Code      button1,
                    x_Code      button2 = X_NULL,
                    x_Code      button3 = X_NULL,
                    x_Code      button4 = X_NULL);

static x_Code Show (x_Code      title,
                    x_Code      message,
                    x_Code      button1,
                    x_Code      button2 = X_NULL,
                    x_Code      button3 = X_NULL,
                    x_Code      button4 = X_NULL);

If the user presses the Esc key to dismiss the dialog, X_NULL is returned.  Otherwise, the x_Code of the pressed button is returned.

Note:
Survey Core x_Codes which start with "x_Softkey..." are generally those whose translations are designed to be short enough to fit on a button.

It is possible to specify a timeout in seconds after which the dialog disappears and returns X_NULL to indicate the timeout (which is indistinguishable from Esc).

static x_Code Show (double      timeoutSecs,
                    const char* title,
                    const char* message,
                    x_Code      button1,
                    x_Code      button2 = X_NULL,
                    x_Code      button3 = X_NULL,
                    x_Code      button4 = X_NULL);

static x_Code Show (double      timeoutSecs,
                    x_Code      title,
                    x_Code      message,
                    x_Code      button1,
                    x_Code      button2 = X_NULL,
                    x_Code      button3 = X_NULL,
                    x_Code      button4 = X_NULL);

Sample code fragments

    switch (tsc_MessageBox::Show("Confirm","Replace the existing file?",   tsc_MessageBox::YesNoCancel))

    {

        case tsc_MessageBox::Yes:

            Replace();

            continue;

        case tsc_MessageBox::Escape:

        case tsc_MessageBox::No:

            continue;

        case tsc_MessageBox::Cancel:

            break;

     }

/////////////////////////////////////////////////////////////////////////////

if (tsc_MessageBox::Show (title, msg, X_SoftkeyContinue,
X_NULL, X_NULL, X_SoftkeyCancel) != X_SoftkeyContinue)

{

    Abort(); 

}