minigui-docs/programming-guide/MiniGUIProgGuidePart1Chapter03.md

Foundation of Dialog Box Programming

• Main Window and Dialog Box
• Dialog Box Template
• Dialog Box Callback Function
• MSG_INITDIALOG Message
• Modal and Modeless Dialog Box
• Control Styles and Operations Relevant to Dialog Box

The dialog box programming is a technique to construct a user interface quickly. In general, when we write a simple user interface, we can directly create all the needed child windows, i.e. the controls, by calling CreateWindow function. But when the user interface is complex, it is undesirable to call the CreateWindow function each time a control is created, and pass many complex arguments. One of the main reasons is that the program code is mixed with the data for creating controls, which is not good for maintaining. Therefore, a usual GUI system provides a mechanism, your can create corresponding main windows and controls according to the specified template by using this mechanism. MiniGUI also provides this method, and can create a modal or modeless dialog box by using a dialog box template.

This chapter first describes the different between main window and dialog box, and then describes the definition of the dialog box template, the dialog box callback function, and usage of some important messages. At last, this chapter illustrates the programming techniques of modal and modeless dialog boxes and the difference between them.

Main Window and Dialog Box

In MiniGUI, a dialog box is a special main window, which pays attention only to the interaction with the user: it displays the output information and more often receives the input from the user. The dialog box can be interpreted as a subclassed main window class. It is specially designed for the specialty of the dialog box (that is to interact with the user). For example, the user can use TAB key to travel the controls and can use ENTER key to indicate the default input.

Dialog Box Template

In MiniGUI, two structures are used to denote the dialog box template (minigui/window.h), shown as follows:

typedef struct _CTRLDATA
{
    /** Class name of the control */
    const char* class_name;
    /** Control style */
    DWORD       dwStyle;
    /** Control position in dialog */
    int         x, y, w, h;
    /** Control identifier */
    int         id;
    /** Control caption */
    const char* caption;
    /** Additional data */
    DWORD       dwAddData;
    /** Control extended style */
    DWORD       dwExStyle;

    /** window element renderer name */
    const char* werdr_name;

    /** table of we_attrs */
    const WINDOW_ELEMENT_ATTR* we_attrs;
} CTRLDATA;
typedef CTRLDATA* PCTRLDATA;

typedef struct _DLGTEMPLATE
{
    /** Dialog box style */
    DWORD       dwStyle;
    /** Dialog box extended style */
    DWORD       dwExStyle;
    /** Dialog box position */
    int         x, y, w, h;
    /** Dialog box caption */
    const char* caption;
    /** Dialog box icon */
    HICON       hIcon;
    /** Dialog box menu */
    HMENU       hMenu;
    /** Number of controls */
    int         controlnr;
    /** Poiter to control array */
    PCTRLDATA   controls;
    /** Addtional data, must be zero */
    DWORD       dwAddData;
} DLGTEMPLATE;
typedef DLGTEMPLATE* PDLGTEMPLATE;

The structure CTRLDATA is used to define controls, and DLGTEMPLATE is used to define the dialog box itself. You should first use CTRLDATA to define all the controls in the dialog box and express them with a structure array. The order of controls in the array is the switch order when the user presses TAB key. And then, you define the dialog box, specify the number of controls in the dialog box, and let the member controls in DLGTEMPLATE structure point to the array defining the controls, as shown in List 1.

NOTE There are two new members, werdr_name and we_attrs, in CTRLDATA structure in MiniGUI 3.0. These two members specify the renderer and window element property. About the descriptions of renderer and window element property, please refer to Chapter 10. They are the last members in the structure, and they will be initialized to zero if the structure is defined as static variable or global variable, it means to use default renderer and window element property. The application based on MiniGUI 1.6/2.0 can be compiled in MiniGUI 3.0 directly, if its CTRLDATA structure is defined as static variable or global variable.

List 1 Definition of dialog box template

static DLGTEMPLATE DlgInitProgress =
{
    WS_BORDER | WS_CAPTION, 
    WS_EX_NONE,
    120, 150, 400, 130, 
    "VAM-CNC is initializing",
    0, 0,
    3, NULL,
    0
};

