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

Copyright (C) 2003-2008   Gerold Veith
Originally based upon Takeshi Kanno's PowerPdf:
Copyright (c) 1999-2001 Takezou. <takeshi_kanno@est.hi-ho.ne.jp>

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 UPDFWriter;

{Contains the base types to write a PDF file. It's not very general, but all
 that is needed to generate a PDF file with the documentation of pascal
 files. ~[link TPDFWriter] is the class needed to write PDF files,
 ~[link TType1Font] describes PDF type 1 fonts, only these fonts are supported,
 because only these fonts are guaranteed to be available in PDF viewers.~[br]

 PDF means ~[em Portable Document Format]; it is an open format
 copyrighted by ~[linkExtern http://www.adobe.com/ Adobe]. Read more
 ~[linkExtern http://www.adobe.com/products/acrobat/adobepdf.html about this
 format] on their website. PDF files can be viewed on several
 platforms with different viewers. The best known is of course Adobe's
 ~[linkExtern http://www.adobe.com/products/acrobat/readermain.html Acrobat
 Reader]. The used version of PDF is 1.2 (current: 1.5), that is quite
 old and it can be read with Acrobat Reader Version 1.3 (current: 1.6)
 (at least it should).
}

interface

uses Windows, Classes,
{$IFNDEF LINUX}
     Graphics
{$ELSE}
     QGraphics
{$ENDIF}
     ;


      //the string used to indicate the end of a line in the PDF file;
      //beware when changing this, that only #10 or #13#10 is allowed or we
      //get problems after "stream"
const NewLine: String = #10;


type
  //the different fonts available
  TPDFFontType = (
                  pftCourier,   //a Courier/Courier New font (fixed width)
                  pftHelvetica, //Arial/Helv(etica) font
                  pftTimes);    //Times/Times New Roman font

  //the available font styles
  TPDFFontStyle = (
                   pfsBold,     //bold font
                   pfsItalic);  //italy font
  //a set of font styles
  TPDFFontStyles = set of TPDFFontStyle;


  //sets the rendering mode of the text
  TPDFTextRenderingMode = (
                           ptrmFill,               //fill the text
                           ptrmStroke,             //stroke the text
                           ptrmFillStroke,         //fill and stroke the text
                           ptrmInvisible,          //invisible text
                           ptrmFillClipping,       //fill and add for clipping
                           ptrmStrokeClipping,     //stroke, add for clipping
                           ptrmFillStrokeClipping, //fill, stroke, clipping
                           ptrmClipping);          //just add for clipping

  //determines how the document should appear when opened
  TPDFPageMode = (
                  pmUseNone,     //show nothing?
                  pmUseOutlines, //show the outline
                  pmUseThumbs,   //show the thumbs
                  pmFullScreen); //show in full screen
  //determines how the document should appear when opened
  TPDFPageModes = set of TPDFPageMode;

const
  //the names to write in the PDF file to indicate how the document should
  //appear when opened
  PDFPageModeNames: array[TPDFPageMode] of string = (
                          'UseNone', 'UseOutlines', 'UseThumbs', 'FullScreen');


  //the character specifying the bullet symbol
  SymbolBullet = 'A';



type
  TPDFColor = TColor;            //a PDF color


  TPDFObjectNumber = Integer;    //a number of an object in the PDF file

  //a PDF number value, for instance to express a position or a length
  TPDFValue = Single;
  //pointer on one or more PDF number values
  PPDFValue = ^TPDFValue;

  TPDFPoint = record              //a point inside a page of a PDF document
    x: TPDFValue;                   //vertical position in the page
    y: TPDFValue;                   //horizontal position in the page
  end;

  TPDFRect = record              //a rect inside a page of a PDF document
    Left: TPDFValue;               //left side of the rect in the page
    Top: TPDFValue;                //top side of the rect in the page
    Right: TPDFValue;              //right side of the rect in the page
    Bottom: TPDFValue;             //bottom side of the rect in the page
  end;

  //a dynamic array of values inside a PDF file
  TPDFValueArray = array of TPDFValue;



  //kind of links of annotations/actions
  TLinkType = (
               ltThisDoc,  //link to a destination inside the same PDF document
               ltURI,      //a link to a general URI (in the WWW)
               ltFile);    //a link to a file









   { * * *  ***  * * *  ***   TType1Font   ***  * * *  ***  * * *  }



  //the widths of all printable characters in a font
  TCharWidths = array[#32..#255] of SmallInt;


  {A class whose objects describe different type 1 fonts. Type 1 fonts are the
   standard fonts, and only a few fonts of this type are guaranteed to be
   available in all viewers. }
  TType1Font = class
  private
    FWidths: TCharWidths;   //width of the characters in the font
    FDefaultWidth: Integer; //default width of characters
    //maximum ascent of characters of the font from the base line
    FAscent: Integer;
    //maximum descent of characters of the font from the base line
    FDescent: Integer;
  public
    //Creates the font object and sets its values.
    constructor Create(const Widths: TCharWidths; DefaultWidth: Integer;
                       Ascent, Descent: Integer);


    //Returns the width of the text in this font.
    function TextWidth(const Text: String): TPDFValue;
    //Returns the total width of the characters in this font.
    function TextWidthCharacters(Characters: PChar; Count: Integer): TPDFValue;

    //Returns the number of fitting characters of the text in the given length
    //in this font.
    function FittingText(const Text: String; AWidth: TPDFValue): Integer;

    //Gets the widths of the specified characters.
    procedure GetCharacterWidths(const Text: String;
                                 var Widths: array of TPDFValue;
                                 StartIndex: Integer);

    property Widths: TCharWidths read FWidths;
    property DefaultWidth: Integer read FDefaultWidth;
    property Ascent: Integer read FAscent;
    property Descent: Integer read FDescent;
  end;











   { * * *  ***  * * *  ***   TPDFWriter   ***  * * *  ***  * * *  }


  {This class can be used to generate a simple PDF file. Only the three default
   fonts with the two styles are supported. An outline can be generated.
   Compression is also supported. A name tree for named destinations is used
   for heavy linked files.

   PDF means ~[em Portable Document Format]; it is an open format
   copyrighted by ~[linkExtern http://www.adobe.com/ Adobe]. Read more
   ~[linkExtern http://www.adobe.com/products/acrobat/adobepdf.html about this
   format] on their website. PDF files can be viewed on several
   platforms with different viewers. The best known is of course Adobe's
   ~[linkExtern http://www.adobe.com/products/acrobat/readermain.html Acrobat
   Reader]. The used version of PDF is 1.2 (current: 1.5), that is quite
   old and it can be read with Acrobat Reader Version 1.3 (current: 1.6)
   (at least it should). }
  TPDFWriter = class
  private
    //the stream to write the PDF file to
    FStream: TStream;

    //if compression of the content of the pages should be enabled
    FCompression: Boolean;


    //the width of the pages in the file
    FPageWidth: TPDFValue;
    //the height of the pages in the file
    FPageHeight: TPDFValue;


    //list of the positions of all PDF objects in the file
    FObjPositions: TList;

    //the content of the currently written page
    FPageStream: TMemoryStream;

    //the current font object
    FFont: TType1Font;
    //the current size of the font
    FSize: TPDFValue;
    //the current font/font type/font family
    FFontType: TPDFFontType;
    //the current font style
    FFontStyle: TPDFFontStyles;
    //the current drawing color, especially that of the text
    FFontColor: TColor;
    //whether a new text region has begun and no font has been set so far,
    //or whether a symbol has just been written and it has to be re-set
    FBegunText: Boolean;






    //all available fonts in the file (will always be added to the PDF file)
    FFonts: array[TPDFFontType] of array[0..3] of TType1Font;



    //position in ~[link FPageStream] to insert text afterwards
    //(beginning of current link)
    //~deprecated without replacement, calculate the needed adjustment
    //            beforehand!
    FInsertionPoint: Integer;

    //the names and PDF object numbers of the images in the PDF file
    FImages: TStringList;
    //the sizes of all images in the PDF file (entrys are TShortPoints)
    FImageSizes: TList;
    //the registered names of the images to be drawn in the current page
    FImageReferences: TStringList;
    //the commands to draw the images in current page
    FImageDrawCommands: String;

    //the commands to draw lines etc. in the current page
    FDrawCommands: String;

    //list of destinations in the current page
    FDestinations: TStringList;
    //list of names of the destinations in the current page
    FDestinationNames: TStringList;
    //list of aliases for the destinations in the current page
    FDestinationAliases: TStringList;
    //list of annotations in the current page
    FAnnotations: TStringList;


    //position in ~[link FPageGroups] to insert new group of pages
    FPageGroupInsertPos: Integer;         //(will automatically be incremented)
    //the groups of pages
    FPageGroups: array of TPDFObjectNumber;
    //the number of pages in each group of pages
    FPageCountGroups: array of Integer;

    //the current part of the tree of pages that has not yet been written~[br]
    //the second dimension will be of size ~[link FPagesTreeNumberInNodes], the
    //number of valid entries is in ~[link FPageTreeObjectsCounter];~[br]
    //FPageTreeObjects[0][i] contains the references of the already written
    //pages, the other levels contain references to Pages-arrays with
    //references to the Pages-arrays of the lower levels, or in case of index 1
    //the references to the pages; the last of those entries hasn't been
    //written yet, it will be at the end or when the level below it is filled
    FPageTreeObjects: array of array of TPDFObjectNumber;
    //the fill level of the current part of the tree of pages that has not yet
    //been written~[br]
    //the number of valid object numbers in ~[link FPageTreeObjects], has
    //always the same size as its first dimension
    FPageTreeObjectsCounter: array of Integer;
    //number of PDF object references per array in tree of pages;
    //has to be set before the first page is ended
    FPagesTreeNumberInNodes: Integer;


    //list of names and PDF object numbers of destinations in the PDF file
    FDestNameTreeItems: TStringList;
    //number of PDF object references per array in name tree of destinations