uicguihelpdata.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) 2002-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 UICGUIHelpData;

{Contains the class to hold the data about a GUI to generate a help about,
 ~[link TICGUIHelpData], and a list of all the GUI/forms/windows,
 ~[link TICGUIHelpList].
}

interface

uses Windows, Classes,
     UGenerationMessages,
     UMakeDoc,
     UILComment,
     UGUIHelpData;



      //the separator between the topic and the base name when generating help
      //on a GUI
const GUIHelpTopicSeparator = '#';
      //the prefix for special sections of topics when generating help on a GUI
      GUIHelpTopicSpecialPrefix = '.';




type

   { * * *  ***  * * *  ***   TICGUIComment   ***  * * *  ***  * * *  }

  {Contains the documentation of a component of a GUI or an extra topic. }
  TICGUIComment = class(TICSimpleComment)
  private
    //the name of the topic in the help of a GUI, of the documented component
    FName: String;
    //the heading for the help topic
    FHeading: String;

    //whether the comment has been referenced/used
    FReferenced: Boolean;
  public

    property Name: String read FName write FName;
    property Heading: String read FHeading write FHeading;
    property Referenced: Boolean read FReferenced write FReferenced;
  end;



  //defined below, so Ctrl-Shift-Up/Down does still work:

  //list of all comments about the GUI
  TICGUICommentList = class;




   { * * *  ***  * * *  ***   TICGUIHelpData   ***  * * *  ***  * * *  }


  {Does not only contain the parsed data of the log files for the GUI, but also
   the comments as the documentation of the GUI from the accompanying .txt
   files is a ~[linkUnit UICNodes COM] - Comment Object Model. }
  TICGUIHelpData = class(TPureGUIHelpData)
  private
    //title of the page to show (and sort) by
    FTitle: String;


    //contains all defined aliases of components to other components to share
    //their documentation
    FAliases: TStringList;

    //list of the manually defined links on the image of the form;
    //the string is the link, the object is the position (type PRect)
    FManualLinks: TStringList;


    //contains the node for the image of the GUI with the links to the
    //documentation of the components
    FImage: TICSimpleComment;
    //the default comment for not documented components
    FDefaultComment: TICGUIComment;
    //a preface to use when generating the documentation
    FPreface: TICGUIComment;
    //an epilogue to use when generating the documentation
    FEpilogue: TICGUIComment;
    //the documentations of the components;
    //in same order as read from the files, as they will be in the final
    //documentation
    FComments: TICGUICommentList;

    //sorted mapping from the names of the comments to their indices in
    //~[link FComments]
//    FCommentMapping: TStringList;


    //Returns the title or, if no title is defined, the base name of the file.
    function GetTitleOrBaseName: String;

  public
    //Creates the object and parses the log file.
    constructor Create(const LogFileName: String;
                       MessageLogger: TMakeDoc;
                       MessageID: TMessageID; MessageNumber: TMessageNumber);
    //Frees the parsed data and the object.
    destructor Destroy; override;


    //Adds a manual link to the image.
    function AddManualLink(const Position, Link: String): Boolean;

    //Gets the comment with specified name or nil if it has not been defined.
//    function GetComment(const Name: String): TICGUIComment;




    property Title: String read FTitle write FTitle;
    property TitleOrBaseName: String read GetTitleOrBaseName;


    property Aliases: TStringList read FAliases;
    property ManualLinks: TStringList read FManualLinks;

    property Image: TICSimpleComment read FImage write FImage;
    property DefaultComment: TICGUIComment read FDefaultComment
                                           write FDefaultComment;
    property Preface: TICGUIComment read FPreface write FPreface;
    property Epilogue: TICGUIComment read FEpilogue write FEpilogue;

    property Comments: TICGUICommentList read FComments write FComments;
  end;






   { * * *  ***  * * *  ***   TICGUIHelpList   ***  * * *  ***  * * *  }



  {The list of objects with data about a GUI to generate a help about it. This
   is really only a simple list with some state information. }
  TICGUIHelpList = class
  private
    //list of files to parse and generate help on a GUI from.
    FGUIHelpFiles: TStringList;

    //list of ~[linkClass TICGUIHelpData]s of parsed files
    FGUIHelpData: TList;

    //index of the current file to generate documentation about a GUI;
    //-1 for none
    FCurrentGUIHelpFileIndex: Integer;
    //current topic in the current file to generate documentation about a GUI
    FCurrentGUIHelpTopic: String;

    //Returns the current file of the GUI the help is generated about.
    function GetCurrentGUIHelpFile: TICGUIHelpData;
    //Returns an data item about a GUI to generate help about.
    function GetData(Index: Integer): TICGUIHelpData;
  public
    //Creates the list of the data of the GUI to generate documentation about.
    constructor Create;
    //Frees the object and all read data of the GUI.
    destructor Destroy; override;

    //Parses all log files to generate a help for a GUI.
    procedure ParseAllLogFiles(GUIHelpFileList: TStrings;
                               MessageLogger: TMakeDoc;
                               MessageID: TMessageID;
                               MessageNumber: TMessageNumber);


    //Returns the number of parsed files with data about a GUI.
    function Count: Integer;
    //Returns the index of the parsed file with data about a GUI in the list.
    function IndexOf(Data: TICGUIHelpData): Integer;


    property Data[Index: Integer]: TICGUIHelpData read GetData; default;

    property GUIHelpFiles: TStringList read FGUIHelpFiles;
    property CurrentGUIHelpFileIndex: Integer read FCurrentGUIHelpFileIndex
                                              write FCurrentGUIHelpFileIndex;
    property CurrentGUIHelpFile: TICGUIHelpData read GetCurrentGUIHelpFile;
    property CurrentGUIHelpTopic: String read FCurrentGUIHelpTopic
                                         write FCurrentGUIHelpTopic;
  end;





   { * * *  ***  * * *  ***   TICGUICommentList   ***  * * *  ***  * * *  }

{$UNDEF ListTemplateUseIndexOf}
{$UNDEF ListTemplateItemIsMethod}
{$DEFINE ListTemplateItemIsObject}
{$DEFINE ListTemplateItemMayBeFreed}
{$DEFINE ListTemplateItemFreedByDefault}
{$DEFINE ListTemplateDoNotEndType}


  //the items for the template list to use
  TListTemplateListItem = TICGUIComment;

{$INCLUDE ..\..\General\Templates\ListTemplate.inc}

  //a list of comments about the components of the GUI
  TICGUICommentList

{$INCLUDE ..\..\General\Templates\ListTemplate.inc}

    //Searches a comment by its name.
    function GetIndexOfName(const Name: String): Integer;
  end;

  //alias for the list to be used by the implementations of the methods
  TListTemplate = TICGUICommentList;




implementation