uguihelpindexcontent.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) 2007-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 UGUIHelpIndexContent;

{Contains the class ~[link TGUIMainIndexEntry] to create a simple tree that can
  be transformed to the ~[linkUnit UICNodes COM] - Comment Object Model - as
  an alternative content for the main index of the documentation.
}

interface


type

   { * * *  ***  * * *  ***   TGUIMainIndexEntry   ***  * * *  ***  * * *  }


  {The kind of links that can be expressed with the nodes in the tree. }
  TGUIMainIndexLinkKind = (
                           //the entry is not a link, only its text should be
                           //shown
                           gmilkNone,
                           //the entry is a link to a comment of a GUI
                           gmilkGUI,
                           //the entry is a link to a page of the (additional)
                           //user documentation
                           gmilkUserDoc,
                           //the entry is a link to an external resource
                           gmilkExtern);


  {An entry in the tree to be used as an alternative content for the main index
   of the documentation. It will probably be more like a list, maybe with a
   second level. The entries are transformed to the ~[linkUnit UICNodes COM]
   with the method ~[link UICCommentDoc.TICCommentDoc.CreateCOMFromEntries]. }
  TGUIMainIndexEntry = class
  private
    //the kind of link represented by this entry
    FLinkKind: TGUIMainIndexLinkKind;

    //the target of the link, the format depends on the kind of the link
    //
    //for simple texts this value is ignored~[br]
    //for external links it is treated verbatim~[br]
    //for links into the user documentation it is used as the name of the page
    //to link to~[br]
    //for the links into the documentation of a GUI the target is described
    //with two parts, first the base name of the GUI to link to (same name as
    //the log file without extension), then optionally and separated by a '#',
    //the second part being the comment for the GUI to link to, if none has
    //been specified the link will point to the main topic of the GUI
    FLinkTarget: String;

    //the text to be shown for the link, if empty '' the heading of the target
    //of the link should be used
    FText: String;

    //the list of child/sub entries, whose ~[link Parent] property points to
    //this object
    FSubTopics: array of TGUIMainIndexEntry;

    //the parent entry containing this element in its ~[link SubTopics]
    //property and will be freeing it
    FParent: TGUIMainIndexEntry;

    //Returns one of the child/sub entries of this entry.
    function GetSubTopic(Index: Integer): TGUIMainIndexEntry;
  public
    //Unlinks this entry from its parent entry and frees also all sub entries.
    destructor Destroy; override;


    //Appends the entry to the list of sub entries.
    procedure AppendEntry(Entry: TGUIMainIndexEntry);
    //Changes the order of two adjacent sub entries.
    procedure SwapSubTopics(UpperIndex: Integer);
    //Inserts an entry as an sub entry after the specified sub entry.
    procedure InsertEntryAfter(After, Entry: TGUIMainIndexEntry);
    //Inserts an entry as an sub entry at the specific index.
    procedure InsertEntry(Index: Integer; Entry: TGUIMainIndexEntry);
    //Unlinks a sub entry so its ~[link Parent] property will be nil.
    function UnlinkEntry(Index: Integer): TGUIMainIndexEntry;


    //Returns the index of this entry in the list of sub entries of its parent.
    function ParentIndex: Integer;

    //Returns the number of sub entries of this entry.
    function SubTopicCount: Integer;




    property LinkKind: TGUIMainIndexLinkKind read FLinkKind write FLinkKind;
    property LinkTarget: String read FLinkTarget write FLinkTarget;
    property Text: String read FText write FText;

    property Parent: TGUIMainIndexEntry read FParent;
    property SubTopics[Index: Integer]: TGUIMainIndexEntry read GetSubTopic;
  end;



implementation



   { * * *  ***  * * *  ***   TGUIMainIndexEntry   ***  * * *  ***  * * *  }


{Unlinks this entry from its parent entry and frees also all sub entries. }
destructor TGUIMainIndexEntry.Destroy;
var        i                 :Integer;  //counter through all sub topics
begin
 if assigned(FParent) then              //is a sub entry?
  FParent.UnlinkEntry(ParentIndex);       //notify its parent from its deletion

 for i := Low(FSubTopics) to High(FSubTopics) do //free all sub entries
  FSubTopics[0].Free;

 assert(Length(FSubTopics) = 0);

 inherited Destroy;                     //free the object
