readme.txt

Canvas打印内容

PrintPreview - TPreview. Copyright Richard Vowles, August 1995
([e-mail])

Try my home page on http://comu2.auckland.ac.nz/~root/

This is Version 1.0, released August 23rd, 1995.

Introduction
------------

Delphi doesn't come with a Print Preview component, which is a
bit of a pest as the printer object is expensive (both in time
and in cost of materials) to experiment with, the user can't see
what is going to come out, and the programmer spends hours of
time just figuring out where that line was supposed to go. 

I needed one, ReportSmith is so slow and big that it is useless,
and it would be a very smart report writer that could do what
I needed it to do (which is primarily price lists with all sorts
of extra configurable features). So I wrote a Print Preview
component, and I assure you, it is no easy task! (Well, it was
primarily a task of understanding what is actually going on 
underneath).

Installing It
-------------

Copy all of the files excluding PRT.* into your 'Net components'
directory (considering the number available on the Net, doesn't
everyone have one? <grin>). Then choose Options | Install Components.
Then choose Add, specify the directory (choose Browse if you like),
and when you find the directory, click on PRINTP.PAS. This contains
a form, references another form, and has a picture to represent it.

You should now have a TPreview component on your Samples palette.

The Details
-----------

I started with the premise that the main point of the component
was that if you said Preview=True then it would pop up a form
which would show you what would appear on the printer, which
you could scale as you liked it. If you said Preview=False then
the output would go to the printer (after asking the user what
they actually wanted to print). There was obviously a need to
provide a Canvas, but I needed that Canvas to work in TWIPS (1
inch = 1440 twips), not pixels as they are not device independant.

So there are two things you need to know about: TPREVIEW which
is the component, and TPREVIEWCANVAS which is the Canvas that
you draw with.

TPREVIEW publishes a number of properties to make it work, I'll go
thru each one.

 property DrawMargins : Boolean;

   If you set this to True, then the component will draw a dotted line around
   the canvas. The area outside of this margin is the area that the printer
   you will be printing to WILL NOT DRAW. Eg on HP's, they have an area of around
   240 twips where they won't print, and the printer object starts from where
   it WILL print.

 property OnPaint : TDrawPPEvent;

   This is what you assign a value to to let you draw on the Canvas. Whenever the
   Canvas needs to repaint itself (resizing or on a new page), it calls this routine
   and passes a TPREVIEWCANVAS and a Page Number. From the page number, you have to
   figure out what to print. Remember, the PageCount can be changed at ANY time, and
   for some types of printing, when you go to print the first page, that is the only
   time you will be able to figure out how many pages there will be (as that is when
   you know about the heights of text, so you know how much will fit into a page). I
   have this problem with the price list I mentioned earlier, and I use the fact of
   the first page (and something else) to know I have to go off and figure out what
   will go on each page and how many pages there will be, so at that point I update the
   page count.


 property PreviewMode : Boolean;

   This is where you tell the component whether you want to see it on
   the screen or you want to print it!

 property Left : Longint read GetLeft write SetLeft;
 property Width : Longint read GetWidth write SetWidth;
 property Top : Longint read GetTop write SetTop;
 property Height : Longint read GetHeight write Setheight;

   These allow you to change the location of the print preview form, 
   not the component itself.

 property PageCount : Longint read FPageCount write SetPageCount;

   This tells the component how many pages there are. This affects 
   the ScrollBar when you are previewing, and the numbers in the Print
   Dialog box when you are printing.

The following TPREVIEW methods are of interest:

 function BeginDoc : Boolean;

   You use this to start the print job and set up the parameters for the printer
   or screen. You MUST call this, you can get GPF's if you don't. It returns TRUE
   if the user wants to print. Herein lies a sticky problem. You can't ask the user
   if they want to print AFTER you have done a BeginDoc, as the system pops up with
   an exception stating that you have already started printing. But in some cases,
   you don't know how many pages you want until you have started printing. Of course
   if you have done a print preview already, then that has told you how many pages
   you will need, so it isn't a problem. So, ---REMEMBER--- if you don't know how
   many pages you want to print until you start printing, you must always do a 
   Print Preview BEFORE a print otherwise the info in the Print Dialog box will be
   wrong. If anyone figures out a solution to this, please let me know!

 procedure EndDoc;
  You call this when you have finished the print (or even if you never started!).

 function Print : Boolean; 
  This is where most of the action takes place. If in Preview mode, the preview form
  is created here and shown (which causes a paint event to occur to paint the first
  page).  If not in preview mode (printer mode?) then it pops up a dialog box which
  tells the user what page is printing (which also disables the rest of your application
  by the way) and prints it. If the user selects Cancel, then the job is aborted,
  otherwise it is sent off to the printer for processing.


