Auto List Utilities Library 1.0.4

Delphi 6 to 2009 and Kylix 3 Implementation

by Dieter Köhler


LICENSE

The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at "http://www.mozilla.org/MPL/"

Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.

The Original Code is "AutoListUtils.pas".

The Initial Developer of the Original Code is Dieter Köhler (Heidelberg, Germany, "http://www.philo.de/"). Portions created by the Initial Developer are Copyright (C) 2003-2008 Dieter Köhler. All Rights Reserved.

Alternatively, the contents of this file may be used under the terms of the GNU General Public License Version 2 or later (the "GPL"), in which case the provisions of the GPL are applicable instead of those above. If you wish to allow use of your version of this file only under the terms of the GPL, and not to allow others to use your version of this file under the terms of the MPL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the GPL. If you do not delete the provisions above, a recipient may use your version of this file under the terms of any one of the MPL or the GPL.


Introduction

The Auto List Utilities Library contains various components for working with lists of different kind. The speciality of these components is that they interact via notification messages similar to Delphi's data base components. The latest version of this software is available at <http://www.philo.de/xml/>.


General Classes

Exception Classes
EAutoListException = class(Exception);
Event Prototypes
TUtilsPositionChangeEvent = procedure(Sender: TObject; OldPos, NewPos: Integer) of object;
Function Classes
TUtilsStringCompare = function(const S1, S2: string): Integer;
Constant Classes
TUtilsAliasOpt = (aoOff, aoFull, aoPrefix);
Helper Methods
procedure AutoListError(Msg: string; Data: Integer);
Defined Resourcestrings

These strings are used for the error messages of exceptions.


Basic List and Iterator Classes

Bookmark Classes

The bookmark classes are internally used in the TUtilsCustomIterator class to bookmark the iterator's position.

TUtilsBookmark = class
TUtilsBookmarkStack = class(TObjectStack)
TUtilsCustomIteratorList = class(TComponent)

TUtilsCustomIteratorList is the base class for all automated lists. It introduces a lot of protected methods and properties which can be modified or published in derived components.

Public Properties
IsActive: Boolean (readonly)

'True' if the list is currently active; 'False' otherwise.

Public Methods
constructor Create(AOwner: TComponent); override;

Creates a new TUtilsCustomIteratorList component.

Parameters:

destructor Destroy; override;

Destroys the TUtilsCustomIteratorList instance and frees its memory. Do not call Destroy directly in an application. Call Free instead, which checks for a nil reference before calling Destroy.

TUtilsCustomIterator = class(TComponent)

TUtilsCustomIterator is the base class for all iterators of automated lists.

Published Properties
FollowItem: Boolean

If FollowItem is true, operations behave has follows:
Exchange: If the item at the current position is involved, the position follows the item.
Delete: If an item before the current position is deleted, the position is decremented. If the item at the current position is deleted, the position is set offleft.
InsertBefore: If an item is inserted somewhere before the current position, the position is incremented.
If FollowItem is false, operations behave has follows:
Exchange: If the item at the current position is involved, the position nevertheless remains the same.
Delete: If the position is offright, it remains offright while the position is decremented. If the position is not offright and an item before or at the current position is deleted, the position nevertheless remains the same.
InsertBefore: If an item is inserted somewhere before the current position, the position nevertheless remains the same.

Published Events

If an operation triggers more than one event, they are called in the following sequence:

  1. OnListModified
  2. OnPositionChanged
  3. OnItemChanged

Event calls can be suppressed by calling BeginUpdate which increases UpdateCount by one. As long as UpdateCount is not 0, no event is triggered. If UpdateCount is set to 0 by calling EndUpdate, an OnListModified event is triggered if an item in the list was added, deleted or modified since the last time UpdateCount was 0. Likewise, an OnPositionChanged event is triggered if the Position has changed since the last time UpdateCount was 0. And an OnItemChanged event is triggered, when the item was at least changed once since the last time UpdateCount was 0 (no matter whether the item was changed back to its original state if it was repeatedly changed, i.e. an OnItemChanged event is triggered anyway in this case.)

