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

SFTPRINTPREVIEW_CONTROL Structure

The SFTPRINTPREVIEW_CONTROL structure is used with the GetControlInfo and SetControlInfo functions to define control attributes.

typedef struct tagSftPrintPreviewControl {
    /* Modifiable fields */
    int cbSize; // structure size
    BOOL fOwnDevHandles; // control owns handles
    BOOL fScrollbars; // scrollbars wanted
    BOOL fToolbar; // tool bar wanted
    BOOL fUseThemes; // Windows themes wanted
    BOOL fWantCloseButton; // tool bar Close button wanted
    BOOL fWantHelpButton; // tool bar Help button wanted
    BOOL fWantPageSetupButton; // tool bar Page Setup button wanted

    HGLOBAL hOwnDevMode; // DevMode handle for selected printer (if owned by SftPrintPreview
    HGLOBAL hOwnDevNames; // DevNames handle for selected printer
    HGLOBAL* lphDevMode; // externally owned Devmode for selected printer
    HGLOBAL* lphDevNames; // externally owned Devnames for selected printer

    long currPage; // current page displayed (if zoomed)
    long firstPage; // 1st page (for row/col display)
    short numPageRows; // number of page rows 1,2,3,4,5,6
#define SFTPRINTPREVIEW_MAXROWS 6
    short numPageGroups; // number of pages per row 2,4,6,8,10,12
#define SFTPRINTPREVIEW_MAXCOLS 12
#define SFTPRINTPREVIEW_MAXVIEWPAGES (SFTPRINTPREVIEW_MAXROWS*SFTPRINTPREVIEW_MAXCOLS)
#define SFTPRINTPREVIEW_MAXPAGES 999998 // maximum supported printed pages
#define SFTPRINTPREVIEW_UNKNOWNPAGES (SFTPRINTPREVIEW_MAXPAGES+1)
    short maxPageRows; // max. number of page rows 1,2,3,4,5,6
    short maxPageGroups; // max. number of pages per row 2,4,6,8,10,12
    int zoom; // 0=show row.col pages, val=show one page
#define SFTPRINTPREVIEW_MINZOOM 10 // 10%
#define SFTPRINTPREVIEW_MAXZOOM 1000 // 1000%
#define SFTPRINTPREVIEW_ZOOM_FULLPAGE (-1) // full page display (for Zoom() only)
    int maxZoom; // max. allowable zoom factor
    int zoomIncrDecr; // zooming increment/decrement
#define SFTPRINTPREVIEW_MINZOOMINCRDECR 10
#define SFTPRINTPREVIEW_MAXZOOMINCRDECR 100
    BOOL fZoomIncreasing; // mouse button click will increase/decrease zoom factor
    int iZoomStyle; // zoom in/out style
#define SFTPRINTPREVIEW_ZOOMSTYLE_NONE 0
#define SFTPRINTPREVIEW_ZOOMSTYLE_LEFTBUTTONONLY 1
#define SFTPRINTPREVIEW_ZOOMSTYLE_BOTHBUTTONS 2
#define SFTPRINTPREVIEW_ZOOMSTYLE_LEFTBUTTONONLY_EXACT 3
#define SFTPRINTPREVIEW_ZOOMSTYLE_BOTHBUTTONS_EXACT 4
    BOOL fWantPrintDialog; // Print button shows dialog before printing
    BOOL fPairPages; // show pages in pairs even if printer doesn't support duplexing
    int marginX, marginY; // minimum margin between pages
    int marginPageGroup; // margin between page groups
    int marginShadow; // size of shadow
    int iPrintPages; // print all, current, (range)
#define SFTPRINTPREVIEW_PRINTSTYLE_MIN 0
#define SFTPRINTPREVIEW_PRINTSTYLE_ALL 0
#define SFTPRINTPREVIEW_PRINTSTYLE_CURR 1
#define SFTPRINTPREVIEW_PRINTSTYLE_MAX 1
#define SFTPRINTPREVIEW_PRINTSTYLE_RANGE 2

    HCURSOR hCursZoomPlus; // zoom in cursors
    HCURSOR hCursZoomMinus; // zoom out cursors
    HCURSOR hCursZoomNeutral; // zoom cursors (neither in nor out)

    // Output related
    SFTPRINTPREVIEW_DWORD_PTR lpDrawPageWorkArea; // application-defined workarea
    SFTPRINTPREVIEW_DRAWINFOPROC lpDrawInfoProc; // application-provided page rendering callback
    HWND hwndContent; // window proving content (attributes + data)
    HWND hwndData; // window proving content (data only)
    int iContentSizing; // Size output
#define SFTPRINTPREVIEW_CONTENTSIZING_EXACT 0
#define SFTPRINTPREVIEW_CONTENTSIZING_SHRINKTOFIT 1
#define SFTPRINTPREVIEW_CONTENTSIZING_ENLARGETOFIT 2
#define SFTPRINTPREVIEW_CONTENTSIZING_FIT 3

#define SFTPRINTPREVIEW_MAXOUTPUTNAME 200
    TCHAR szOutputName[SFTPRINTPREVIEW_MAXOUTPUTNAME+1]; // job output name

    // Page formatting
    double fltLeftMargin; // left border margin width (in inches)
    double fltTopMargin; // top border margin width (in inches)
    double fltRightMargin; // right border margin width (in inches)
    double fltBottomMargin; // bottom border margin width (in inches)
    double fltHeaderFromEdge; // header distance from top edge (in inches)
    double fltFooterFromEdge; // footer distance from bottom edge (in inches)
    double fltGutterMargin; // gutter margin size (in inches)
    BOOL fGutterLeft; // gutter margin left or top
    BOOL fMirrorMargins; // mirror margins on every other (back) page
    BOOL fShowAreas; // show areas
    int iUnitsOfMeasure; // cm or inches
#define SFTPRINTPREVIEW_UOM_INCHES 0
#define SFTPRINTPREVIEW_UOM_CM 1
#define SFTPRINTPREVIEW_MAXHEADERSIZE 200
    HFONT hFontHeader; // font used for page header
    HFONT hFontFooter; // font used for page footer
    BOOL fLineBelowHeader; // underline below header
    BOOL fLineAboveFooter; // underline above header
    TCHAR szHeaderLeft[SFTPRINTPREVIEW_MAXHEADERSIZE+1];// left aligned header text
    TCHAR szHeaderCenter[SFTPRINTPREVIEW_MAXHEADERSIZE+1];// centered header text
    TCHAR szHeaderRight[SFTPRINTPREVIEW_MAXHEADERSIZE+1];// right aligned header text
    TCHAR szFooterLeft[SFTPRINTPREVIEW_MAXHEADERSIZE+1];// left aligned footer text
    TCHAR szFooterCenter[SFTPRINTPREVIEW_MAXHEADERSIZE+1];// centered footer text
    TCHAR szFooterRight[SFTPRINTPREVIEW_MAXHEADERSIZE+1];// right aligned footer text

    long nCustomCode; // Custom modifications

    // New in 2.0 (inserted)
    int cntLimitPages; // default # of pages to print (Print Dialog)
    BOOL fSupportNonTTFonts; // support non-tt fonts for header/footer
    BOOL fCenterOnClick; // center page on clicked position when zooming in/out
    BOOL fDragPage; // allow page dragging
    BOOL fCachePages; // cache all pages (up to SFTPRINTPERVIEW_MAXCACHEDPAGES)
#define SFTPRINTPREVIEW_MAXCACHEDPAGES 200 // maximum number of cached pages

    TCHAR resc2;
    TCHAR chVarLeadin; // variable leadin

    double fltMinHeaderGap; // minimum gap between header and page body (in inches)
    double fltMinFooterGap; // minimum gap between footer and page body (in inches)

    LPSFTPRINTPREVIEW_CUSTOMVAR lpCustomVars; // caller variables

    BOOL fPrintUserAbort; // Last Print() call cancelled by user
    BOOL fPrintAppShutDown; // Last Print() call cancelled by application shutdown
    BOOL fPrintPageOutOfRange; // Last Print() call cancelled by Page out of range

    short fShowErrorMessage; // Show messagebox on error
    short fWantCancelDialog; // Show Preparing to print / Cancel dialog
    // End of New in 2.0

    /* read/only fields */
    int errorValue; // Error
#define SFTPRINTPREVIEW_ERR_marginX 100
#define SFTPRINTPREVIEW_ERR_marginY 101
#define SFTPRINTPREVIEW_ERR_zoom 102
#define SFTPRINTPREVIEW_ERR_maxZoom 103
#define SFTPRINTPREVIEW_ERR_offsetX 107
#define SFTPRINTPREVIEW_ERR_offsetY 108
#define SFTPRINTPREVIEW_ERR_numPageRows 109
#define SFTPRINTPREVIEW_ERR_numPageGroups 110
#define SFTPRINTPREVIEW_ERR_marginPageGroup 111
#define SFTPRINTPREVIEW_ERR_marginShadow 112
#define SFTPRINTPREVIEW_ERR_maxPageRows 113
#define SFTPRINTPREVIEW_ERR_maxPageGroups 114
#define SFTPRINTPREVIEW_ERR_zoomIncrDecr 115
#define SFTPRINTPREVIEW_ERR_fltLeftMargin 116
#define SFTPRINTPREVIEW_ERR_fltTopMargin 117
#define SFTPRINTPREVIEW_ERR_fltRightMargin 118
#define SFTPRINTPREVIEW_ERR_fltBottomMargin 119
#define SFTPRINTPREVIEW_ERR_fltHeaderFromEdge 120
#define SFTPRINTPREVIEW_ERR_fltFooterFromEdge 121
#define SFTPRINTPREVIEW_ERR_fltGutterMargin 122
#define SFTPRINTPREVIEW_ERR_iUnitsOfMeasure 123
#define SFTPRINTPREVIEW_ERR_iPrintPages 124
#define SFTPRINTPREVIEW_ERR_iContentSizing 125
#define SFTPRINTPREVIEW_ERR_iZoomStyle 126
#define SFTPRINTPREVIEW_ERR_hwndContent 127
#define SFTPRINTPREVIEW_ERR_hwndData 128
#define SFTPRINTPREVIEW_ERR_fltMinHeaderGap 129
#define SFTPRINTPREVIEW_ERR_fltMinFooterGap 130

    DWORD PrintDlgLastError; // last error value (PrintDlg(Ex))

    POINT pagePos[SFTPRINTPREVIEW_MAXVIEWPAGES];// preview page location
    SIZE pageSize[SFTPRINTPREVIEW_MAXVIEWPAGES];// preview page dimensions (pixels)

    // Display
    int DPixelsX; // screen pixels per inch (x)
    int DPixelsY; // screen pixels per inch (y)

    // Zoom
    int offsetX; // desired x offset when viewing zoomed page
    int offsetY; // desired y offset when viewing zoomed page

    // Printer
    int PPaperPixX; // printer page size in pixels (x)
    int PPaperPixY; // printer page size in pixels (y)
    int PPixInchX; // printer pixels per inch (x)
    int PPixInchY; // printer pixels per inch (y)
    int PPrintableOffsX; // offset to start of printable area on page (x)
    int PPrintableOffsY; // offset to start of printable area on page (y)
    int PPrintablePixX; // width of printable area on page in pixels
    int PPrintablePixY; // height of printable area on page in pixels

    // Pages
    long maxPages; // pages available for preview
    long visitedLastPage; // highest visited page # so far
    SFTPRINTPREVIEW_DWORD_PTR* aVisitedPageInfo;// array of SFTPRINTPREVIEW_DWORD_PTR for visited pages

    // Print error return
    DWORD dwdPrintLastError; // Last error (GetLastError) from szPrintLastFunc
    char szPrintLastFunc[16]; // Last function called

} SFTPRINTPREVIEW_CONTROL, * LPSFTPRINTPREVIEW_CONTROL;
typedef const SFTPRINTPREVIEW_CONTROL * LPCSFTPRINTPREVIEW_CONTROL;

