updftextwriter.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2007-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}



unit UPDFTextWriter;

{This unit contains the class ~[link TPDFTextWriter] what should be a mostly
 general class to write text to a PDF file with a ~[link TPDFWriter] object.
 But it contains at least some types special to this program, like
 ~[link TSymbol], and uses others, like ~[link TImageLinkList].

 The class handles mostly simple text that can be arranged like in a paragraph,
 it will automatically wrap around when the end of the line has been reached
 and can be aligned to one of the sides or even written in block mode. It is
 also possible to define the indentation of text and to create not to complex
 tables.

 There is also a utility stack of font styles available that is used at
 different positions. And images can be shown in the PDF file.

 The headings of chapters and sections inside the PDF file can also be written,
 their destinations will automatically be saved and can be used to write the
 outline of the PDF file and its table of contents.
}

interface

uses Windows,               //for TPoint
     Classes,               //for THelpContext
     Graphics,
     UImages,
     UDocumentationTexts,
     UPDFWriter;


      //factor from centimeters to points (the PDF internal unit)
const CmToPoint = 28.34;
      //factor from millimeters to points (the PDF internal unit)
      MmToPoint = CmToPoint / 10;


type
  //the different symbols, that can be written in the PDF file
  TSymbol = (
             sPrivate,       //icon indicating a private member
             sProtected,     //icon indicating a protected member
             sPublic,        //icon indicating a public member
             sPublished,     //icon indicating a published member
             sAutomated,     //icon indicating a automated member
             //icon indicating an identifier in the implementation part of a
             //unit or in a file, that is not a unit (i.e. program or library)
             sUnitLocal,
             //icon indicating an identifier in the interface of a unit
             sUnitInterface,
             sReadOnly,      //icon indicating a read-only property
             sAbstract,      //icon indicating an abstract method
             sDeprecated,    //icon indicating a deprecated identifier
             sLibrary,       //icon indicating a library-specific identifier
             sPlatform,      //icon indicating a platform-specific identifier
             sBullet);       //a bullet for a list


             


  //the settings describing the format of a text
  TFontSetting = record
    //the font of the text
    Font: TPdfFontType;
    //the style of the text
    Style: TPdfFontStyles;
    //the size of the font
    Size: TPDFValue;
    //the color of the text
    Color: TColor;
  end;

  //a list of settings describing the formats of a text
  TFontSettings = array of TFontSetting;




  //an array of characters, f.i. the buffer of the characters to be written
  TCharacterArray = array of Char;


  //the alignment of the text in a paragraph, or a column in a table
  TTextAlignment = (
                    taLeft,    //align the text to the left
                    //write the text in block mode, fill each line but the last
                    //up to the right margin
                    taBlock,
                    taRight,   //align the text to the right
                    taCenter); //center the text in the middle of the text area

  //the alignment of the text lines in a cell of a table
  TVerticalAlignment = (
                        //align the text lines to the top of the cell
                        vaTop,
                        //align the text lines to the bottom of the cell
                        vaBottom,
                        //center the text lines in the middle of the cell
                        vaMiddle,
                        //increase the distance between the text lines in order
                        //to fill the whole cell with the text
                        vaFill);

  //The definition of a column in a table to be written to the PDF file.
  TTableCellDefinition = record
                           //position of left side of the cell;
                           //right side goes up to the next cell or for the
                           //last cell to the right margin of the page
                           CellStart: TPDFValue;
                           //alignment of the text inside the column
                           Alignment: TTextAlignment;
                           //vertical alignment of the text lines inside the
                           //cells of the column
                           VerticalAlignment: TVerticalAlignment;

                           //padding of the content to the left side of the
                           //cell
                           LeftPadding: TPDFValue;
                           //padding of the content to the right side of the
                           //cell
                           RightPadding: TPDFValue;

