updftextwriter.pas

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

    //the (maximum) font size of the text in this object
    FFontSize: TPDFValue;
    //the text will automatically be wrapped if it does not fit in the
    //available width, the information about each line is saved in this field,
    //the number of lines and therefore valid entries in this field are in
    //~[link FLineCount]
    FLineInfo: array of TWrapReturn;
    //the number of needed lines to show the whole text in the available width;
    //if the text does not fit in one line, it is automatically wrapped
    FLineCount: Integer;



    //summed up widths of the characters in the paragraph
    FSumCharWidths :TPDFValueArray;
    //the index of the next attribute inside the text that has to be applied
    FAttrIndex: Integer;
    //the index of the current or next link inside the text
    FLinkIndex: Integer;
    //the font being currently used to show the text
    FCurrentParagraphFont: TFontSetting;

    //current vertical position on the page to show the next text at
    FYPos: TPDFValue;
    //current horizontal position on the page to show the next text at
    FXPos: TPDFValue;
    //the horizontal position on the page where the current link has been
    //started on the current line
    FStartLink: TPDFValue;


    //Adjusts the indices of characters for the attributes and links if only
    //part of the text is written with this object.
    procedure AdjustAttributeIndices(By: Integer);

    //Calculates meta data about the text after the object has been created and
    //the text saved.
    procedure CalculateTextMetaData(const CharWidths: TPDFValueArray;
                                    const Breakable: TCharacterBreakables;
                                    FirstIndex: Integer);
    //Calculates the summed up widths of the characters in the paragraph.
    procedure CalculateSumCharWidths(CharWidths: PPDFValue;
                                     const SumCharWidths :TPDFValueArray);
    //Calculates the (maximum) font size used for the text.
    procedure CalculateFontSize(Attributes: TParagraphAttributes);
    //Calculates the number of lines necessary to show the text in the
    //available width and where to break it.
    procedure CalculateLines(Breakables: PCharacterBreakable);

    //Returns the number of spaces in the specified range of the paragraph.
    function GetSpaceCount(FromIndex, ToIndex: Integer): Integer;
    //Handles the link on the just shown text between the current position and
    //the position in ~[link FStartLink].
    procedure HandleLink(LinkType: TLinkType; const Target: String;
                         Writer: TPDFWriter);
    //Handles the next attribute of the text.
    function HandleAttribute(const Attr: TParagraphAttribute;
                             Writer: TPDFWriter): Boolean;

    //Writes one line of the paragraph.
    procedure WriteTextLine(RangeStart, RangeEnd: Integer;
                            WordSpacing: TPDFValue; Writer: TPDFWriter);


  public
    //Creates the object to represent a cell of a table without content.
    constructor CreateEmptyColumn(Owner: TPDFTextWriterManager;
                                  Writer: TPDFWriter;
                                  Left, Right: TPDFValue);
    //Creates the object to represent the text of a cell of a table.
    constructor CreateColumn(Owner: TPDFTextWriterManager; Writer: TPDFWriter;
                             Left, Right: TPDFValue; Alignment: TTextAlignment;
                             VerticalAlignment: TVerticalAlignment;
                             FirstCharacter, LastCharacter: Integer;
                             const Characters: TCharacterArray;
                             const CharWidths: TPDFValueArray;
                             const Breakable: TCharacterBreakables;
                             const Attributes: TParagraphAttributes;
                             FirstAttr, LastAttr: Integer;
                             const Links: TParagraphLinks;
                             FirstLink, LastLink: Integer);
    //Creates the object to represent the text of a paragraph.
    constructor CreateTheText(Owner: TPDFTextWriterManager; Writer: TPDFWriter;
                              Left, Right: TPDFValue;
                              Alignment: TTextAlignment;
                              CharacterCount: Integer;
                              const Characters: TCharacterArray;
                              const CharWidths: TPDFValueArray;
                              const Breakable: TCharacterBreakables;
                              const Attributes: TParagraphAttributes;
                              AttrCount: Integer;
                              const Links: TParagraphLinks;
                              LinkCount: Integer;
                              InLink: Boolean);
    //Frees the object and unregisters it from its manager.
    destructor Destroy; override;


    //Writes a number of lines of the text into the PDF file.
    procedure WriteLines(YPos: TPDFValue; Writer: TPDFWriter; Single: Boolean;
                         LineFrom, LineWriteCount: Integer;
                         ForceSetFont: Boolean);


    property LeftPosition: TPDFValue read FLeftPosition;
    property FontSize: TPDFValue read FFontSize;
    property LineCount: Integer read FLineCount;
    property CurrentParagraphFont: TFontSetting read FCurrentParagraphFont;
  end;




   { * * *  ***  * * *  ***   TPDFTextWriterManager   ***  * * *  ***  * * *  }

  //A mostly general class to write text to a PDF file with a
  //~[link TPDFWriter] object.
  TPDFTextWriter = class;


  {Manages the text of a paragraph or of the cells of a row of a table. The
   text itself is saved and shown by objects of class ~[link TPDFTextColumn],
   for normal paragraphs only one object is used with all the text, for table
   rows, an object is used for each cell with its corresponding text. This
   class mainly holds those objects, it also handles the starting of new pages
   if the text does not fit on the current one and also manages the writing of
   cells of a table.

   This class is needed because text can be written recursively, meaning, that
   during the writing of some text a new page may need to be started, the new
   page will then need page markings to be written (the current chapter, number
   of the page and so on). So all (global) information needed to write the text
   has to be copied before starting to actually write it.

   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. }
  TPDFTextWriterManager = class
  private
    //the text writer object which created this object to write some text into
    //a PDF file
    FTextWriter: TPDFTextWriter;
    //the writer of the PDF file;
    //same as ~[link FTextWriter.Writer], just an optimization as it might be
    //accessed very often
    FWriter: TPDFWriter;

    //the definition of the current table;
    //empty if a simple paragraph is written
    FTable: TTableDefinition;
    //the objects for the texts of each cell in the table or just one object
    //for the whole text if no table is defined
    FColumns: array of TPDFTextColumn;
    //the index of the next column that has to be added
    FColumnIndex: Integer;

  public
    //Creates the manager for the text of a paragraph.
    constructor Create(TextWriter: TPDFTextWriter);
    //Creates the manager for the text of the cells of a row of the table.
    constructor CreateTable(TextWriter: TPDFTextWriter;
                            const Table: TTableDefinition);
    //Frees the manager and all its managed texts.
    destructor Destroy; override;


    //Adds a text object to this manager, will be dones automatically by the
    //text object
    procedure AddTextObject(TextObject: TPDFTextColumn);
    //Unregisters a text object from this manager, will be dones automatically
    //by the text object
    procedure TextObjectFreed(TextObject: TPDFTextColumn);

    //Writes the added text.
    function WriteTheText: TPDFValue;


    property TextWriter: TPDFTextWriter read FTextWriter;
    property Writer: TPDFWriter read FWriter;
  end;












   { * * *  ***  * * *  ***   TPDFTextWriter   ***  * * *  ***  * * *  }


  //level of detail in the table of contents, i.e. sub-topics on what level
  //will be listed in it
  TTableOfContentsDetailLevel = 1..4;

  //the color of links inside the generated file
  TLinkColors = array[TLinkType] of TColor;

  //pointer on an entry (sub tree) of an outline
  POutlineEntry = ^TOutlineEntry;
  {Contains all values of an entry in an outline of the document structure and
   the table of contents. }
  TOutlineEntry = record
    Dest: String;          //internal link destination of the entry
    Title: String;         //title of the entry (chapter, section etc.)

    Next: POutlineEntry;   //the next outline entry on the same level

    Count: Integer;        //number of outline entries below this entry
    First: POutlineEntry;  //list of sub entries in the outline

    Page: Integer;         //the page of the entry
  end;







  {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]. It 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
   simple 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. }
  TPDFTextWriter = class
  private
    //The writer of the PDF file to write the paragraphs to.
    //This is just a reference, not owned!
    FWriter: TPDFWriter;

    //event used when an image is drawn inside a paragraph to add its links
    FOnImageLinks: TImageLinksCallBack;


    //The width of the pages in the file in PDF units.
    FPageWidth: TPDFValue;
    //The height of the pages in the file in PDF units.
    FPageHeight: TPDFValue;

    //The left margin of the pages in the file in PDF units.
    FLeftMargin: TPDFValue;
    //The right margin of the pages in the file in PDF units.
    FRightMargin: TPDFValue;
    //The margin at the top of pages in the file in PDF units.
    FTopMargin: TPDFValue;
    //The margin at the bottom of pages in the file in PDF units.
    FBottomMargin: TPDFValue;


    {the normal size of text in the document; default: 10 (point)
    ~see FDefaultFontType
    ~see FLineDistanceScale }
    FNormalFontSize: TPDFValue;
    {the vertical distance between two lines of text in the document;
     default: 1 1/6, i.e. there is an extra vertical space of a sixth of a line
     between two lines
    ~see FNormalFontSize }
    FLineDistanceScale: TPDFValue;
    {the default font type to use for text in the document;
     for the header and footer another font can be defined with
     ~[link FPageFontType]; default: pftTimes
    ~see FNormalFontSize }
    FDefaultFontType: TPDFFontType;



    {the font type to use to write the header and footer of the pages
    ~see FPageFontSize
    ~see FPageFontStyle }
    FPageFontType: TPDFFontType;
    {the font style to use to write the header and footer of the pages
    ~see FPageFontType
    ~see FPageFontSize }
    FPageFontStyle: TPDFFontStyles;
    {the size of the text to write the header and footer of the pages
    ~see FPageFontType
    ~see FPageFontStyle }
    FPageFontSize: TPDFValue;


    //the color of links inside the generated file;
    //inside file default: clGreen, external URIs (in the WWW) default: clBlue,
    //links to additional files; default: clNavy
    FLinkColors: TLinkColors;


    //whether additional Named Destinations should be generated for the help
    //contexts
    FGenerateHelpContextDestinations: Boolean;

{
    //whether the first line of every paragraph should be indented
    FIndentFirstLineOfParagraph: Boolean;
    //by how much the first line of every paragraph should be indented
    FParagraphFirstLineIndentation: TPDFValue;
                                                                  
    add another flag, whether this is _currently_ enabled?
    also check whether FIndentFirstLineOfParagraph is less then current
      available width / 4
}