Using Common Dialog Boxes

This section covers tasks that invoke common dialog boxes:

• Choosing a Color
• Choosing a Font
• Opening a File
• Displaying the Print Dialog Box
• Using the Print Property Sheet
• Setting Up the Printed Page
• Finding Text

Choosing a Color

This topic describes sample code that displays a Color dialog box so that a user can select a color. The sample code first initializes a CHOOSECOLOR structure, and then calls the ChooseColor function to display the dialog box. If the function returns TRUE, indicating that the user selected a color, the sample code uses the selected color to create a new solid brush.

This example uses the CHOOSECOLOR structure to initialize the dialog box as follows:

• Initializes the lpCustColors member with a pointer to a static array of values. The colors in the array are initially black, but the static array preserves custom colors created by the user for subsequent ChooseColor calls.
• Sets the CC_RGBINIT flag and initializes the rgbResult member to specify the color that is initially selected when the dialog box opens. If not specified, the initial selection is black. The example uses the rgbCurrent static variable to preserve the selected value between calls to ChooseColor.
• Sets the CC_FULLOPEN flag so the custom colors extension of the dialog box is always displayed.

CHOOSECOLOR cc;                 // common dialog box structure 
static COLORREF acrCustClr[16]; // array of custom colors 
HWND hwnd;                      // owner window
HBRUSH hbrush;                  // brush handle
static DWORD rgbCurrent;        // initial color selection

// Initialize CHOOSECOLOR 
ZeroMemory(&cc, sizeof(cc));
cc.lStructSize = sizeof(cc);
cc.hwndOwner = hwnd;
cc.lpCustColors = (LPDWORD) acrCustClr;
cc.rgbResult = rgbCurrent;
cc.Flags = CC_FULLOPEN | CC_RGBINIT;
 
if (ChooseColor(&cc)==TRUE) 
{
    hbrush = CreateSolidBrush(cc.rgbResult);
    rgbCurrent = cc.rgbResult; 
}

Choosing a Font

This topic describes sample code that displays a Font dialog box so that a user can choose the attributes of a font. The sample code first initializes a CHOOSEFONT structure, and then calls the ChooseFont function to display the dialog box.

This example sets the CF_SCREENFONTS flag to specify that the dialog box should display only screen fonts. It sets the CF_EFFECTS flag to display controls that allow the user to select strikeout, underline, and color options.

If ChooseFont returns TRUE, indicating that the user clicked the OK button, the CHOOSEFONT structure contains information that describes the font and font attributes selected by the user, including the members of the LOGFONT structure pointed to by the lpLogFont member. The rgbColors member contains the selected text color. The sample code uses this information to set the font and text color for the device context associated with the owner window.

HWND hwnd;                // owner window
HDC hdc;                  // display device context of owner window

CHOOSEFONT cf;            // common dialog box structure
static LOGFONT lf;        // logical font structure
static DWORD rgbCurrent;  // current text color
HFONT hfont, hfontPrev;
DWORD rgbPrev;

// Initialize CHOOSEFONT
ZeroMemory(&cf, sizeof(cf));
cf.lStructSize = sizeof (cf);
cf.hwndOwner = hwnd;
cf.lpLogFont = &lf;
cf.rgbColors = rgbCurrent;
cf.Flags = CF_SCREENFONTS | CF_EFFECTS;

if (ChooseFont(&cf)==TRUE)
{
    hfont = CreateFontIndirect(cf.lpLogFont);
    hfontPrev = SelectObject(hdc, hfont);
    rgbCurrent= cf.rgbColors;
    rgbPrev = SetTextColor(hdc, rgbCurrent);
 .
 .
 .
}

Opening a File

Note

Starting with Windows Vista, the Common File Dialog has been superseded by the Common Item Dialog when used to open a file. We recommend that you use the Common Item Dialog API instead of the Common File Dialog API. For more information, see Common Item Dialog.

This topic describes sample code that displays an Open dialog box so that a user can specify the drive, directory, and name of a file to open. The sample code first initializes an OPENFILENAME structure, and then calls the GetOpenFileName function to display the dialog box.

In this example, the lpstrFilter member is a pointer to a buffer that specifies two file name filters that the user can select to limit the file names that are displayed. The buffer contains a double-null terminated array of strings in which each pair of strings specifies a filter. The nFilterIndex member specifies that the first pattern is used when the dialog box is created.

