umfgenerate.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 UMFGenerate;

{Contains a page to generate the documentation about the parsed source code
 files or only with the user documentation. It is also the base class of the
 page to generate the documentation as a help about a GUI. }

interface

uses Classes, Forms, Controls, StdCtrls, ExtCtrls, 
     UMainFormFrame,
     UJADDState;

type
  {A page to generate the documentation about the parsed source code files or
   only with the user documentation. There are two buttons for this and
   controls to set the directory, in which the documentation will be generated,
   its file name is applicable and the name/title of the project to include. It
   is also the base class of the page to generate the documentation as a help
   about a GUI. }
  TMFGenerate = class(TMainFormFrame)
    ButtonEditAllOptions: TButton;
    ButtonGenerate: TButton;
    ButtonOnlyUserDoc: TButton;
    LabelDocPath: TLabel;
    EditDocPath: TEdit;
    ButtonBrowseDocDir: TButton;
    LabelFileName: TLabel;
    EditFileName: TEdit;
    CheckBoxUseJavadocCharacter: TCheckBox;
    LabelProjectName: TLabel;
    EditProjectName: TEdit;
    procedure ButtonEditAllOptionsClick(Sender: TObject);
    procedure ButtonGenerateClick(Sender: TObject);
    procedure ButtonBrowseDocDirClick(Sender: TObject);
    procedure CheckBoxUseJavadocCharacterClick(Sender: TObject);
  private
    //if only the user documentation should be generated
    FOnlyUserDoc: Boolean;

  protected
    //if the documentation has been generated
    FGenerated: Boolean;
    //if the documentation has been successfully generated
    FSuccesfullyGenerated: Boolean;


    //Called when the generator changes.
    procedure StateGeneratorChanged(State: TJADDState); override;


    //Generates the documentation.
    function DoGenerate: Boolean; virtual;
    //Prepares for and generates the documentation.
    function GenerateFrame: Boolean;
    //Handles the request to generate the documentation.
    procedure GenerateRequest; virtual;

    //Shows some of the options of the generator on the page.
    procedure ShowOptions;
    //Sets some of the options of the generator to the values set on the form.
    procedure SetDocGeneratorOptions;
  public
    //Creates the components, shows the options and allows dropping of files
    //(directories).
    constructor Create(Parent: TWinControl; State: TJADDState); override;
    //Saves the options of the generator and frees the frame.
    destructor Destroy; override;

    //Called sometimes when the frame is to be replaced by another frame.
    procedure SelectNextFrame(var NewFrameClass: TMainFormFrameClass;
                              IsNext: Boolean); override;

    //Called when some files are dropped on the form.
    procedure FilesDropped(Files: TStrings); override;
  end;


implementation

{$R *.dfm}

{$IFDEF LINUX}
 {$DEFINE DONT_USE_MESSAGEGRID}
{$ENDIF}

uses SysUtils, Dialogs,
{$IFDEF VER120}
     FileCtrl,
{$ENDIF}
     General, GeneralVCL,
     UCatExpert,
     UOptions, UGenerate,
     UMFGenerator, UMFExtractor,
{$IFDEF DONT_USE_MESSAGEGRID}
     UMFGenerateMessages_kyl;
{$ELSE}
     UMFGenerateMessages;
{$ENDIF}




{Creates the components, shows the options and allows dropping of files
 (the target directory).
~param Parent the component to show the frame in, preferably a TPanel or a
              similar component
~param State  the state of the program }
constructor TMFGenerate.Create(Parent: TWinControl; State: TJADDState);
begin
 inherited Create(Parent, State);             //create the page

 Include(FProperties, mffpAcceptsFileDrop);   //accept dropped files
end;


{Saves the options of the generator and frees the frame. }
destructor TMFGenerate.Destroy;
begin
 if Assigned(State) and State.Generate.GeneratorAvailable then
  SetDocGeneratorOptions;                 //save the options

 inherited Destroy;                       //free the page
end;




{Called sometimes when the frame is to be replaced by another frame. This
 method is ~[em not] always called before the frame is being replaced (and
 freed).
~param NewFrameClass the class of the frame that should replace this one
~param IsNext        if the next frame should be shown (instead of the previous
                     one) in some kind of an order }
procedure TMFGenerate.SelectNextFrame(var NewFrameClass: TMainFormFrameClass;
                                      IsNext: Boolean);