The TPREVIEWCANVAS is a not fully implemented TCanvas equivalent (I only implemented
those functions that I use, the rest I haven't tested so this may be a place to go if
you are finding difficulty - please let me know if you do have difficulty!).

The following properties are of interest:

 preview                     : Boolean;
   This tells you whether you are in Preview mode or not.
  
 Brush                       : TBrush;
 Pen                         : TPen;
 Font                        : TFont;
   These control the drawing, as a normal canvas. They (except the Font) 
   in fact point to the canvas itself!

 PageNumber                  : Longint;
   This tells you what page number you are on. PageNumber passed with the Event also
   tells you this.

 twipMaxX, twipMaxY          : longint;

   These tell you how much printable area in twips you have available to you. 

The following methods are also of interest:

 function  GetFont : TFont;
 procedure SetFont( font : TFont );
   These two are of interest primarily because when you print your first 
   page, you should use SetFont to copy all details of the font you require
   to the Canvas's font. I use hidden labels on my form, set their fonts to
   what fonts I will use in the printout, and then just SetFont them when
   I want them. Doing a Font := won't work, you must use SetFont.
   Eg
       SetFont( lbDefault.Font ); (* sets to the same font as the label lbDefault *)
   

 procedure Arc( x1, y1, x2, y2, x3, y3, x4, y4 : integer );
 procedure BrushCopy( const dest : TRect; Bitmap : TBitmap;
         const Source : TRect; Color : TColor );
 procedure Chord( x1, y1, x2, y2, x3, y3, x4, y4 : integer );
 procedure FrameRect( rect : TRect );
 procedure Rectangle( x, y, x2, y2 : integer );
 procedure RoundRect( x1, y1, x2, y2, x3, y3 : integer );
 procedure TextOut( x, y : integer; const text : string );
 procedure TextRect( Rect : TRect; X, Y : Longint; const Text : string );
 procedure FloodFill( X,Y : Longint; Color : TColor; FillStyle : TFillStyle );
 procedure StretchDraw( const rect : TRect; Graphic : TGraphic );
 function TextHeight( const text : string ) : Longint;
 function TextWidth( const text : string ) : Longint;
 procedure FillRect( const rect : TRect );
 procedure MoveTo( x, y : longint );
 procedure LineTo( x, y : longint );
   These are all the standard Canvas routines. They are just intercepted, their
   co-ordinates change from twips to pixels, and the original routine called. I have
   been inconsistent in my use of Integer vs Long Integer, i'll fix that in another
   release (an 11.5 inch A4 Height is around 16500 twips, which is OK with an integer,
   but may cause a problem on an A3 printer...)

   See the example program for examples on how to use these.

Using It
--------

Here is a most typical code scenario. I use Preview1 in two different places
on the same form, each with a different report, so I need to assign OnPaint
each time I use it. You won't have to do this if you just use one TPREVIEW,
one form:

     Preview1.OnPaint := Preview1Paint;
     Preview1.PreviewMode := True;
     Preview1.PageCount   := 1;
     Preview1.BeginDoc;
     wantToPrint := Preview1.Print;
     Preview1.EndDoc;

     if wantToPrint then
        begin
        Preview1.PreviewMode := False;
        if Preview1.BeginDoc then
          begin
          Preview1.Print;
          Preview1.EndDoc;
          end;
        end;

The ACTUAL PageCount is set in my Preview1Paint routine, as mentioned above.
The sample application (PRT) also includes very basic info on how to use the
component.

The Essential Bits
------------------

This work is copyrighted by Richard Vowles, [e-mail].
You can use it as you like it, you can publish as part of shareware
collections and so forth. What you cannot do is take it am claim it
as your own and/or sell it as part of a collection of your own work.
Oh, and you must leave this entire text at the top of the unit
declaration. Oh, and any bugs, please send them to me at the above
Internet address.

Now, I was going to make this postcardware, but my wife insisted that
I ask people to send me a donation for using it instead! Ok, so I
would like $US15 (unless you are in NZ, in which case $NZ15 as it
is easier). You can send it in currency (if you trust your postee) or
bank cheque. Consider this shareware.

The address to send to is
Richard Vowles
Micro Utilities Ltd
PO BOX 100 214
North Shore Mail Center
Auckland
New Zealand

If you send your email address along with it, I'll let you know any
time I send an update version. In fact, I'll email one out to you!

Richard