Members

cbSize

The size of the SFTPRINTPREVIEW_CONTROL structure. When using GetControlInfo and SetControlInfo, the specified size must match the actual size of the structure. This value must be initialized before calling GetControlInfo and SetControlInfo.

fOwnDevHandles

Set to TRUE so the control owns the DEVMODE and DEVNAMES handles defining the current printer (see hOwnDevMode, hOwnDevNames), FALSE otherwise. This is usually set to TRUE to allow the control to manage and define the current printer. In certain frameworks, such as MFC or .NET, the current printer may need to be defined by the framework, if framework functions are also used to print. This is automatically set to FALSE for C++/MFC when using the CSftPrintPreview_View class.

When set to TRUE, hOwnDevMode, hOwnDevNames define the current printer. When set to FALSE, lphDevMode and lphDevNames point to the actual DEVMODE and DEVNAMES handles.

fScrollbars

Set to TRUE so the control automatically manages horizontal and vertical scroll bars, FALSE otherwise. If an application wants to display and manage its own scroll bars, this value must be set to FALSE.

fToolbar

Set to TRUE so the control automatically displays its built-in tool bar, FALSE otherwise.

fUseThemes

Set to TRUE to use Windows themes, FALSE otherwise. When defining the use of Windows themes, the application must use an application manifest to make use of the Common Controls version 6, otherwise the Page Setup dialog will use themes for some of the controls, but not for the entire dialog.