OnPositionChanged: TUtilsPositionChangeEvent

Triggered whenever Position has changed.

OnItemChanged: TNotifyEvent

Triggered whenever the value or the item itself has changed.

OnListModified: TNotifyEvent

Triggered whenever an item in the list was added, deleted or modified.

Public Properties
UpdateCount: Integer (readonly)

Counts the number of times BeginUpdate was called without a corresponding call to EndUpdate.

General Public Methods
constructor Create(AOwner: TComponent); override;

Creates a new TUtilsCustomIterator component.

Parameters:

destructor Destroy; override;

Destroys the TUtilsCustomIterator instance and frees its memory. Do not call Destroy directly in an application. Call Free instead, which checks for a nil reference before calling Destroy.

Public Methods for Movements
procedure First; virtual;

Sets the iterator's position to the first item of the associated list.

procedure Last; virtual;

Sets the iterator's position to the last item of the associated list.

procedure Prior; virtual;

Sets the iterator's position to the privious item of the associated list.

procedure Next; virtual;

Sets the iterator's position to the next item of the associated list.

procedure Go(const Index: Integer); virtual;

Sets the iterator's position to the specified value.

Parameters:

Exceptions:

Public Methods for Bookmarking
procedure Mark; virtual;

Sets a bookmark by putting the current position on the internal bookmark stack.

procedure Return; virtual;

Resets the position to the value stored at the top of the internal bookmark stack and removes the value from the stack.

Exceptions:

Public Methods for Event Flow Control

Event calls can be suppressed by calling BeginUpdate which increases UpdateCount by one. As long as UpdateCount is not 0, no event is triggered. If UpdateCount is set to 0 by calling EndUpdate, an OnListModified event is triggered if an item in the list was added, deleted or modified since the last time UpdateCount was 0. Likewise, an OnPositionChanged event is triggered if the Position has changed since the last time UpdateCount was 0. And an OnItemChanged event is triggered, when the item was at least changed once since the last time UpdateCount was 0 (no matter whether the item was changed back to its original state if it was repeatedly changed, i.e. an OnItemChanged event is triggered anyway in this case.)

procedure BeginUpdate; virtual;

Prevents event calls until the EndUpdate method is called.

procedure EndUpdate; virtual;

Reenables event calls that were turned off with the BeginUpdate method.

Public Methods for Iterator Position Inquiring
function Position: Integer; virtual;

Returns the current position of the iterator.

Return Value:

function IsFirst: Boolean; virtual;

Determines whether the iterator is currently positioned on the first item of the associated list.

Return Value:

function IsLast: Boolean; virtual;

Determines whether the iterator is currently positioned on the last item of the associated list.

Return Value:

function Offleft: Boolean; virtual;

Determines whether the iterator is currently positioned off the left edge of the associated list.

Return Value:

function Offright: Boolean; virtual;

Determines whether the iterator is currently positioned off the right edge of the associated list.

Return Value:

function Offlist: Boolean; virtual;

Determines whether the iterator is currently positioned off the left or right edge of the associated list.

Return Value:

Public Methods for Inquiring General List Attributes
function Count: Integer; virtual;

Returns the number of items in the associated list.

Return Value:

function Empty: Boolean; virtual;

Returns whether the associated list is empty.

Return Value:


Object List and Iterator Classes

TUtilsCustomObjectIteratorList = class(TUtilsCustomIteratorList)

TUtilsCustomObjectIteratorList is the base class for all automated object lists. It modifies some of the protected methods inherited from TUtilsCustomIteratorList to work with object and introduces some additional protected methods and properties.

Public Properties
CanModify: Boolean (readonly)

'True' if the list can be modified; 'False' otherwise.


String List and Iterator Classes

TUtilsCustomStringIteratorList = class(TUtilsCustomIteratorList)

