Windows Programming/Dialog Boxes

< Windows Programming
This page may need to be reviewed for quality.

People are familiar with dialog boxes. They are the grey windows that pop up
on Windows systems to display messages, and allow the user to set
parameters. There are 3 types of dialog boxes: modeless, modal, and system
modal.
Modal
Modal dialog boxes are generally used inside a program, to display
messages, and to set program parameters. Modal dialog boxes come to
the front of the screen, and you may not use the program while the
modal dialog box is open. to continue using the program, the modal
dialog box must be closed.
System Modal
System modal dialog boxes are like modal boxes, except that they
supersede the entire desktop area. When a system modal dialog box is
open, nothing else on the screen can be clicked or selected.
Modeless
Modeless dialog boxes are able to be deselected, and control can be
taken away from a modeless dialog box and transferred to some other
window. Modeless dialog boxes are frequently used as a fast and easy
way to create a window, without having to register a window class.
Modeless dialog boxes are common in the Windows control panel.
Contents
 [hide]

 1 MessageBox
o 1.1 Buttons
o 1.2 Icons
o 1.3 Modality
 2 Dialog Box Procedures
 3 Creating Modal Dialog Boxes
o 3.1 Indirect Dialog Boxes
 4 Creating Modeless Dialog Boxes
 5 Without Class
 6 With Class
 7 Common Dialog Boxes
o 7.1 ChooseColor
o 7.2 GetOpenFileName and
GetSaveFileName
o 7.3 ChooseFont
 8 Dialog Box Resources
o 8.1 The DIALOG keyword
 9 Next Chapter

[edit]MessageBox

The most simple type of dialog box is the MessageBox function.

The MessageBox function takes 4 parameters: a handle to a
parent, a message, a title, and an option. If the parent handle is
NULL, the message box is modeless. If you provide a handle for a
parent window, the MessageBox can become Modal to the parent
window.
MessageBox dialog boxes have a number of different options that
can be specified: Button types, Icons, modality (modal/modeless),
and text justification. These options are specified as bit flags, that
can be used by bitwise ORing them together.
[edit]Buttons
Message boxes can have standard OK or Cancel buttons, or they
can have a "Yes, No, Cancel" configuration, or a number of
derivatives. Only one primary button scheme can be used per
message box:

 MB_ABORTRETRYIGNORE: The message box contains three

push buttons: Abort, Retry, and Ignore.
 MB_CANCELTRYCONTINUE: Same as
MB_ABORTRETRYIGNORE, but preferred on Windows
2000/XP.
 MB_OK: The message box contains an "OK" button. This is
the default.
 MB_OKCANCEL: The message box contains two push
buttons: OK and Cancel.
 MB_RETRYCANCEL: The message box contains two push
buttons: Retry and Cancel.
 MB_YESNO: The message box contains two push buttons:
Yes and No.
 MB_YESNOCANCEL: The message box contains three push
buttons: Yes, No, and Cancel.
To display an icon in the message box, specify one of the
following values. In addition, a message box can add an
additional "Help" button by specifying the "MB_HELP" flag. A
"Default Button", a concept that we will see frequently in this
chapter, is the button that is automatically selected when a dialog
box is opened. Windows provides the ability to set the default
button to any of the buttons on a message box, by using the
MB_DEFBUTTONx macro. Here is an example:

MessageBox(NULL, "This is a Test",

"Test", MB_OKCANCEL|MB_HELP|
MB_DEFBUTTON2);

This will have a message box with an "OK", a "Cancel", and a

"Help" button, and the "Cancel" button will be automatically
selected.
[edit]Icons
A message box may have no icons, or it may have one. You
shouldn't specify a message box to have multiple icons. The
different icons, according to MSDN are:
 MB_ICONEXCLAMATION: An exclamation point icon appears
in the message box.
 MB_ICONWARNING: An exclamation point icon appears in the
message box.
 MB_ICONINFORMATION: An icon consisting of a lowercase
letter i in a circle appears in the message box.
 MB_ICONASTERISK: An icon consisting of a lowercase letter i
in a circle appears in the message box.
 MB_ICONQUESTION: A question mark icon appears in the
message box.
The question mark message icon is no longer recommended
because it does not clearly represent a specific type of
message and because the phrasing of a message as a
question could apply to any message type. In addition, users
can confuse the message symbol question mark with Help
information. Therefore, do not use this question mark message
symbol in your message boxes. The system continues to
support its inclusion only for backward compatibility.
 MB_ICONSTOP: A stop sign icon appears in the message
box.
 MB_ICONERROR: A stop sign icon appears in the message
box.
 MB_ICONHAND: A stop sign icon appears in the message
box.
[edit]Modality
Finally, the MessageBox can be defined as being Modal,
Modeless, or System Modal, by using another identifier:
MB_APPLMODAL, MB_SYSTEMMODAL, or MB_TASKMODAL.
MB_APPLMODAL is the default value, and only works if a parent
window handle was specified to the function. There are a number
of other options available, check out MSDN for more details.

[edit]Dialog Box Procedures