fWantCloseButton

Set to TRUE so the Close button is visible on the built-in tool bar, FALSE otherwise.

fWantHelpButton

Set to TRUE so the Help button is visible on the built-in tool bar, FALSE otherwise.

fWantPageSetupButton

Set to TRUE so the Page Setup button is visible on the built-in tool bar, FALSE otherwise.

hOwnDevMode

A DEVMODE handle defining the current printer, NULL otherwise. This member is only valid if fOwnDevHandles is set to TRUE.

hOwnDevNames

A DEVNAMES handle defining the current printer, NULL otherwise. This member is only valid if fOwnDevHandles is set to TRUE.

lphDevMode

A pointer to a DEVMODE handle defining the current printer, NULL otherwise. This member is only valid if fOwnDevHandles is set to FALSE.

lphDevNames

A pointer to a DEVNAMES handle defining the current printer, NULL otherwise. This member is only valid if fOwnDevHandles is set to FALSE.

currPage

The current, zero-based page number.

firstPage

The first page displayed in a multi-page preview. Page numbers are zero-based.

numPageRows

The number of page rows displayed in a multi-page preview. Valid values are in the range 1 - 6.

numPageGroups

The number of pages per row displayed in a multi-page preview. Valid values are 2, 4, 6, 8, 10, 12.