TUtilsCustomStringIteratorList is the base class for all automated string lists. It modifies some of the protected methods inherited from TUtilsCustomIteratorList to work with strings and introduces some additional protected methods and properties.

Public Properties
CanModify: Boolean (readonly)

'True' if the list can be modified; 'False' otherwise.

TUtilsCustomAliasedStrings = class(TUtilsCustomStringIteratorList)

TUtilsCustomAliasedStrings is the base class for all automated string lists which are connected with a TUtilsCustomIteratorAliases component. It modifies some of the protected methods inherited from TUtilsCustomStringIteratorList and introduces some additional protected methods and properties.

TUtilsAutoStrings = class(TUtilsCustomAliasedStrings)

TUtilsAutoStrings hold an automated string lists which are connected with a TUtilsCustomIteratorAliases component.

Published Properties
AliasOpt: TUtilsAliasOpt (default: aoOff)

Specifies how aliases from an object holding alias definition, referenced by the Aliases property, are applied. Possible values are:

Aliases: TUtilsCustomIteratorAliases

Specifies the TUtilsCustomIteratorAliases object holding alias definition, which are used to calculated the aliased value of each string from its literal value according to the value of the AliasOpt property.

Duplicates: TDuplicates

Specifies whether duplicate strings can be added to sorted lists.

Enabled: Boolean

Determines whether the iterators associated with the automated string list component are active.

Sorted: Boolean

Specifies whether the strings in the list should be automatically sorted.

Public Properties
CanModify: Boolean (readonly)

'True' if the list can be modified; 'False' otherwise.

Capacity: Integer

Indicates the number of strings the string list has allocated memory to hold.

CaseSensitive: Boolean

Controls whether strings are located, sorted, and identified as duplicates in a case-sensitive or case-insensitive manner.

Count: Integer (readonly)

Indicates the number of strings in the list.

Literals[Index: Integer]: string

Lists the literal (non-aliased) value of the strings, referenced by a 0-based index.

Objects[Index: Integer]: TObject

Lists a set of objects associated one with each of the strings in the Strings/Literal property.

Strings[Index: Integer]: string

Lists the aliased value of the strings, referenced by a 0-based index.

Public Methods for List Mutation
function Add(const S: string): Integer; override;

Adds the specified string to the list according to the alias settings.

Parameters:

Return Value:

function AddObject(const S: string; AObject: TObject): Integer; override;

Adds the specified string and an associated object to the list according to the alias settings.

Parameters:

Return Value:

procedure Clear; override;

Deletes all the strings from the list.

procedure Delete(Index: Integer); override;

Removes the string specified by the Index parameter.

Parameters:

procedure DeleteAllOccurences(const S: string); override;

Deletes all occurences of the specified string from the list according to the alias settings.

Parameters:

function Insert(Index: Integer; const S: string): Boolean; override;

Inserts a string into an unsorted list at the specified position according to the alias settings.

Parameters:

Return Value:

function InsertObject(Index: Integer; const S: string; AObject: TObject): Boolean; override;

Inserts a string and an associated object into an unsorted list at the specified position according to the alias settings.

Parameters:

Return Value:

Public Methods for List Mutation via Literal Value
function AddLiteral(const S: string): Integer; override;

Adds the specified string to the list treating it as the literal (non-aliased) string value.

Parameters:

Return Value:

function AddLiteralObject(const S: string; AObject: TObject): Integer; override;

Adds the specified string, treating it as the literal (non-aliased) string value, and an associated object to the list.

Parameters:

Return Value:

procedure DeleteAllLiteralOccurences(const S: string); override;

Deletes all occurences of the specified string, treating it as the literal (non-aliased) string value, from the list.

Parameters:

function InsertLiteral(Index: Integer; const S: string): Boolean; override;

Inserts a string, treating it as the literal (non-aliased) string value, into an unsorted list at the specified position.

Parameters:

Return Value:

function InsertLiteralObject(Index: Integer; const S: string; AObject: TObject): Boolean; override;

