uoptionswizard.pas

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

~param Value      out: the value of the option
~result if the generator has a string option of the name }
function GetStringOption(Options: TOptionWrapper; OptionName: String;
                         var Value: String): Boolean;
var      Index          :Cardinal;                //index of the option
begin
 //search the option
 Result := Options.GetOptionIndex(OptionName, otString, Index);
 if Result then                                   //option found?
  Value := Options.Option[Index].StrData;           //return its value
end;

{Sets the value of a string option.
~param Options    the list of options to set the option in
~param OptionName the name of the option to set
~param Value      the value to set for the option
~result if the generator has a string option of the name }
function SetStringOption(Options: TOptionWrapper; OptionName: String;
                         Value: String): Boolean;
var      Index          :Cardinal;               //index of the option
         OptionValue    :TOptionValue;           //to set the option
begin
 //search the option
 Result := Options.GetOptionIndex(OptionName, otString, Index);
 if Result then                                  //option found?
  begin
   OptionValue.StrData := Value;
   Options.Option[Index] := OptionValue;           //set the new value
  end;
end;


{Checks whether the generator generates documentation in HTML format.
~param Generator the generator to check
~result whether the generator generates documentation in HTML format }
function CheckHTMLFormat(Generator: TMakeDoc): Boolean;
var      GeneratorClass :TClass;                //ancestor classes of generator
begin
 if Generator is TCommentDoc then               //can handle comments?
  begin
   GeneratorClass := Generator.ClassType;
   while (GeneratorClass <> TCommentDoc) and      //check class hierarchy
         not GeneratorClass.ClassNameIs('TBaseHTMLDoc') do
    GeneratorClass := GeneratorClass.ClassParent;
   Result := GeneratorClass <> TCommentDoc;
  end
 else
  Result := False;
end;


























   { * * *  ***  * * *  ***  TGeneratorOptionsWizard  ***  * * *  ***  * * *  }


{Creates the page and initializes its attributes.
~param Form         the form to show the page of the wizard on
~param Parent       the parent to show the components of the page on
~param Data         custom data for the wizard
~param PreviousPage the previous page of this page (to go back to) }
constructor TGeneratorOptionsWizard.Create(Form: TForm; Parent: TWinControl;
                                           Data: TObject;
                                           PreviousPage: TWizardPage);
begin
 inherited Create(Form, Parent, Data, PreviousPage);  //create the object

 FCaption := 'Use comments?';
 FHelpContext := 31101;
end;

{Returns the next page to be shown.
~result the next page to be shown }
function TGeneratorOptionsWizard.GetNextPage: TWizardPage;
begin
 //generator uses comments and comments should be used?
 if (TGeneratorManager(Data).TheGenerator is TCommentDoc) and
    ((assigned(FCheckBoxFileComment) and FCheckBoxFileComment.Checked) or
     (assigned(FCheckBoxIdentifierComment) and
      FCheckBoxIdentifierComment.Checked)) then
  begin                                     //create the next page
   Result := TCommentPositionsWizard.Create(Form, Parent, Data, Self);
   Result.SuperPage := SuperPage;
  end
 else
  Result := nil;                            //end this sub-thread
end;

{Called when the page should be shown.
~param PreviousPage the previously shown page or nil }
procedure TGeneratorOptionsWizard.ShowPage(PreviousPage: TWizardPage);
var       Generator              :TCommentDoc; //the currently chosen generator
          Value                  :Boolean;     //value of options
begin
 inherited ShowPage(PreviousPage);             //start the page

 //coming from the succeeding page?
 if assigned(FNextPage) and (PreviousPage = FNextPage) then
  begin
   FNextPage := nil;                             //no succeeding page again
   PreviousPage.Free;                            //free the succeeding page
  end;


 ShowText('Only options pertaining comments and their extraction from the source code can be set within this wizard. One of the reasons is, that these options are common in most real generators.' + LineDelimiter +
          'Of course there are lots of other options, after you finished with this string of pages of the wizard you may again edit all options of the generator to fine-tune it and also change options specific to the format.');

 assert(Data is TGeneratorManager);
 //generator uses comments?
 if TGeneratorManager(Data).TheGenerator is TCommentDoc then
  begin
   inc(FNewComponentTop, 10);

   ShowText('The first thing you can select is whether you want DelphiDoc to use comments. This can be differentiated for files and for identifiers (everything, that is not a file).');

   //get the current generator
   Generator := TCommentDoc(TGeneratorManager(Data).TheGenerator);

   //can use comments of files?
   if GetBooleanOption(Generator.Extractor.GetOptions, 'IgnoreFileComments',
                       Value) then
    //show option to select whether they should be used
    FCheckBoxFileComment := AddCheckBox('Use comments on &files?',
                                        not Value, CheckBoxClicked)
   else
    assert(False);

   //can use comments of identifiers?
   if GetBooleanOption(Generator.Extractor.GetOptions,
                       'IgnoreIdentifierComments', Value) then
    //show option to select whether they should be used
    FCheckBoxIdentifierComment := AddCheckBox('Use comments on &identifiers?',
                                              not Value, CheckBoxClicked)
   else
    assert(False);
  end; //if Generator is TCommentDoc

 CheckBoxClicked(nil);                          //update buttons
end;