static CTRLDATA CtrlInitProgress [] =
{ 
    {
        "static",
        WS_VISIBLE | SS_SIMPLE,
        10, 10, 380, 16, 
        IDC_PROMPTINFO, 
        "Initializing...",
        0
    },
    {
        "progressbar",
        WS_VISIBLE,
        10, 40, 380, 20,
        IDC_PROGRESS,
        NULL,
        0
    },
    {
        "button",
        WS_TABSTOP | WS_VISIBLE | BS_DEFPUSHBUTTON, 
        170, 70, 60, 25,
        IDOK, 
        "OK",
        0
    }
};

NOTE Data variables for defining the dialog box template in the program should be defined as static data, so that the data definition is validate only in its file, and it can be avoided causing potential compiling or linking errors due to the pollution of the name space.

Dialog Box Callback Function

You need define the callback function of the dialog box after defining its template data, and call DialogBoxIndirectParam function to create a dialog box, as shown in List 2. The running effect of the created dialog box is as shown in Figure 1. Please refer to dialogbox.c of the sample program package mg-samples for this guide to get the complete source code of this program.

List 2 Defining the callback function of a dialog box and creating the dialog box

/* Define the dialog box callback function */
static int InitDialogBoxProc (HWND hDlg, int message, WPARAM wParam, LPARAM lParam)
{
   switch (message) {
   case MSG_INITDIALOG:
       return 1;
   case MSG_COMMAND:
       switch (wParam) {
       case IDOK:
       case IDCANCEL:
          EndDialog (hDlg, wParam);
          break;
       }
       break;
   }
   return DefaultDialogProc (hDlg, message, wParam, lParam);
}
static void InitDialogBox (HWND hWnd)
{
   /* Assoiciate the dialog with the control structure array */
   DlgInitProgress.controls = CtrlInitProgress;
   DialogBoxIndirectParam (&DlgInitProgress, hWnd, InitDialogBoxProc, 0L);
}

Figure 1 The dialog box created by program in List 2

The prototypes of DialogBoxIndirectParam and related functions are listed as follow:

int GUIAPI DialogBoxIndirectParamEx (PDLGTEMPLATE pDlgTemplate,
        HWND hOwner, WNDPROC DlgProc, LPARAM lParam,
        const char* werdr_name, WINDOW_ELEMENT_ATTR* we_attrs,
        const char* window_name, const char* layer_name);

static inline int GUIAPI DialogBoxIndirectParam (PDLGTEMPLATE pDlgTemplate,
        HWND hOwner, WNDPROC DlgProc, LPARAM lParam)
{
    return DialogBoxIndirectParamEx (pDlgTemplate, hOwner, DlgProc, lParam,
                                    NULL, NULL, NULL, NULL);
}

BOOL GUIAPI EndDialog (HWND hDlg, int endCode);
void GUIAPI DestroyAllControls (HWND hDlg);

When calling DialogBoxIndirectParam, you should specify the dialog box template (pDlgTemplate), the handle of the hosting main window of the dialog box (hOwner), the callback function address of the dialog box (DlgProc), and the parameter value (lParam) to be passed to the dialog box callback procedure. EndDialog is used to terminate the dialog box. DestroyAllControls is used to destroy all the child controls of the dialog box (This function can be used by a main window).

In MiniGUI 3.0, DialogBoxIndirectParam is defined as an inline function, it invokes DialogBoxIndirectParamEx to create dialog box. There are four new arguments in DialogBoxIndirectParamEx function:

• werdr_name: the name of renderer
• we_attrs: the property sheet of window element
• window_name: the name of window string, reserved, shall pass NULL
• layer_name: the name of window's graph layer, reserved, shall pass NULL

The dialog box callback function does not perform any substantial work in List 2, and calls EndDialog function to return directly when the user click “OK” button.

MSG_INITDIALOG Message

