PrintDlgEx Function

BOOL PrintDlgEx(LPPRINTDLGEX pPrintDlgEx);

The PrintDlgEx function displays the extended Print dialog box. This function is the extended version of the PrintDlg function and allows for greater customization and control over the print dialog.

Parameters

pPrintDlgEx
A pointer to a PRINTDLGEX structure that contains information used to initialize the dialog box and receive information from it.

Return Value

If the user clicks the OK button, the return value is TRUE. Otherwise, it is FALSE.

To get extended error information, call GetLastError.

Remarks

The PrintDlgEx function is designed to be flexible and support various print-related operations. It allows developers to:

The PRINTDLGEX structure is central to the operation of PrintDlgEx. It contains fields for:

Structure

PRINTDLGEX Structure

The PRINTDLGEX structure is used with the PrintDlgEx function.

typedef struct tagPrintDlgEx {
    DWORD           cbSize;
    HWND            hwndOwner;
    HANDLE          hDevMode;
    HANDLE          hDevNames;
    HDC             hDC;
    DWORD           Flags;
    DWORD           ExFlags;
    LPUNKNOWN       lpfnSetupCallBack;
    LPUNKNOWN       lpfnPrintCallBack;
    LPCSTR          lpszName;
    DWORD           nCopies;
    DWORD           nFromPage;
    DWORD           nToPage;
    DWORD           nMinPage;
    DWORD           nMaxPage;
    DWORD           nCopies;
    HINSTANCE       hInstance;
    LPCSTR          lpszCaption;
    LPVOID          pPrintParent;
    LPCSTR          lpszPrintTemplateName;
    LPVOID          pDevMode;
    LPVOID          pDevNames;
} PRINTDLGEX, *LPPRINTDLGEX;

Fields:

cbSize
The size, in bytes, of the structure. This member must be initialized to the size of the structure.
hwndOwner
A handle to the owner window of the dialog box. This member can be NULL if the dialog box has no owner.
hDevMode
A handle to a DEVMODE structure that specifies the device mode for the device identified by the hDevNames member. If this member is NULL, the system uses the device mode information associated with the default printer.
hDevNames
A handle to a DEVNAMES structure that specifies the properties of the printer driver, device, and output port. If this member is NULL, the system uses the printer name information associated with the default printer.
hDC
A handle to a device context for the selected printer. If this member is NULL, the system creates a device context. It is recommended to set this to NULL and let the system create the DC.
Flags
A set of bit flags that specify how the dialog box should be displayed. This can be a combination of the following values:
ExFlags
Extended flags for more fine-grained control over the dialog's behavior.
lpfnSetupCallBack
A pointer to a setup callback function.
lpfnPrintCallBack
A pointer to a print callback function.
lpszName
A pointer to a null-terminated string that specifies the default printer name. If NULL, the default printer is used.
nCopies
The number of copies to print.
nFromPage
The starting page for printing.
nToPage
The ending page for printing.
nMinPage
The minimum allowed page number.
nMaxPage
The maximum allowed page number.
hInstance
Handle to an instance of the application that owns the dialog template.
lpszCaption
Pointer to a null-terminated string that specifies the window title for the dialog box.
pPrintParent
Pointer to a parent window for the print dialog.
lpszPrintTemplateName
Pointer to a null-terminated string that specifies the name of the custom print dialog template resource.
pDevMode
Pointer to a DEVMODE structure.
pDevNames
Pointer to a DEVNAMES structure.

Example Usage

Here's a simplified example demonstrating how to call PrintDlgEx:


#include <windows.h>
#include <commdlg.h>
#include <stdio.h>

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) {
    PRINTDLGEX pd;
    HPROPSHEETPAGE ahpage[1];
    HPROPSHEETPAGE *lphpage = ahpage;
    INT nReturn;
    LPPROPSHEETPAGE lpPage = NULL;

    ZeroMemory(&pd, sizeof(pd));
    pd.dwSize = sizeof(pd);
    pd.Flags = PD_ALLPAGES | PD_USEDIALOGEX; // Use extended dialog, print all pages
    pd.nMinPage = 1;
    pd.nMaxPage = 100;
    pd.nCopies = 1;
    pd.hInstance = hInstance;
    pd.lpszCaption = L"Select Printer Options";

    // If you have custom pages, you would populate lphpage here.
    // For this example, we assume no custom pages.
    pd.nPageRanges = 1;
    pd.nFromPage = 1;
    pd.nToPage = 1;

    nReturn = PrintDlgEx(&pd);

    if (nReturn == IDOK) {
        // User clicked OK. Retrieve print job information.
        // You would typically use pd.hDevMode and pd.hDevNames
        // to get printer and device information.
        wprintf(L"Printer selected: %s\n", (LPWSTR)GlobalLock(pd.hDevNames) + ((LPDEVMODEW)GlobalLock(pd.hDevMode))->dmDeviceName);
        wprintf(L"Copies: %d\n", pd.nCopies);
        if (pd.Flags & PD_PAGECOLORS) {
             wprintf(L"Page Colors selected.\n");
        }
        if (pd.Flags & PD_COLLATE) {
             wprintf(L"Collate selected.\n");
        }
        GlobalUnlock(pd.hDevNames);
        GlobalUnlock(pd.hDevMode);

        // Now you would typically start a print job using the retrieved information.
    } else if (nReturn == IDCANCEL) {
        // User clicked Cancel
        MessageBox(NULL, L"Print operation cancelled.", L"Cancelled", MB_OK);
    } else {
        // Some error occurred
        MessageBox(NULL, L"An error occurred during the print dialog.", L"Error", MB_OK);
    }

    return 0;
}

Notes

See Also