Inserts a string, treating it as the literal (non-aliased) string value, and an associated object into an unsorted list at the specified position.

Parameters:

Return Value:

Public Methods for Sorting
procedure CustomSort(Compare: TUtilsStringCompare); override;

Sorts the strings in the list in a customized order using the specified comparison function.

Parameters:

procedure Exchange(Index1, Index2: Integer); override;

Swaps the position of two strings in the list.

Parameters:

procedure Sort; override;

Sorts the strings in the list in ascending order. Call Sort to sort the strings in a list that has the Sorted property set to false. String lists with the Sorted property set to true are automatically sorted. Sort uses AnsiCompareStr to sort the strings when CaseSensitive is true and AnsiCompareText when CaseSensitive is false. To provide your own comparison operator instead, use the CustomSort method.

Public Methods for String Access
function HasStr(const S: string): Boolean; override;

Test whether the specifed string, according to the alias settings, is in the list.

Parameters:

Return Value:

function IndexOf(const S: string; I: Integer): Integer; override;

Returns the list index of the specifed string, according to the alias settings.

Parameters:

Return Value:

Public Methods for Literal String Access
function HasLiteralStr(const S: string): Boolean; override;

Test whether the specifed string, treating it as the literal (non-aliased) string value, is in the list.

Parameters:

Return Value:

function LiteralIndexOf(const S: string; I: Integer): Integer; override;

Returns the list index of the specifed string, treating it as the literal (non-aliased) string value.

Parameters:

Return Value:

Public Methods for View Control
procedure DisableControls; virtual;

Disables list-aware controls associated with this automated string list.

procedure EnableControls; virtual;

Enables list-aware controls associated with this automated string list.

TUtilsStringIterator = class(TUtilsCustomIterator)

TUtilsStringIterator components are used to iterate an associated TUtilsCustomAliasedStrings list.

Published Properties
List: TUtilsCustomAliasedStrings

The associated TUtilsCustomAliasedStrings list.

Public Properties
LiteralValue: string (readonly)

The literal value of the string at the iterator's position.

Value: string (readonly)

The aliased value of the string at the iterator's position.

CanModify: Boolean (readonly)

'True' if the list can be modified; 'False' otherwise.


Adapter Classes

The adapter classes are used to link an iterator with an auto-updated view component for its associated list data.

TUtilsIteratorAdapter = class(TPersistent)
Public Properties
IteratorFixed: Boolean

Indicates whether the Iterator property can be set.

Public Events
OnActiveChanged: TNotifyEvent

Triggered if the active status of the associated iterator changed.

OnPositionChanged: TUtilsPositionChangeEvent

Triggered if the position of the associated iterator changed.

OnItemChanged: TNotifyEvent

Triggered if the focused item of the associated iterator changed.

OnListModified: TNotifyEvent

Triggered if the automated list associated with the associated iterator was modified.

Public Methods
destructor Destroy; override;

Destroys the TUtilsIteratorAdapter instance and frees its memory. Do not call Destroy directly in an application. Call Free instead, which checks for a nil reference before calling Destroy.

function ExecuteAction(Action: TBasicAction): Boolean; dynamic;

ExecuteAction is called automatically when the user invokes an action with the Owner as a target. The Action parameter specifies the action that was invoked. ExecuteAction checks whether the associated iterator can handle the action, and if so, forwards the action to the iterator.

Parameters:

Return Value:

function UpdateAction(Action: TBasicAction): Boolean; dynamic;

UpdateAction is called automatically when the application is idle to give the iterator adapter an opportunity to update associated actions.

Parameters:

Return Value:

TUtilsStandardIteratorAdapter = class(TUtilsIteratorAdapter)

TUtilsStandardIteratorAdapter is a TUtilsIteratorAdapter descendant which publishes the Iterator property which is protected in TUtilsIteratorAdapter.

Published Properties
Iterator: TUtilsCustomIterator