The dialog box callback function is a special main window procedure function. When you define your own dialog box callback function, MSG_INITDIALOG message needs to be handled. This message is sent to the dialog box after MiniGUI creates the dialog box and controls according to the dialog box template. LParam parameter of this message includes the value that passed to the dialog box callback function by the fourth argument of DialogBoxIndirectParam function. The user can use this value to initialize the dialog box or save it for future use. For example, the program in List 3 saves lParam parameter of MSG_INITDIALOG message to the additional data of the dialog box window, so that this data can be readily gotten from the additional data of the dialog box window whenever needed.

List 3 Handling of MSG_INITDIALOG message

static int DepInfoBoxProc (HWND hDlg, int message, WPARAM wParam, LPARAM lParam)
{
    struct _DepInfo *info;

    switch(message) {
    case MSG_INITDIALOG:
    {
        /* Get lParam parameter passed to this dialog box, and assign it 
         * to the first additional data assoiciated with the dialog box
         * for future use. */

        info = (struct _DepInfo*)lParam;

        /* Use the data in the info structure to initialize the dialog box */
        ......

        SetWindowAdditionalData (hDlg, (DWORD)lParam);
        break;
    }

    case MSG_COMMAND:
    {
        /* Get the parameter from the first additional data 
         * assoiciated with the dialog box */

        info = (struct _DepInfo*) GetWindowAdditionalData (hDlg);

        switch(wParam) {
        case IDOK:
            /* Use the data in the info structure. */
            ......

        case IDCANCEL:
            EndDialog(hDlg,wParam);
            break;
        }
    }
    }

    return DefaultDialogProc (hDlg, message, wParam, lParam);
}

Generally, the parameter passed to the dialog box callback function is a pointer to a structure. The structure includes some data for initializing the dialog box, and can also save the input data of the dialog box and pass it outside of the dialog box for use.

If the dialog box callback function returns a nonzero value when handling MSG_INITDIALOG message, MiniGUI will set the input focus to the first control with WS_TABSTOP style.

Modal and Modeless Dialog Box

At a word, the modal dialog box is a dialog box that the user cannot switch to other main windows once this dialog box has been displayed. The user can only use other main windows when closing the modal dialog box. In MiniGUI, the dialog box created by DialogBoxIndirectParam function is a modal dialog. In fact, the dialog box first creates a dialog box according to the template, then disables its hosting main window and creates controls in MSG_CREATE message of the main window, and then sends MSG_INITDIALOG message to the callback function, and lastly enters a new message loop until the program calls EndDialog function.

In fact, we also can create a normal main window using the dialog box template in MiniGUI, i.e. the modeless dialog box. Here we use CreateMainWindowIndirect function. The following is the prototypes of this function and its related functions (minigui/window.h):

MG_EXPORT HWND GUIAPI CreateMainWindowIndirectParamEx (PDLGTEMPLATE pDlgTemplate,
        HWND hOwner, WNDPROC WndProc, LPARAM lParam,
        const char* werdr_name, WINDOW_ELEMENT_ATTR* we_attrs,
        const char* window_name, const char* layer_name);

static inline HWND GUIAPI
CreateMainWindowIndirectParam (PDLGTEMPLATE pDlgTemplate,
        HWND hOwner, WNDPROC WndProc, LPARAM lParam)
{
    return CreateMainWindowIndirectParamEx (pDlgTemplate, hOwner,
            WndProc, lParam, NULL, NULL, NULL, NULL);
}

#define CreateMainWindowIndirect(pDlgTemplate, hOwner, WndProc) \
            CreateMainWindowIndirectParam(pDlgTemplate, hOwner, WndProc, 0)

BOOL GUIAPI DestroyMainWindowIndirect (HWND hMainWin);

In MIniGUI 3.0, CreateMainWindowIndirect and CreateMainWindowIndirectParam are defined as inline functions, they invoke CreateMainWindowIndirectParamEx to create dialog box. There are four new arguments in CreateMainWindowIndirectParamEx function:

• werdr_name: the name of renderer
• we_attrs: the property sheet of window element
• window_name: the name of window string, reserved, shall pass NULL
• layer_name: the name of window's graph layer, reserved, shall pass NULL

