Tutorial 10: Dialog Box as Main Window

Now comes the really interesting part about GUI, the dialog box. In this tutorial (and the next), we will learn how to use a dialog box as our main window.
 

Theory:

If you play with the examples in the previous tutorial long enough, you 'll find out that you cannot change input focus from one child window control to another with Tab key. The only way you can do that is by clicking the control you want it to gain input focus. This situation is rather cumbersome. Another thing you might notice is that I changed the background color of the parent window to gray instead of normal white as in previous examples. This is done so that the color of the child window controls can blend seamlessly with the color of the client area of the parent window. There is a way to get around this problem but it's not easy. You have to subclass all child window controls in your parent window.
The reason why such inconvenience exists is that child window controls are originally designed to work with a dialog box, not a normal window. The default color of child window controls such as a button is gray because the client area of a dialog box is normally gray so they blend into each other without any sweat on the programmer's part.
Before we get deep into the detail, we should know first what a dialog box is. A dialog box is nothing more than a normal window which is designed to work with child window controls. Windows also provides internal "dialog box manager" which is responsible for most of the keyboard logic such as shifting input focus when the user presses Tab, pressing the default pushbutton if Enter key is pressed, etc so programmers can deal with higher level tasks. Dialog boxes are primarily used as input/output devices. As such a dialog box can be considered as an input/output "black box" meaning that you don't have to know how a dialog box works internally in order to be able to use it, you only have to know how to interact with it. That's a principle of object oriented programming (OOP) called information hiding. If the black box is *perfectly* designed, the user can make use of it without any knowledge on how it operates. The catch is that the black box must be perfect, that's hard to achieve in the real world. Win32 API is also designed as a black box too.
Well, it seems we stray from our path. Let's get back to our subject. Dialog boxes are designed to reduce workload of a programmer. Normally if you put child window controls on a normal window, you have to subclass them and write keyboard logic yourself. But if you put them on a dialog box, it will handle the logic for you. You only have to know how to get the user input from the dialog box or how to send commands to it.
A dialog box is defined as a resource much the same way as a menu. You use SpAsm resource editor to do the job visually since arranging child window controls on a dialog box is hard to do manually.
There are two main types of dialog box: modal and modeless. A modeless dialog box lets you change input focus to other window. The example is the Find dialog of MS Word. There are two subtypes of modal dialog box: application modal and system modal. An application modal dialog box doesn't let you change input focus to other window in the same application but you can change the input focus to the window of OTHER application. A system modal dialog box doesn't allow you to change input focus to any other window until you respond to it first.
A modeless dialog box is created by calling CreateDialogParam API function. A modal dialog box is created by calling DialogBoxParam. The only distinction between an application modal dialog box and a system modal one is the DS_SYSMODAL style. If you include DS_SYSMODAL style in a dialog box template, that dialog box will be a system modal one.
You can communicate with any child window control on a dialog box by using SendDlgItemMessage function. Its syntax is like this:
 
SendDlgItemMessage proto hwndDlg:DWORD,\
                                             idControl:DWORD,\
                                             uMsg:DWORD,\
                                             wParam:DWORD,\
                                             lParam:DWORD
This API call is immensely useful for interacting with a child window control. For example, if you want to get the text from an edit control, you can do this:
call 'USER32.SendDlgItemMessageA'  D§hDlg  ID_EDITBOX  &WM_GETTEXT   256  text_buffer
In order to know which message to send, you should consult your Win32 API reference.
Windows also provides several control-specific API functions to get and set data quickly, for example, GetDlgItemText, CheckDlgButton etc. These control-specific functions are provided for programmer's convenience so he doesn't have to look up the meanings of wParam and lParam for each message. Normally, you should use control-specific API calls when they're available since they make source code maintenance easier. Resort to SendDlgItemMessage only if no control-specific API calls are available.
The Windows dialog box manager sends some messages to a specialized callback function called a dialog box procedure which has the following format:
Proc DlgProc:
        Arguments  @hDlg,  @iMsg,  @wParam,  @lParam