Dialog box procedures are slightly different from window
procedures. Specifically, they return BOOL values, instead of
LRESULT values. Also, dialog boxes do not have a default
message processing function, because messages don't always
need to be handled. Specifically, Windows manages dialog boxes,
and Windows will handle the unused messages. If a dialog box
processes a certain message, it should return TRUE. If the
message is not processed, the function should return FALSE.
Also, Dialog boxes do not get a WM_CREATE message, but
instead get a WM_INITDIALOG message. Furthermore, when a
dialog box has finished its business, it should call
the EndDialog function.
Here is an example of a skeleton dialog box function:

BOOL CALLBACK MyDlgProc(HWND hDlg, UINT

msg, WPARAM wParam, LPARAM lParam)
{
switch(msg)
{
case WM_INITDIALOG:
return TRUE;
case WM_DESTROY:
EndDialog(hDlg, 0);
return TRUE;
}
return FALSE;
}

[edit]Creating Modal Dialog Boxes

Once a dialog box procedure has been defined, a dialog box can
be created by calling either
the DialogBox or DialogBoxParam function. These functions
return an NRESULT value, that is the integer number passed to
the EndDialog function in the dialog box procedure.
The DialogBox function will not return until the dialog box is
closed. This means, essentially, that the program is frozen in time
until we close the dialog box. The DialogBox function requires 2
handles: the module instance handle and the handle of the parent
window. Also, the DialogBox function requires that a string be
passed naming the resource where the dialog box is defined. The
last argument to DialogBox is a pointer to the dialog box
procedure function, that you have already defined.
To pass a parameter to a dialog box, the function
DialogBoxParam can be used. DialogBoxParam has all the same
parameters as the regular version, except it takes a fifth argument
as a 32-bit pointer. This 32 bit value will be passed as the
LPARAM element of the WM_INITDIALOG message.
[edit]Indirect Dialog Boxes
DialogBox and DialogBoxParam both require that the dialog box
be defined in a resource. However, if you want to make the dialog
box on the fly, you can use the DialogBoxIndirect or
the DialogBoxIndirectParam functions. When defining a dialog
box indirectly, we need to fill out a DLGTEMPLATE structure, and
pass a pointer to that structure to the function, in place of a
resource identifier. The DLGTEMPLATE contains fields for
determining some of the characteristics of the dialog box, such as
the dimensions and screen location.
The DLGITEMTEMPLATE structure is used to define individual
dialog box items. For more information on this subject, search
MSDN.

[edit]Creating Modeless Dialog Boxes

Modeless dialog boxes are a breed of a different color, and are
more like windows than dialog boxes. First, we need to modify the
message loop, to ensure that dialog box messages are routed
correctly:
while(GetMessage(&msg, NULL, 0, 0))
{
if(!IsDialogMessage(hDlg, &msg))
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
}

Now, there are 2 ways we can define a message box in a

resource script, with a class or without. We will discuss each in
turn.

[edit]Without Class
We can define a dialog box in a resource script with the DIALOG
keyword. The resource will have an ID associated with it (either a
number or a string), and this ID can be passed directly to the
CreateDialog function.

[edit]With Class
If we want to define a modeless dialog box in terms of a window
class, we can use a few additions to make the job easier. First, we
create a WNDCLASS structure with the information about our
dialog box. However, there is one difference, in that we must set
the cbWndExtra field to the value DLGWINDOWEXTRA value:

wnd.cbWndExtra = DLGWINDOWEXTRA;

Then, we register the class like normal. Since we are registering

our window classes like normal windows, it shouldn't come as a
surprise that Modeless dialog boxes use a regular window
procedure, and not a dialog box procedure. Now, Windows
identifies classes by name, so we should remember the name of
our class. Let's say we named our class "MyDlgClass". We could
create a dialog box resource as such:

MYDLGCLASS DIALOG DISCARDABLE 100, 100,

200, 200
CAPTION "My Dialog Box"
CLASS "MyDlgClass"
FONT 8, "MS Sans Serif"
BEGIN
...
END

Notice the field that says "CLASS"? This is the same string that
we used in our WNDCLASS structure to name the class. It is
important that these two strings be identical, because Windows
needs this string to link the WNDCLASS and the dialog box
resource together. Notice also that we used the string
"MYDLGCLASS" to identify the dialog resource. This isn't
mandatory, but it does make things convenient later on.
Now, instead of calling CreateWindow, we will call the easier-to-
use function CreateDialog. We do not use the DialogBox
function, because CreateDialog returns immediately, and doesn't
halt program execution.
Here is an example:

HWND hDlg;
hDlg = CreateDialog(hInst, "MyDlgClass",
hwndParent, MyDlgProc);

Here, we are saying that "hInst" is the instance handle of the