This example sets the OFN_PATHMUSTEXIST and OFN_FILEMUSTEXIST flags in the Flags member. These flags cause the dialog box to verify, before returning, that the path and file name specified by the user actually exist.

The GetOpenFileName function returns TRUE if the user clicks the OK button and the specified path and file name exist. In this case, the buffer pointed to by the lpstrFile member contains the path and file name. The sample code uses this information in a call to the function to open the file.

Although this example does not set the OFN_EXPLORER flag, it still displays the default Explorer-style Open dialog box. However, if you want to provide a hook procedure or a custom template and you want the Explorer user interface, you must set the OFN_EXPLORER flag.

Note

In the C programming language, a string enclosed in quotation marks is null-terminated.

 

OPENFILENAME ofn;       // common dialog box structure
char szFile[260];       // buffer for file name
HWND hwnd;              // owner window
HANDLE hf;              // file handle

// Initialize OPENFILENAME
ZeroMemory(&ofn, sizeof(ofn));
ofn.lStructSize = sizeof(ofn);
ofn.hwndOwner = hwnd;
ofn.lpstrFile = szFile;
// Set lpstrFile[0] to '\0' so that GetOpenFileName does not 
// use the contents of szFile to initialize itself.
ofn.lpstrFile[0] = '\0';
ofn.nMaxFile = sizeof(szFile);
ofn.lpstrFilter = "All\0*.*\0Text\0*.TXT\0";
ofn.nFilterIndex = 1;
ofn.lpstrFileTitle = NULL;
ofn.nMaxFileTitle = 0;
ofn.lpstrInitialDir = NULL;
ofn.Flags = OFN_PATHMUSTEXIST | OFN_FILEMUSTEXIST;

// Display the Open dialog box. 

if (GetOpenFileName(&ofn)==TRUE) 
    hf = CreateFile(ofn.lpstrFile, 
                    GENERIC_READ,
                    0,
                    (LPSECURITY_ATTRIBUTES) NULL,
                    OPEN_EXISTING,
                    FILE_ATTRIBUTE_NORMAL,
                    (HANDLE) NULL);

Displaying the Print Dialog Box

This topic describes sample code that displays a Print dialog box so that a user can select options for printing a document. The sample code first initializes a PRINTDLG structure, and then calls the PrintDlg function to display the dialog box.

This example sets the PD_RETURNDC flag in the Flags member of the PRINTDLG structure. This causes PrintDlg to return a device context handle to the selected printer in the hDC member. You can use the handle to render output on the printer.

On input, the sample code sets the hDevMode and hDevNames members to NULL. If the function returns TRUE, these members return handles to DEVNAMES structures that contain the user input and information about the printer. You can use this information to prepare the output to be sent to the selected printer.

PRINTDLG pd;
HWND hwnd;

// Initialize PRINTDLG
ZeroMemory(&pd, sizeof(pd));
pd.lStructSize = sizeof(pd);
pd.hwndOwner   = hwnd;
pd.hDevMode    = NULL;     // Don't forget to free or store hDevMode.
pd.hDevNames   = NULL;     // Don't forget to free or store hDevNames.
pd.Flags       = PD_USEDEVMODECOPIESANDCOLLATE | PD_RETURNDC; 
pd.nCopies     = 1;
pd.nFromPage   = 0xFFFF; 
pd.nToPage     = 0xFFFF; 
pd.nMinPage    = 1; 
pd.nMaxPage    = 0xFFFF; 

if (PrintDlg(&pd)==TRUE) 
{
    // GDI calls to render output. 

    // Delete DC when done.
    DeleteDC(pd.hDC);
}

Using the Print Property Sheet

This topic describes sample code that displays a Print property sheet so that a user can select options for printing a document. The sample code first initializes a PRINTDLGEX structure, then calls the PrintDlgEx function to display the property sheet.

The sample code sets the PD_RETURNDC flag in the Flags member of the PRINTDLG structure. This causes the PrintDlgEx function to return a device context handle to the selected printer in the hDC member.

On input, the sample code sets the hDevMode and hDevNames members to NULL. If the function returns S_OK, these members return handles to DEVNAMES structures containing the user input and information about the printer. You can use this information to prepare the output to be sent to the selected printer.

