uicnodes.pas

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

                      //this topic is added, in case the class is abstract
                      //(contains abstract methods)
                      ictcAbstract,
                      //topic containing the lists of interfaces implemented by
                      //the class
                      ictcImplementedInterfacesMain,
                      //topic containing the list of interfaces implemented
                      //directly by the class (may be empty)
                      ictcImplementedInterfacesDirect,
                      //topic containing the list of interfaces implemented
                      //by ancestors of the class (may be empty)
                      ictcImplementedInterfacesInherit,
                      //topic containing the list of direct descendants
                      //(sub-classes) of the class or interface (may be empty)
                      ictcDescendants,
                      //topic containing the list of classes implementing the
                      //interface (may be empty)
                      ictcImplementingClasses,
                      //topic containing the list of classes (record-like
                      //types) that use this class (record-like type) (may be
                      //empty)
                      ictcUsedInClasses,
                      //topic containing the list of abstract methods of the
                      //class that have not been implemented by the class or
                      //one of its ancestors
                      ictcStillAbstractMethods
                     );


  {The class for nodes representing one of several topics in the documentation
   of classes (record-like types). }
  TICNTopicForClass = class(TICNCompound)
  private
    //the topic this node represents
    FTopic: TICTopicForClass;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing a topic in the documentation of a class
    //(record-like type).
    constructor CreateTopic(Owner: TICNodeOwner; Topic: TICTopicForClass);

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

    property Topic: TICTopicForClass read FTopic;
  end;






   { * * *  ***  * * *  ***   TICNParameterlist   ***  * * *  ***  * * *  }

  {The class for nodes representing a list of parameters of a function or
   function type. This is dictionary, each entry describes one parameter. }
  TICNParameterlist = class(TICNDictionary)
  public
    //Creates a node representing a list of parameters.
    constructor CreateParameterlist(Owner: TICNodeOwner);

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


   { * * *  ***  * * *  ***   TICNExceptionlist   ***  * * *  ***  * * *  }

  {The class for nodes representing a list of exceptions raised by a function
   or by functions of a function type. This is dictionary, each entry describes
   an exception and the circumstances when it will be raised. }
  TICNExceptionlist = class(TICNDictionary)
  public
    //Creates a node representing a list of exceptions.
    constructor CreateExceptionlist(Owner: TICNodeOwner);

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









   { * * *  ***  * * *  ***   TICNTokenAncestorList   ***  * * *  ***  * * *  }


  //this enumeration type holds all possible tokens in the list of ancestors of
  //a class
  TICAncestorListToken = (
                          //the token before the final class, the class whose
                          //list of ancestors it is
                          icaltFinalPre,
                          //the token after the final class, the class whose
                          //list of ancestors it is
                          icaltFinalPost,
                          //the token for unknown or undocumented ancestors
                          icaltMissing,
                          //the separator between the ancestors
                          icaltArrow);


  {The class for nodes representing a token in the list of ancestors of a class
   or interface. }
  TICNTokenAncestorList = class(TICSimpleNode)
  private
    //the token this node represents
    FToken: TICAncestorListToken;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing a token in the list of ancestors of a class.
    constructor CreateAncestorListToken(Owner: TICNodeOwner;
                                        Token: TICAncestorListToken);

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

    property Token: TICAncestorListToken read FToken;
  end;



   { * * *  ***  * * *  ***   TICNTokenClassList   ***  * * *  ***  * * *  }

  //this enumeration type holds all possible tokens in the tree of all classes
  //(the class hierarchy).
  TICClassListToken = (
                       //token indicating the list of implemented interfaces of
                       //a class
                       iccltImplements,
                       //links to the files with diagrams of the classes
                       iccltClassTreeFileLinks,
                       //links to the files with diagrams of all files
                       //~todo should be moved from here to an another class?
                       iccltFileListFileLinks);

  {The class for nodes representing a token in the hierarchy of all classes,
   or the links to files with diagrams of the classes or files. }
  TICNTokenClassList = class(TICSimpleNode)
  private
    //the token this node represents
    FToken: TICClassListToken;
    //the kind of record-like type the token is for
    FKind: TRecordKind;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing a token in the hierarchy of all classes.
    constructor CreateClassListToken(Owner: TICNodeOwner;
                                     Token: TICClassListToken;
                                     Kind: TRecordKind);

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

    property Token: TICClassListToken read FToken;
  end;





























   { * * *  ***  * * *  ***   TICVisitor   ***  * * *  ***  * * *  }

  {The abstract base class defining the interface of visitors of the
   ~[link UICNodes COM]-hierarchy.

   Some of its methods contain a reference parameter ~[code VisitChildren]
   additionally to the node itself, it is by default True but can be changed so
   the children are not visited after the call. This is especially useful,
   when some work has to be done after the child nodes have been visited. In
   these cases the parameter has to be set to False and the children must be
   visited manually by calling the method ~[link TICNCompound.VisitChildren] of
   the parent node.

   ~[diagram ~[insertVariable ThisClass].tree
             /layout=post /size=8 /margin=5 /members /ShowFile=False]
  }
  TICVisitor = class
  public
    {Called for all text nodes in the ~[link UICNodes COM].
    ~param Text the text of the node }
    procedure Text(const Text: String); virtual; abstract;
    {Called for all raw text nodes/raw data in the ~[link UICNodes COM].
    ~param Text the raw data to be inserted unchanged in the documentation }
    procedure RawText(const Text: String); virtual; abstract;
    {Called for all nodes of all kinds of breaks in the ~[link UICNodes COM].
     This means line breaks or paragraph breaks.
    ~param BreakStyle the kind of the break }
    procedure Break(BreakStyle: TICBreakStyle); virtual; abstract;


    {Called for nodes in the ~[link UICNodes COM] that change the style of the
     text for their contained nodes.
    ~param Node          the node representing a different text style
    ~param VisitChildren out: whether the children of the node should also be
                         visited; default is True }
    procedure TextStyle(Node: TICNTextStyle; var VisitChildren: Boolean);
                                                             virtual; abstract;
    {Called for nodes in the ~[link UICNodes COM] that change the font of the
     text for their contained nodes.
    ~param Node          the node representing a different font
    ~param VisitChildren out: whether the children of the node should also be
                         visited; default is True }
    procedure FontStyle(Node: TICNFontStyle; var VisitChildren: Boolean);
                                                             virtual; abstract;
    {Called for nodes in the ~[link UICNodes COM] that let their contained
     nodes keep their format. This means a fixed-width font should be used and
     line breaks should be kept.
    ~param Node          the node causing its children to keep their format
    ~param VisitChildren out: whether the children of the node should also be
                         visited; default is True }
    procedure Preformatted(Node: TICNPreformatted; var VisitChildren: Boolean);
                                                             virtual; abstract;

    {Called for each link to an identifier or file.
    ~param Identifier the identifier to link to; nil if a link to a file
    ~param TheFile    the file to link to; nil if a link to an identifier }
    procedure LinkTo(Identifier: TIdentifier; TheFile: TPascalFile); virtual;
                                                                     abstract;
    {Called for each link to a file by one of its aliases (used in the uses
     clauses).
    ~param TheFile the file to link to
    ~param Alias   the used alias of the file }
    procedure LinkFileByAlias(TheFile: TPascalFile;
                              const Alias: String); virtual; abstract;

    {Called for each link whose target could not be found.
    ~param Node          the node with the invalid/unknown link target
    ~param VisitChildren out: whether the children of the node (the link text)
                         should also be visited; default is True }
    procedure InvalidLink(Node: TICNInvalidLink; var VisitChildren: Boolean);
                                                             virtual; abstract;
    {Called for each manual link to an identifier or file.
    ~param Node          the node of a link to an identifier or file
    ~param VisitChildren out: whether the children of the node (the link text)
                         should also be visited; default is True }
    procedure LinkIdentifier(Node: TICNLinkIdentifier;
                             var VisitChildren: Boolean); virtual; abstract;
    {Called for each link to a target outside of the generated documentation
     (either in the internet or in the local file system).
    ~param Node          the node of a link to an external target
    ~param VisitChildren out: whether the children of the node (the link text)
                         should also be visited; default is True }
    procedure LinkExtern(Node: TICNLinkExtern; var VisitChildren: Boolean);
                                                             virtual; abstract;
    {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 LinkPage(Node: TICNLinkPage; var VisitChildren: Boolean);
                                                             virtual; abstract;
    {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 LinkGUI(Node: TICNLinkGUI; var VisitChildren: Boolean); virtual;
                                                                      abstract;

    {Called for each node representing an image.
    ~param Data the node representing the options to include the image }
    procedure Image(Data: TICNImage); virtual; abstract;
    {Called for each node representing a diagram of classes or files.
    ~param Parameters the parameters to create the diagram }
    procedure Diagram(Parameters: TStrings); virtual; abstract;

    {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 PascalCode(const Code: String; Kind: TICPascalCode); virtual;
                                                                   abstract;







    {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 List(Node: TICNList; var VisitChildren: Boolean); virtual;
                                                                abstract;
    {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 Dictionary(Node: TICNDictionary; var VisitChildren: Boolean);
                                                             virtual; abstract;
    {Called for each node representing a topic in the documentation of
     identifiers or