application, and "hwndParent" is the handle to the parent window
of our dialog box. If the hwndParent parameter is NULL, the
dialog box won't have a parent. When the modeless dialog box is
finished, it calls "DestroyWindow", not "EndDialog", like a modal
dialog box would.
[edit]Common Dialog Boxes
The Common Dialogs is a library of functions that automatically
produce some of the most common dialog boxes in Windows.
This is an effort to make some amount of continuity between
different programs, so that each different program doesn't create
its own proprietary "File Open" dialog, for instance.
Each Common Dialog generally has a single function that takes a
pointer to a structure. This structure is defined specifically for
each different control. The common controls can be added to a
project by including the <commdlg.h> header file, and linking to
the comdlg32.dll library.
Some of the common controls available through this library are
the "Choose Font" dialog box, the "File open" and "File save"
boxes, and the "Color Palette" dialog box.
MSDN
[edit]ChooseColor
The ChooseColor function brings up the color palette window,
and returns a 32-bit color value to your program.

BOOL ChooseColor(LPCHOOSECOLOR lpcc);

ChooseColor takes a single argument, in the form of a pointer to a

CHOOSECOLOR structure. This structure is initialized with
various values, and when the function returns, the
CHOOSECOLOR structure contains the color value code.
[edit]GetOpenFileName and GetSaveFileName
These two functions bring up the familiar file open and file save
dialog boxes that are found in nearly every Windows application.

BOOL GetOpenFileName(LPOPENFILENAME
lpofn);
BOOL GetSaveFileName(LPOPENFILENAME
lpofn);

Both of these functions take a pointer to an OPENFILENAME

structure. This structure controls such things as the file extensions
that may be loaded, and the starting path to look in. When the
function returns, the structure will contain the name of the file
selected. Once your program has this information, you can use
the File I/O API to access the file.
[edit]ChooseFont
The ChooseFont function brings up a familiar dialog box that
allows the user to select a font and various font attributes such as
size, underline/bold/italics, color, etc. This function takes a pointer
to a CHOOSEFONT structure.

BOOL ChooseFont(LPCHOOSEFONT lpcf);

[edit]Dialog Box Resources

Dialog boxes can be specified in a resource script, to handle the
tricky task of creating all the various child windows (buttons and
editboxes, etc.) that a dialog box may contain. This process is
described in detail in the Resource Script Reference in the
appendix. Here, we will discuss some of the basics of using a
resource script to define a dialog box.
[edit]The DIALOG keyword
A dialog box resource is specified with the DIALOG (must be all
caps) keyword. The DIALOG keyword is preceeded by the
resource identifier, and is followed by a series of dimension
values:
ID_DLGBOX DIALOG X, Y, CX, CY
X and Y are the location coordinates of the upper-left corner of the
dialog box, in relation to the upper-left corner of the screen.
Remember, all the coordinates start at (0,0) in the upper-left hand
corner. The next set of numbers, CX and CY, are the dimensions
of the dialog box. These dimensions do not include the title bar (if
any), so setting your Y value to 0 will make a dialog box that is
only a title bar.

+---------------> X
["DialogBox" [_][O][x]]
+ | |
| | |
| | |
| | |
| | |
| | |
v | |
Y | |
| |
| |
+-----------------------+

After the DIALOG declaration, there are a number of other fields

that can be filled in, to provide information about your dialog box:

ID_DLGBOX DIALOG 100, 100, 200, 150

STYLE WS_OVERLAPPED | WS_CAPTION |
WS_VISIBLE
CAPTION "Title Bar Text"
FONT 8, "MS Sans Serif"

The STYLE declaration contains all the window styles, bitwise

OR'd, that you would have used in the WNDCLASS structure, or
in the style field of the CreateWindow function. All the same
values are available. The CAPTION is the title of the dialog box.
The FONT is the point-size and the TrueType font to be used on
all the surfaces of the dialog box. Any font and size can be
specified, although if the font is too big, your dialog box will be
very annoying.
Now, once we have our dialog box sized and shaped the way we
want it, we can start to fill it with control buttons and edit boxes,
and all sorts of other goodies. First, we use the BEGIN and END
tags:

ID_DLGBOX DIALOG 100, 100, 200, 150

STYLE WS_OVERLAPPED | WS_CAPTION |
WS_VISIBLE
CAPTION "Title Bar Text"
FONT 8, "MS Sans Serif"
BEGIN
...
END

Next, we can start to fill in the dialog box with buttons,

checkboxes, or whatever we want, using the following format:

ID_DLGBOX DIALOG 100, 100, 200, 150

STYLE WS_OVERLAPPED | WS_CAPTION |
WS_VISIBLE
CAPTION "Title Bar Text"
FONT 8, "MS Sans Serif"
BEGIN
PUSHBUTTON "OK", IDOK, 10, 10,
50, 15, WS_TABSTOP
CHECKBOX "Box 1", IDC_CB1, 10, 30,
50, 15, WS_TABSTOP
EDITTEXT IDC_EDIT1, 10, 50,
100, 100
END

After the declaration, you may optionally include one or more style
flags, to specify how you want a particular control to appear. The
WS_TABSTOP identifier specifies which controls can be selected
when you press the TAB key on the keyboard. When you press
the TAB key, control switches among the dialog box controls in
the same order that they are specified in the resource script (top
to bottom).