maxPageRows

The maximum number of page rows a user can select on the built-in tool bar using the "Multiple Pages" button. If output is slow to generate for preview purposes, it may be advantageous to limit the maximum number of displayable pages. Valid values are in the range 1 - 6.

maxPageGroups

The maximum number of pages per row a user can select on the built-in tool bar using the "Multiple Pages" button. If output is slow to generate for preview purposes, it may be advantageous to limit the maximum number of displayable pages. Valid values are 2, 4, 6, 8, 10, 12.

zoom

The zoom factor expressed in percent. Valid values are 0 and the range 10 - 1000. If 0 is specified, a multi-page preview is in effect, otherwise the page is scaled by the specified percentage.

maxZoom

The maximum zoom factor a user can enter on the built-in tool bar using the "Zoom Factor" combo box. Valid values are in the range 10 - 1000.

zoomIncrDecr

The zoom factor increment/decrement used when the user clicks on a page in preview mode to zoom in/out. Valid values are in the range 10 - 1000.

fZoomIncreasing

TRUE if the next mouse click on a page in preview mode results in zooming in by the amount specified by zoomIncrDecr, FALSE if zooming out.

iZoomStyle

Defines the zoom in/out action available to the end-user.

fWantPrintDialog

Set to TRUE so the built-in tool bar's Print button displays the Print dialog before printing, FALSE otherwise, in which case printing starts immediately.

fPairPages

Set to TRUE so pages are displayed in pairs, showing the front and back of a page next to each other. If set to FALSE, pages are shown individually. If the current printer supports duplexing, the pages are always shown in pairs, regardless of the fPairPages setting.

