ubasepdfdoc.pas

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

    //the list of annotations in the current line; will be added to the
    //document after the line has been finished; may also include images
    FCurrentLineAnnotations: TStringList;


  protected
    //current vertical position in the current page, where the next text will
    //be written
    FYPos: TPDFValue;
    //current horizontal position in the current page, where the next text will
    //be written
    FXPos: TPDFValue;
    //the rect in the page where text should be written (without headers and
    //footers)
    FPageRect: TPDFRect;
    //the position of the start of the line
    //= ~[link FPageRect].Left + ~[link FIndention]
    FLeftLineStart: TPDFValue;

    //the object to write the PDf file
    FWriter: TPDFWriter;


    //the currently used font in the documentation
    FCurrentFont: TPDFFontType;
    //the currently used size of the font in the documentation
    FCurrentSize: TPDFValue;
    //the currently used style of the font in the documentation
    FCurrentStyle: TPDFFontStyles;
    //the currently used color of text in the documentation
    FCurrentColor: TColor;

    //the current link target, is a link should be generated
    FCurrentLink: String;
    //the kind of the current link
    FCurrentLinkType: TLinkType;
    //the number of words (spaces) in the current line so far; needed to
    //adjust the position of the annotations in the line by the used word
    //spacing
    FCurrentWordsInLine: Integer;

    //the number of the current page
    FPage: Integer;
    //if the number of the page should be written in roman letters instead with
    //latin digits
    FRomanPageNumber: Boolean;
    //if sections shouldn't start a new page (used in the index and the
    //user documentation)
    FSectionSamePage: Boolean;

    //the root of the outline of the document; also used to generate the table
    //of contents
    FOutlineRoot: TOutlineEntry;
    //number of the current chapter/part of the documentation
    FMainSectionNumber: Integer;
    //the entry of the current chapter/part of the documentation
    FMainSectionOutlineEntry: POutlineEntry;











    //Returns the string token with an applied format macro.
    function FormatStringToken(const StringToken: String): String; override;







    //Returns the format needed to express the scope (as an icon).
    function GetScope(Scope: TScope): String; override;
    //Returns the format needed to express the portability issues (as icons).
    function GetPortabilityIssues(Issues: TIdentPortabilities): String;
                                                                      override;





    //Returns a string expressing the current position in the documentaton by
    //the number of its section, subsection and so on.
    function GetSectionString: String;

    //Writes the header and footer of current page.
    procedure WritePageMarkings;

    //Starts a new page.
    procedure NewPage(FirstPage: Boolean = False);
    //Starts a new page if the current is not still empty.
    procedure ClearPage;
    //Starts a new page, if the given number of lines won't fit on the current
    //one.
    procedure EnsurePageLines(Lines: Integer);


    //Registers the current position in the document by the internal name.
    procedure CreateDestination(const LabelName: String);


    //Starts a new chapter/part of the documentation.
    procedure WriteNewMainSection(const Title, LabelName: String;
                                  OutlineEntry: POutlineEntry = nil);
    //Starts a section of the documentation.
    procedure WriteNewSection(const Title, LabelName: String);
    //Starts a subsection of the documentation.
    procedure WriteNewSubSection(const Title, LabelName: String);
    //Starts a section of an item in the documentation.
    procedure WriteNewItemSection(const Title, LabelName: String);




    //Sets the indentation, of the following text.
    procedure SetLeftMargin(LeftMargin: TPDFValue);

    //Sets the font to be used for the following text.
    procedure SetFont(FontType: TPDFFontType; Size: TPDFValue;
                      Style: TPDFFontStyles = []);


    //Write the text of the documentation with automatical word-wrapping.
    procedure WriteText(Text: String;
                        HandleRect: THandleTextRectProc = nil;
                        BlockAlignment: Boolean = True);

    //Ends the current line and starts a new one.
    procedure WriteNewLine;
    //Writes the text and ends the line.
    procedure WriteSimpleLine(const Text: String;
                              BlockAlignment: Boolean = True);






    //Will be called when each line ends. All annotations are added to the
    //PDF document and images are drawn.
    procedure HandleAnnotations(WordSpacing: TPDFValue);


    //Handler of texts for creating links (annotations); its type is
    //~[link THandleTextRectProc]
    procedure WriteLinkOnTextRect(Rect: TPDFRect);


    //Handles the command to draw an image centered.
    function HandleCenteredImageCommand(const ImageName: String;
                                        ImageSize: TPoint;
                                        Data: PChar): PChar;
    //Handles the command to draw an image as a character.
    function HandleCharImageCommand(const ImageName: String; ImageSize: TPoint;
                                    Data: PChar): PChar;
    //Handles the command to draw an image in the intermediary code.
    function HandleImageCommand(Data: PChar): PChar;


    //Writes the text with intermediary code to the PDF document.
    procedure WriteParsedText(const Text: String; NewLine: Boolean = True);












    //Writes a link to an identifier.
    procedure WriteFileNameLink(TheFile: TPascalFile);
    //Writes a link to an identifier.
    procedure WriteIdentNameLink(Ident: TIdentifier;
                                 WriteFile: Boolean = False);
    //Writes a link to a member of a record-like type.
    procedure WriteRecordFieldNameLink(Ident: TIdentifier;
                                       WriteRecord: Boolean = False);










    //Writes the outline of the documentation.
    procedure WriteOutline;
    //Frees the outline of the documentation.
    procedure FreeOutline(Entry: POutlineEntry);




    property DefaultFontType: TPDFFontType read FDefaultFontType;
    property PageWidth: Single read FPageWidth;
    property PageHeight: Single read FPageHeight;
    property LeftMargin: Single read FLeftMargin;
    property RightMargin: Single read FRightMargin;
    property TopMargin: Single read FTopMargin;
    property BottomMargin: Single read FBottomMargin;
    property NormalFontSize: TPDFValue read FNormalFontSize;
    property LineDistanceScale: TPDFValue read FLineDistanceScale;
    property LinkColor: TColor read FLinkColor;

  public
    //Creates the generator object and initializes its fields.
    constructor Create; override;
    //Destroys the generator object.
    destructor Destroy; override;


    //Will be called for all reserved words.
    function ReservedWord(const Word: String): String; override;

    //Returns the number of available options in generators of this class.
    class function GetOptionCount: Cardinal; override;
    //Gets a description of an option.
    class procedure GetOptionDescription(Index: Cardinal;
                                         var Desc: TOptionDescription);
                                                                      override;
    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; override;
    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;




    //Handles text by encoding special characters.
    function HandleRawText(const Text: String): String; override;

    //Returns the text in the format; text may already include other formats.
    function FormatText(TextFormat: TDocumentationTextFormat;
                        const Text: String;
                        var SkipWhitespaces: Boolean): String; override;



    //Writes a link to an identifier or file in the documentation.
    function InternalLink(const URI, LinkLabel: String): String; override;
    //Writes a link to an external URI.
    function ExternalLink(const URI, LinkLabel: String): String; override;

    //Includes an image in the documentation.
    function WriteImage(CharFormat, JPEGFormat: Boolean; Resolution: TPoint;
                        BMP: TBitmap; const FileName: String;
                        Links: TImageLinkList;
                        const AlternativeText: String): String; override;



    //Resets the attributes to ready the generator for a new generation.
    procedure ResetForNewGeneration; override;
  end;





