Copyright© Kambiz R. Khojasteh. All rights reserved.
Get future component updates from http://www.delphiarea.com.

DESCRIPTION

TPrintPreview is a descendent of TScrollBox and has properties of both TScrollBox component and TPrinter class. The special 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 created pages while the new pages are in process to create
• 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
• Has a complete set of events

ACKNOWLEDGMENT

Special thanks to:

• Rinaldo Andrea <laser@nuovacs.it>
• Jens Christian Fogtmann <jefo@post2.tele.dk>
• Damian Tarnawsky <tarnawsky@ali.com.au>
• Bill Miller <w2m@netheaven.com>
• Peter Hedlund <peter@peterandlinda.com>
• Pavel Zidek <delphi@kopr.cz>

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.
  
  
• 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 PaintGraphic method for drawing the image, it is recommended to set FastPrint to false because some printers do not support fast print method.
  
  
• Font: TFont
  Specifies the default font of each new page. I do recommend to use TrueType fonts. In addition, I suggest to use Font.Height instead of Fonr.Size, which determines height of the font in the selected measurement unit.
  
  
• 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.
  
  
• PaperType: TPaperType
  Specifies the paper size. 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)
  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.

  
  
• TotalPages: Integer (Read-only)
  Determines the total number of available pages to preview/print.
  
  
• Units: TUnits
  TUnits = (mmPixel, mmLoMetric, mmHiMetric, mmLoEnglish, mmHiEnglish, mmTWIPS)
  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.1 inch
  mmHiEnglish		1 unit = 0.01 inch
  mmTWIPS		1 unit = 1 twip = 1/20 point = 1/1440 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.
  
  
• 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.

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 any of page creating or printing processes.
  
  
• 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.
  
  
• function ConvertUnit(Value: Integer; FromUnit, ToUnit: TUnits): Integer
  Returns the result of the conversion of a value from one measurement unit to another one.
  
  
• Function ToPrinterUnit(Value, resolution: Integer): Integer
  Returns the result of the conversion of a value from pixels in the given resolution to the control's selected measurement unit and the printer resolution.
  
  
• Function Screen2PrinterUnit(Value: Integer): Integer
  Returns the result of the conversion of a value from pixels in the screen resolution to the control's selected measurement unit and the printer resolution.
  
  
• function PaintGraphic(X, Y: Integer; Graphic: TGraphic): TPoint
  Draws an image on the page's canvas at X and Y position in actual size. The function returns the size of the graphic in selected unit.
  
  
• function PaintWinControl(X, Y: Integer; WinControl: TWinControl): TPoint
  Draws the WinControl on the page's canvas at X and Y position in actual size. The function returns the size of the graphic in selected unit.

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.
  
  
• 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 print 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.

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.

HISTORY

• 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 the tracks of the older versions.

LICENSE

TPrintPreview and TPaperPreview components are freeware. You may copy component's 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

TPrintPreview and TPaperPreview components are 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.