uicnodes.pas

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

    //only for HTML and PDF output: whether the image should be converted to
    //JPEG format instead of PNG format
    FJPEGFormat: Boolean;
    //the list of links inside the image
    //~feature what to do with alternative texts of links?
    FImageLinks: TImageLinkList;
    //alternative text for the image (only shown/used in HTML output so far)
    //~feature maybe, if not empty, add a visible description below the image
    //         for those not in ~[link FCharFormat]
    FAlternativeText: String;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing an image.
    constructor CreateImage(Owner: TICNodeOwner; const FileName: String;
                            Resolution: TPoint;
                            CharFormat, JPEGFormat: Boolean;
                            ImageLinks: TImageLinkList;
                            const AlternativeText: String);
    //Frees this node and the list of links inside the image.
    destructor Destroy; override;

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

    property FileName: String read FFileName;
    property Resolution: TPoint read FResolution;
    property CharFormat: Boolean read FCharFormat;
    property JPEGFormat: Boolean read FJPEGFormat;
    property ImageLinks: TImageLinkList read FImageLinks;
    property AlternativeText: String read FAlternativeText;
  end;



   { * * *  ***  * * *  ***   TICNDiagram   ***  * * *  ***  * * *  }

  {The class for nodes to create and insert a diagram of classes or files. }
  TICNDiagram = class(TICSimpleNode)
  private
    //the list of parameters to set up and fill the diagram
    FParameters: TStringList;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;

    //Creates this node and the list of parameters.
    constructor Create(Owner: TICNodeOwner); override;
  public
    //Creates a node representing a diagram with the list of parameters.
    constructor CreateDiagram(Owner: TICNodeOwner; Parameters: TStrings);
    //Frees this node and the list of parameters.
    destructor Destroy; override;

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

    property Parameters: TStringList read FParameters;
  end;













   { * * *  ***  * * *  ***   TICNPascalCode   ***  * * *  ***  * * *  }


  //what kind of pascal code the text is
  TICPascalCode = (
                   icpcIdentifier,     //the code is an identifier
                   icpcReservedWord,   //the code is a reserved word
                   icpcString);        //the code is a string

  {The class for nodes of pascal tokens. }
  TICNPascalCode = class(TICNText)
  private
    //the kind of pascal token the text represents
    FKind: TICPascalCode;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing a pascal token.
    constructor CreatePascalCode(Owner: TICNodeOwner; Kind: TICPascalCode;
                                 const Text: String);

    //Visits the node.
    procedure Visit(Visitor: TICVisitor); override;

    property Kind: TICPascalCode read FKind;
  end;














   { * * *  ***  * * *  ***   TICNSection   ***  * * *  ***  * * *  }

  {The class for nodes of special (top-level) "sections". }
  TICNSection = class(TICNCompound)
  public
    //Creates a node representing a section.
    constructor CreateSection(Owner: TICNodeOwner);

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


   { * * *  ***  * * *  ***   TICNExceptionSection   ***  * * *  ***  * * *  }

  {The class for nodes of special (top-level) sections to document thrown
   exceptions by a function or functions of a function type. }
  TICNExceptionSection = class(TICNSection)
  private
    //the name of the exeption that could be thrown;
    //used when exception class can't be found
    FExceptionText: String;
    //the identifier of the exception, might be nil if it couldn't be found;
    //beware: it might also be excluded from the documentation
    FException: TIdentifier;
  public

    property ExceptionText: String read FExceptionText write FExceptionText;
    property Exception: TIdentifier read FException write FException;
  end;


   { * * *  ***  * * *  ***   TICNSeeSection   ***  * * *  ***  * * *  }

  {The class for nodes of special (top-level) sections to emphasize the
   relationship with another identifier or file, preferably with a link to it.
  }
  TICNSeeSection = class(TICNSection)
  private
    //the name of the identifier or file to emphasize and link to;
    //used when it can't be found
    FSeeText: String;
    //the identifier to emphasize and link to, nil when it is a file;
    //might also be nil if it couldn't be found;
    //beware: it might also be excluded from the documentation
    FSeeIdentifier: TIdentifier;
    //the file to emphasize and link to, nil when it is an identifier;
    //might also be nil if it couldn't be found;
    //beware: it might also be excluded from the documentation
    FSeeFile: TPascalFile;
  public

    property SeeText: String read FSeeText write FSeeText;
    property SeeIdentifier: TIdentifier read FSeeIdentifier
                                        write FSeeIdentifier;
    property SeeFile: TPascalFile read FSeeFile write FSeeFile;
  end;

















   { * * *  ***  * * *  ***   TICNList   ***  * * *  ***  * * *  }


  //the size of the separation between items in a list
  TICItemSeparation = (
                       //no separation between items in a list
                       icisNone,
                       //an empty line between items in a list
                       icisLine,
                       //a paragraph (or between one and two lines) between
                       //items in a list
                       icisParagraph);

  //the indentation of the items, this is especially important when there is an
  //~[link TICListItemMarker marker] for each item
  TICItemIndentation = (
                        //no indentation at all
                        iciiNone,
                        //only a smaller indentation for each item
                        iciiSmall,
                        //a normal indentation for each item
                        iciiNormal,
                        //will result in most cases in a
                        //~[link iciiNormal normal] indentation for each item
                        iciiAuto);


  //the kind of the marker for each item in the list
  TICListItemMarker = (
                       //no marker for the items of the list
                       iclimNone,
                       //enumerate the items of the list
                       iclimEnumeration,
                       //use some kind of bullet for each item; the kind of the
                       //bullet may change, especially when lists are nested
                       iclimBullet
                       {, ...});

  //the kind of markers to use to enumerate the items in the list
  TICListItemEnumeration = (
                            //use normal decimal numbers
                            //to enumerate the items in the list
                            iclimNumeric,
                            //use capital letters
                            //to enumerate the items in the list
                            iclimAlphaCap,
                            //use lower case letters
                            //to enumerate the items in the list
                            iclimAlphaSmall,
                            //use roman numbers in capital letters
                            //to enumerate the items in the list
                            iclimRomanCap,
                            //use roman numbers in lower case letters
                            //to enumerate the items in the list
                            iclimRomanSmall);


  {The class for nodes representing lists. Each child node is an item in the
   list, for more complex items a ~[linkClass TICNCompound compound node] has
   to be used.

   The items of the list can be marked either by a bullet or enumerated. It is
   also possible to use no marker. Each item can be indented, so the marker is
   emphasized. There are several systems available to enumerate the items. The
   vertical spacing between the items can also be selected. }
  TICNList = class(TICNCompound)
  private
    //the indentation of the items; if the items are
    //~[link FItemMarker marked], the marking will not be indented with the
    //content of the items
    FItemIndentation: TICItemIndentation;
    //the kind of marker for each item, so every item can be identified
    FItemMarker: TICListItemMarker;
    //the system to express the number of the item in the list, if
    //~[link FItemMarker] is ~[link iclimEnumeration]
    FItemEnumeration: TICListItemEnumeration;
    //the vertical spacing between the items
    FItemSeparation: TICItemSeparation;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;
  public
    //Creates a node representing a general list.
    constructor CreateList(Owner: TICNodeOwner;
                           Indentation: TICItemIndentation = iciiNormal;
                           Marker: TICListItemMarker = iclimBullet;
                           Enumeration: TICListItemEnumeration = iclimNumeric;
                           Separation: TICItemSeparation = icisNone);
    //Creates a node representing a list with bullets as markers for each item.
    constructor CreateListBullet(Owner: TICNodeOwner;
                            Indentation: TICItemIndentation = iciiNormal;
                            Separation: TICItemSeparation = icisNone;
                            Marker: TICListItemMarker = iclimBullet);
    //Creates a node representing a numbered list.
    constructor CreateListEnum(Owner: TICNodeOwner;
                            Enumeration: TICListItemEnumeration = iclimNumeric;
                            Indentation: TICItemIndentation = iciiAuto;
                            Separation: TICItemSeparation = icisNone);
    //Creates a node representing a simple list without a marker for the items.
    constructor CreateListSimple(Owner: TICNodeOwner;
                                 Indentation: TICItemIndentation = iciiNone;
                                 Separation: TICItemSeparation = icisNone);

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

    property ItemIndentation: TICItemIndentation read FItemIndentation;
    property ItemMarker: TICListItemMarker read FItemMarker;
    property ItemEnumeration: TICListItemEnumeration read FItemEnumeration;
    property ItemSeparation: TICItemSeparation read FItemSeparation;
  end;






   { * * *  ***  * * *  ***   TICNDictionary   ***  * * *  ***  * * *  }


  {The class for nodes representing a dictionary. The items of a dictionary
   consist of a pair, the first part is the term to be defined while the second
   describes the first one.~[br]
   Likewise an item in the dictionary consists of ~[em two] child nodes, the
   first (with even indices) being the term being described, the second (odd
   indices) the description of the previous term. For more complex items a
   ~[linkClass TICNCompound compound node] has to be used.

   This is general dictionary that can be used to express different things. For
   instance simple sub-classes are used to express the lists of parameters for
   functions with their descriptions or their possibly thrown exceptions. }
  TICNDictionary = class(TICNCompound)
  private
    //the indentation of the terms to be described
    FItemIndentation: TICItemIndentation;
    //the indentation of the descriptions of the terms
    FDescriptionIndentation: TICItemIndentation;
    //the vertical space between the described items
    FWholeItemSeparation: TICItemSeparation;
    //the vertical space between each term and its description
    FItemDescriptionSeparation: TICItemSeparation;
  protected
    //Clones the content of the node to the specified (new) node.
    procedure CloneTo(Node: TICNode); override;