end;



{Returns one of the child/sub entries of this entry.
~param Index the index of the sub entry to return,
             must be between 0 and ~[link SubTopicCount] - 1
~result the requested sub entry }
function TGUIMainIndexEntry.GetSubTopic(Index: Integer): TGUIMainIndexEntry;
begin
 assert((Index >= 0) and (Index < Length(FSubTopics)));
 Result := FSubTopics[Index];           //return the entry at the position
end;



{Appends the entry to the list of sub entries.
~param Entry the entry to add as a sub entry }
procedure TGUIMainIndexEntry.AppendEntry(Entry: TGUIMainIndexEntry);
var       Index             :Integer;   //the index of the new entry
begin
 Index := Length(FSubTopics);           //get the next index
 SetLength(FSubTopics, Index + 1);      //enlarge the list
 FSubTopics[Index] := Entry;            //and assign the entry
 Entry.FParent := Self;                 //set the new parent of the entry
end;

{Changes the order of two adjacent sub entries.
~param UpperIndex the index of the sub entry to swap with the entry after it }
procedure TGUIMainIndexEntry.SwapSubTopics(UpperIndex: Integer);
var       SwapEntry         :TGUIMainIndexEntry;  //temporary variable to swap
begin
 assert(UpperIndex >= 0);
 assert(UpperIndex < Length(FSubTopics) - 1);

 SwapEntry := FSubTopics[UpperIndex + 1];         //save the lower value
 FSubTopics[UpperIndex + 1] := FSubTopics[UpperIndex]; //set it to the upper
 FSubTopics[UpperIndex] := SwapEntry;             //set upper to the lower
end;


{Inserts an entry as an sub entry after the specified sub entry.
~param After the sub entry after which the new one should be inserted
~param Entry the entry to add as a sub entry }
procedure TGUIMainIndexEntry.InsertEntryAfter(After,
                                              Entry: TGUIMainIndexEntry);
begin
 assert(After.Parent = Self);
 InsertEntry(After.ParentIndex + 1, Entry);
end;

{Inserts an entry as an sub entry at the specific index.
~param Index the index which the entry to be inserted should have
~param Entry the entry to add as a sub entry }
procedure TGUIMainIndexEntry.InsertEntry(Index: Integer;
                                         Entry: TGUIMainIndexEntry);
var       Count             :Integer;           //number of sub entry
begin
 assert(not assigned(Entry.Parent));
 assert(Index >= 0);
 assert(Index <= Length(FSubTopics));

 Count := Length(FSubTopics);
 SetLength(FSubTopics, Count + 1);              //enlarge the list
 Move(FSubTopics[Index], FSubTopics[Index + 1], //move all following entries
      (Count - Index) * SizeOf(FSubTopics[0]));
 FSubTopics[Index] := Entry;                    //assign the new entry
 Entry.FParent := Self;                         //set its new parent
end;

{Unlinks a sub entry so its ~[link Parent] property will be nil.
~param Index of the entry to be unlinked
~result the unlinked entry }
function TGUIMainIndexEntry.UnlinkEntry(Index: Integer): TGUIMainIndexEntry;
var      Count             :Integer;                //number of sub entry
begin
 assert(Index >= 0);
 assert(Index < Length(FSubTopics));

 Result := FSubTopics[Index];                       //get entry to be unlinked

 Count := Length(FSubTopics);
 Move(FSubTopics[Index + 1], FSubTopics[Index],     //fill the removed entry
      (Count - Index - 1) * SizeOf(FSubTopics[0]));
 SetLength(FSubTopics, Count - 1);                  //shorten the list

 Result.FParent := nil;                             //and unset its parent
end;





{Returns the index of this entry in the list of sub entries of its parent.
~result the index in the parent's list of sub entries }
function TGUIMainIndexEntry.ParentIndex: Integer;
begin
 assert(assigned(FParent));

 Result := Parent.SubTopicCount - 1;     //search itself in its parent's list
 while (Result >= 0) and (Parent.SubTopics[Result] <> Self) do
  Dec(Result);

 assert(Result >= 0);
end;


{Returns the number of sub entries of this entry.
~result the number of sub entries }
function TGUIMainIndexEntry.SubTopicCount: Integer;
begin
 Result := Length(FSubTopics);           //return the size of the list
end;



end.