After the printing operation has been completed, the sample code frees the DEVMODE, DEVNAMES, and PRINTPAGERANGE buffers and calls the DeleteDC function to delete the device context.

// hWnd is the window that owns the property sheet.
HRESULT DisplayPrintPropertySheet(HWND hWnd)
{
    HRESULT hResult;
    PRINTDLGEX pdx = {0};
    LPPRINTPAGERANGE pPageRanges = NULL;

    // Allocate an array of PRINTPAGERANGE structures.
    pPageRanges = (LPPRINTPAGERANGE) GlobalAlloc(GPTR, 10 * sizeof(PRINTPAGERANGE));
    if (!pPageRanges)
        return E_OUTOFMEMORY;

    //  Initialize the PRINTDLGEX structure.
    pdx.lStructSize = sizeof(PRINTDLGEX);
    pdx.hwndOwner = hWnd;
    pdx.hDevMode = NULL;
    pdx.hDevNames = NULL;
    pdx.hDC = NULL;
    pdx.Flags = PD_RETURNDC | PD_COLLATE;
    pdx.Flags2 = 0;
    pdx.ExclusionFlags = 0;
    pdx.nPageRanges = 0;
    pdx.nMaxPageRanges = 10;
    pdx.lpPageRanges = pPageRanges;
    pdx.nMinPage = 1;
    pdx.nMaxPage = 1000;
    pdx.nCopies = 1;
    pdx.hInstance = 0;
    pdx.lpPrintTemplateName = NULL;
    pdx.lpCallback = NULL;
    pdx.nPropertyPages = 0;
    pdx.lphPropertyPages = NULL;
    pdx.nStartPage = START_PAGE_GENERAL;
    pdx.dwResultAction = 0;
    
    //  Invoke the Print property sheet.
    
    hResult = PrintDlgEx(&pdx);

    if ((hResult == S_OK) && pdx.dwResultAction == PD_RESULT_PRINT) 
    {
        // User clicked the Print button, so use the DC and other information returned in the 
        // PRINTDLGEX structure to print the document.
    }

    if (pdx.hDevMode != NULL) 
        GlobalFree(pdx.hDevMode); 
    if (pdx.hDevNames != NULL) 
        GlobalFree(pdx.hDevNames); 
    if (pdx.lpPageRanges != NULL)
        GlobalFree(pPageRanges);

    if (pdx.hDC != NULL) 
        DeleteDC(pdx.hDC);

    return hResult;
}

Setting Up the Printed Page

This topic describes sample code that displays a Page Setup dialog box so that a user can select the attributes of the printed page, such as the paper type, paper source, page orientation, and page margins. The sample code first initializes a PAGESETUPDLG structure, and then calls the PageSetupDlg function to display the dialog box.

This example sets the PSD_MARGINS flag in the Flags member and uses the rtMargin member to specify the initial margin values. It sets the PSD_INTHOUSANDTHSOFINCHES flag to ensure that the dialog box expresses margin dimensions in thousandths of an inch.

On input, the sample code sets the hDevMode and hDevNames members to NULL. If the function returns TRUE, the function uses these members to return handles to DEVNAMES structures containing the user input and information about the printer. You can use this information to prepare the output to be sent to the selected printer.

The following example also enables a PagePaintHook hook procedure to customize drawing the contents of the sample page.

PAGESETUPDLG psd;    // common dialog box structure
HWND hwnd;           // owner window

// Initialize PAGESETUPDLG
ZeroMemory(&psd, sizeof(psd));
psd.lStructSize = sizeof(psd);
psd.hwndOwner   = hwnd;
psd.hDevMode    = NULL; // Don't forget to free or store hDevMode.
psd.hDevNames   = NULL; // Don't forget to free or store hDevNames.
psd.Flags       = PSD_INTHOUSANDTHSOFINCHES | PSD_MARGINS | 
                  PSD_ENABLEPAGEPAINTHOOK; 
psd.rtMargin.top = 1000;
psd.rtMargin.left = 1250;
psd.rtMargin.right = 1250;
psd.rtMargin.bottom = 1000;
psd.lpfnPagePaintHook = PaintHook;

if (PageSetupDlg(&psd)==TRUE)
{
    // check paper size and margin values here.
}