marginX

Defines the minimum horizontal distance between pages of a multi-page preview (in pixels).

marginY

Defines the minimum vertical distance between pages of a multi-page preview (in pixels).

marginPageGroup

Defines the distance between paired pages of a multi-page preview (in pixels). This area is shaded using the color defined using the SFTPRINTPREVIEW_COLORS structure's colorPageGap member.

marginShadow

Defines the width and height of the shadow around pages of a multi-page preview (in pixels). This area is shaded using the color defined using the SFTPRINTPREVIEW_COLORS structure's colorShadow member.

iPrintPages

Defines the pages to be printed using the Print function. The Print dialog sets this member automatically, based on the user's selection.

hCursZoomPlus

The cursor displayed when the mouse cursor rests over a page and the next mouse click zooms in (fZoomIncreasing is set to TRUE). This member is only used if iZoomStyle is set to SFTPRINTPREVIEW_ZOOMSTYLE_LEFTBUTTONONLY.

hCursZoomMinus

The cursor displayed when the mouse cursor rests over a page and the next mouse click zooms out (fZoomIncreasing is set to FALSE). This member is only used if iZoomStyle is set to SFTPRINTPREVIEW_ZOOMSTYLE_LEFTBUTTONONLY.

hCursZoomNeutral

The cursor displayed when the mouse cursor rests over a page. This member is only used if iZoomStyle is set to SFTPRINTPREVIEW_ZOOMSTYLE_BOTHBUTTONS.

lpDrawPageWorkArea

An application-defined value. This value is used when calling the provided lpDrawInfoProc drawing callback. It is passed to the callback function as the lpDrawPageWorkArea member of the SFTPRINTPREVIEW_DRAWINFO structure.

lpDrawInfoProc

The address of a drawing callback of type SFTPRINTPREVIEW_DRAWINFOPROC, which is used to render pages for preview and printing purposes. RichEdit controls require the use of the drawing callback SftPrintPreview_RenderRicheditWindow_Callback.

hwndContent

The window whose contents are to be printed. If no drawing callback lpDrawInfoProc is provided, this window must support printing and print preview using the SFTPRINTPREVIEW_CONTENTWINDOWMESSAGE protocol. SftTree/DLL and SftTree/OCX 5.0 (and up) can be rendered in this manner. RichEdit controls require the use of the drawing callback SftPrintPreview_RenderRicheditWindow_Callback. For application-generated output, this parameter must be set to NULL.

hwndData

SftTree/DLL and SftTree/OCX 5.0 (and up) support the data window handle hwndData. If this value is not NULL, the tree control defined by hwndContent is rendered using the data (items, cells, etc.) provided by hwndData. For application-generated output, this parameter must be set to NULL.

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 with 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.

szOutputName

Defines the output name that should be used when sending output to the print queue of a printer.

fltLeftMargin

Defines the left margin (in inches).

fltTopMargin

Defines the top margin (in inches). The fltMinHeaderGap member can be used to insure that the header doesn't overlap the page body.

fltRightMargin

Defines the right margin (in inches).

fltBottomMargin

Defines the bottom margin (in inches). The fltMinFooterGap member can be used to insure that the header doesn't overlap the page body.

fltHeaderFromEdge

Defines the distance of the header from the top edge of the paper (in inches).

fltFooterFromEdge

Defines the distance of the footer from the bottom edge of the paper (in inches).

fltGutterMargin

Defines the additional gutter margin (in inches). A gutter margin is useful when printing pages that are to be bound or two and three-hole punched. The gutter margin provides extra space for such binding. If mirrored margins are selected (fMirrorMargins member), the gutter margin will alternate between left and right (or top and bottom) on the front and back of pages.

fGutterLeft

Set to TRUE so the gutter margin is added to the left margin, FALSE otherwise, in which case the gutter margin is added to the top margin.

fMirrorMargins

Set to TRUE so margins alternate between front and back of a page, FALSE otherwise.

fShowAreas

Defines whether the print preview display shows margins and gutter margin using the defined colors (see SFTPRINTPREVIEW_COLORS). Set to TRUE to show margins and gutter margin, FALSE otherwise.

