    README.TXT
    ==========

    What is SimplePrintout?
    =======================

    This directory contains a very simple printing class.

    SimplePrintout unit provides a very basic printout for your
    quick and dirty Delphi for .NET projects. Many times when
    you sit down to write a tiny software project you feel like
    there is no easy way of printing out relatively small amounts
    of data.

    Of course, .NET makes it easier to print text and pictures. However
    the first time you need to print justified text or bordered text, or
    pages with simple header or footer, you come to realize that you
    still have to revert to counting pixels.

    In many cases using a professional report generating tools
    may be an overkill, but writing your own printing component
    can be a daunting task too.

    That is where SimplePrintout class comes into play.

    SimplePrintout keeps all those details hidden from you. Although
    it is not a full-blown reporting tool, you will be amazed just
    how much you can accomplish with this little unit...

    Installation
    ============

    At the time of this writing SimplePrintout for Delphi for .NET
    has some minor problems with code serialization. I need to clean
    that up to make it into a component. So for now SimplePrintout
    is provided as a Delphi unit, rather than an installable component.
    As a result, it does not require any installation. Simply copy the
    unit called Simp_Prn.PAS to your project directory and add
    "Simp_Prn" to your unit's USES statement.

    Don't forget to check Borland CodeCentral for the latest code
    updates.

    How to use SimplePrintout component?
    ====================================

    The best way to find out about SimplePrintout is to compile and
    run the DemoProj application. This demo application will get
    you started.

    Lesson 1.
    --------
      You may simply create and use an instance of SimplePrintout at
      runtime. It is relatively easy. Start by adding "Simp_Prn" unit
      to your "uses" stament.

        procedure TWinForm.Button1_Click(sender: System.Object;
                                         e: System.EventArgs);
        VAR p: SimplePrintout;
            s: StreamReader;
        begin
          // It's very simple to create
          // a SimplePrintout...
          //
          p := SimplePrintout.Create();

          try
            // Always call BeginPrintout!
            //
            p.BeginPrintout();

            // And finally here is how to print out a text file...
            // This is much simpler than Microsoft .NET sample.
            //
            s := StreamReader.Create('c:\autoexec.bat');
            p.WriteString(s.ReadToEnd());
            s.Close();

            // Use this call to flush the text to the printer
            //
            p.EndPrintout();

            // NOTE: To cancel printout you may use
            //   p.AbortPrintout(); instead of p.EndPrintout();
            //
          except
            on E: Exception do
              MessageBox.Show(E.Message);
          end;
          p.Free; // with .NET you do not really need this one
        end;

    Lesson 2.
    --------
    Let us add some meat to our sample code...

        procedure TWinForm.Button1_Click(sender: System.Object;
                                         e: System.EventArgs);
        VAR p: SimplePrintout;
            s: StreamReader;
        begin
          p := SimplePrintout.Create();

          try
            // Always call BeginPrintout!
            //
            p.BeginPrintout();

            // You may set margins (measured in inches)
            //
            p.TopMargin := 1.5; // leave some room for the header
            p.BottomMargin := 1; // leave some room for the footer

            // It is pretty easy to set footers and headers...
            //
            p.Header.Text := 'you can have'+#13#10+'multi-line HEADERS';
            p.Footer.TextIndentBottom := 0.3;
            p.Footer.Text := 'Footer text';

            // To align your paragraph text to Left,
            // simply set Band.TextAlignment to baLeft
            // (Your choices for alignment are:
            //  baLeft, baRight, baCentered, and baJustified
            //
            p.Band.TextAlignment := BandAlignment.baLeft;

            // This is how you can change fonts.
            // It's pretty striaghtforward.
            //
            p.Band.TextFont := System.Drawing.Font.Create('Arial', 12);

            // And finally here is how to print out a text file...
            // This is much simpler than Microsoft .NET sample.
            //
            s := StreamReader.Create('c:\autoexec.bat');
            p.WriteString(s.ReadToEnd());
            s.Close();

            // Use this call to flush the text to the printer
            //
            p.EndPrintout();

            // NOTE: To cancel printout you may use
            //   p.AbortPrintout(); instead of p.EndPrintout();
            //
          except
            on E: Exception do
              MessageBox.Show(E.Message);
          end;
          p.Free; // with .NET you do not really need this one
        end;

    Lesson 3.
    --------
      How to add Page numbering to the footer (or header). Or rather,
      let us paraphrase this question. How to make headers and footers
      more dynamic?

      All you need is to add an event handler like this:

        procedure TWinForm.on_PrintPage(sender: System.Object;
                                  ua: UserPrintPageEventArgs);
        begin
          (sender as SimplePrintout).Footer.Text :=
            'Page ' + ua.PageNo.ToString;
        end;

        procedure TWinForm.Button1_Click(sender: System.Object;
                                         e: System.EventArgs);
        VAR p: SimplePrintout;
            s: StreamReader;
        begin
          p := SimplePrintout.Create();

          try
            // Always call BeginPrintout!
            //
            p.BeginPrintout();

            // Add our print page handler here
            //
            Include(p.PrintPage, on_PrintPage);

            s := StreamReader.Create('c:\autoexec.bat');
            p.WriteString(s.ReadToEnd());
            s.Close();

            p.EndPrintout();
          except
            on E: Exception do
              MessageBox.Show(E.Message);
          end;
        end;

    Lesson 4.
    --------
      We already know some methods and some properties of the SimplePrintout
      class. But there are other methods and properties you may want to use
      as you go.

         BeginPrintout  - use this call before calling any other methods.

         WriteString    - lets you print one string at the time. The string
                          can be as long as you want it to be. It will be
                          wrapped as necessary. This way you can put your
                          entire document into one string and send it to
                          printer with one command.

         PageBreak      - inserts a page break.

         EndPrintout    - this will flush data to the physical printer.

         AbortPrintout  - this will terminate output without printing
                          to physical device, if called instead of EndPrintout.

         Page setup:
           NonPrintableGutterSize - measured in inches.
                          Most printers do not let you print at
                          the very edge of the page. We set this
                          non-printable gutter size to 3/16" by default
                          The programmer can change this setting.

           TopMargin -    Top margin including the gutter, in inches
           LeftMargin -   Left margin including the gutter, in inches
           RightMargin -  Right margin including the gutter, in inches
           BottomMargin - Bottom margin including the gutter, in inches

           HeaderText -   Static text for the page header, this text
                          can be changed dynamically in an event handler

           FooterText -   Static text for the page footer, this text
                          can be changed dynamically in an event handler

           There are two areas on the page. One is within the page margins
           and another is the page including the margin areas. For the lack
           of a better term, these two areas are called Inner and Outer:

             InnerBorderPixels - measured in pixels
                          Thickness of the border inside the margins, in pixels

             OuterBorderPixels - measured in pixels
                          Thickness of the border outside the margins, but still
                          within the non-printable gutter area.

             InnerBorderColor - Color of the border inside the margins
             OuterBorderColor - Color of the border outside the margins
             InnerBackColor - Background color of the page inside the margins
             OuterBackColor - Background color of the margins

      Header, Footer, Band properties:

       First of all you probably realize that there is a property called
       Footer. Then there is a Header. There is also a property called
       "Band." All of these properties are of type TBand. TBand represents
       a paragraph of text with its own set of parameters.

       Header and Footer are probably easy to understand. The Band property
       simply means current paragraph. You can set up the current paragraph
       font, size, etc., and simply call WriteString(text). The text will
       be printed with current settings. Then you change the Band again,
       call WriteString() and the text will be printed with new paragraph
       settings.

       So as you see there are three paragraphs you work with: Header, Footer,
       and the current paragraph exposed through the Band property.

       A paragraph (or band) has the following properties:

             TextAlignment - current text alignment
                          instructs the simple printout component to switch
                          paragraph alignment. This property can be changed
                          in the middle of printing, it will affect subsequent
                          WriteString() calls.
                          This property can be set to: baRight, baCentered,
                          baJustified, and default: baLeft.

             TextFont   - lets you select and change a font for the body of
                          the paragraph.

          Keep in mind that a paragraph usually consists of a box
          (background) and the text (foreground). Box  and text can
          have their own indents, colors, etc:

             BorderPixelSize - paragraph [box] border pixel size
                          By default this is set to 0, so no box is not
                          printed. But the box is still there. It has
                          a white background color. You can get rid of the
                          box by setting Transparent property to TRUE

             Transparent - we just explained this one

             BorderColor - paragraph [box] border color
             ForeColor   - text color
             BackColor   - paragraph [box] color, background color

             IndentLeft  - paragraph indents, in inches
             IndentTop
             IndentRight
             IndentBottom

             TextIndentLeft - text indents within the paragraph
             TextIndentRight
             TextIndentTop
             TextIndentBottom

    Lesson 5.
    --------
      SimplePrintout also has a couple of Event handlers. Please
      take a look at the DemoProj application to see how they are used.

      PrintPage event is of type UserPrintPageEvent. It is very similar to
      .NET PrintPage event, so that the programmer gets the full control
      before printing each page. Pay attention to the second parameter
      of type UserPrintPageEventArgs. It has these members:

        PageParms: PrintPageEventArgs;
            -- this is the original PrintPageEventArgs, we
               pass it to the user.

        PageNo: Integer;  -- (read only) current page count

        The following five Boolean members are set to FALSE by default.
        However the programmer can set them to TRUE in the event handler
        to indicate specific behaviors:

        PrintoutLastPage: Boolean;
            -- User may set this to TRUE, which means that SimplePrintout
               will print this page and then stop printing.

        BackgroundHandledByUser: Boolean;
            -- If set by user to TRUE it means that SimplePrintout does not
               have to paint the page background, user may have added a
               background picture, for example.

        PageHandledByUser: Boolean;
            -- (set by user) SimplePrintout does not paint the current
               page user handled the page. Note that it still paints the
               header and footer. The next two items let you disable the
               header or the footer, or both.

        HeaderHandledByUser: Boolean; -- indicates that user handled the header
        FooterHandledByUser: Boolean; -- indicates that user handled the header

    ----------------------------------------------------
    Please take a look at the demo project to see the working code. You
    may find it easier to cut and paste the code into your project and
    build it up from there.

    ----------------------------------------------------
    Enjoy!

    Feedback to: alfred@softsci.com
    Ref: SimplePrintout for Delphi for .NET (11/19/03)
    ----------------------------------------------------