Delphi Component TSKUPrintPlainText
Version 2.0, October 11, 1999
Print/preview text & text files with word or line wrap
Copyright (C) 1999, Sanjay kanade
All rights reserved.
Email: skanade@superb.net
http://skanade.simplenet.com/delphistuff/

SPECIAL NOTE ON PRINT PREVIEW CODE:
Copyright (C) 1997-1999, Ben Ziegler
The print preview related code is adapted from Ben Ziegler's
print preview (pprev) component. Hence, the copyright for 
those sources is still owned by Ben Zielger:
  http://www.radix.net/~bziegler/Delphi/Index.html

IMPORTANT: Before you proceed, please read the LICENSE AGREEMENT and
the DISCLAIMER OF WARRANTY at the end of this file. If you do not
agree to the terms and conditions mentioned there in, please do not
use this software and destroy all the accompanying files from your
disk.
  
HISTORY:
--------
Version 2.0 -- October 11, 1999
- Adapted Ben Ziegler's Print Preview (pprev) code for adding
  the print preview functionality
Version 1.1 -- September 15, 1999
- Tested with Delphi 4.
- If the spooler was used, the title was not appearing for the print
  job. Fixed.
Version 1.0 -- March 16, 1999 (initial version)
  
  
INTRODUCTION:
-------------

TSKUPrintPlainText is a Delphi printing component which gives you
text and text wrapping features with line wrap or word wrap. The Demo 
EXEs are included. Just drop this component on a form, and set some 
options such as, print title, header/footer text, wrap mode, font etc. 
Then, start sending text lines or files to it. It is especially useful 
for compact programs which want to avoid the overhead of report tools,
just for printing text and text files. This version 2.0 adds the
print preview functionality which is specially adapted from Ben
Ziegler's code as mentioned at the top.


HOW TO INSTALL:
---------------
This evaluation version of the component only provides a runtime
package for Delphi 3 and Delphi 4. Hence, you will be able to
evaluate it using the given demo projects or in your own projects,
but only with the runtime package option. If you purchase the licensed
version, you get the full sources, and the installation is more
flexible so that you can statically link the component in your EXE.

DELPHI3 INSTALLATION:
1) Just click on the Delphi menu, Component--Install Packages.
2) Click on "Add" button and install the file 'Delphi3\printPlainText.dpl.' 
3) You will see a new tab created on your Component palette,
SKanade's Components. You will see the TSKUPrintPlainText component
there.
4) Compile the demo project: Delphi3\demoprog.dpr
5) Run it and see how it works. 
Note that this is an evaluation version of the component and it will add 
an 'Unlicensed' message at the top of each page. Unlicensed message will also 
appear in the preview form and on page progress dialog. In the licensed 
version, this message is removed.

See the next section for usage details on the component.

DELPHI4 INSTALLATION:
1) Just click on the Delphi menu, Component--Install Packages.
2) Click on "Add" button and install the file 'Delphi3\printPlainText.bpl.' 
3) You will see a new tab created on your Component palette,
SKanade's Components. You will see the TSKUPrintPlainText component
there.
4) Compile the demo project: Delphi4\demoprog.dpr
5) Run it and see how it works. 
Note that this is an evaluation version of the component and it will add 
an 'Unlicensed' message at the top of each page. Unlicensed message will also 
appear in the preview form and on page progress dialog. In the licensed 
version, this message is removed.

See the next section for usage details on the component.


HOW TO USE:
-----------
Please see the demo for actual code usage examples.

TSKUPrintPlainText is a non-visual component. Just drop it on a form
and you can start using it. You can set the properties such as
wrapMode, margins, title, header, and footer at design time or run
time. For printing text to it, you first openPrinter, then use
printALine and printAFile methods to send text to it. Finally, you
closePrinter and you are done. It automatically shows a progress
dialog. To signal end of printing, in case of the user initiated
cancel or end of a range of pages, it uses exceptions so that you
don't have to check for these conditions at each stage of printing.
Hence, it is advisable to use the following nested exception blocks
where printText is the name of a TSKUPrintPlainText component on your
form.

  try //outer block
    try //inner block
      printText.openPrinter;
      ...one or more print commands of the following types
      printText.printAFile...
      printText.skiplines...
      printText.printALine...
      ...
    except
      on E:exception do
      begin
        if printText.hadErrors then
          showMessage(E.Message);
      end;
    end; //inner block
  finally
    printText.closePrinter;
  end; //outer block
  
In the above, you just go on using the print methods. If an error
occurs, you get an exception and the property 'hadErrors' is turned
on. If the user cancels printing, you can an exception where the
property 'printCancelled' is turned on. If the user specifies a range
of pages to print and the end page has been printed then also an
exception occurs where neither of the above properties is on. This
way, you can deal with these situations in the except block if you
want to. Normally, only checking for hadErrors and showing the
message is enough. Finally, you must remember to close the printer as
shown.

Print preview example:
To do a preview, you just have to make these changes:
1) Before openPrinter, put the isPreview property to TRUE. Since you
would most probably be using the same handler, it would be better to
check the sender and set it as in the Demo example. 
     printText.isPreview := sender=btPreview;
     
CAUTION: Don't use a code like this:

     if sender = btPreview then
       printText.isPreview := true;

Why? The isPreview flag will permanently remain on and will never be
put off so your non-preview printing won't work. Try the above code
in the Demo and you will understand what I mean here. It is important
to set the isPreview to false when preview is not required.            
     
2) After closePrinter, put this code:
   if (not printtext.hadErrors) and (not printtext.printCancelled)
   then
     printText.showPreview;
     