iUnitsOfMeasure

Defines the units used to display distance values when using the Page Setup dialog.

hFontHeader

Defines the font used for headers. The specified font handle is owned by the control and is automatically deleted using DeleteObject, when it is no longer needed.

hFontFooter

Defines the font used for footers. The specified font handle is owned by the control and is automatically deleted using DeleteObject, when it is no longer needed.

fLineBelowHeader

Set to TRUE to show a solid, 1 point line below the headers, FALSE otherwise. The color can be defined using SFTPRINTPREVIEW_COLORS, colorHeaderLine.

fLineAboveFooter

Set to TRUE to show a solid, 1 point line above the footers, FALSE otherwise. The color can be defined using SFTPRINTPREVIEW_COLORS, colorFooterLine.

szHeaderLeft

Defines the text of the left-aligned portion of the header. The color used for header and footer text can be defined using SFTPRINTPREVIEW_COLORS, colorHeaderText and colorFooterText.

szHeaderCenter

Defines the text of the centered portion of the header. The color used for header and footer text can be defined using SFTPRINTPREVIEW_COLORS, colorHeaderText and colorFooterText.

szHeaderRight

Defines the text of the right-aligned portion of the header. The color used for header and footer text can be defined using SFTPRINTPREVIEW_COLORS, colorHeaderText and colorFooterText.

szFooterLeft

Defines the text of the left-aligned portion of the footer. The color used for header and footer text can be defined using SFTPRINTPREVIEW_COLORS, colorHeaderText and colorFooterText.

szFooterCenter

Defines the text of the centered portion of the footer. The color used for header and footer text can be defined using SFTPRINTPREVIEW_COLORS, colorHeaderText and colorFooterText.

szFooterRight

Defines the text of the right-aligned portion of the footer. The color used for header and footer text can be defined using SFTPRINTPREVIEW_COLORS, colorHeaderText and colorFooterText.

nCustomCode

Defines optional product customization. Valid values are made available by Product Support, in response to purchased enhancements, special features, etc. and are only available upon request.

cntLimitPages

Defines the default number of pages to print, when the Print Dialog is shown. Set to 0 to print all pages.

fSupportNonTTFonts

Defines whether screen and printer fonts can be used for headers and footers. If set to FALSE, only TrueType fonts must be used. If set to TRUE, any font can be used, however, font substitution will occur when selecting a printer font that is not available as a screen font (and vice versa). It is recommended to use only TrueType fonts.

fCenterOnClick

Defines how the page is zoomed in/out when clicking on the page. The iZoomStyle member defines which mouse buttons allow zoom in/out. If fCenterOnClick is set to TRUE, the page location clicked will be centered or as close to the center of the resulting display as possible. If fCenterOnClick is set to FALSE, the page location clicked will be in the same position on the resulting display as possible. When using fCenterOnClick set to FALSE, iZoomStyle should define either SFTPRINTPREVIEW_ZOOMSTYLE_LEFTBUTTONONLY_EXACT or SFTPRINTPREVIEW_ZOOMSTYLE_BOTHBUTTONS_EXACT.

fDragPage

Defines whether a page can be repositioned by dragging it, while previewing a single page. This option has no effect when multiple pages are viewed. Set to TRUE to allow page dragging, FALSE otherwise. When using fDragPage set to TRUE, iZoomStyle should define either SFTPRINTPREVIEW_ZOOMSTYLE_LEFTBUTTONONLY_EXACT or SFTPRINTPREVIEW_ZOOMSTYLE_BOTHBUTTONS_EXACT to allow full dragging of the page, including when most of the page is off-screen.

fCachePages

Defines whether pages (up to the maximum of SFTPRINTPREVIEW_MAXCACHEDPAGES) are cached, rather than recreated every time they are rendered. The current page is always cached. This option determines whether the entire output is cached for maximum performance, at the expense of additional system resources use. Set to TRUE to cache all pages, FALSE otherwise. It is recommended not to use caching of the entire output, due to the significant resource use, but it may be useful initially when implementing the first stages of application-generated output.

chVarLeadin