The dialog box procedure is very similar to a window procedure except for the type of return value which is TRUE/FALSE instead of LRESULT. The internal dialog box manager inside Windows IS the true window procedure for the dialog box. It calls our dialog box procedure with some messages that it received. So the general rule of thumb is that: if our dialog box procedure processes a message,it MUST return TRUE in eax and if it does not process the message, it must return FALSE in eax. Note that a dialog box procedure doesn't pass the messages it does not process to the DefWindowProc call since it's not a real window procedure.
There are two distinct uses of a dialog box. You can use it as the main window of your application or use it as an input device. We 'll examine the first approach in this tutorial.
"Using a dialog box as main window" can be interpreted in two different senses.
  1. You can use the dialog box template as a class template which you register with RegisterClassEx call. In this case, the dialog box behaves like a "normal" window: it receives messages via a window procedure referred to by lpfnWndProc member of the window class, not via a dialog box procedure. The benefit of this approach is that you don't have to create child window controls yourself, Windows creates them for you when the dialog box is created. Also Windows handles the keyboard logic for you such as Tab order etc. Plus you can specify the cursor and icon of your window in the window class structure.

  2. Your program just creates the dialog box without creating any parent window. This approach makes a message loop unnecessary since the messages are sent directly to the dialog box procedure. You don't even have to register a window class!
This tutorial is going to be a long one. I'll present the first approach followed by the second.

Examples:


10dialogA


[DLGWINDOWEXTRA 30]

[WindowClassEx: wc_Size: len        wc_style: &CS_HREDRAW+&CS_VREDRAW   WndProc: MainWindowProc
                wc_ClsExtra: 0      wc_WndExtra: DLGWINDOWEXTRA         hInstance: 0
                wc_hIcon: 0         wc_hCursor: 0                       wc_hbrBackground: 16
                wc_MenuName: 2000   wc_ClassName: ClassName             wc_hIconSm: 0]
 

[ClassName: 'DLGCLASS' 0   AppName: 'Our First Window' 0]
[TestString:  "Wow! I'm in an edit box now" 0]
[DlgName: 'MyDialog' 0  MenuName: 'MyMenu' 0]
 

