PrintDlg

3.1

The PrintDlg function displays a Print dialog box or a Print Setup dialog box. The Print dialog box makes it possible for the user to specify the properties of a particular print job. The Print Setup dialog box makes it possible for the user to select additional job properties and configure the printer.

Parameters

lppd

Points to a PRINTDLG structure that contains information used to initialize the dialog box. When the PrintDlg function returns, this structure contains information about the user's selections.

The PRINTDLG structure has the following form:

#include <commdlg.h>

typedef struct tagPD {  /* pd */
    DWORD     lStructSize;
    HWND      hwndOwner;
    HGLOBAL   hDevMode;
    HGLOBAL   hDevNames;
    HDC       hDC;
    DWORD     Flags;
    UINT      nFromPage;
    UINT      nToPage;
    UINT      nMinPage;
    UINT      nMaxPage;
    UINT      nCopies;
    HINSTANCE hInstance;
    LPARAM    lCustData;
    UINT    (CALLBACK* lpfnPrintHook)(HWND, UINT, WPARAM, LPARAM);
    UINT    (CALLBACK* lpfnSetupHook)(HWND, UINT, WPARAM, LPARAM);
    LPCSTR    lpPrintTemplateName;
    LPCSTR    lpSetupTemplateName;
    HGLOBAL   hPrintTemplate;
    HGLOBAL   hSetupTemplate;
} PRINTDLG;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

Return Value

The return value is nonzero if the function successfully configures the printer. The return value is zero if an error occurs, if the user chooses the Cancel button, or if the user chooses the Close command on the System menu to close the dialog box. (The return value is also zero if the user chooses the Setup button to display the Print Setup dialog box, chooses the OK button in the Print Setup dialog box, and then chooses the Cancel button in the Print dialog box.)

Errors

Use the CommDlgExtendedError function to retrieve the error value, which may be one of the following:

Example

The following example initializes the PRINTDLG structure, calls the PrintDlg function to display the Print dialog box, and prints a sample page of text if the return value is nonzero:

PRINTDLG pd;

/* Set all structure fields to zero. */

memset(&pd, 0, sizeof(PRINTDLG));

/* Initialize the necessary PRINTDLG structure fields. */

pd.lStructSize = sizeof(PRINTDLG);
pd.hwndOwner = hwnd;
pd.Flags = PD_RETURNDC;

/* Print a test page if successful */

if (PrintDlg(&pd) != 0) {
    Escape(pd.hDC, STARTDOC, 8, "Test-Doc", NULL);

    /* Print text and rectangle */

    TextOut(pd.hDC, 50, 50, "Common Dialog Test Page", 23);
    Rectangle(pd.hDC, 50, 90, 625, 105);
    Escape(pd.hDC, NEWFRAME, 0, NULL, NULL);
    Escape(pd.hDC, ENDDOC, 0, NULL, NULL);
    DeleteDC(pd.hDC);
    if (pd.hDevMode != NULL)
       GlobalFree(pd.hDevMode);
    if (pd.hDevNames != NULL)
       GlobalFree(pd.hDevNames);
}
else
    ErrorHandler();