begin
 if IsNext then                                //next page shouldbe shown?
  begin
   //the generator's status text is empty?
   if not State.Generate.GeneratorAvailable or
      (State.Generate.GetGenerateStatusText = '') then
    NewFrameClass :=                             //skip the page
{$IFDEF DONT_USE_MESSAGEGRID}
                     TMFGenerateMessagesKylix;
{$ELSE}
                     TMFGenerateMessages;
{$ENDIF}
  end
 else
  //the generator does not use user documentation and helper objects?
  if not State.Generate.GeneratorUsesCommentEvaluators then
   if State.Generate.GeneratorUsesCommentExtractors then
    NewFrameClass := TMFExtractor                  //skip those pages
   else
    NewFrameClass := TMFGenerator;                 //skip those pages
end;



{Called when some files are dropped on the form.
~param Files the list of the dropped files }
procedure TMFGenerate.FilesDropped(Files: TStrings);
var       Path       :String;           //the dropped directory
begin
 Path := Files[0];                      //get the first dropped file/directory
 if not DirectoryExists(Path) then      //is not a directory?
  begin
   //set the base name of the dropped file
   EditFileName.Text := ChangeFileExt(ExtractFileName(Path), '');
   Path := ExtractFilePath(Path);          //and extract directory of the file
  end;
 if DirectoryExists(Path) then          //is (now) a directory?
  EditDocPath.Text := Path;               //set the new path
end;





{Called when the generator changes.
~param State the state that has been changed }
procedure TMFGenerate.StateGeneratorChanged(State: TJADDState);
begin
 //enable button for user documentation only, if the generator supports it
 ButtonOnlyUserDoc.Enabled := State.Generate.
                                            GeneratorSupportsUserDocumentation;
 //enable check box to toggle special characters inside comments only if the
 //generator supports comments
 CheckBoxUseJavadocCharacter.Enabled := State.Generate.
                                                GeneratorUsesCommentExtractors;

 ShowOptions;                             //show the options of the generator
end;














{Generates the documentation.
~result if the generation was successful }
function TMFGenerate.DoGenerate: Boolean;
begin
 Result := State.GenerateDocumentation(FOnlyUserDoc);
end;

{Prepares for and generates the documentation.
~result if the documentation has been generated successfully }
function TMFGenerate.GenerateFrame: Boolean;
begin
 SetDocGeneratorOptions;                   //set options

 Result := DoGenerate;                     //generate documentation
end;




{Handles the request to generate the documentation. Should call
 ~[link GenerateFrame] when the documentation should be generated. }
procedure TMFGenerate.GenerateRequest;
begin
 if FOnlyUserDoc or State.CompletelyParsed or   //the data is valid?
    (MessageDlg('No data has been parsed validly. If parsing was aborted, documentation of the incomplete data will probably be faulty and may crash the program.' + LineDelimiter + 
                'Are you sure, you want to create documentation of the data?',
                mtWarning, [mbYes, mbCancel],
                ButtonGenerate.HelpContext) = mrYes) then
  begin
   FGenerated := True;                            //generated the documentation
   FSuccesfullyGenerated := False;                //not successful so far

   FSuccesfullyGenerated := GenerateFrame;        //generate documentation
  end;
end;










{Shows some of the options of the generator on the page. }
procedure TMFGenerate.ShowOptions;
begin
 if State.Generate.GeneratorAvailable then
  begin
   EditDocPath.Text := State.Generate.DestPath;
   EditProjectName.Text := State.Generate.ProjectName;
   if State.Generate.GeneratorHasFileName then     //generates a main file?
    begin
     EditFileName.Color := EditDocPath.Color;        //"enable" the component
     EditFileName.Text := State.Generate.FileName;   //show name of the file
    end
   else
    EditFileName.ParentColor := True;                //"disable" the component
  end;

 if State.Generate.GeneratorUsesCommentExtractors then //uses comments?
  begin
   //don't set option when showing it
   CheckBoxUseJavadocCharacter.OnClick := nil;

   //show whether the special character has been changed to the same as for
   //Javadoc
   case State.Generate.UseJavadocCompatibilityCharacters of
     ynmYes:   CheckBoxUseJavadocCharacter.State := cbChecked;
     ynmNo:    CheckBoxUseJavadocCharacter.State := cbUnchecked;
     ynmMaybe: begin
                CheckBoxUseJavadocCharacter.AllowGrayed := True;
                CheckBoxUseJavadocCharacter.State := cbGrayed;
               end;
   else
    Assert(False);
   end;

   //"gray" state is only to show it, not as an action, so disable it if not
   //needed
   CheckBoxUseJavadocCharacter.AllowGrayed :=
                                  CheckBoxUseJavadocCharacter.State = cbGrayed;

   //handle user (input) again
   CheckBoxUseJavadocCharacter.OnClick := CheckBoxUseJavadocCharacterClick;
  end;
