listtemplate.inc

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) 2005-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/>.
}



{This file serves as a template for creating classes, like it is used in the
 C++ programming language. Simply include the file three time, twice for the
 declaration of the class, for instance in the interface of the unit, and
 as third for the implementation in the implementation part.~[br]
 This concept has a big contraint, a template can only be used once per pascal
 file. But you could create small dummy-units to create classes from the
 template and then use all those units from a central unit, re-defining the
 types to a type in the central unit, so only it has to be used by other
 pascal files.~[p]

 This file contains a template for a class acting like a list of items. Before
 you include the file the first time, you have to make sure the type
 ~[code TListTemplateListItem] is defined to the type of items the list should
 contain. After it has been included for the first time to prepare for the
 class only the name of the new to be created class has to follow (without the
 equal sign and any semicolons). Then it has to be included the second time.
 Thereafter it the type ~[code TListTemplate] has to be declared to have the
 same type as the new declared class, because it is used as the name of the
 class at the implementations of the methods.~[p]

 If ~[code ListTemplateDoNotEndType] is defined the final ~[code end] is not
 added, so the type is not ended and can be extended.~[p]

 If ~[code ListTemplateUseIndexOf] defined the methods ~[code IndexOf] and
 ~[code Remove] will be defined. If the items can not be compared directly,
 ~[code ListTemplateUseCompareFunction] has also do be defined and a compare
 function has to be declared as follows:~[br]~[code
 function CompareItems(const One, Two: TListTemplateListItem): Boolean;]~[br]
 For function/method pointer you can simply define
 ~[code ListTemplateItemIsMethod]~[p]

 If the items are objects, the compiler symbol ~[code ListTemplateItemIsObject]
 can be defined before including the file, then, if also
 ~[code ListTemplateItemMayBeFreed] is defined, the list may automatically free
 the objects. If this is done by default depends whether also
 ~[code ListTemplateItemFreedByDefault] is defined.

 ~[code ListTemplateItemAssignFromSelf] is a new define which shouldn't exist
 at all. When it is present the Method ~[code AddAll] will be declared. For
 that there needs to be a forward declaration of the new type. Because this
 feature was introduces later on and I'm currently to lazy to change all usages
 of the template, this define has been defined.

}

{
 TListTemplateListItem has to be defined to the base/item type!
 TListTemplate then has to be defined as the class type.
}


//{$DEFINE ListTemplateDoNotEndType}

//{$DEFINE ListTemplateItemAssignFromSelf}


//{$DEFINE ListTemplateUseIndexOf}
//  {$DEFINE ListTemplateUseCompareFunction}
//  {$DEFINE ListTemplateItemIsMethod}

//{$DEFINE ListTemplateItemIsObject}
//  {$DEFINE ListTemplateItemMayBeFreed}
//    {$DEFINE ListTemplateItemFreedByDefault}



(*  An Example:

...

interface

...

//here some defines, to specify how the list should be declared
{$DEFINE ListTemplateUseIndexOf}
{$DEFINE ListTemplateItemIsMethod}
{$UNDEF ListTemplateItemIsObject}
{$UNDEF ListTemplateItemMayBeFreed}
{$UNDEF ListTemplateItemFreedByDefault}
{$DEFINE ListTemplateItemAssignFromSelf}

//Item is the type of the items
  TListTemplateListItem = Item;

//List is the name the new type should have

  //forward declaration to be able to define an alias so the template can
  //reference itself
  List = class;

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

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

//List is again the name the new type should have
  List

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

...

implementation

...

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

...







*)





















{$IFNDEF ListTemplateItemIsObject}
 {$UNDEF ListTemplateItemMayBeFreed}
{$ENDIF}

{$IFNDEF ListTemplateItemMayBeFreed}
 {$UNDEF ListTemplateItemFreedByDefault}
{$ENDIF}






{$IFNDEF ListTemplateSecondRun}

 {$DEFINE ListTemplateSecondRun}


{$ELSE}
 {$IFNDEF ListTemplateThirdRun}

     {A simple list of items. }
//     TListTemplate


      = class
     private
       //number of items saved in the list, in ~[link FContent]
       FCount: Integer;
       //the items in the list, the number of valid items is in ~[link FCount]
       FContent: array of TListTemplateListItem;

{$IFDEF ListTemplateItemMayBeFreed}
       //if the objects (items) should be automatically freed
       FFreeItems: Boolean;
{$ENDIF}

       //Returns the current size/capacity of the list.
       function GetSize: Integer;

       //Sets an item in the list to another value.
       procedure SetItems(Index: Integer; const Value: TListTemplateListItem);
       //Sets the size/capacity of the list, can also truncate the content.
       procedure SetSize(Value: Integer);

     public
{$IFDEF ListTemplateItemMayBeFreed}
       //Creates a new list.
       constructor Create(FreeItems: Boolean =
 {$IFDEF ListTemplateItemFreedByDefault}
                                               True
 {$ELSE}
                                               False
 {$ENDIF}
                                                     );
{$ENDIF}

{$IFDEF ListTemplateItemMayBeFreed}
       //Free all items, if needed.
       destructor Destroy; override;
{$ENDIF}


       //Adds an item to the list.
       procedure Add(const Item: TListTemplateListItem);

       //Returns an item of the list.
       function Get(Index: Integer): TListTemplateListItem;

{$IFDEF ListTemplateUseIndexOf}
       //Returns the index of the element in the list or -1.
       function IndexOf(const Item: TListTemplateListItem): Integer;
{$ENDIF}


       //Returns the last item of the list.
       function Last: TListTemplateListItem;

       //Returns the last item of the list and removes it.
       function Pop: TListTemplateListItem;


{$IFDEF ListTemplateItemAssignFromSelf}
       //Adds all items of the other list.
       procedure AddAll(OtherList: TListTemplate);
{$ENDIF}





       //Removes an item from the list.
       procedure Delete(Index: Integer);

       //Removes several items from the list.
       procedure DeleteRange(StartIndex, EndIndex: Integer);


{$IFDEF ListTemplateUseIndexOf}
       //Removes an item from the list.
       function Remove(const Item: TListTemplateListItem): Boolean;

 {$IFDEF ListTemplateItemMayBeFreed}
       //Removes an item from the list without freeing it.
       function RemoveReference(const Item: TListTemplateListItem): Boolean;
 {$ENDIF}
{$ENDIF}


       //Removes all items from the list.
       procedure Clear;

       //Returns whether the list is empty.
       function IsEmpty: Boolean;



       property Size: Integer read GetSize write SetSize;
       property Count: Integer read FCount;

       //Can be used to access the contents of the list.
       property Items[Index: Integer]: TListTemplateListItem read Get
                                                             write SetItems;
                                                                       default;
{$IFDEF ListTemplateItemMayBeFreed}
       property FreeItems: Boolean read FFreeItems write FFreeItems;
{$ENDIF}

{$IFNDEF ListTemplateDoNotEndType}
     end;
{$ENDIF}






 {$DEFINE ListTemplateThirdRun}

//  implementation

 {$ELSE NOT ListTemplateSecondRun }