implementation

uses SysUtils,
{$IFNDEF NOJPEGSUPPORT}
 {$IFNDEF LINUX}
     jpeg,
 {$ENDIF}
{$ENDIF}
     General, UFilePaths,
     UDocumentationTexts;















    //list for the option "PageMarkingFont" of the generator
    //~[link TBasePDFDoc]
var PageMarkingFontEnumerationList: TStringList = nil;
    //list for the option "PageMarkingFontStyle" of the generator
    //~[link TBasePDFDoc]
    PageMarkingFontStyleEnumerationList: TStringList = nil;




   { * * *  ***  * * *  ***   TBasePDFDoc   ***  * * *  ***  * * *  }



      //the colors for the different symbols
const SymbolColors: array[TSymbol] of TColor =
             (clRed, $E000E0, clBlue, $00B800, $808000,
              clRed, $00B800,
              clBlue,   //Yellow,
              clRed,
              clRed, clBlue, clYellow);

      //the text in the PDF-file indicating scopes of identifiers
      ScopeText = 'A'; //'*';
      //the text in the PDF-file indicating portability issues of identifiers
      PortabilityText = 'B'; //#171#187;
      //the texts in the PDF-file of the symbols
      SymbolTexts: array[TSymbol] of Char = //String =
                   (ScopeText, ScopeText, ScopeText, ScopeText, ScopeText,
                    ScopeText, ScopeText,
                    'D',  //'*',
                    'C',  //#247,
                    PortabilityText, PortabilityText, PortabilityText);

      //format to create names of images from an integer value
      ImageNameFormat = 'Img_%d';









{Creates the generator object and initializes its fields. }
constructor TBasePDFDoc.Create;
begin
 inherited Create;                 //create the object

 FDefaultFontType := pftTimes;     //use Times New Roman as default font

 FPageWidth := 21;                 //page is DIN A4
 FPageHeight := 29.7;

 FLeftMargin := 3;                 //use margins of three centimeters
 FRightMargin := 3;
 FTopMargin := 3;
 FBottomMargin := 3;


 FNormalFontSize := 10;            //use this size for the font
 FLineDistanceScale := 7 / 6; //add an exra space of a sixth line between lines