Defines the default lead-in character for string substitution variables (%) used in headers and footers.

fltMinHeaderGap

Defines the required, minimum gap between the bottom of the header and the body of the page. If 0 is specified, there is no minimum gap and header and body may overlap. The header and body margins are defined using the header distance (fltHeaderFromEdge) and top margin (fltTopMargin) values. Depending on the contents of the header and the font chosen, the header may become too large and overlap into the page body. Using fltMinHeaderGap this can be avoided by adding a minimum gap below the header, in effect overriding the fltTopMargin value.

fltMinFooterGap

Defines the required, minimum gap between the bottom of the footer and the body of the page. If 0 is specified, there is no minimum gap and footer and body may overlap. The footer and body margins are defined using the footer distance (fltFooterFromEdge) and top margin (fltBottomMargin) values. Depending on the contents of the footer and the font chosen, the footer may become too large and overlap into the page body. Using fltMinFooterGap this can be avoided by adding a minimum gap below the footer, in effect overriding the fltBottomMargin value.

lpCustomVars

Defines a custom string substitution variable table for variables used in headers/footers. Set to NULL to omit the table. lpCustomVars should point to the first entry of an array of SFTPRINTPREVIEW_CUSTOMVAR entries, each defining a variable and the substitution text. The last entry, marking the end of the table, must have both the lpszVarName and lpszText members set to NULL. The contents of the table are not copied and must remain valid as long as the table is defined to the preview control.

The built-in variables are always available.

fPrintUserAbort

Read/only. After a call to Print, returns whether the user aborted printing. Set to TRUE if the user cancelled printing, FALSE otherwise.

fPrintAppShutDown

Read/only. After a call to Print, returns whether the application aborted printing. Set to TRUE if the application ended, FALSE otherwise.

fPrintPageOutOfRange

Read/only. After a call to Print, returns whether printing was aborted, because a non-existent page was requested. Set to TRUE if a non-existent page was requested, FALSE otherwise.

fShowErrorMessage

Defines whether the next call to the Print function will display error messages. Set to TRUE to display error messages to the end-user, FALSE otherwise. Regardless of the setting of the fShowErrorMessage member, error information is always available by retrieving the SFTPRINTPREVIEW_CONTROL structure (fPrintUserAbort, fPrintAppShutDown, fPrintPageOutOfRange, dwdPrintLastError, szPrintLastFunc) after calling the Print function.

fWantCancelDialog

Defines whether the modeless dialog is shown while printing, informing the user that printing is in progress, along with the current page count. This dialog allows the end-user to cancel printing. Set to TRUE to display the dialog, FALSE otherwise.

errorValue

Read/only. If the SetControlInfo function fails, the errorValue member contains an error code, indicating which structure member has caused the failure. Please see the SetControlInfo function for a list of possible values.

PrintDlgLastError

Read/only. If the DefaultPrinter, PrintDialog or PrintSetup fail, the PrintDlgLastError member contains an error code returned by the last call to the Windows API CommDlgExtendedError(). Please see the CommDlgExtendedError function for a list of possible values.

pagePos

Read/only. An array of POINT structures, defining the top, left position of each page of a preview display. If zoom is 0, a multi-page preview is in effect, in which case numPageRows * numPageGroups pages are available, otherwise only 1 page is available.

pageSize

Read/only. An array of SIZE structures, defining the width and height of each page of a preview display. If zoom is 0, a multi-page preview is in effect, in which case numPageRows * numPageGroups pages are available, otherwise only 1 page is available.

DPixelsX

Read/only. Defines the number of pixels per logical inch along the screen width.

DPixelsY

Read/only. Defines the number of pixels per logical inch along the screen height.

offsetX

Read/only. Defines the desired horizontal offset when viewing a zoomed page (in pixels).

offsetY

Read/only. Defines the desired vertical offset when viewing a zoomed page (in pixels).

PPaperPixX

Read/only. Defines the width of the physical page (in pixels). E.g., 8.5 x 11 inch paper on a 600 dpi printer has a physical width of 5100 pixels. The physical page is almost always greater than the printable area of the page.

PPaperPixY