{Called when the page should no longer be shown, but not when the wizard is
 ended.
~param NewPage the page that will be shown instead }
procedure TGeneratorOptionsWizard.HidePage(NewPage: TWizardPage);
var       Generator              :TCommentDoc; //the currently chosen generator
begin
 //generator uses comments?
 if TGeneratorManager(Data).TheGenerator is TCommentDoc then
  begin
   //get the current generator
   Generator := TCommentDoc(TGeneratorManager(Data).TheGenerator);

   //comments of files can be ignored?
   if assigned(FCheckBoxFileComment) then
    SetBooleanOption(Generator.Extractor.GetOptions,   //set the option
                     'IgnoreFileComments', not FCheckBoxFileComment.Checked);

   //comments of identifiers can be ignored?
   if assigned(FCheckBoxIdentifierComment) then
    SetBooleanOption(Generator.Extractor.GetOptions,   //set the option
                     'IgnoreIdentifierComments',
                     not FCheckBoxIdentifierComment.Checked);
  end;

 FCheckBoxFileComment := nil;                  //controls will be deleted
 FCheckBoxIdentifierComment := nil;

 inherited HidePage(NewPage);                  //hide the page
end;


{Called when the state of one of the checkboxes is changed.
~param Sender the sender of the event, either ~[link FCheckBoxFileComment] or
              ~[link FCheckBoxIdentifierComment] }
procedure TGeneratorOptionsWizard.CheckBoxClicked(Sender: TObject);
begin
 if (TGeneratorManager(Data).TheGenerator is TCommentDoc) and
    ((assigned(FCheckBoxFileComment) and FCheckBoxFileComment.Checked) or
     (assigned(FCheckBoxIdentifierComment) and
      FCheckBoxIdentifierComment.Checked)) then  //at least some comments used?
  Include(FButtonsEnabled, wbNext)                 //there is a next page
 else
  Exclude(FButtonsEnabled, wbNext);                //end of options
 RequestButtonUpdate;
end;













   { * * *  ***  * * *  ***  TCommentPositionsWizard  ***  * * *  ***  * * *  }


{Creates the page and initializes its attributes.
~param Form         the form to show the page of the wizard on
~param Parent       the parent to show the components of the page on
~param Data         custom data for the wizard
~param PreviousPage the previous page of this page (to go back to) }
constructor TCommentPositionsWizard.Create(Form: TForm; Parent: TWinControl;
                                           Data: TObject;
                                           PreviousPage: TWizardPage);
begin
 inherited Create(Form, Parent, Data, PreviousPage);  //create the object

 FCaption := 'Where to search for comments?';
 FHelpContext := 31102;
end;

{Returns the next page to be shown.
~result the next page to be shown }
function TCommentPositionsWizard.GetNextPage: TWizardPage;
begin
 //current generator uses comments?
 if TGeneratorManager(Data).TheGenerator is TCommentDoc then
  begin                                     //create the next page
   Result := TCommentFilterWizard.Create(Form, Parent, Data, Self);
   Result.SuperPage := SuperPage;
  end
 else
  Result := nil;                            //end this sub-thread
end;

{Called when the page should be shown.
~param PreviousPage the previously shown page or nil }
procedure TCommentPositionsWizard.ShowPage(PreviousPage: TWizardPage);
var       Generator              :TCommentDoc; //the currently chosen generator
          Value                  :Boolean;     //value of the options
begin
 inherited ShowPage(PreviousPage);             //start the page

 //generator uses comments?
 if TGeneratorManager(Data).TheGenerator is TCommentDoc then
  begin
   ShowText('Here you can select where comments should be searched.');
   inc(FNewComponentTop, 10);

   //get the current generator
   Generator := TCommentDoc(TGeneratorManager(Data).TheGenerator);

   //can use comments of files?
   if GetBooleanOption(Generator.Extractor.GetOptions,
                       'IgnoreFileComments', Value) then
    begin
     if not Value then                         //comments of files are used?
      //can use comments of files before and after the first token?
      if GetBooleanOption(Generator.Extractor.GetOptions,
                          'FileCommentAfterFirstStatement', Value) then
       begin
        //show option to select where they should be searched
        ShowText('The comment for the file is the first comment in the file. But you can set this option so, that only the first comment after the first token is considered. ' +
                 'That way you can for instance skip the legal comment, like used in DelphiDoc''s source.');
        FCheckBoxFileCommentAfterFirstStatement :=
                    AddCheckBox('&File comment after first statement?', Value);
        inc(FNewComponentTop, 10);
       end
      else
       assert(False);
    end
   else
    assert(False);

   //can use comments of identifiers
   if GetBooleanOption(Generator.Extractor.GetOptions,
                       'IgnoreIdentifierComments', Value) then
    begin
     if not Value then                         //their comments are used?
      begin
       //can search comments of identifiers at their forward- and their final
       //declaration?
       if GetBooleanOption(Generator.Extractor.GetOptions,
                           'GetForwardComments', Value) then
        begin
        //show option to select where they should be searched
        ShowText('Some identifiers, like functions and classes, can have forward declarations. Here you can define whether you want the comment collected at these forward declarations or always at the real/implementating declaration.');
         FCheckBoxIdentifierCommentAtForward :=
               AddCheckBox('Get comments from the first &declaration?', Value);
        end
       else
        assert(False);

       //can also search at the other position?
       if GetBooleanOption(Generator.Extractor.GetOptions,
                           'FallBackToOtherPositionForComment', Value) then
        begin
         //show option to select whether the other position should also be
         //searched
         ShowText('For identifiers with forward declarations DelphiDoc can try the other declaration, if at the first tested one no comment could have been found.');
         FCheckBoxIdentifierCommentFallBack :=
                           AddCheckBox('Fall back to &other position?', Value);
        end
       else