[FirstMessage: 0 #7] [Buffer: B§ 0 #512]  [hDlg: 0   WindowHandle: 0]

[IDC_EDIT       3000   IDC_BUTTON     3001   IDC_EXIT       3002  IDM_EXIT       2]

[M00_Menu  2100        M00_Test_Controls  2101   M00_Get_Text  2102
 M00_Clear_Text  2103  M00_Exit  2104]

[MyDialogID 2000]

____________________________________________________________________________________________
____________________________________________________________________________________________

Main:
    call 'Kernel32.GetModuleHandleA' &NULL   | mov D§hInstance eax
    call 'User32.LoadIconA'  0  &IDI_WINLOGO | mov D§wc_hIcon eax  D§wc_hIconSm eax
    call 'User32.LoadCursorA' 0  &IDC_ARROW  | mov D§wc_hCursor eax
    call 'User32.RegisterClassExA'  WindowClassEX
    call 'User32.CreateDialogParamA' D§hInstance MyDialogID &NULL &NULL &NULL | mov D§hDlg eax
    call 'User32.GetDlgItem' D§hDlg IDC_EDIT
    call 'User32.SetFocus' eax
    call 'User32.ShowWindow' D§hDlg &SW_SHOWNORMAL
    call 'User32.UpdateWindow' D§hDlg

L1: call 'User32.GetMessageA' FirstMessage 0 0 0 | cmp eax 0 | je L9>
        call 'User32.IsDialogMessage'  D§hDlg  FirstMessage
            If eax = 0
                call 'User32.TranslateMessage'  FirstMessage
                call 'User32.DispatchMessageA'  FirstMessage
            End_If
    jmp L1<

L9: call 'Kernel32.ExitProcess' 0
 

____________________________________________________________________________________________

Proc MainWindowProc:
    Arguments @Adressee, @Message, @wParam, @lParam
 
    pushad
 
    ...If D@Message = &WM_DESTROY
         call 'User32.PostQuitMessage' &NULL
 
    ...Else_if D@Message = &WM_CREATE
         call 'User32.SetDlgItemTextA' D@Adressee IDC_EDIT AppName
 
    ...Else_if D@Message = &WM_COMMAND
         mov eax D@wParam
         ..If D@lParam = 0
              .If ax = M00_Get_Text
                  call 'User32.GetDlgItemTextA' D@Adressee IDC_EDIT buffer 512
                  call 'User32.MessageBoxA' &NULL buffer AppName &MB_OK
              .Else_If ax = M00_Clear_Text
                  call 'User32.SetDlgItemTextA' D@Adressee IDC_EDIT &NULL
              .Else
                  call 'User32.DestroyWindow' D@Adressee
              .End_If
 
         ..Else
             mov edx D@wParam | shr edx 16
             .If dx = &BN_CLICKED
                 If ax = IDC_BUTTON
                    call 'User32.SetDlgItemTextA' D@Adressee IDC_EDIT TestString
                 Else_If ax = IDC_EXIT
                   call 'User32.SendMessageA' D@Adressee &WM_COMMAND IDM_EXIT 0
                 End_If
             .ENDIF
         ..End_If
 
    ...Else
        popad
        call 'User32.DefWindowProcA' D@Adressee D@Message D@wParam D@lParam
        Exit
 
    ...End_If
 
      popad | mov eax &FALSE
EndP

Analysis:

Let's analyze this first example.
This example shows how to register a dialog template as a window class and create a "window" from that class. It simplifies your program since you don't have to create the child window controls yourself.

The interesting part the assembly source code is in the window class structure:

          wc_WndExtra: DLGWINDOWEXTRA
          wc_ClassName: ClassName

Normally, this member is left NULL, but if we want to register a dialog box template as a window class, we must set this member to the value DLGWINDOWEXTRA. Note that the name of the class must be identical to the one following the CLASS keyword in the dialog box template. The remaining members are initialized as usual. After you fill the window class structure, register it with RegisterClassEx. Seems familiar? This is the same routine you have to do in order to register a normal window class.
 

After registering the "window class", we create our dialog box. In this example, I create it as a modeless dialog box with CreateDialogParam function. This function takes 5 parameters but you only have to fill in the first two: the instance handle and the pointer to the name of the dialog box template. Note that the 2nd parameter is not a pointer to the class name.
At this point, the dialog box and its child window controls are created by Windows. Your window procedure will receive WM_CREATE message as usual. After the dialog box is created, I want to set the input focus to the edit control. If I put these codes in WM_CREATE section, GetDlgItem call will fail since at that time, the child window controls are not created yet. The only way you can do this is to call it after the dialog box and all its child window controls are created. So I put these two lines after the UpdateWindow call. GetDlgItem function gets the control ID and returns the associated control's window handle. This is how you can get a window handle if you know its control ID.

 
L1: call 'User32.GetMessageA' FirstMessage 0 0 0 | cmp eax 0 | je L9>
        call 'User32.IsDialogMessage'  D§hDlg  FirstMessage
            If eax = 0
                call 'User32.TranslateMessage'  FirstMessage
                call 'User32.DispatchMessageA'  FirstMessage
            End_If
    jmp L1<

The program enters the message loop and before we translate and dispatch messages, we call IsDialogMessage function to let the dialog box manager handles the keyboard logic of our dialog box for us. If this function returns TRUE , it means the message is intended for the dialog box and is processed by the dialog box manager. Note another difference from the previous tutorial. When the window procedure wants to get the text from the edit control, it calls GetDlgItemText function instead of GetWindowText. GetDlgItemText accepts a control ID instead of a window handle. That makes the call easier in the case you use a dialog box.



Now let's go to the second approach to using a dialog box as a main window. In the next example, I 'll create an application modal dialog box. You'll not find a message loop or a window procedure because they're not necessary!
10DialogB (Part 2)


[hInstance: 0] [buffer: B§ 0 #512]
[AppName: 'Our Second Dialog Box' 0  TestString: "Wow! I'm in an edit box now" 0]

; menu equates (given by the editor):
 

[M00_Menu  1000                  M00_Test_Controls  1001         M00_Get_Text  1002
 M00_Clear_Text  1003            M00_Exit  1004]
 
; Controls equates (set by me):

[IDC_BUTTON 3001  IDC_EXIT 3002  IDC_EDIT 3000]
_____________________________________________________________________________________

Main:

    call 'Kernel32.GetModuleHandleA' 0  | mov D§hInstance eax

    call 'USER32.DialogBoxParamA'  0 1000 0 DialogProc 0

    call 'Kernel32.ExitProcess' 0

______________________________________________________________________________________

Proc DialogProc:
    Arguments @Adressee, @Message, @wParam, @lParam

    pushad

   .If D@message = &WM_COMMAND
        mov eax D@wParam
        ..If D@lParam = 0
            If ax = M00_Get_Text
                call 'USER32.GetDlgItemTextA' D@Adressee IDC_EDIT buffer 512
                call 'USER32.MessageBoxA' &NULL buffer AppName &MB_OK
            Else_If ax = M00_Clear_Text
                call 'USER32.SetDlgItemTextA' D@adressee IDC_EDIT &NULL
            Else_If ax = M00_Exit
                call 'USER32.EndDialog' D@adressee 0
            End_If
        ..Else
            mov edx D@wParam | shr edx 16
            ...If dx = &BN_CLICKED
                If ax = IDC_BUTTON
                    call 'USER32.SetDlgItemTextA' D@adressee IDC_EDIT TestString
                Else_If ax = IDC_EXIT
                    call 'USER32.SendMessageA' D@adressee &WM_COMMAND M00_Exit 0
                End_If
            ...End_If
        ..End_If

   .Else_If D@message = &WM_INITDIALOG
        call 'USER32.GetDlgItem' D@adressee IDC_EDIT
        call 'USER32.SetFocus' eax

   .Else_If D@message = &WM_CLOSE
        call 'USER32.SendMessageA' D@adressee &WM_COMMAND M00_Exit 0
   .Else
L8:     popad | mov eax &FALSE | Exit
 
   .End_If

L9: popad | mov eax &TRUE
EndP



The analysis follows:

 

        call 'USER32.DialogBoxParamA'  0 1000 0 DialogProc 0

The above line calls DialogBoxParam function which takes 5 parameters: the instance handle, the name of the dialog box template, the parent window handle, the address of the dialog box procedure, and the dialog-specific data. DialogBoxParam creates a modal dialog box. It will not return until the dialog box is destroyed.
 

  .Else_If D@message = &WM_INITDIALOG
        call 'USER32.GetDlgItem' D@adressee IDC_EDIT
        call 'USER32.SetFocus' eax

   .Else_If D@message = &WM_CLOSE
        call 'USER32.SendMessageA' D@adressee &WM_COMMAND M00_Exit 0
 

The dialog box procedure looks like a window procedure except that it doesn't receive WM_CREATE message. The first message it receives is WM_INITDIALOG. Normally you can put the initialization code here. Note that you must return the value TRUE in eax if you process the message.
The internal dialog box manager doesn't send our dialog box procedure the WM_DESTROY message by default when WM_CLOSE is sent to our dialog box. So if we want to react when the user presses the close button on our dialog box, we must process WM_CLOSE message. In our example, we send WM_COMMAND message with the value M00_EXIT in wParam. This has the same effect as when the user selects Exit menu item. EndDialog is called in response to M00_EXIT.
The processing of WM_COMMAND messages remains the same.
When you want to destroy the dialog box, the only way is to call EndDialog function. Do not try DestroyWindow! EndDialog doesn't destroy the dialog box immediately. It only sets a flag for the internal dialog box manager and continues to execute the next instructions.


[Iczelion's Win32 Assembly Homepage]