uguihelpdata.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 UGUIHelpData;

{Contains the class ~[linkClass TPureGUIHelpData] for the data read from the
 generated log file for the help on a GUI - a Graphical User Interface. That
 input method is used in Delphi programs in most cases. }

interface

uses Windows, Classes,
     UGenerationMessages, UMakeDoc;


type

   { * * *  ***  * * *  ***   TLoggedComponents   ***  * * *  ***  * * *  }

  {A component as read from the log file. }
  TLoggedComponent = record
    //the name of the component
    Name: String;
    //the position of the component
    Position: TRect;
    //the help context of the component
    HelpContext: THelpContext;
    //whether the component is within the contraint
//    InConstraint: Boolean;
  end;


  //a list of components as read from a log file;
  //declared at the end of the interface section to allow Ctrl-Shift-Up/Down
  //to work in the Delphi IDE
  TLoggedComponents = class;





   { * * *  ***  * * *  ***   TPureGUIHelpData   ***  * * *  ***  * * *  }

  {Parses and manages all raw data from the log file to generate help on a
   GUI - Graphical User Interface. That input method is in most cases used in
   Delphi programs.  It might be extended by sub classes to also hold the
   comments for the components of the GUI. }
  TPureGUIHelpData = class
  private
    //the path of the log file that has been parsed
    FLogFilePath: String;

    //generator to add the messages to
    FMessageLogger: TMakeDoc;
    //ID of the messages when adding to the generator
    FMessageID: TMessageID;
    //number of the messages when adding to the generator
    FMessageNumber: TMessageNumber;

    //the help context of the window itself
    FWindowHelpContext: THelpContext;
    //whether the log of the form has been constrained
    FHasConstraint: Boolean;


    //the read components from the log
    FLoggedComponents: TLoggedComponents;

    //contains the logged aliases of components to other ones;
    //labels are logged as an alias to their FocusControl property
    FLoggedAliases: TStringList;


    //Returns the base name of the file.
    function GetBaseName: String;


    //Parses a definition of a component in the GUI.
    function ParseComponent(const Line: String): Boolean;
    //Parses a definition of an alias of a component.
    procedure ParseAlias(Line: String);

    //Parses the log file.
    procedure ParseLogFile;
  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;




    property LogFilePath: String read FLogFilePath;
    property BaseName: String read GetBaseName;

    property WindowHelpContext: THelpContext read FWindowHelpContext;
    property HasConstraint: Boolean read FHasConstraint;
    property LoggedComponents: TLoggedComponents read FLoggedComponents;
    property LoggedAliases: TStringList read FLoggedAliases;
  end;





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

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

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

  {A list of components as read from a log file. }
  TLoggedComponents

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

    //Returns the index of the component with the name or -1.
    function FindComponent(const Name: String): Integer;
  end;


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













//Parses the given position of the component/link target.
function ParseRectString(Definition: String; var Rect: TRect): Boolean;

implementation

uses SysUtils,
     UPascalConsts;





{Parses the given position of the component/link target.
~param Definition the string defining the position
~param Rect       the position will be returned through this parameter
~result whether the definition was valid and could be parsed }
function ParseRectString(Definition: String; var Rect: TRect): Boolean;
var      i              :Integer;     //index of separators in the definition
         Code           :Integer;     //index of error while reading number
begin
 Result := False;                     //not completely parsed so far

 Definition := Trim(Definition);      //clean it up
 i := pos(',', Definition);           //get first separator
 if i <> 0 then
  begin                                 //get first value - x-position
   Val(copy(Definition, 1, i - 1), Rect.Left, Code);
   if Code = 0 then
    begin
     Delete(Definition, 1, i);
     i := pos(',', Definition);           //get next separator
     if i <> 0 then
      begin                                 //get the second value - y-position
       Val(copy(Definition, 1, i - 1), Rect.Top, Code);
       if Code = 0 then
        begin
         Delete(Definition, 1, i);
         i := pos(',', Definition);           //get last separator
         if i <> 0 then
          begin                                 //get the third value
           Val(copy(Definition, 1, i - 1), Rect.Right, Code);
           if Code = 0 then
            begin
             Delete(Definition, 1, i);
             Val(Definition, Rect.Bottom, Code);  //get the last value
             Result := Code = 0;                  //also correct?
            end;
          end;
        end;
      end;
    end;
  end;
end;















   { * * *  ***  * * *  ***   TPureGUIHelpData   ***  * * *  ***  * * *  }


{Creates the object and parses the log file.
~param LogFileName   the name of the log file to parse
~param MessageLogger the generator to log all messages to
~param MessageID     the ID of the messages to use when they are logged
~param MessageNumber the number of the message to use when they are logged }
constructor TPureGUIHelpData.Create(const LogFileName: String;
                                    MessageLogger: TMakeDoc;
                                    MessageID: TMessageID;
                                    MessageNumber: TMessageNumber);
begin
 inherited Create;                               //create the object

 FLogFilePath := LogFileName;                    //save parameters
 FMessageLogger := MessageLogger;
 FMessageID := MessageID;
 FMessageNumber := MessageNumber;