The main window created by CreateMainWindowIndirect according to the dialog template is not different from a normal main window at all. However, CreateMainWindowIndirect is different from DialogBoxIndirectParam function as follows:

• After creating the main window with the data in the dialog box template, CreateMainWindowIndirect function will return immediately, while DialogBoxIndirectParam will enters a new message loop.

The program in List 4 creates a main window with the dialog box template in List 1

List 4 Creating a main window with a dialog box template

/* Define the window callback function */
static int InitWindowProc (HWND hDlg, int message, WPARAM wParam, LPARAM lParam)
{
    switch (message) {
    case MSG_COMMAND:
        switch (wParam) {
        case IDOK:
        case IDCANCEL:
            DestroyMainWindowIndirect (hWnd);
            break;
        }
        break;

    }

    return DefaultWindowProc (hDlg, message, wParam, lParam);
}

    ...

{
    HWND hwnd;
    MSG  Msg;

    /* Assocate the dialog box template with control array */
    DlgInitProgress.controls = CtrlInitProgress;

    /* Create the main window */
    hwnd = CreateMianWindowIndirect (&DlgInitProgress, HWND_DESKTOP, InitWindowProc);

    if (hwnd == HWND_INVALID)
        return -1;

    while (GetMessage (&Msg, hwnd)) {
       TranslateMessage (&Msg);
       DispatchMessage (&Msg);
    }
}

The program in List 4 will create a main window, which is completely the same with the dialog box in Figure 1.

Control Styles and Operations Relevant to Dialog Box

Some general window styles are only valid for child controls in the dialog box; Table 1 summarizes these styles. The default window procedure of the dialog box will handle control with these styles.

Table 1 Some styles used only for the controls in a dialog box

Style Identifier	Purpose	Comment
WS_GROUP	Controls with this style will be the leader of the same group.	Controls from this control to the control before next control with WS_GROUP style, or to the control before the control with different class, belong to the same group
WS_TABSTOP	Have TAB-stop function	Indicates the user can set the input focus to the control by using Tab key

MiniGUI provides some operation function for the dialog box, summarized as in Table 2. It should be noted that, these functions are not limited to be used in dialog boxes although their name having prefix of “Dlg”. For example, GetDlgItemText function can be used to get the text of the child controls if only the handle of parent window and the identifier of child controls are known.

Table 2 Operation functions of the dialog box

Function	Purpose	Comment
DestroyAllControls	Destroys all controls in a window
GetDlgCtrlID	Gets the integer identifier of a control
GetDlgItem	Retrieves the handle to a control in a dialog box
GetDlgItemInt	Translates the text of a control in a dialog box into an integer value
SetDlgItemInt	Sets the text of a control in a dialog box to the string representation of a specified integer value
GetDlgItemText	Retrieves the title or text associated with a control in a dialog box	Function is same as GetWindowText
GetDlgItemText2	Retrieves the title or text associated with a control in a dialog box	Automatically allocate memory according to the text length, application is responsible for releasing these memory.
SetDlgItemText	Sets the title or text of a control in a dialog box	Function is same as SetWindowText
GetNextDlgGroupItem	Retrieves the handle to the first control in a group of controls that precedes (or follows) the specified control in a dialog box	Used for traveling the same group controls, please refer to WS_GROUP style
GetNextDlgTabItem	Retrieves the handle to the first control that has the WS_TABSTOP style that precedes (or follows) the specified control	Used for TAB key traveling controls, please refer to WS_TABSTOP style
SendDlgItemMessage	Sends a message to the specified control in a dialog box	Function is same as SendMessage
CheckDlgButton	Changes the check status of a button control
CheckRadioButton	Adds a check mark to (checks) a specified radio button in a group and removes a check mark from (clears) all other radio buttons in the group
IsDlgButtonChecked	Determines whether a button control has a check mark next to it or whether a three-state button control is grayed, checked, or neither
GetDlgDefPushButton	Gets the default push button control in a window

---

<< Window and Message | Table of Contents | Foundation of Control Programming >>