SftPrintPreview/DLL 2.0 - Print Preview Control for C/C++

SFTPRINTPREVIEW_DRAWINFO Structure

The SFTPRINTPREVIEW_DRAWINFO structure is used as a parameter to the SFTPRINTPREVIEW_DRAWINFOPROC function.

typedef struct tagSftPrintPreviewDrawInfo {

    int function; // reason for call to drawing callback
#define SFTPRINTPREVIEW_PRINT_INIT 1
#define SFTPRINTPREVIEW_PRINT_ONEPAGE 2
#define SFTPRINTPREVIEW_PRINT_TERM 3
#define SFTPRINTPREVIEW_PRINT_CLEARCACHE 4
#define SFTPRINTPREVIEW_PRINT_DIMENSIONS 5
#define SFTPRINTPREVIEW_PRINT_PREPAREPAGE 6

    BOOL fRealPrinter; // True if a real printer (not preview)
    BOOL fPositioning; // True if printing for page positioning only

    HDC hDC; // output DC
    HDC hDCPrinter; // printer DC
    HWND hwndContent; // window providing content (attributes + data)
    HWND hwndData; // window providing content (data only)

    RECT PageRectPrinterPix; // page rectangle (entire page)
    RECT PrintableRectPrinterPix; // (physically) printable portion of page
    RECT MarginRectPrinterPix; // printable area defined by user-defined margins
    RECT ClientRect; // current page (in screen pixels)
    RECT OutputRectDisplayPix; // output area

    int absPage; // current page (0..maxPages-1)
    int lastPage; // last page available (or SFTPRINTPREVIEW_UNKNOWNPAGES)
    int iContentSizing; // desired content sizing
    int contentWidth; // best content width (in screen pixels)
    int contentHeight; // best content height (in screen pixels)
    int maxContentWidth; // maximum content width (in screen pixels)
    int maxContentHeight; // maximum content height (in screen pixels)

    SFTPRINTPREVIEW_DWORD_PTR lpDrawPageWorkArea; // application-defined workarea

    SFTPRINTPREVIEW_DWORD_PTR previousVisitedPageInfo;// info for previous page (page preceding absPage)
    SFTPRINTPREVIEW_DWORD_PTR visitedPageInfo;// info for this page (absPage) if available

    LPVOID pGraphics; // GDI+ printer Graphics object
    HWND hwndPrintPreviewControl; // window handle of print preview control

} SFTPRINTPREVIEW_DRAWINFO, * LPSFTPRINTPREVIEW_DRAWINFO;
typedef const SFTPRINTPREVIEW_DRAWINFO * LPCSFTPRINTPREVIEW_DRAWINFO;

Members

function

Defines the reason for the current call to the callback function.

fRealPrinter

Set to TRUE if the output is sent to a real printer, FALSE otherwise, in which case the output is produced for a Print Preview display.

fPositioning

Set to TRUE if the current page is being rendered for formatting purposes only. This is the case if pages need to be formatted to display a later page. For example, if the page to be displayed is page 50, but pages 2-49 have not yet been displayed (and formatted), the intervening pages have to be rendered for formatting purposes, before page 50 can be displayed. If fPositioning is set to TRUE, any output rendered into the output device context hDC or printer object pGraphics is discarded. An application can optimize the page rendering process by formatting only, without actually rendering the page. If fPositioning is set to FALSE, the output rendered is displayed or printed.

hDC

Defines the output device context. Output is rendered using this device context. In addition, an application can also render output using the printer object pGraphics. Output to hDC and pGraphics can be mixed on the same page. As the page is rendered to the display or printer, all output to hDC is rendered before pGraphics.

hDCPrinter

Defines the printer device context. When generating a preview display, the output device context hDC describes a screen device context. To query attributes of the actual printer device, the hDCPrinter device context must be used.

hwndContent

Defines the window handle, describing the window to be rendered. This member is equivalent to the value provided by the application in the SFTPRINTPREVIEW_CONTROL structure's hwndContent member.

hwndData

Defines the window handle, describing the window to be rendered. This member is equivalent to the value provided by the application in the SFTPRINTPREVIEW_CONTROL structure's hwndData member.

PageRectPrinterPix

A rectangle describing the dimensions of the page in printer coordinates (pixels).

PrintableRectPrinterPix

A rectangle describing the dimensions of the physically printable area on the page in printer coordinates (pixels).

MarginRectPrinterPix

A rectangle describing the dimensions of the printable area, excluding all margins, on the page in printer coordinates (pixels).

ClientRect

A rectangle describing the dimensions of the printable area, excluding all margins, on the page in screen or printer coordinates (pixels). This area is available for any application-generated output and reflects the actual output area of the output device context hDC and printer object pGraphics.

OutputRectDisplayPix

A rectangle describing the dimensions of the printable area, excluding all margins, on the page in screen coordinates (pixels).

absPage

Defines the current page being rendered. Page numbers are zero-based.

lastPage

Defines the last page. The last page number defaults to SFTPRINTPREVIEW_UNKNOWNPAGES until the last page has been rendered by the callback routine SFTPRINTPREVIEW_DRAWINFOPROC and it sets the lastPage member to the page number of the last page. Page numbers are zero-based.

iContentSizing

Defines how the output is displayed on each page.table row cellh iContentSizing cellh Description row cell SFTPRINTPREVIEW_CONTENTSIZING_EXACT cell The output is printed in its exact size. row cell SFTPRINTPREVIEW_CONTENTSIZING_SHRINKTOFIT cell If the output is too large/wide to fit on one page, it will be reduced in size to fit the available space. row cell SFTPRINTPREVIEW_CONTENTSIZING_ENLARGETOFIT cell The output will be increased in size to fill the available space on the page. row cell SFTPRINTPREVIEW_CONTENTSIZING_FIT cell The output will be increased/decreased in size to fill the available space on the page (combines SFTPRINTPREVIEW_CONTENTSIZING_SHRINKTOFIT and SFTPRINTPREVIEW_CONTENTSIZING_ENLARGETOFIT).