In fact, you can use the same code and use a condition like:
  (Sender=btPreview) 
to check whether the print was called from a preview button or menu.
For a real example, please see the demo application. One final note,
the preview works on the basis of current printer. So, you could
either let the user select a printer just before the preview like
the normal printing (demo uses that approach). Or, you may give
another menu option in your application to set up the current 
printer and don't give a printer selection before preview.       
  
Properties: (in alphabetical order)
-----------
  property BarGapInches: single
    This is the gap which appears between the header or footer bar
    and the text of the page. Default is 0.1 inch.
    
  property Footer: string  
    Set the footer which appears on the left side of the page footer.
    If it is bigger than a predetermined size, it is truncated.

  property Font: TFont
    Whatever font you set is used for the entire page including the
    headers and footers. Default is Courier, size 8. You can change
    the font only when not printing. 

  property HadErrors: boolean  
    This property is true if there were errors encountered.

  property HeaderRight: string
    Set the right-side of the header. An example is date/time as in
    the demo. If it is bigger than a predetermined size, it is
    truncated.

  property IsPreview: boolean
    Set it before you openPrinter. Then, after closePrinter, you can
    call showPreview, provided there were no errors (hadErrors) and
    the user didn't cancel the printing (printCancelled).

  property MarginInches: single
    Set the margin in inches. This margin is used on all four sides.
    The default is 0.25 inch.
    
  property PagePrefix: string
    Page number automatically appears on the right side of the page
    footer. Default prefix is 'Page' which you can change.

  property PrintCancelled: boolean
    This property is true if the user cancelled the printing.
    
  property StartPage, EndPage: Integer
    Just transfer the values from your print dialog as in Demo and
    it will take care of printing the proper page range for you.
    
  property Title: string
    Set a title for your printout which appears in the center of the
    page header. If it is bigger than a predetermined size, it is
    truncated.
    
  property WrapMode: TSKUPptWrapMode
    You can set it to three values: pptNoWrap, pptLineWrap, pptWordWrap.
    In line wrap, a wrap simply occurs on the right margin. In Word Wrap,
    care is taken not to split a word on two lines.
    
Methods:
-------

  procedure openPrinter;
    Use it when you want to send text to the printer.
    
  procedure closePrinter;
    Remember to finally close it.
  
  procedure printAFile(aTxtFile: TFileName);
    Print the given file.
    
  procedure printALine(instr: string);
    Print a line, line or word wrapping as necessary.
    
  procedure skipLines(lines: integer);
    Skip a number of lines.
    
  procedure showPreview;
    Set isPreview before you openPrinter. Then, after closePrinter, you 
    can this method showPreview, provided there were no errors (hadErrors) 
    and the user didn't cancel the printing (printCancelled).
  
TIPS:    
----

Tab characters: This component handles tab characters in a default
manner. If you have some tabular data, such as reports, it is best
not to use tabs and use a fixed font such as Courier. In that case,
if you allow the user to change the font, make sure that only fixed 
fonts are selectable.


HOW TO PURCHASE:
----------------
Note that this is an evaluation version of the component and it will add 
an 'Unlicensed' message at the top of each page. Unlicensed message will also 
appear in the preview form and on page progress dialog. In the licensed 
version, this message is removed.

A registration fee of US$15 gives you the complete source files for this
component so that you can statically link the component in your EXE file. 
You also get bonus sample code and other components. Just visit the following 
web site to see what all you get:

  http://skanade.simplenet.com/delphistuff/

For details on how to order, please see the ordering section of the above web 
site.

Sanjay Kanade
Email: skanade@superb.net
http://skanade.simplenet.com/delphistuff/


  
            LIMITED LICENSE FOR SOFTWARE EVALUATION

Please note that this is copyrighted software. You may not
sublicense, rent, lease, or sell this software. However, you are
permitted to freely distribute it to other programmers, provided
you transfer the evaluation version only in its original packaged
form with the original sources and the documentation.

As a NON-REGISTERED user of this software, you are granted a limited
license to use this copy for the express purpose of determining
whether this software is suitable for your needs. At the end of a 
30-day trial period you should either purchase the licensed product, 
or discontinue using the software. 


                     DISCLAIMER OF WARRANTY

THIS SOFTWARE (including instructions for its use) IS PROVIDED "AS IS"
WITHOUT WARRANTY OF ANY KIND. THE AUTHOR DISCLAIMS ALL WARRANTIES
RELATING TO THIS SOFTWARE, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT
NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND
SPECIFICALLY DISCLAIMED.  THE ENTIRE RISK ARISING OUT OF THE USE OR
PERFORMANCE OF THE SOFTWARE AND DOCUMENTATION REMAINS WITH YOU.

IN NO EVENT SHALL THE AUTHOR, OR ANYONE ELSE INVOLVED IN THE CREATION,
PRODUCTION, OR DELIVERY OF THE SOFTWARE BE LIABLE FOR ANY DAMAGES
WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF
BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION,
OR OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE
THE SOFTWARE OR DOCUMENTATION, EVEN IF THE AUTHOR HAS BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT SHALL THE AUTHOR'S
LIABILITY FOR ANY DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE
TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF CLAIM.

Some states do not allow the exclusion of the limit of liability for
consequential or incidental damages, so the above limitation may not
apply to you.

This agreement shall be governed by the laws of the State of
California and shall inure to the benefit of the AUTHOR and any
successors, administrators, heirs and assigns. Any action or
proceeding brought by either party against the other arising out of or
related to this agreement shall be brought only in a STATE or FEDERAL
COURT of competent jurisdiction located in Santa Clara County,
California. The parties hereby consent to in personam jurisdiction of
said courts.  