{
                           //nice again would be some kind of border, but
                           //should be a call back, to allow creating
                           //horizontal and vertical borders

                           //vertical space between table cells should also
                           //be defined somehow

  TTableCellBorderCallBack = procedure (const Table: TTableDefinition;
                                        BorderIndex: Integer;
                                        YStartFrom, YEndTo: TPDFValue;
                                        RightX: TPDFValue;
                                        Break: (cbbOnePage,
                                                cbbFirstPage,
                                                cbbMiddlePage,
                                                cbbEndPage)) of object;
                           BorderCallBack: TTableCellBorderCallBack;
}
                         end;
  //The definitions of the columns of a table to be written to the PDF file.
  TTableDefinition = array of TTableCellDefinition;




  //the kind of the characters/tokens in the paragraph, and how they can be
  //broken
  TCharacterBreakable = (
                         cbNormal,     //is any normal character/letter
                         cbCapital,    //is a normal capital letter
                         cbNoLetter,   //any normal character, but not a letter
                         cbSpace,      //is a simple space
                         cbSymbol,     //is a special symbol
                         cbImage);     //is an image

  //the kinds of all the characters/tokens in the paragraph, and how they can
  //be broken
  TCharacterBreakables = array of TCharacterBreakable;

  //the kinds of all the characters/tokens in the paragraph, and how they can
  //be broken
  PCharacterBreakable = ^TCharacterBreakable;

  //an attribute of the different tokens in the paragraph
  TParagraphAttribute = record
                          //the first character having the attribute
                          StartIndex: Integer;
                          //what kind of token it is
                          Attribute: (
                                      //show text with the selected font
                                      aFont,
                                      //a symbol
                                      aSymbol,
                                      //an image
                                      aImage,
                                      //beginning of a new cell in a table
                                      aTableCell);

                          //for ~[link Attribute] = aFont: the font to be used
                          Font: TFontSetting;

                          //for ~[link Attribute] = aSymbol: the symbol
                          Symbol: TSymbol;

                          //for ~[link Attribute] = aImage: the name of the
                          //already with the PDF writer registered image
                          ImageName: String;
                          //for ~[link Attribute] = aImage: the list of links
                          //inside the image; only a reference, will not be
                          //freed and has to be kept alive until the
                          //paragraph/the row of the table is written;
                          //this type is actually specialized and has to be
                          //interpreted by the call back procedure
                          ImageLinks: TImageLinkList;
                        end;

  //attributes of the different tokens in the paragraph
  TParagraphAttributes = array of TParagraphAttribute;


  //definition of links on text in a paragraph
  TParagraphLink = record
                     //the first character of the link
                     StartIndex: Integer;
                     //the last character of the link, -1 means not ended yet
                     EndIndex: Integer;
                     //the kind of the link
                     LinkType: TLinkType;
                     //the target of the link
                     Target: String;
                   end;

  //the list of links on text in the paragraphs
  TParagraphLinks = array of TParagraphLink;




  {Call back procedure to add the links inside images.
  ~param ImageName     the name of the already with the PDF writer registered
                       image
  ~param ImageLinks    the list of links inside the image;
                       this type is actually specialized and has to be
                       interpreted by the call back procedure
  ~param Width, Height the size of the image as shown in the PDF file
  ~param X, Y          the position on the current page where the image is
                       shown }
  TImageLinksCallBack = procedure (const ImageName: String;
                                   ImageLinks: TImageLinkList;
                                   Width, Height, X, Y: TPDFValue) of object;





   { * * *  ***  * * *  ***   TPDFTextColumn   ***  * * *  ***  * * *  }


  //result of the test where text has to be wrapped around and a new line has
  //to be started
  TWrapReturn = record
                  //the last character to be written in the current line
                  EndPoint: Integer;
                  //whether a hyphen should be added at the end of the line
                  AddHyphen: Boolean;
                  //first character of the next line, might be different from
                  //~[code ~[link EndPoint] + 1] if white spaces at the end
                  //of the line are skipped
                  ResumePoint: Integer;
                end;


  //the manager of a paragraph or a row of a table to be written
  TPDFTextWriterManager = class;


  {Manages and shows some text of a paragraph or a table cell in the PDF file.
   For paragraphs it is the whole text of the paragraph, for tables the text of
   each cell is manages by an own object. The overall writing and if necessary
   changing of pages in the text is managed by an object of class
   ~[link TPDFTextWriterManager], which owns one or more objects of this class.

   This is an internal type, it does not have to be used outside of this unit.

   Objects of this class are created and used ~[em very] often during the
   creation of a PDF file, so it is optimized where possible. This includes for
   instance to specify objects, arrays and other values as parameters which are
   already available to the functions through longer (less efficient) access
   paths.

   Link check: this should be two different links:
   ~[link FManager]~[link FLeftPosition] }
  TPDFTextColumn = class
  private
    //the manager of the whole text, mostly used to access the writer objects,
    //~[link FManager.TextWriter] and ~[link FManager.Writer]
    FManager: TPDFTextWriterManager;

    //the horizontally left starting position to show the text at
    FLeftPosition: TPDFValue;
    //the (maximum) width on the page to be occupied by the text
    FColumnWidth: TPDFValue;

    //the horizontal alignment of the text
    FAlignment: TTextAlignment;
    //the vertical alignment of the text, only used for text within cells of
    //tables
    FVerticalAlignment: TVerticalAlignment;
    //the characters of the text to be shown
    FCharacters: TCharacterArray;
    //the attributes of the text or parts of it
    FAttributes: TParagraphAttributes;
    //the links inside the text
    FLinks: TParagraphLinks;
    //whether currently text is shown that is a link
    FInLink: Boolean;