The iterator associated with this iterator adapter.

TUtilsStringIteratorAdapter = class(TUtilsIteratorAdapter)

TUtilsStringIteratorAdapter is a TUtilsIteratorAdapter descendant which publishes a specialized Iterator property.

Published Properties
Iterator: TUtilsStringIterator

The string iterator associated with this iterator adapter.


Alias List Classes

Alias lists hold the alias definitions, each consisting of a key-alias-pair, used for automatic aliasing of strings in iterator lists.

TUtilsCustomAliases = class(TComponent)

TUtilsCustomAliases is the base class of all alias lists.

Public Properties
Alias[Index: Integer]: string (readonly)

Lists the aliases referenced by a 0-based index.

Count: Integer (readonly)

The number of definitions in the alias list.

Key[Index: Integer]: string (readonly)

Lists the keys referenced by a 0-based index.

General Public Methods
constructor Create(AOwner: TComponent); override;

Creates a new TUtilsCustomAliases component.

Parameters:

destructor Destroy; override;

Destroys the TUtilsCustomAliases instance and frees its memory. Do not call Destroy directly in an application. Call Free instead, which checks for a nil reference before calling Destroy.

Public Methods for Alias Definition Access
function HasAlias(S: string): Boolean; virtual;

Determines whether an alias for the specified key exists.

Parameters:

Return Value:

function HasKey(S: string): Boolean; virtual;

Determines whether a key for the specified alias exists.

Parameters:

Return Value:

function IndexOfAlias(S: string): Integer; virtual;

Returns the list index of the first occurrence of the specified string as alias part in an alias definition.

Parameters:

Return Value:

function IndexOfKey(S: string): Integer; virtual;

Returns the list index of the first occurrence of the specified string as key part in an alias definition.

Parameters:

Return Value:

Public Methods for String Escaping
function EscapeStr(S: string; Opt: TUtilsAliasOpt): string; virtual;

Escapes the specified string according to the specified option.

Parameters:

Return Value:

function UnescapeStr(S: string; Opt: TUtilsAliasOpt): string; virtual;

Unescapes the specified string according to the specified option.

Parameters:

Return Value:

TUtilsCustomIteratorAliases = class(TUtilsCustomAliases)

TUtilsCustomIteratorAliases is a TUtilsCustomAliases descendant which introduces some private und protected methods to automatically interact with a TUtilsCustomIteratorList component.

TUtilsAutoAliases = class(TUtilsCustomIteratorAliases)

TUtilsAutoAliases makes some of TUtilsCustomIteratorAliases' methods and properties public or published.

Published Events
OnChange: TNotifyEvent

Triggered after the alias list was changed.

OnChanging: TNotifyEvent

Triggered when the alias list is about to be changed.

Public Methods
procedure BeginUpdate; override;

Prevents event calls until the EndUpdate method is called.

procedure Clear; override;

Deletes all the definitions from the alias list.

procedure Define(Key, Alias: string); override;

Defines a key-alias pair.

Parameters:

procedure EndUpdate; override;

Reenables event calls that were turned off with the BeginUpdate method.

procedure LoadFromFile(const FileName: string); override;

Fills the alias list with the definitions stored in the specified file. LoadFromFile first clears any strings already in the alias list.

Parameters:

procedure LoadFromStream(Stream: TStream); override;

Fills the alias list with the definitions stored in the specified stream. LoadFromStream first clears any strings already in the alias list.

Parameters:

function RemoveAlias(S: string): Boolean; override;

Removes the first key-alias pair with the specified alias from the alias list.

Parameters:

Return Value:

function RemoveKey(S: string): Boolean; override;

Removes the first key-alias pair with the specified key from the alias list.

Parameters:

Return Value:

procedure SaveToFile(const FileName: string); override;

Saves the defintions in the alias list to the specified file.

Parameters:

procedure SaveToStream(Stream: TStream); override;

Saves the defintions in the alias list to the specified stream.

Parameters: