uicnodes.pas

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

    //Creates a new node representing the text and appends it as a child node.
    procedure AppendText(const Text: String);

    //PrependNode? InsertNode? ReplaceNode? RemoveNode?
    //TextNode changable?

    //Returns the number of child nodes of this node.
    function ChildCount: Integer;
    //Returns whether this node contains any child nodes.
    function HasChildren: Boolean;
    //Returns whether this node contains no child nodes.
    function NoChildren: Boolean;

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;
    //Visits all children of the node.
    procedure VisitChildren(Visitor: TICVisitor);

    property Children[Index: Integer]: TICNode read GetChild;
  end;




   { * * *  ***  * * *  ***   TICNTextStyle   ***  * * *  ***  * * *  }

  //a style how text should be formatted in the documentation
  TICTextStyle = (
                  //emphasize the text (this will most likely mean something
                  ictsEmphasize,      //similar to italic)
                  //format the text with a "strong" (bold) font
                  ictsStrong
                  //, ictsItalic
                  );

  {The class for nodes to cause contained text nodes to be formatted in a
   special way.
  ~feature maybe a set of styles should be used? }
  TICNTextStyle = class(TICNCompound)
  private
    //the style with which contained text should be formatted
    FTextStyle: TICTextStyle;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing the specified text style.
    constructor CreateStyle(Owner: TICNodeOwner; TextStyle: TICTextStyle);

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;

    property TextStyle: TICTextStyle read FTextStyle;
  end;




   { * * *  ***  * * *  ***   TICNFontStyle   ***  * * *  ***  * * *  }


  //a style representing the font to be used to show text in the documentation
  TICFontStyle = (
                  //format the text as code
                  //(with fixed width (mono-spaced) characters)
                  icfsCode);

  {The class for nodes to cause contained text nodes to be shown with a special
   font. }
  TICNFontStyle = class(TICNCompound)
  private
    //the font with which contained text should be shown
    FFontStyle: TICFontStyle;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing the specified font.
    constructor CreateFontStyle(Owner: TICNodeOwner; FontStyle: TICFontStyle);

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;

    property FontStyle: TICFontStyle read FFontStyle;
  end;




   { * * *  ***  * * *  ***   TICNPreformatted   ***  * * *  ***  * * *  }

  //A style how text should be shown pre-aligned (-formatted) in the
  //documentation. This means it should be shown with the same format/alignment
  //as in the source code. This also implies an mono-spaced font (with
  //fixed-width characters) to be used.
  TICPreformattedKind = (
                         icpkSimple,   //just pre-formatted (<br>s and <code>)
                         icpkSample);  //add an empty line before (and after?)

  {The class for nodes to cause contained text nodes to be shown with the same
   alignment/format as in the source code. This also implies an mono-spaced
   font (with fixed-width characters) to be used. }
  TICNPreformatted = class(TICNCompound)
  private
    //the style in which contained text should be shown pre-aligned
    FPreformattedKind: TICPreformattedKind;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing pre-aligned text.
    constructor CreatePreformatted(Owner: TICNodeOwner;
                                   PreformattedKind: TICPreformattedKind);

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;

    property PreformattedKind: TICPreformattedKind read FPreformattedKind;
  end;



   { * * *  ***  * * *  ***   TICNPascalLink   ***  * * *  ***  * * *  }

  {The class for nodes to create a link to an identifier or file. The linked
   text will be the name of the identifier or file. }
  TICNPascalLink = class(TICSimpleNode)
  private
    //the identifier to link to, nil if a link to a file
    FIdentifier: TIdentifier;
    //the file to link to, nil if a link to an identifier
    FTheFile: TPascalFile;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing a link to the specified identifier or file.
    constructor CreateLink(Owner: TICNodeOwner;
                           Identifier: TIdentifier; TheFile: TPascalFile);

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;

    property Identifier: TIdentifier read FIdentifier;
    property TheFile: TPascalFile read FTheFile;
  end;


   { * * *  ***  * * *  ***   TICNLinkFileByAlias   ***  * * *  ***  * * *  }

  {The class for nodes to create a link to a file by an alias of that file. The
   linked text will probably consist of the alias and/or the name of the file.
  }
  TICNLinkFileByAlias = class(TICNPascalLink)
  private
    //the used alias name of the file
    FAlias: String;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing a link to the file by the specified alias.
    constructor CreateFileLinkByAlias(Owner: TICNodeOwner;
                                      TheFile: TPascalFile;
                                      const Alias: String);

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;

    property Alias: String read FAlias;
  end;




   { * * *  ***  * * *  ***   TICNAbstractLink   ***  * * *  ***  * * *  }

  {The abstract base class for nodes of links. The text of the link is defined
   by the child nodes (as opposed to ~[link TICNPascalLink]).

  Links can't be nested:
  ~[link TICNAbstractLink test ~[em test2 ~[link TICNCompound test3]]] }
  TICNAbstractLink = class(TICNCompound)
  private
    //the text defining the link target;
    //may also be used as text of the link, if the node contains no other text
    FLinkText: String;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;

    //Creates a node representing an abstract link.
    constructor CreateAbstractLink(Owner: TICNodeOwner;
                                   const LinkText: String);
  public

    property LinkText: String read FLinkText;
  end;


   { * * *  ***  * * *  ***   TICNInvalidLink   ***  * * *  ***  * * *  }

  {The class for nodes to represent a link whose target couldn't be found. }
  TICNInvalidLink = class(TICNAbstractLink)
  public
    //Creates a node representing a link to an unknown target.
    constructor CreateInvalidLink(Owner: TICNodeOwner; const LinkText: String);

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;
  end;


   { * * *  ***  * * *  ***   TICNLinkIdentifier   ***  * * *  ***  * * *  }

  //a simple array of references to objects, either identifiers or files
  TObjectArray = array of TObject;

  {The class for nodes to create a link to an identifier or file. }
  TICNLinkIdentifier = class(TICNAbstractLink)
  private
    //the identifier to link to, nil if a link to a file
    FIdentifier: TIdentifier;
    //the file to link to, nil if a link to an identifier
    FTheFile: TPascalFile;
    //the list of the file and/or identifiers in the path to define the link
    //target; can be assembled with dots "." between the items to form the link
    //target similar to ~[link LinkText]
    FPathLinks: TObjectArray;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing a link to an identifier or file.
    constructor CreateIdentifierLink(Owner: TICNodeOwner;
                                     const LinkText: String;
                                     Identifier: TIdentifier;
                                     TheFile: TPascalFile;
                                     PathLinks: TList);

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;

    property Identifier: TIdentifier read FIdentifier;
    property TheFile: TPascalFile read FTheFile;
    property PathLinks: TObjectArray read FPathLinks;
  end;



   { * * *  ***  * * *  ***   TICNLinkExtern   ***  * * *  ***  * * *  }

  {The class for nodes to create an extern link (in the internet or the local
   file system). }
  TICNLinkExtern = class(TICNAbstractLink)
  public
    //Creates a node representing a link to a target outside the documentation.
    constructor CreateExternLink(Owner: TICNodeOwner;
                                 const LinkText: String);

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;

    property URI: String read FLinkText;
  end;


   { * * *  ***  * * *  ***   TICNLinkPage   ***  * * *  ***  * * *  }

  {The class for nodes to create a link to a page of additional user
   documentation. }
  TICNLinkPage = class(TICNAbstractLink)
  private
    //the index of the page to create the link to
    FPageIndex: Integer;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing a link to a page of user documentation.
    constructor CreatePageLink(Owner: TICNodeOwner; const LinkText: String;
                               PageIndex: Integer);

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;

    property PageIndex: Integer read FPageIndex;
  end;


   { * * *  ***  * * *  ***   TICNLinkGUI   ***  * * *  ***  * * *  }

  {The class for nodes to create a link inside documentation as a help on a
   GUI. }
  TICNLinkGUI = class(TICNAbstractLink)
  private
    //the index of the documented window/form
    FGUIIndex: Integer;
    //the name of the sub-component inside the form to link to;
    //-1 for the form itself, -2 for the default comment
    FCommentIndex: Integer;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing a link to a topic as help on a GUI.
    constructor CreateGUILink(Owner: TICNodeOwner; const LinkText: String;
                              GUIIndex, CommentIndex: Integer);

    //Visits the node and all its children.
    procedure Visit(Visitor: TICVisitor); override;

    property GUIIndex: Integer read FGUIIndex;
    property CommentIndex: Integer read FCommentIndex;
  end;



   { * * *  ***  * * *  ***   TICNImage   ***  * * *  ***  * * *  }

  {The class for nodes to create an image inside documentation. }
  TICNImage = class(TICSimpleNode)
  private
    //the name of the file to load the image from
    FFileName: String;
    //resolution/size/dimension of the image; (0, 0) for auto-detect
    //~todo is this still useful?
    FResolution: TPoint;
    //whether the image should be inserted directly into the text
    //"as a character";
    //if not, it will be inserted horizontally centered in an own paragraph
    FCharFormat: Boolean;