uicpdfdoc.pas

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

end;

{Called for each link to a page of the additional user documentation.
~param Node          the node of a link to a page of user documentation
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICPDFVisitor.LinkPage(Node: TICNLinkPage;
                                 var VisitChildren: Boolean);
begin
 //start the link to the page of user documentation
 FTextWriter.StartLink(ltThisDoc, FGenerator.GetPageURI(Node.PageIndex));

 VisitChildren := False;                    //will be visited manually
 if Node.NoChildren then                    //no text of the link specified?
  WriteText(Node.LinkText)                    //write the text of the target
 else
  Node.VisitChildren(Self);                   //write the text

 FTextWriter.EndLink;                       //end the link
end;

{Called for each link to a help topic in the documentation as a help on a GUI.
~param Node          the node of a link to a help topic
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICPDFVisitor.LinkGUI(Node: TICNLinkGUI;
                                var VisitChildren: Boolean);
begin
 //start the link into the documentation as a help on a GUI
 FTextWriter.StartLink(ltThisDoc,
                       FGenerator.GetGUIHelpURIByIndex(Node.GUIIndex,
                                                       Node.CommentIndex));

 VisitChildren := False;                    //will be visited manually
 if Node.NoChildren then                    //no text of the link specified?
  WriteText(Node.LinkText)                    //write the text of the target
 else
  Node.VisitChildren(Self);                   //write the text

 FTextWriter.EndLink;                       //end the link
end;



{Called for each node representing an image.
~param Data the node representing the options to include the image }
procedure TICPDFVisitor.Image(Data: TICNImage);
var       ImageName    :String;     //the name by which the image is registered
          ImageSize    :TPoint;     //the size of the original image in pixels
          MaxHeight    :TPDFValue;  //the maximum height of the image
          ImageScale   :TPDFValue;  //the factor to scale the image by
begin
 //prepare image to be shown in the documentation, add it to the PDF file
 ImageName := FGenerator.WriteImage(Data.CharFormat, Data.JPEGFormat,
                                    Data.Resolution, nil, Data.FileName,
                                    Data.ImageLinks, Data.AlternativeText);

 if ImageName <> '' then                //image could be loaded?
  begin
   ImageSize := FWriter.GetImageSize(ImageName); //get size of image

   Assert(ImageSize.x > 0);
   Assert(ImageSize.y > 0);

   if Data.CharFormat then                //should be in-(the)-line?
    begin

//     MaxHeight := FTextWriter.BiggestFontSize;   //get height of current line
//     if MaxHeight < FWriter.Size then
      MaxHeight := FWriter.Size;

     ImageScale := MaxHeight / ImageSize.y;        //calculate scale factor

     //width too big, does not fit in one line?
     if ImageScale * ImageSize.x > FTextWriter.CurrentLineWidth then
      //scale to fit it in a line
      ImageScale := FTextWriter.CurrentLineWidth / ImageSize.x;

     if ImageScale > FGenerator.MaxImageScale then //don't zoom images too much
      ImageScale := FGenerator.MaxImageScale;

     //add the image to the current paragraph
     FTextWriter.AddImage(ImageName, Data.ImageLinks,
                          ImageSize.x * ImageScale);
    end
   else
    begin
     FTextWriter.EndLine;                          //end the current paragraph
     DrawCenteredImage(ImageName, ImageSize, Data.ImageLinks); //draw the image
    end;
  end;
end;



{Called for each node representing a short token of pascal code.
~param Code the text of the code token
~param Kind what kind of code the token is }
procedure TICPDFVisitor.PascalCode(const Code: String;
                                   Kind: TICPascalCode);
var       Font         :TFontSetting;     //the font used so far
          Handle       :Integer;          //handle of the new font
begin
 if Kind <> icpcIdentifier then           //code has a special format?
  begin
   Font := FTextWriter.CurrentFont;         //get the font of the text so far

   case Kind of                             //start the format
     icpcReservedWord: Include(Font.Style, pfsBold);
     icpcString:       Font.Color := FGenerator.StringColor;
     icpcIdentifier:   Assert(False);
   else
    assert(False);
   end;
   Handle := FTextWriter.PushFontRec(Font); //and set the new font
   FTextWriter.SetParagraphFont(Font);

   WriteText(Code);                         //write the code

   FTextWriter.PopFont(Handle);             //reset to previous font
   FTextWriter.SetParagraphFont(FTextWriter.CurrentFont);
  end
 else
  WriteText(Code);                          //write the identifier
end;





{Called for each node representing a list. Each child node is an item in the
 list.
~param Node          the node representing a list
~param VisitChildren out: whether the children of the node (the items)
                     should also be visited; default is True }
procedure TICPDFVisitor.List(Node: TICNList; var VisitChildren: Boolean);
var       MarkerWidth  :TPDFValue;      //width of the indentation of markers
          OldIndention :TPDFValue;      //previous indentation of the text
          i            :Integer;        //counter through all items of the list
begin
 if Node.HasChildren then               //list not empty?
  begin
   FTextWriter.FlushLine;                 //write last paragraph

   OldIndention := FTextWriter.Indention; //save indentation so far
   //calculate indention of items
   if Node.ItemIndentation <> iciiNone then
    MarkerWidth := IndentationSizes[Node.ItemIndentation = iciiSmall]
   else
    MarkerWidth := 0;

   //no marker, but list (items) indented?
   if (Node.ItemIndentation <> iciiNone) and (Node.ItemMarker = iclimNone) then
    FTextWriter.SetLeftMargin(OldIndention + MarkerWidth); //indent whole list


   VisitChildren := False;                //visit the items manually
   for i := 0 to Node.ChildCount - 1 do   //for each item of the list
    begin
     if Node.ItemMarker <> iclimNone then   //has a marker?
      if Node.ItemMarker = iclimBullet then   //is a bullet?
       FTextWriter.WriteListMarker(True, '', MarkerWidth)  //write the bullet
      else
       FTextWriter.WriteListMarker(False,                  //write its number
                                   GetEnumerationValue(i + 1,
                                                       Node.ItemEnumeration),
                                   MarkerWidth);

     Node.Children[i].Visit(Self);          //write the item

     FTextWriter.EndLine;                   //make sure it is written

     case Node.ItemSeparation of            //add vertical space as requested
       icisNone:      ;
       icisLine:      FTextWriter.EndLine;
       icisParagraph: FTextWriter.EndParagraph;
     else
      Assert(False);
     end;

     if (Node.ItemMarker <> iclimNone) and  //has a marker for each item?
        (Node.ItemIndentation <> iciiNone) then //and items are indented?
      FTextWriter.SetLeftMargin(OldIndention);    //restore old intentation
    end;


   //no marker, but list (items) indented?
   if (Node.ItemIndentation <> iciiNone) and (Node.ItemMarker = iclimNone) then
    FTextWriter.SetLeftMargin(OldIndention);    //stop indenting the whole list

//   FTextWriter.EndParagraph;       //add an empty line as separator
  end; //if Node.HasChildren
end;


{Called for each node representing a dictionary. The child nodes are used in
 pairs, the first always specifies the term to be described while the second
 contains the description.
~param Node          the node representing a dictionary
~param VisitChildren out: whether the children of the node (the terms and
                     descriptions) should also be visited; default is True }
procedure TICPDFVisitor.Dictionary(Node: TICNDictionary;
                                     var VisitChildren: Boolean);
var       ItemIndent   :TICItemIndentation; //indentation of the items
          DescrIndent  :TICItemIndentation; //indentation of descriptions
          OldIndention :TPDFValue;      //previous indentation of the text
          WholeWidth   :TPDFValue;      //indentation of the whole list
          DescrWidth   :TPDFValue;      //indentation of descriptions to marker
          i            :Integer;        //counter through all items
begin
 if Node.HasChildren then                //dictionary is not empty?
  begin
   Assert(not Odd(Node.ChildCount));
{
   Node.DescriptionIndentation    (iciiNone, iciiSmall, iciiNormal, iciiAuto)
   Node.ItemDescriptionSeparation (icisNone, icisLine, icisParagraph)
   Node.ItemIndentation           (iciiNone, iciiSmall, iciiNormal, iciiAuto)
   Node.WholeItemSeparation       (icisNone, icisLine, icisParagraph)
}

   OldIndention := FTextWriter.Indention;      //save indentation so far

   ItemIndent := Node.ItemIndentation;         //get the indentations
   DescrIndent := Node.DescriptionIndentation;

   WholeWidth := 0;
   DescrWidth := 0;

   //same level of indentation for the descriptions as for the items?
   if DescrIndent <> iciiNone then
    if ItemIndent <> iciiNone then
     begin                              //same indentation?
      if (ItemIndent = DescrIndent) and (ItemIndent <> iciiAuto) then
       begin
        //indent the whole list
        WholeWidth := IndentationSizes[ItemIndent = iciiSmall];
        FTextWriter.SetLeftMargin(OldIndention + WholeWidth);
       end
      else
       begin
        //indent the whole list
        WholeWidth := IndentationSizes[ItemIndent in [iciiSmall, iciiAuto]];
        FTextWriter.SetLeftMargin(OldIndention + WholeWidth);
        //and the descriptions even further
        DescrWidth := IndentationSizes[DescrIndent = iciiSmall] - WholeWidth;
       end;
     end
    else                                //only description is indented
     DescrWidth := IndentationSizes[DescrIndent = iciiSmall]
   else
    if ItemIndent <> iciiNone then      //only terms indented?
     begin
      //indent the whole list
      WholeWidth := IndentationSizes[ItemIndent = iciiSmall];
      FTextWriter.SetLeftMargin(OldIndention + WholeWidth);
      DescrWidth := -WholeWidth;          //and back-indent the descriptions
     end;


   VisitChildren := False;                     //visit the items manually
   for i := 0 to Node.ChildCount div 2 - 1 do  //visit each item as a pair
    begin
     if i <> 0 then                              //between two items?
      //add selected separation between the items
      case Node.WholeItemSeparation of
        icisNone:      ;
        icisLine:      FTextWriter.EndLine;
        icisParagraph: FTextWriter.EndParagraph;
      else
       Assert(False);
      end;

     //at least a chance that the descriptions follows the term
     FTextWriter.EnsurePageLines(2);

     Node.Children[i * 2].Visit(Self);           //show term to be described

     FTextWriter.EndLine;                        //make sure it is written
     //add vertical space as requested between terms and their descriptions
     case Node.ItemDescriptionSeparation of
       icisNone:      ;
       icisLine:      FTextWriter.EndLine;
       icisParagraph: FTextWriter.EndParagraph;
     else
      Assert(False);
     end;


     if DescrWidth <> 0 then                     //description is indented?
      FTextWriter.SetLeftMargin(OldIndention + WholeWidth + DescrWidth);

     Node.Children[i * 2 + 1].Visit(Self);       //show description of the term

     FTextWriter.EndLine;                        //make sure it is written

     if DescrWidth <> 0 then                     //description is indented?
      FTextWriter.SetLeftMargin(OldIndention + WholeWidth);  //end indention
    end;

   //whole dictionary is indented?
   if WholeWidth <> 0 then
    FTextWriter.SetLeftMargin(OldIndention);    //stop indenting the whole list

//   FTextWriter.EndParagraph;       //add an empty line as separator
  end; //if Node.HasChildren
end;




{Called for each node representing a topic in the documentation of identifiers
 or files as derived from its comment.
~param Node          the node representing a topic
~param VisitChildren out: whether the children of the node (the content)
                     should also be visited; default is True }
procedure TICPDFVisitor.TopicComment(Node: TICNTopicForComment;
                                     var VisitChildren: Boolean);
var       i            :Integer;       //counter through child nodes
          Heading      :String;        //a heading to be used
          OldIndention :TPDFValue;     //previous indentation of the text
begin
 case Node.Topic of                    //handle the topic
   ictcComment:             ;
   ictcCommentExtendedInfo: if not FGenerator.KeepRawLineBreaks then
                             FTextWriter.SetParagraphAlignment(taBlock);
   ictcCommentSpecials:     if not FGenerator.KeepRawLineBreaks then
                             FTextWriter.SetParagraphAlignment(