Using the OFN_EXPLORER Flag

In Windows 3.1 and Windows NT 3.1 and 3.5, if you want to change a common dialog box in some way, you need to have a copy of the DLG file and then use the #include statement to incorporate it in your resource file. In Windows 95, however, you no longer need to do this in order to include your own custom template that works with the new Open (and Save As) template. Now, you can simply include the OFN_EXPLORER flag and create a dialog template that contains only the items that you want to add to the dialog box. If the OFN_EXPLORER flag is set in the Flags field of the OPENFILENAME structure, the hInstance, lpfnHook, and lpTemplateName fields are interpreted as follows:

If the OFN_ENABLETEMPLATE flag is set in the Flags field, the lpTemplateName field is the name of the dialog template, and the hInstance field is the module instance. The dialog template must have the WS_CHILD style set, or GetOpenFileName will fail. The common dialog handler creates a child dialog box (a subdialog box) and the standard dialog box. This child dialog box, which is placed in the upper left corner of the standard dialog box, is resized to contain not only its own, new controls but also all the controls in the standard dialog box. Thus the hDlg parameter passed to the application's hook function is the child of the dialog box containing the standard controls. If your application must communicate with a standard control from the hook procedure, it should call GetParent on the hDlg passed to the hook procedure. For example, to get the text from the Types combo box, you use the following code:

GetDlgItemText (GetParent (hDlg), cmb1, buf, MAX_PATH);

If the OFN_ENABLETEMPLATEHANDLE flag is set in the Flags field, the hInstance field should contain the memory handle for the dialog template.
If the OFN_ENABLEHOOK flag is set in the Flags field, the lpfnHook field is a DLGPROC (not an LPOFNHOOKPROC) that is associated with the child dialog box.
If neither the OFN_ENABLETEMPLATE flag nor the OFN_ENABLETEMPLATEHANDLE flag is set in the Flags field, the common dialog handler creates an empty template.

For example, in the Win32 SDK COMDLG32 sample, the following dialog template adds some fields to the Open dialog box:

IDD_COMDLG32 DIALOG DISCARDABLE 0, 0, 300, 74

STYLE WS_CHILD | WS_VISIBLE | WS_CLIPSIBLINGS | DS_3DLOOK |
DS_CONTROL

FONT 8, "MS Sans Serif"

BEGIN

LTEXT "Path:",-1,28,4,36,8

LTEXT "This is to the left",-1,4,16,20,40

LTEXT "Selected:",-1,32,49,40,8

EDITTEXT IDE_SELECTED,74,47,200,12,ES_AUTOHSCROLL

LTEXT "This is to the right.",-1,232,20,65,8

LTEXT "",stc32,28,16,204,31

EDITTEXT IDE_PATH,65,2,200,12,ES_AUTOHSCROLL

END

Once I created this template, I used the notification code to trap the notifications and to update the new fields that I added. Also, when I filled out the OPENFILENAME structure, I included the OFN_ENABLETEMPLATE flag to enable the template. Figure 6-4 shows the resulting customized Open dialog box.

In the preceding code, notice the next-to-last resource, which is a control with the ID stc32. In the common dialog handler, this ID has a special purpose: to let the handler know where to place all the standard controls. Without an stc32 control, the common dialog handler places all the new controls added by the application-defined template below the standard controls. If you include the stc32 control, the handler assesses the size of this control.

Figure 6-4.

A customized Open common dialog box created with a template.

If it is too small to hold all the standard controls, the handler moves them to the right of the stc32 control or below it to make room for the new controls. Figure 6-5 shows the child dialog box that is provided to customize the Open dialog box from the Win32 SDK COMDLG32 sample.

Figure 6-5.

A child dialog box used to customize an Open common dialog box.

If you want to maintain the old-style look of a common dialog box or if you need to insert new controls that are interspersed among the existing controls (as opposed to being positioned around them), your application should use a hook or a template and must not include the OFN_EXPLORER flag. The hook can be as simple as a function that returns NULL. If you don't use a hook or a template, your dialog box will display the Explorer look by default. To be compatible with previous versions of the common controls, your application must use a template to position controls among the standard controls.

You can also set the tab order of the controls in a customized common dialog box. Let's say you want the user to be able to tab from the OK button to an added button and then to the Cancel button. To do this, the child dialog box containing the added button must have the DS_CONTROL style. With this style set, you can use a call to SetWindowPos to change the z-order. The dialog box manager determines which control will receive the focus next by walking in z-order through windows that have the WS_TABSTOP style.

NOTE: To allow the user to select more than one file to open in the Open common dialog box, specify the OFN_ALLOWMULTISELECT flag. The lpstrFile member of the OPENFILENAME structure points to a buffer into which the path to the current folder and the selected filenames are copied. Normally, a space separates the first filename from the path, and each subsequent filename is separated from the preceding filename by a space. If you include the OFN_EXPLORER flag, a NULL (\0) character rather than a space will separate the filenames. The entire buffer is terminated by two NULL characters (\0\0).