Read/only. Defines the height of the physical page (in pixels). E.g., 8.5 x 11 inch paper on a 600 dpi printer has a physical height of 6600 pixels. The physical page is almost always greater than the printable area of the page.

PPixInchX

Read/only. Defines the number of pixels per logical inch along the (printed) page width.

PPixInchY

Read/only. Defines the number of pixels per logical inch along the (printed) page height.

PPrintableOffsX

Read/only. Defines the distance from the left edge of the physical page to the left edge of the printable area (in pixels).

PPrintableOffsY

Read/only. Defines the distance from the top edge of the physical page to the top edge of the printable area (in pixels).

PPrintablePixX

Read/only. Defines the width of the printable area on the page (in pixels).

PPrintablePixY

Read/only. Defines the height of the printable area on the page (in pixels).

maxPages

Read/only. Defines the total number of pages available for preview and printing.

If the total number of pages is currently unknown, maxPages is set to 999998 (SFTPRINTPREVIEW_MAXPAGES). Once all pages have been viewed or formatted by visiting the last page, the maxPages member reflects the actual number of pages.

visitedLastPage

Read/only. Defines the currently last known page. Page numbers are zero-based.

aVisitedPageInfo

Read/only. An array of application-defined values of type SFTPRINTPREVIEW_DWORD_PTR. These values are returned by the page rendering callback lpDrawInfoProc as each page is rendered. These values can be used to store page information, so output can resume without extensive page formatting of already visited pages. The Page Management topic shows how these values are saved and can be used to optimize page positioning.

dwdPrintLastError

Read/only. Defines the last error returned by the Windows API function contained in the szPrintLastFunc member. This error was recorded while the application was printing using the the Print function. The szPrintLastFunc member contains the name of the API that failed. The last error code was retrieved using the Windows GetLastError() function.

szPrintLastFunc

Read/only. Contains the name of the Windows API that failed. This error was recorded while the application was printing using the the Print function. The szPrintLastFunc member contains the name of the API that failed. The last error code (dwdPrintLastError member) was retrieved using the Windows GetLastError() function.

Comments

The SFTPRINTPREVIEW_CONTROL structure is used with the GetControlInfo and SetControlInfo functions to define control attributes.

Example

C

SFTPRINTPREVIEW_CONTROL Ctl;
Ctl.cbSize = sizeof(SFTPRINTPREVIEW_CONTROL);
if (!SftPrintPreview_GetControlInfo(hwndCtl, &Ctl))
    _ASSERT(0);
// set all desired options
Ctl.numPageRows = 1; // default to 1x2 pages
Ctl.numPageGroups = 2;
Ctl.zoom = 0; // start out with multiple pages
lstrcpy(Ctl.szOutputName, TEXT("SftPrintPreview PreviewPages Sample Output"));
lstrcpy(Ctl.szHeaderRight, TEXT("SftPrintPreview/DLL PreviewPages Sample"));
lstrcpy(Ctl.szFooterLeft, TEXT("www.softelvdm.com"));

if (!SftPrintPreview_SetControlInfo(hwndCtl, &Ctl)) {
    int errorValue = Ctl.errorValue;
    _ASSERT(0); // an error occurred, check errorValue for error code
}

C++

SFTPRINTPREVIEW_CONTROL Ctl;
Ctl.cbSize = sizeof(SFTPRINTPREVIEW_CONTROL);
if (!m_Preview.GetControlInfo(&Ctl))
    _ASSERT(0);
// set all desired options
Ctl.numPageRows = 1; // default to 1x2 pages
Ctl.numPageGroups = 2;
Ctl.zoom = 0; // start out with multiple pages
lstrcpy(Ctl.szOutputName, TEXT("SftPrintPreview RichEdit Output"));
lstrcpy(Ctl.szHeaderRight, TEXT("SftPrintPreview/DLL RichEdit Preview Sample"));
lstrcpy(Ctl.szFooterLeft, TEXT("www.softelvdm.com"));

if (!m_Preview.SetControlInfo(&Ctl)) {
    int errorValue = Ctl.errorValue;
    _ASSERT(0); // an error occurred, check errorValue for error code
}

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