udiagram.pas

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

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2004-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}


unit UDiagram;

{Contains classes to create and edit diagrams of the parsed data.
 ~[link TDiagram] manages all options and all boxes (files or classes) of the
 diagram and its painting. }

interface

uses Windows, SysUtils, Classes,
{$IFNDEF LINUX}
     Graphics,
{$ELSE}
     QGraphics,
{$ENDIF}
     General,
     UPascalConsts,
     UBaseIdents, UExtIdents;








      //text to append after the name of a method to mark it as a method
const MethodBraces = '(...)';
      //text to add to an interface to mark it as an interface
      InterfaceHeader = '<<interface>>';

      //prefix for properties in the diagram, UML 1.x: '/'
      PropertyPrefix = '/';
      //postfix for properties in the diagram, UML 2.0: ' {isDerived}'
      PropertyPostfix = '';

      //delimiter of modules to their super-module(s)
      ModuleDelimiter = '/';



      //the possible scopes (visibility) of members of a class
type  TMemberScopes = sPrivate..sAutomated;

      //the characters depicting scopes (visibility) of members of classes
const MemberScopeCharacters: array[TMemberScopes] of Char =
                             ('-', '#', '+', '*', '%');


      //the colors for the different kind of methods
      MethodColors: array[TFunctionKind] of TColor =
                    (clBlack, clGray, clGreen, clRed);



type
  //Used to select what kinds of links should be included in exported SVG image
  //files.
  TSVGImageLinkKind = (
                       //don't add any links
                       svgilkNoLinks,
                       //add links to the documentation in HTML format
                       svgilkHTMLLinks,
                       //add links to the documentation in HTML Help format
                       //without sub-directories
                       svgilkHTMLHelpNoSubDir,
                       //add links to the documentation in HTML Help format
                       //with sub-directories for each file
                       svgilkHTMLHelpSubForFiles,
                       //add links to the documentation in HTML Help format
                       //with sub-directories for each file and
                       //sub-sub-directories for each class
                       svgilkHTMLHelpSubForFilesClasses);