The iContentSizing member is not used for SftTree/DLL and SftTree/OCX or RichEdit controls. It only applies to application-generated output, which may inspect the iContentSizing member for custom output formatting. It is otherwise not used by SftPrintPreview/DLL.

contentWidth

Defines the best width for the current output.

contentHeight

Defines the best height for the current output.

maxContentWidth

Defines the maximum available width for the current output.

maxContentHeight

Defines the maximum available height for the current output.

lpDrawPageWorkArea

An application-defined value. This member is equivalent to the value provided by the application in the SFTPRINTPREVIEW_CONTROL structure's lpDrawPageWorkArea member.

previousVisitedPageInfo

When the drawing callback SFTPRINTPREVIEW_DRAWINFOPROC is called with a function of SFTPRINTPREVIEW_PRINT_ONEPAGE or the OnPrintOnePage function is called, the information saved in the visitedPageInfo member for the preceding page is available to the application in previousVisitedPageInfo.

visitedPageInfo

When the drawing callback SFTPRINTPREVIEW_DRAWINFOPROC is called with a function of SFTPRINTPREVIEW_PRINT_ONEPAGE or the OnPrintOnePage function is called, the application renders the requested page. At the end, it can save an application defined value in visitedPageInfo. This value can be a simple long or DWORD value, or a pointer to an application allocated structure.

pGraphics

Defines the printer object based on Gdiplus::Graphics. Output is rendered using this GDI+ Graphics object by GDI+ drawing functions, supported by GDI+. In addition, an application can also render output using the output device context hDC. Output to hDC and pGraphics can be mixed on the same page. As the page is rendered to the display or printer, all output to hDC is rendered before pGraphics. The graphics member is typically cast to a GDI+ Graphics object:

Gdiplus::Graphics* pGraphics = (Gdiplus::Graphics*) lpInfo->pGraphics;

hwndPrintPreviewControl

Defines the window handle of the SftPrintPreview control.

Comments

The SFTPRINTPREVIEW_DRAWINFO structure is used as a parameter to the SFTPRINTPREVIEW_DRAWINFOPROC callback function. It contains all relevant information for a supporting window to render itself for previewing or printing.

The drawing callback can use the GetControlInfo function to obtain additional information about the Preview control. The callback function should under no circumstances modify or update the Preview control in any way.

For function type SFTPRINTPREVIEW_PRINT_INIT and SFTPRINTPREVIEW_PRINT_TERM, only the members hDC, hDCPrinter, hwndContent, hwndData, fRealPrinter, lpDrawPageWorkArea, pGraphics are valid. All others are undefined.

For function type SFTPRINTPREVIEW_PRINT_DIMENSIONS, only the members hDC, hDCPrinter, hwndContent, hwndData, fRealPrinter, lpDrawPageWorkArea, absPage, PageRectPrinterPix, PrintableRectPrinterPix, MarginRectPrinterPix, iContentSizing, maxContentWidth, contentWidth are valid. All others are undefined.

For function type SFTPRINTPREVIEW_PRINT_CLEARCACHE, only the members hwndContent, hwndData, lpDrawPageWorkArea are valid. All others are undefined.

For function type SFTPRINTPREVIEW_PRINT_ONEPAGE, all members of the SFTPRINTPREVIEW_DRAWINFO are valid.

For function type SFTPRINTPREVIEW_PRINT_PREPAREPAGE, all members of the SFTPRINTPREVIEW_DRAWINFO are valid.

Example

C

UINT contentMessage;

...

contentMessage = RegisterWindowMessage(TEXT(SFTPRINTPREVIEW_CONTENTWINDOWMESSAGE);

...

LRESULT CALLBACK SftTree_WndProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
    switch (msg) {

        // Standard Windows Messages
        ....

    }
    if (pData->ContentMessage != 0 && msg == pData->contentMessage) {
        LPSFTPRINTPREVIEW_CALLBACKINFO lpCB = (LPSFTPRINTPREVIEW_CALLBACKINFO) lParam;
        lpCB->lpDrawInfoProc = SftTree_PrintCallback;
        lpCB->lpDrawPageWorkArea = (SFTPRINTPREVIEW_DWORD_PTR) pData;
        return 1L;
    }
    return DefWindowProc(hwnd, msg, wParam, lParam);
}

BOOL CALLBACK SftTree_PrintCallback(LPSFTPRINTPREVIEW_DRAWINFO lpInfo)
{
    register PWINDATA pData = (PWINDATA) lpInfo->lpDrawPageWorkArea;

    switch (lpInfo->function) {
        default:
        case SFTPRINTPREVIEW_PRINT_INIT:
            return TRUE;
        case SFTPRINTPREVIEW_PRINT_TERM:
            return TRUE;
        case SFTPRINTPREVIEW_PRINT_CLEARCACHE:
            return TRUE;
        case SFTPRINTPREVIEW_PRINT_DIMENSIONS:
            lpInfo->contentWidth = lpInfo->maxContentWidth;
            lpInfo->iContentSizing = SFTPRINTPREVIEW_CONTENTSIZING_FIT;
            return TRUE;
        case SFTPRINTPREVIEW_PRINT_ONEPAGE:
            PrintOnePage(pData, lpInfo);
            return TRUE;
    }
}

See Also C/C++ API | C++ Classes | Notifications