Print
Preview Suite v4.52
|
Copyright ©
Kambiz R. Khojasteh. All rights reserved.
Get future component updates from http://www.delphiarea.com.
Delphi
3 |
Delphi
4 |
Delphi
5 |
Delphi
6 |
Delphi
7 |
DESCRIPTION
TPrintPreview
is a descendent of TScrollBox and has properties of both TScrollBox component
and TPrinter class. The key features of TPrintPreview are:
- Automatically
adjusts printer's paper size and orientation at the print time
- Automatically
adjusts mapping modes
- Preview pages
can be scaled with an arbitrarily zoom factor
- Shows prepared
pages while the new pages are still in progress to be prepared
- Displayed
pages can be scrolled by mouse dragging
- Pages can
be saved/restored to/from disk
- Each page
is accessible as a Windows MetaFile image
- Regardless
of number of previewed pages and their complexity, only consumes a small
portion of Windows resources
- Easy to use
for printing rich text and graphics
- Has a complete
set of events
- Has a complementary
control to show thumbnail pages
KEY PROPERTIES
- Aborted
(Read-only)
Indicates whether the print process is aborted.
- Canvas:
TCanvas (Read-only)
Provides access to a drawing surface that represents
the page. Each page has its own canvas and any access to this property must
be inside the BeginDoc and EndDoc block.
- CurrentPage:
Integer
Determines the current showing page number.
- DirectPrint:
Boolean
Determines whether the control creates preview pages or directly print
the pages on the printer.
- FastPrint:
Boolean
If set to true, the component uses a faster method
for printing the pages on the printer. If there is any page containing image
and you have not used either PaintGraphic or PaintGraphicEx
methods for drawing the image, it is recommended to set FastPrint to
false because some printers do not support the algorithm used for fast print
method.
- Font:
TFont
Specifies the default font for each new page. It
is reommended to use a scalable font (e.g. TrueType and OpenType).
- FormName:
String
Determines the name of selected form for the paper
size.
- AutoFormName:
String
Determines the name of the form that is added by
the control automatically.
- Orientation:
TPrinterOrientation
TPrinterOrientation = (poPortrait, poLanscape)
Determines the the paper orientation of pages that will be created. The
paper orientation could not change inside the BeginDoc and EndDoc
block.
- Pages[PageNo:
Integer]: TMetaFile (Read-only)
Contains the list of prepared pages.
- PageBounds:
TRect
(Read-only)
Specifies the bounding rectangle of the page in
logical coordinates.
- PageBounds:
TPoint
(Read-only)
Specifies the paper size in logical coordinates.
- PagePixels:
TPoint
(Read-only)
Specifies the paper size in device coordinates.
- PaperType:
TPaperType
Specifies the paper size by the paper's type. There
are 68 predefined sizes however by setting this property to pCustom
you can use PaperWidth and PaperHeight properties to set your
own custom paper size.
- PaperHeight:
Integer
Determines the physical height of the paper in
logical units. Changing this property will change PaperType to pCustom.
The value of PaperHeight must be between 1 and 32767.
- PaperWidth:
Integer
Determines the physical width of the paper in logical
units. Changing this property will change PaperType to pCustom.
The value of PaperWidth must be between 1 and 32767.
- PrinterInstalled:
Boolean (Read-only)
Indicates whether is there any installed printer (driver) on the system.
- PrintJobTitle:
String
Specifies the title of the print job on the system's print queue.
- State:
TPreviewState (Read-only)
TPreviewState = (psReady, psCreating, psPrinting, psEditing)
Determines the current state of the control.
psReady |
|
The control
is idle. |
psCreating |
|
The BeginDoc
method has called and the control is preparing the preview pages to
display. |
psPrinting |
|
One of
the print methods has called and the control is printing pages on the
printer. |
psEditing |
|
The BeginEdit
methods has called and control is editing a page. |
- TotalPages:
Integer (Read-only)
Determines the total number of available pages
to preview/print.
- Units: TUnits
TUnits = (mmPixel, mmLoMetric, mmHiMetric, mmLoEnglish, mmHiEnglish, mmTWIPS,
mmPoints)
Determines how the control interprets the measurement values (e.g. paper
size, margins, font's size, font's height, pen's size, ...)
mmPixel |
|
1 unit
= 1 pixel |
mmLoMetric |
|
1 unit
= 0.1 millimeter |
mmHiMetric |
|
1 unit
= 0.01 millimeter |
mmLoEnglish |
|
1 unit
= 0.01 inch |
mmHiEnglish |
|
1 unit
= 0.001 inch |
mmTWIPS |
|
1 unit
= 1 twip = 1/20 point = 1/1440 inch |
mmPoints |
|
1 unit
= 1 point = 1/72 inch |
- UseTempFile:
Boolean
Indicates whether the control uses a temporary file for its internal storage.
When there are more than 500 pages, it is recommended to use temporary files.
- UsePrinterOptions:
Boolean
Specifies where the control looks for page information. When UseUserPage
is true, the control uses the printer's paper size and orientation to for
the paper size, otherwise it uses the paper size and orientation set in the
control.
- Zoom:
Integer
Specifies how much the control scales pages on
the screen. Changing this property will change ZoomState to zsZoomOther.
- ZoomState:
TZoomState
TZoomState = (zsZoomOther, zsZoomToWidth, zsZoomToHeight, zsZoomToFit)
Determines how the control scales pages on the
screen.
zsZoomOther |
|
Scaling
factor determines by Zoom property. |
zsZoomToWidth |
|
Whole
the page's width will be visible. |
zsZoomToHeight |
|
Whole
the page's height will be visible. |
zsZoomToFit |
|
Whole
the page will be visible. |
- ZoomSavePos:
Boolean
Indicates whether the control keeps the old scroll
positions when the zoom is changing.
- ZoomStep:
Integer
Determines the amount of changes in zoom percentage
when it increments or decrements by a keyboard shurtcut or mouse wheel movement.
- ZoomMin:
Integer
Determines the minimum allowed value for the Zoom
property.
- ZoomMax:
Integer
Determines the maximum allowed value for the Zoom
property.
KEY METHODS
- procedure
BeginDoc
Initiates a new job and creates the Canvas.
- procedure
EndDoc
Finalizes the current job.
- procedure
NewPage
Starts a new page.
- procedure
Abort
Aborts one of page creating or printing processes.
- function
BeginEdit(PageNo: Integer): Boolean
Intializes Canvas to edit an existing page.
- procedure
EndEdit
Finalizes editing a page.
- procedure
Clear
Clears all pages and resets the control.
- procedure
Print
Sends all pages to the printer.
- procedure
PrintPages(FirstPage, LastPage: Integer)
Sends the selected range of pages to the printer.
- procedure
LoadFromStream(Stream: TStream)
Loads pages from a stream.
- procedure
SaveToStream(Stream: TStream)
Saves pages into a stream.
- procedure
LoadFromFile(const FileName: String)
Loads pages from a previously saved file.
- procedure
SaveToFile(const Filename: String)
Saves pages into a file.
- procedure
UpdateZoom
Forces the control to recalculate zoom scale and update the screen.
- procedure
ConvertPoints(var Points; NumPoints: Integer; InUnits, OutUnits: TUnits)
Converts the Points coordinates from the input unit specified by InUnits
parameter to the unit specified by the OutUnits. The metod uses the horizontal
and vertical resolution of the target device
for the conversion.
- function
ConvertXY(X, Y: Inetger; InUnits, OutUnits: TUnits): TPoint
Returns
the point coordinate converted from the input unit specified by InUnits parameter
to the unit specified by the OutUnits. The metod uses the horizontal and vertical
resolution of the target device
for the conversion.
- function
ConvertX(Value: Integer;
InUnits, OutUnits: TUnits):
Integer
Returns
the conversion of a value specified by the Value parameter from
the input unit specified by InUnits parameter to the unit specified by the
OutUnits. The metod uses the horizontal resolution of the target device for
the conversion.
- function
ConvertY(Value: Integer;
InUnits, OutUnits: TUnits):
Integer
Returns
the conversion of a value specified by the Value parameter from
the input unit specified by InUnits parameter to the unit specified by the
OutUnits. The metod uses the vertical resolution of the target device for
the conversion.
- function
PaintGraphic(X, Y: Integer; Graphic: TGraphic): TPoint
Renders the graphic specified by the Graphic parameter on the canvas at
the location given by the coordinates (X, Y). The coordinates are in the control's
unit. The function returns the size of the graphic in the control's unit.
- function
PaintGraphicEx(const Rect: TRect; Graphic: TGraphic; Proporional, ShrinkOnly,
Cnter: Boolean): TRect
Draws the graphic specified by the Graphic parameter in the rectangle
specified by the Rect parameter. The coordinates are in the control's unit.
The function returns the bounding rectangle of the graphic in the control's
unit.
- function
PaintGraphicEx2(const Rect: TRect; Graphic: TGraphic; VertAlign: TVertAlign;
HorzAlign: THorzAlign): TRect;
Draws the graphic specified by the Graphic parameter in the rectangle
specified by the Rect parameter. The coordinates are in the control's unit.
The function returns the bounding rectangle of the graphic in the control's
unit.
- function
PaintWinControl(X, Y: Integer; WinControl: TWinControl): TPoint
Renders the windowed control specified by the WinControl parameter on
the canvas at the location given by the coordinates (X, Y). The coordinates
are in the control's unit. The function returns the size of the rendered image
in the control's unit.
- function
PaintWinControlEx(const Rect: TRect; WinControl: TWinControl; Proporional,
ShrinkOnly, Cnter: Boolean): TRect
Draws the windowed control specified by the WinControl parameter in the
rectangle specified by the Rect parameter. The coordinates are in the control's
unit. The function returns the bounding rectangle of the graphic in the control's
unit.
- funtion PaintRichText(const
Rect: TRect; RichEdit: TCustomRichEdit; MaxPages: Integer; pOffset: PInteger):
Integer
Renders the content of the RichEdit control specified by the RichEdit
parameter in the rectangle specified by the Rect parameter. The coordinates
are in the control's unit. If the content does not fit to the specified rectangle,
the functions draw the rest in a new page. The function returns the number
of pages used to render the content. The maximum number of pages allowed to
print can be controlled by the MaxPages parameter. When MaxPages is zero,
the function prints all the pages. The pOffset parameter is a pointer to an
integer containing the offset (zero based) of the text, which rendering begins
from that point. When the function does not render all the pages, the variable
pointed by pOffset updates to the offset of the next part of the text that
should be rendered in the next call, otherwise it sets to -1. The pOffset
parameter can be nil. The functions returns the number of pages that are rendered.
- funtion GetRichTextRect(var
Rect: TRect; RichEdit: TCustomRichEdit; pOffset: PInteger): Integer
Claulates the smallest bounding rectangle required for rendering one page
of the content of the RichEdit control specified by the RichEdit parameter
in the rectangle specified by the Rect parameter. The coordinates are in the
control's unit. The pOffset parameter is a pointer to an integer containing
the offset (zero based) of the text, which rendering begins from that point.
When the content of the rich edit does not fit into the specified rectangle,
the variable pointed by pOffset updates to the offset of the next part of
the text that, otherwise it sets to -1. The pOffset parameter can be nil.
The functions returns the number of bottom of the bounding rectangle..
- procedure
GetPrinterOptions
Sets the paper size and orientation of the control to the currently selected
printer's paper and orientation. When the UsePrinterOptions property
is True, just after calling the BeginDoc method, the paper size and
paper orientation of the control automatically set to the printer's ones.
- procedure
SetPrinterOptions
Sets the paper and orientation of the currently selected printer to paper
size and orientation of the control. When the UsePrinterOptions property
is False, the control automatically calls this method before beginning to
print.
- function
ClientToPaper(const Pt: TPoint): TPoint
Translates a given point from client area coordinates to the paper coordinates.
The paper coordinates are in the currently selected measurement unit.
- function
PaperToClient(const Pt: TPoint): TPoint
Translates a given point from the paper coordinates to the client area coordinates.
The paper coordinates are in the currently selected measurement unit.
- function
FetchFormNames(FormNames: TStrings): Boolean
Fills the specified list with the name of available (predefined and custom)
forms in the system.
- function
GetFormSize(const AFormName: String; out FormWidth, FormHeight: Integer):
Boolean
Gets width and height of the specified form in the selected measurement unit.
- function
AddNewForm(const AFormName: String; FormWidth, FormHeight): Boolean;
Adds a custom form to the system. The form's size should be expressed in the
selected measurement unit. The user must have full rights to the printer driver
to call this function.
- function
RemoveForm(const AFormName: String): Boolean
Removes a custom form.
This function does not delete the standard forms that the operating system
defines. The user must have full rights to the printer driver to call this
function.
KEY EVENTS
- OnBeginDoc:
TNotifyEvent
Occurs when BeginDoc method calls.
- OnEndDoc:
TNotifyEvent
Occurs
when EndDoc method calls.
- OnNewPage:
TNotifyEvent
Occurs immediately after a new page is created.
- OnEndPage:
TNotifyEvent
Occurs when a page is finished.
- OnAbort:
TNotifyEvent
Occurs when an operation is aborted.
- OnChange:
TNotifyEvent
Occurs when the current page or content of the control changes.
- OnBeforePrint:
TNotifyEvent
Occurs just before sending pages to the printer.
- OnAfterPrint:
TNotifyEvent
Occurs when printing process is finished.
- OnPrintProgress:
TPreviewPrintProgress
TPreviewPrintProgress = procedure(Sender: TObject; PageNum, Progress: Integer;
var AbortIt: Boolean) of object
Occurs periodically during the print operation.
Setting AbortIt to true, aborts the operation.
- OnZoomChange:
TNotifyEvent
Occurs when the zoom ratio of the view is changed.
- OnAutoCustomForm:
TPreviewAutoCustomForm
TPreviewAutoCustomForm = procedure(Sender: TObject; const CustomFormName:
String; Operation: TOperation) of object
Occurs when the control automatically adds/removes
a custom form to/from the system.
GLOBAL PROCEDURES
- procedure
StretchDrawGraphicAsDIB(DC: HDC; Rect: TRect; Graphic: TGraphic)
Converts the graphic specified by the Graphic parameter to Device Independent
Bitmap (DIB) and draws it in the rectangle specified by the Rect parameter
on the device context specified by the DC parameter. This procedure is useful
for printing images on a printer device context.
- procedure
DrawGraphicAsDIB(DC: HDC; X, Y: Integer; Graphic: TGraphic)
Converts the graphic specified by the Graphic parameter to Device Independent
Bitmap (DIB) and draws it at the position specified by the X and Y parameters
on the device context specified by the DC parameter. This procedure is useful
for printing images on a printer device context.
- function
ConvertUnits(Value, DPI: Integer; InUnits, OutUnits: TUnits): Integer
Returns the conversion of the value specified by the Value parameter from
the measurement unit specified by the InUnits parameter to the measurement
unit specified by the OutUnit parameter. If neither source nor destination
units are mmPixel, the DPI parameter will be ignored.
KEYBOARD SHURTCUTS
- Home
Scrolls the current page to the left most position.
- Ctrl+Home
Scrolls the current page to the top most position.
- End
Scrolls the current page to the right most position.
- Ctrl+End
Scrolls the current page to the bottom most position.
- Left
Scrolls the current page to the right with the number of pixels specified
in HorzScrollbar.Increment property.
- Shift+Left
Scrolls the current page one pixel to the right.
- Ctrl+Left
Scrolls the current page one screen to the right.
- Right
Scrolls the current page to the left with the number of pixels specified in
HorzScrollbar.Increment property.
- Shift+Right
Scrolls the current page one pixel to the left.
- Ctrl+Right
Scrolls the current page one screen to the left.
- Up
Scrolls the current page down with the number of pixels specified in VertScrollbar.Increment
property.
- Shift+Up
Scrolls the current page one pixel down.
- Ctrl+Up
Scrolls the current page one screen down.
- Down
Scrolls the current page up with the number of pixels specified in VertScrollbar.Increment
property.
- Shift+Down
Scrolls the current page one pixel up.
- Ctrl+Down
Scrolls the current page one screen up.
- Page Up
Shows the previous page.
- Ctrl+Page
Up
Shows the first page.
- Page Down
Shows the next page.
- Ctrl+Page
Down
Shows the last page.
- Plus (Numeric
Pad)
Zoom in by the amount specified in the ZoomStep property.
- Minus (Numeric
Pad)
Zoom out by the amount specified in the ZoomStep property.
MOUSE WHEEL FUNCTIONS
- Wheel Down
Scrolls the current page up with the number of pixels specified in VertScrollbar.Increment
property.
- Wheel Up
Scrolls the current page down with the number of pixels specified in VertScrollbar.Increment
property.
- Ctrl+Wheel
Down
Zoom out by the amount specified in the ZoomStep property.
- Ctrl+Wheel
Up
Zoom in by the amount specified in the ZoomStep property.
- Shift+Wheel
Down | Wheel Press + Wheel Down
Shows the next page.
- Shift+Wheel
Up | Wheel Press + Wheel Up
Shows the previous page.
ZLIB COMPRESSION
To save preview
pages to a file (or stream) as compressed format:
- If you are
using Delphi 5 or lower, get the freeware ZLib library for your version
of Delphi at http://www.gzip.org/zlib.
- Open the Preview.pas
file and define the ZLIB compiler directive in the begining of the
file.
When the ZLib
compression is active, the component can load both compressed and non-compressed
files.
KNOWN ISSUES
- If Units
property is set to mmHiMetric and width or height of the paper size
is bigger than 32767 units, the page will not display correctly. This happens
because SetWindowExtEx API function expects a two bytes signed integer (Smallint)
as its X and Y parameters, so values bigger than 32767 are interpreted as
negative values.
- When the zoom
is not on the actual size (100%), the control may display the preview of the
non-scalable fonts inproperly.
- The PaintRichText
and GetRichTextRect methods use EM_FORMATRANGE message of the rich edit control.
This message has different behavior on different versions of the rich edit
control. In addition, this message ignores the embedded objects in the RTF
text.
- The preview
of a rich text may differ from its printed version. This issue is a known
rich edit control problem.
HISTORY.
- Version 4.52
(June 25, 2004)
- Now,
when a custom page size is set in the control, the control automatically adds
it to the system. Consequently, the AutoFormName property and OnAutoCustomForm
event are added.
- A possible bug on custom page sizes on Windows 98 fixed.
- Version 4.50
(June 19, 2004)
- The
new property FormName, and the new methods FetchFormNames, GetFormSize,
AddNewForm, and RemoveForm added to TPrintPreview component.
- Now, the StretchDrawGraphicAsDIB procedure doesn't convert metafiles
to DIB if the metafile doesn't have a DDB record.
- Some minor tweaks.
- Version 4.40
(May 14, 2004)
- To
make editing of an existing page easier, BeginEdit and EndEdit methods added.
Consequently, The new state psEditing added to the list of available control's
states.
- Version 4.36
(May 13, 2004)
- New
OnEndPage event added.
- Version 4.35
(April 10, 2004)
- New
method PaintGraphicEx2 added to TPrintPreview component (Thanks to
Roy M Klever).
- The global variable UseHalfTonePrinting added (Thanks to Roy
M Klever).
- Version 4.341
(March 24, 2004)
- Bug
fixed (Thanks to Janet Agney).
- Version 4.34
(December 8, 2003)
- Now, a preview page can be changed just by assigning a metafile to it.
- Version 4.33
(December 6, 2003)
- Now, the preview pages can be saved as compressed using the ZLib
library. As default this feature is disabled.
- Two new methods ClientToPaper and PaperToClient are added to TPrintPreview
component.
- Now, the preview scrolls faster and smoother.
- Some minore tweaks.
- Version 4.32
(November 20, 2003)
- Incorrect printing of the content when the measurement unit was mmPixel,
is fixed (Thanks to Bria Dorin).
- Version 4.31
(November 2, 2003)
- The ConvertUnit, ToPrinterUnit, and Screen2PrinterUnit methods are no longer
exist in this release. Instead of the mentioned methods use the new ConvertPoints,
ConvertXY, ConvertX and ConvertY methods.
- For convenience the PageBounds, PageSize, and PagePixels
peroperies added.
- The new property DirectPrint added. To print pages directly on the
printer without generating the preview pages, set this property to True.
- And, some minor tweaks in rendering rich text and drawing preview pages.
- Version 4.30
(October 19, 2003)
- The bug in printing pages on a printer with different horizontal and vertical
resolution fixed.
- The bug in font size fixed.
- The points unit added to measurement units.
- The new component TThumbnailPreview added to the suite. This control shows
the thumbnails of TPrintPreview pages.
- Version 4.21
(September 18, 2003)
- The paper size and paper orientation were missed in the saved preview files,
which are added in this release. The old preview files are still readable
by the control.
- Now, the component can be compiled on C++Builder 3 (Thanks to Patrizio
Zelotti).
- Version 4.20
(July 27, 2003)
- The new properties ZoomMin, ZoomMax, and ZoomStep added.
- The new event OnZoomChange added.
- The mouse wheel support added.
- Version 4.19
(July 8, 2003)
- The mistake in interpreting mmLoEnglish and mmHiEnglish units fixed.
- Version
4.18 (July 6, 2003)
- The bug on zooming the pages fixed (Thanks to Hubert
"Johnny_Bit" Kowalski).
- Now changing the ZoomState property will update the value of
the Zoom property.
- Version 4.17
(May 29, 2003)
- The new method GetRighTextRect added (Thanks to rgesswein).
- The PaintRichText method modified to support custom RichEdit controls (Thanks
to Sebastien).
- Version 4.16
(May 18, 2003)
- The component modified to use the resolution of the currently selected
printer for more accurate print result.
- Version 4.15
(May 3, 2003)
- Bug in printing windowed controls fixed.
- The UsePrinterOptions property added.
- The SetPrinterOptions and GetPrinterOptions methods added.
- Version 4.14
(April 23, 2003)
- Bug in setting the printer's paper orientation to landscape fixed.
- Version
4.13 (April 16, 2003)
- Components' icons changed (Thanks to Paul
Van Gundy).
- Now, two different cursor states for scrolling the page by dragging (Thanks
to Paul Van Gundy).
- Version 4.12
(April 8, 2003)
- Bug in printing pages with custom paper size fixed.
- Version
4.11 (March 31, 2003)
- Bug in rendering images on Windows 2000 and XP fixed (Thanks to Roy
M Klever)
- Version 4.10
(March 29, 2003)
- PaintGraphicEx, PaintWinControlEx, and PaintRichText
methos added.
- Version
4.01 (May 11, 2002)
- A little optimization in SaveToStream and LoadFromStream
methods.
- Version
4.00 (January 19, 2002)
- The control does not support 16bit platform anymore.
- Peformance and stability of the control on both display and print parts
has improved.
- SaveToStream and LoadFromStream method added.
- Memory leak bug fixed.
- Definition of PaintGraphic and PaintWinControl methods changed.
- Because of the applied improvements, the following properties are obsolete:
MarginLeft, MarginTop, MarginRight, MarginBottom,
PageRect, PageWidth, PageHeight, and ZoomOrigion.
- Version 3.20
(January 13, 2002)
- To improve the control functionality and speed, some internal procedures
changed.
- A value larger than 0.7mm limit for margin properties removed.
- Version 3.10
(January 6, 2002)
- New property ZeroOrigion added.
- Version 3.01
(April 26, 2001)
- ZoomSavePos property added to 32bit version of the component
(Thanks to Pavel Zidek).
- Older Versions
(Unknown Date)
- Unfortunately, I have missed tracks of the older versions.
ACKNOWLEDGMENT
Special thanks
to:
LICENSE
The Print Preview
Suite (TPrintPreview, TThumbnailPreview, and TPaperPreview components) is
freeware. You may copy components' files AS LONG AS YOU COPY ALL OF THEM.
If you want to change the source code in order to improve the components'
features, performance, etc. please send me the new source code so that I can
have a look at it. The changed source code should contain descriptions what
you have changed, and of course your name. The only thing you MAY NOT CHANGE
is the ORIGINAL COPYRIGHT INFORMATION.
DISCLAIMER
The Print Preview
Suite (TPrintPreview, TThumbnailPreview, and TPaperPreview components) is
provided "AS IS" without any warranty of any kind, either express
or implied. The entire risk as to the quality and performance of the software
is with you. The author is NOT liable for any DAMAGES resulting from the use
and misuse of the components, especially he is NOT liable for DAMAGES that
were caused BY ANY VERSION WHICH HAS NOT BEEN PROGRAMMED BY THE AUTHOR HIMSELF.