PageSetupDlg Function

The PageSetupDlg function displays the Windows Page Setup dialog box. This dialog box enables the user to select printing options, such as paper size, paper source, and page orientation. It also allows the user to select a printer and configure printer-specific settings.

Syntax

BOOL PageSetupDlg(
  [in, out] LPPSH PageSetup
);

Parameters

Parameter Description
PageSetup A pointer to a PSH structure that contains information used to initialize the dialog box and receive the user's input.

Return Value

If the user clicks the OK button, the function returns a non-zero value. This value indicates that the PSH structure has been updated with the user's selections.

If the user cancels or closes the dialog box, the function returns zero. To get extended error information, call GetLastError.

Remarks

The PageSetupDlg function uses the PSH structure to exchange information with the dialog box. Before calling PageSetupDlg, you must initialize the PSH structure with appropriate values. The following flags can be used to customize the behavior of the dialog box:

The PSH structure contains members for paper size, margins, orientation, and a handle to the printer device context.

Note: For older versions of Windows, you might need to use the CommDlg32.dll library. Ensure you are linking against the correct library for your target platform.

Structure Definition

The PSH structure is defined as follows:

typedef struct tagPSH {
    DWORD           cbSize;
    HWND            hwndOwner;
    HGLOBAL         hDevMode;
    HGLOBAL         hDevNames;
    DWORD           Flags;
    LONG            nMinMargin[3];
    LONG            nMaxMargin[3];
    LONG            nMargin[3];
    LONG            rcMargin[4];
    LONG            nScale;
    short           wScaleMin;
    short           wScaleMax;
    short           wOrientation;
    short           PrintArea[4];
    short           xRasterSize;
    short           yRasterSize;
    short           nCopies;
    short           nFarEastOrientation;
    short           sCopies;
    short           sEMFValue;
    short           sLang;
    short           sCountry;
    char            szTemplate[32];
    LPVOID          pfnSetupHook;
    LPVOID          pfnPrintHook;
    HTPROOT         hThriftRoot;
    WORD            wParentId;
    WORD            wControlId;
    WORD            nStartingPage;
    LPPRINTDLG      lpPrintDlg;
} PSH, *LPSH;

Members

Example Usage

The following code snippet demonstrates how to display the Page Setup dialog box:

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

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) {
    PAGESETUPDLG psd;
    DEVMODE dm;
    DEVNAMES dn;
    ZeroMemory(&psd, sizeof(PAGESETUPDLG));

    psd.cbSize = sizeof(PAGESETUPDLG);
    psd.hwndOwner = NULL; // Or your application's main window handle
    psd.Flags = PSD_INHERITHGLOBALFONT | PSD_SHOWPRINTER | PSD_SHOWPAGEENABLE;

    // Initialize DEVMODE and DEVNAMES structures if needed
    // For simplicity, we'll let the dialog fill them
    psd.hDevMode = GlobalAlloc(GMEM_SHARE | GMEM_ZEROINIT, sizeof(DEVMODE));
    psd.hDevNames = GlobalAlloc(GMEM_SHARE | GMEM_ZEROINIT, sizeof(DEVNAMES));

    if (psd.hDevMode) {
        dm = *(LPDEVMODE)GlobalLock(psd.hDevMode);
        // Set initial values for DEVMODE here if necessary
        GlobalUnlock(psd.hDevMode);
    }

    if (psd.hDevNames) {
        dn = *(LPDEVNAMES)GlobalLock(psd.hDevNames);
        // Set initial values for DEVNAMES here if necessary
        GlobalUnlock(psd.hDevNames);
    }


    if (PageSetupDlg(&psd)) {
        // User clicked OK. Retrieve settings from psd.hDevMode and psd.hDevNames
        // For example:
        if (psd.hDevMode) {
            dm = *(LPDEVMODE)GlobalLock(psd.hDevMode);
            // Use dm.dmOrientation, dm.dmPaperSize, etc.
            GlobalUnlock(psd.hDevMode);
        }
        if (psd.hDevNames) {
            dn = *(LPDEVNAMES)GlobalLock(psd.hDevNames);
            // Use dn.wDevice, dn.wDriver, etc.
            GlobalUnlock(psd.hDevNames);
        }
    } else {
        // User canceled or an error occurred
        DWORD dwError = GetLastError();
        // Handle error
    }

    // Clean up allocated memory
    if (psd.hDevMode) GlobalFree(psd.hDevMode);
    if (psd.hDevNames) GlobalFree(psd.hDevNames);

    return 0;
}
Tip: It's good practice to initialize the hDevMode and hDevNames members with handles to previously selected device information, if available. This provides a better user experience by pre-selecting familiar settings.

See Also