type

  TDiagram = class;           //class to manage the whole diagram



  { * * *  ***  * * *  ***   TDiagramDrawer   ***  * * *  ***  * * *  }

  {Abstract base class for objects used to draw the diagram. }
  TDiagramDrawer = class
  protected
    //the diagram to be drawn
    FDiagram: TDiagram;
  public
    {Draws an arrow.
    ~param Src             the start point of the arrow
    ~param Dest            the end point of the arrow
    ~param Arr1, Arr2      the end points of the arrow head
    ~param FilledArrowHead whether the arrow head should be filled
    ~param ThickLine       whether the arrow should be painted thickly
    ~param LineStyle       the style of the line, either psSolid, psDash or
                           psDashDot }
    procedure DrawArrow(Src, Dest, Arr1, Arr2: TPoint;
                        FilledArrowHead: Boolean; ThickLine: Boolean;
                        LineStyle: TPenStyle); virtual; abstract;
    {Draws the rectangle of a module and its name.
    ~param Left, Top, Right, Bottom the sides of the rectangle of the module
    ~param Rounding                 by how much the rectangle should be rounded
    ~param ModuleName               the name of the module to be drawn
    ~param TextOffset               the offset of the text from the upper left
                                    corner
    ~param Monochrome               whether the diagram is drawn monochrome }
    procedure DrawModule(Left, Top, Right, Bottom: Integer; Rounding: Integer;
                         const ModuleName: String; TextOffset: Integer;
                         Monochrome: Boolean); virtual; abstract;
    {Draws a box of a file or class in the diagram.
    ~param Left, Top, Right, Bottom the sides of the rectangle of the box
    ~param Rounding                 by how much the rectangle should be
                                    rounded }
    procedure DrawBox(Left, Top, Right, Bottom: Integer;
                      Rounding: Integer); virtual; abstract;
    {Draws selection markers at a box of a file or class in the diagram.
    ~param Left, Top, Right, Bottom the sides of the rectangle of the box
    ~param HalfSize                 the half size of the selection markers }
    procedure DrawBoxSelection(Left, Top, Right, Bottom: Integer;
                               HalfSize: Integer); virtual; abstract;
    {Draws some text.
    ~param Top    the vertical position where the text should be drawn
    ~param Left   the horizontal position where the text should be drawn, or if
                  Center is true the left position where to center it in
    ~param Right  only relevant if Center is true, the right position to center
                  the text in
    ~param Text   the text to be drawn
    ~param Center whether the text should be centered between the left and
                  right margin, of not it is drawn at the left position
    ~param Style  the font style to use, one or more of fsBold, fsItalic and
                  fsUnderline is possible
    ~param Color  the color to draw the text in, clBlack is the default }
    procedure DrawText(Top, Left, Right: Integer; const Text: String;
                       Center: Boolean; Style: TFontStyles;
                       Color: TColor); virtual; abstract;
    {Draws a line.
    ~param Xs, Ys the starting point of the line
    ~param Xe, Ye the end point of the line }
    procedure DrawLine(Xs, Ys, Xe, Ye: Integer); virtual; abstract;
    {Draws an icon representing a scope of a member of a record-like type.
    ~param X, Y  the position where to draw the icon
    ~param Scope the scope, whose icon should be drawn }
    procedure DrawScopeIcon(X, Y: Integer; Scope: TScope); virtual; abstract;

    property Diagram: TDiagram read FDiagram write FDiagram;
  end;

  { * * *  ***  * * *  ***   TExternalDiagramDrawer   ***  * * *  ***  * * *  }

  {Abstract base class for objects used to draw the diagram. The units are
   actual class will be defined outside this unit. }
  TExternalDiagramDrawer = class(TDiagramDrawer)
  public
    {Allows the object to initialize itself with the size of the diagram.
    ~param Size the size of the image of the diagram in pixels
    ~param FontHeight the height of the font in pixels }
    procedure Initialize(Size: TPoint; FontHeight: Integer); virtual; abstract;
  end;




  { * * *  ***  * * *  ***   TCanvasDiagramDrawer   ***  * * *  ***  * * *  }

  {Used to draw the diagram on a canvas, either for a bitmap or a Windows Meta
   File. }
  TCanvasDiagramDrawer = class(TDiagramDrawer)
  private
    //the canvas to draw the diagram on
    FCanvas: TCanvas;
  public
    //Draws an arrow.
    procedure DrawArrow(Src, Dest, Arr1, Arr2: TPoint;
                        FilledArrowHead: Boolean; ThickLine: Boolean;
                        LineStyle: TPenStyle); override;
    //Draws the rectangle of a module and its name.
    procedure DrawModule(Left, Top, Right, Bottom: Integer; Rounding: Integer;
                         const ModuleName: String; TextOffset: Integer;
                         Monochrome: Boolean); override;
    //Draws a box of a file or class in the diagram.
    procedure DrawBox(Left, Top, Right, Bottom: Integer;
                      Rounding: Integer); override;
    //Draws selection markers at a box of a file or class in the diagram.
    procedure DrawBoxSelection(Left, Top, Right, Bottom: Integer;
                               HalfSize: Integer); override;
    //Draws some text.
    procedure DrawText(Top, Left, Right: Integer; const Text: String;
                       Center: Boolean; Style: TFontStyles;
                       Color: TColor); override;
    //Draws a line.
    procedure DrawLine(Xs, Ys, Xe, Ye: Integer); override;
    //Draws an icon representing a scope of a member of a record-like type.
    procedure DrawScopeIcon(X, Y: Integer; Scope: TScope); override;

    property Canvas: TCanvas read FCanvas write FCanvas;
  end;



  { * * *  ***  * * *  ***   TSVGDiagramDrawer   ***  * * *  ***  * * *  }

  {Used to write the diagram in an SVG image file. }
  TSVGDiagramDrawer = class(TDiagramDrawer)
  private
    //the file to save the diagram in
    FSVGFile: TBufferStream;
    //the offset from the top of a text to the base line
    FBaseLineOffset: Integer;
  public
    //Draws an arrow.
    procedure DrawArrow(Src, Dest, Arr1, Arr2: TPoint;
                        FilledArrowHead: Boolean; ThickLine: Boolean;
                        LineStyle: TPenStyle); override;
    //Draws the rectangle of a module and its name.
    procedure DrawModule(Left, Top, Right, Bottom: Integer; Rounding: Integer;
                         const ModuleName: String; TextOffset: Integer;
                         Monochrome: Boolean); override;
    //Draws a box of a file or class in the diagram.
    procedure DrawBox(Left, Top, Right, Bottom: Integer;
                      Rounding: Integer); override;
    //Draws selection markers at a box of a file or class in the diagram.
    procedure DrawBoxSelection(Left, Top, Right, Bottom: Integer;
                               HalfSize: Integer); override;
    //Draws some text.
    procedure DrawText(Top, Left, Right: Integer; const Text: String;
                       Center: Boolean; Style: TFontStyles;
                       Color: TColor); override;
    //Draws a line.
    procedure DrawLine(Xs, Ys, Xe, Ye: Integer); override;
    //Draws an icon representing a scope of a member of a record-like type.
    procedure DrawScopeIcon(X, Y: Integer; Scope: TScope); override;

    property SVGFile: TBufferStream read FSVGFile write FSVGFile;
    property BaseLineOffset: Integer read FBaseLineOffset
                                     write FBaseLineOffset;
  end;












  { * * *  ***  * * *  ***   TAssociation   ***  * * *  ***  * * *  }

  TBox = class;               //base class of any "box" inside the diagram



  //the different kinds of associations available in a diagram
  //~see TAssociation
  TAssociationKind = (
                      //class Source is a child of class Destination
                      akInheriting,
                      //class Source implements interface Destination
                      akImplementing,
                      //class Source has a field or property of type class
                      akUsingClass,                      //Destination
                      //file Source uses file Destination (not in the interface
                      akUsingFile,                       //part)
                      //unit Source uses file Destination in its interface
                      akUsingInterface);


  {Expresses an association between boxes in the diagram. It contains also
   methods to draw it and to test whether it should be drawn. }
  TAssociation = class
  private
    FDiagram: TDiagram;        //the diagram containing it and several options
    FSource: TBox;             //the box from where the association emerges
    FDestination: TBox;        //the box where the association points to
    FKind: TAssociationKind;   //the kind of the association

  public
    //Creates the association with all its properties.
    constructor Create(Diagram: TDiagram; Source, Destination: TBox;
                       Kind: TAssociationKind);

    //Tests whether the association is filtered and shouldn't be drawn.
    function IsFiltered: Boolean;

    //Draws the association.
    procedure Draw(Drawer: TDiagramDrawer; const Size, Pos: TPoint;
                   Monochrome: Boolean);


    property Diagram: TDiagram read FDiagram;
    property Source: TBox read FSource;
    property Destination: TBox read FDestination;
    property Kind: TAssociationKind read FKind;
  end;