end;

{Sets some of the options of the generator to the values set on the form. }
procedure TMFGenerate.SetDocGeneratorOptions;
begin
 State.Generate.ProjectName := EditProjectName.Text; //set name of the project
 State.Generate.DestPath := EditDocPath.Text;       //and path of documentation
 if State.Generate.GeneratorHasFileName then        //has option "FileName"?
  State.Generate.FileName := EditFileName.Text;        //set it
end;













{Called when the button to edit all options of the generator and its helper
 objects sorted by their category is chosen.
~param Sender the sender of the event, ~[link ButtonEditAllOptions] }
procedure TMFGenerate.ButtonEditAllOptionsClick(Sender: TObject);
var       Wrapper    :TOptionWrapper;             //the encapsulating wrapper
begin
 SetDocGeneratorOptions;                          //save current options
                    
 //wrap the wrappers of all options of the different objects
 Wrapper := TCollectionOptionWrapper.Create(State.Generate.AllOptions);
 try
   EditOptionsByCategory(Wrapper);                  //edit all options
 finally
  Wrapper.Free;                                     //free the wrapper
 end;

 ShowOptions;                                     //show the edited options
end;

{Called when one of the buttons to generate documentation is clicked.
~param Sender the sender of the event, ~[link ButtonGenerate] or
              ~[link ButtonOnlyUserDoc] }
procedure TMFGenerate.ButtonGenerateClick(Sender: TObject);
var       WorkDir    :String;     //the current working directory
begin
 GetDir(0, WorkDir);              //get current working directory
 if (EditDocPath.Text <> '') or   //not empty directory or it is confirmed?
    (MessageDlg('No directory to generate the documentation in is set, this means the documentation will be generated in the current working directory:'#13 +
                WorkDir + #13 +
                'Are you sure about that?',
                mtConfirmation, [mbOK, mbAbort],
                EditDocPath.HelpContext) = mrOK) then
  begin
   FOnlyUserDoc := Sender <> ButtonGenerate;  //save if only user documentation
   GenerateRequest;                           //generate the documentation
  end
 else
  EditDocPath.SetFocus;                     //focus the control to fill it now
end;

{Called when the button to browse for the target directory of the generated
 documentation is clicked.
~param Sender the sender of the event, ~[link ButtonBrowseDocDir] }
procedure TMFGenerate.ButtonBrowseDocDirClick(Sender: TObject);
var       S        :String;       //the currently selected path
begin
 S := EditDocPath.Text;           //get the current path and show dialog
 if AskForRelativeDirectory('Select directory for the documentation (should be empty):',
                            S) then
  EditDocPath.Text := S;            //if successful, use the new path
end;

{Called when the checkbox to select the special character inside comments is
 changed.
~param Sender the sender of the event, ~[link CheckBoxUseJavadocCharacter] }
procedure TMFGenerate.CheckBoxUseJavadocCharacterClick(Sender: TObject);
begin
 if State.Generate.GeneratorUsesCommentExtractors then //supports comments?
  //set the special characters for compatibility for Javadoc or set defaul
  //values for JADD
  case CheckBoxUseJavadocCharacter.State of
    cbChecked:   State.Generate.UseJavadocCompatibilityCharacters := ynmYes;
    cbUnchecked: State.Generate.UseJavadocCompatibilityCharacters := ynmNo;
    cbGrayed:    State.Generate.UseJavadocCompatibilityCharacters := ynmMaybe;
  else
   Assert(False);
  end;

 //"gray" state is only to show it, not as an action, so disable it if not
 //needed
 CheckBoxUseJavadocCharacter.AllowGrayed :=
                                  CheckBoxUseJavadocCharacter.State = cbGrayed;
end;

end.