The following example shows a sample PagePaintHook hook procedure that draws the margin rectangle in the sample page area:

BOOL CALLBACK PaintHook(HWND hwndDlg, UINT uMsg, WPARAM wParam, LPARAM lParam) 
{ 
    LPRECT lprc; 
    COLORREF crMargRect; 
    HDC hdc, hdcOld; 
 
    switch (uMsg) 
    { 
        // Draw the margin rectangle. 
        case WM_PSD_MARGINRECT: 
            hdc = (HDC) wParam; 
            lprc = (LPRECT) lParam; 
 
            // Get the system highlight color. 
            crMargRect = GetSysColor(COLOR_HIGHLIGHT); 
 
            // Create a dash-dot pen of the system highlight color and 
            // select it into the DC of the sample page. 
            hdcOld = SelectObject(hdc, CreatePen(PS_DASHDOT, .5, crMargRect)); 
 
            // Draw the margin rectangle. 
            Rectangle(hdc, lprc->left, lprc->top, lprc->right, lprc->bottom); 
 
            // Restore the previous pen to the DC. 
            SelectObject(hdc, hdcOld); 
            return TRUE; 
 
        default: 
            return FALSE; 
    } 
    return TRUE; 
}

Finding Text

This topic describes sample code that displays and manages a Find dialog box so that the user can specify the parameters of a search operation. The dialog box sends messages to the window procedure so you can perform the search operation.

The code for displaying and managing a Replace dialog box is similar, except that it uses the ReplaceText function to display the dialog box. The Replace dialog box also sends messages in response to user clicks on the Replace and Replace All buttons.

To use the Find or Replace dialog box, you must perform three separate tasks:

1. Get a message identifier for the FINDMSGSTRING registered message.
2. Display the dialog box.
3. Process FINDMSGSTRING messages when the dialog box is open.

When you initialize your application, call the RegisterWindowMessage function to get a message identifier for the FINDMSGSTRING registered message.

UINT uFindReplaceMsg;  // message identifier for FINDMSGSTRING 

uFindReplaceMsg = RegisterWindowMessage(FINDMSGSTRING);

To display a Find dialog box, first initialize a FINDREPLACE structure and then call the FindText function. Note that the FINDREPLACE structure and the buffer for the search string should be a global or static variable so that it does not go out of scope before the dialog box closes. You must set the hwndOwner member to specify the window that receives the registered messages. After you create the dialog box, you can move or manipulate it by using the returned handle.

FINDREPLACE fr;       // common dialog box structure
HWND hwnd;            // owner window
CHAR szFindWhat[80];  // buffer receiving string
HWND hdlg = NULL;     // handle to Find dialog box

// Initialize FINDREPLACE
ZeroMemory(&fr, sizeof(fr));
fr.lStructSize = sizeof(fr);
fr.hwndOwner = hwnd;
fr.lpstrFindWhat = szFindWhat;
fr.wFindWhatLen = 80;
fr.Flags = 0;

hdlg = FindText(&fr);

When the dialog box is open, your main message loop must include a call to the IsDialogMessage function. Pass a handle to the dialog box as a parameter in the IsDialogMessage call. This ensures that the dialog box correctly processes keyboard messages.

To monitor messages sent from the dialog box, your window procedure must check for the FINDMSGSTRING registered message and process the values passed in the FINDREPLACE structure as in the following example.

LPFINDREPLACE lpfr;

if (message == uFindReplaceMsg)
{ 
    // Get pointer to FINDREPLACE structure from lParam.
    lpfr = (LPFINDREPLACE)lParam;

    // If the FR_DIALOGTERM flag is set, 
    // invalidate the handle that identifies the dialog box. 
    if (lpfr->Flags & FR_DIALOGTERM)
    { 
        hdlg = NULL; 
        return 0; 
    } 

    // If the FR_FINDNEXT flag is set, 
    // call the application-defined search routine
    // to search for the requested string. 
    if (lpfr->Flags & FR_FINDNEXT) 
    {
        SearchFile(lpfr->lpstrFindWhat,
                   (BOOL) (lpfr->Flags & FR_DOWN), 
                   (BOOL) (lpfr->Flags & FR_MATCHCASE)); 
    }

    return 0; 
}