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.

SChangeSinceMark = 'Change since last mark';
SIndexOutOfBounds = 'Index out of bounds (%d)';
SInvalidAbbr = 'Invalid abbreviation';
SNoDuplicatesAllowed = 'List does not allow duplicates';
SNoMarkAvailable = 'No mark available';
SNoModification = 'No modification allowed';

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:

AOwner
The AOwner parameter indicates the component (usually a form) that is responsible for freeing the TUtilsCustomIteratorList instance. It becomes the value of the Owner property.

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:

OnListModified
OnPositionChanged
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:

AOwner
The AOwner parameter indicates the component (usually a form) that is responsible for freeing the TUtilsCustomIterator instance. It becomes the value of the Owner property.

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:

Index
The new position of the iterator.

Exceptions:

EAutoListException
Raised if the index is out of bounds.

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:

EAutoListException
Raised if the internal bookmark stack contains no value of if the associated list has changed since the corresponding bookmark was set so that it cannot be guaranteed that the stored bookmark refers still to the same item.

Public Methods for Event Flow Control

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:

The iterator's position within the associated list.

function IsFirst: Boolean; virtual;

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

Return Value:

'True' if the iterator is currently positioned on the first item of the associated list; 'False' otherwise.

function IsLast: Boolean; virtual;

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

Return Value:

'True' if the iterator is currently positioned on the last item of the associated list; 'False' otherwise.

function Offleft: Boolean; virtual;

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

Return Value:

'True' if the iterator is currently positioned off the left edge of the associated list or if the list is empty; 'False' otherwise.

function Offright: Boolean; virtual;

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

Return Value:

'True' if the iterator is currently positioned off the right edge of the associated list or if the list is empty; 'False' otherwise.

function Offlist: Boolean; virtual;

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

Return Value:

'True' if the iterator is currently positioned off the left or right edge of the associated list or if the list is empty; 'False' otherwise.

Public Methods for Inquiring General List Attributes

function Count: Integer; virtual;

Returns the number of items in the associated list.

Return Value:

The number of items in the associated list.

function Empty: Boolean; virtual;

Returns whether the associated list is empty.

Return Value:

'True' if the associated list has no items; 'False' otherwise.

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:

aoOff: No aliases are used.
aoFull: An alias definition must match the whole literal string. The resulting aliased string is the alias part of the alias definition.
aoPrefix: An alias definition must match the beginning of a literal string. The resulting string is calculated by replacing the matching prefix of the literal string with the alias part of the alias definition.

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:

S
The string to be added.

Return Value:

The index position of the added string in the list.

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:

S
The string to be added.
AObject
The associated object.

Return Value:

The index position of the added string in the list.

procedure Clear; override;

Deletes all the strings from the list.

procedure Delete(Index: Integer); override;

Removes the string specified by the Index parameter.

Parameters:

Index
The list index of the string to be removed.

procedure DeleteAllOccurences(const S: string); override;

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

Parameters:

S
The value of the strings to be removed.

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:

Index
The index position where the strings should be inserted.
S
The value of the strings to be inserted.

Return Value:

'True' if the string has been successfully inserted; 'False' otherwise.

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:

Index
The index position where the strings should be inserted.
S
The value of the strings to be inserted.
AObject
The associated object.

Return Value:

'True' if the string has been successfully inserted; 'False' otherwise.

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:

S
The string to be added.

Return Value:

The index position of the added string in the list.

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:

S
The string to be added.
AObject
The associated object.

Return Value:

The index position of the added string in the list.

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:

S
The value of the strings to be removed.

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:

Index
The index position where the strings should be inserted.
S
The value of the strings to be inserted.

Return Value:

'True' if the string has been successfully inserted; 'False' otherwise.

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:

Index
The index position where the strings should be inserted.
S
The value of the strings to be inserted.
AObject
The associated object.

Return Value:

'True' if the string has been successfully inserted; 'False' otherwise.

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:

Compare
The comparison function used to sort the list.

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

Swaps the position of two strings in the list.

Parameters:

Index1
The index position of one of the strings to swap.
Index2
The index position of the other of the strings to swap.

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:

S
The string to test.

Return Value:

'True' if the specified string is contained in the list; 'False' otherwise.

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

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

Parameters:

S
The string to find.

Return Value:

The list index of the specifed string, or '-1' if the string was not found.

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:

S
The string to test.

Return Value:

'True' if the specified string is contained in the list; 'False' otherwise.

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:

S
The string to find.

Return Value:

The list index of the specifed string, or '-1' if the string was not found.

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:

Action
The action that was invoked.

Return Value:

'True' if the action was successfully dispatched; 'False' if the iterator adapter could not handle the action.

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:

Action
The action that should be updated.

Return Value:

'True' if the action component successfully updated the associated iterator; 'False' if it did not know how to update the iterator.

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:

AOwner
The AOwner parameter indicates the component (usually a form) that is responsible for freeing the TUtilsCustomAliases instance. It becomes the value of the Owner property.

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:

S
The key to test.

Return Value:

'True' if the specifid key has an alias; 'False' otherwise.

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

Determines whether a key for the specified alias exists.

Parameters:

S
The alias to test.

Return Value:

'True' if a key for the specified alias exists; 'False' otherwise.

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:

S
The alias to look for.

Return Value:

The list index of the first occurrence of the specified string as alias part in an alias definition; or '-1' if the string does not occur as alias part in an alias definition.

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:

S
The key to look for.

Return Value:

The list index of the first occurrence of the specified string as key part in an alias definition; or '-1' if the string does not occur as key part in an alias definition.

Public Methods for String Escaping

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

Escapes the specified string according to the specified option.

Parameters:

S
The string to escape.
Opt
Specifies how aliases are applied when escaping a string. Valid values are:
- aoOff: No aliases are applied. The returned string is identical with the specified string.
- aoFull: The first alias definition with a key part matching the specifed string is used to escape the string. The resulting escaped string is the alias part of the matching alias definition. If no matching alias definition was found the returned string is identical with the specified string.
- aoPrefix: The first alias definition with a key part matching the beginning of the specifed string is used to escape the string. The resulting escaped string consists of the specified string with its beginning replaced by the alias part of the matching alias definition. If no matching alias definition was found the returned string is identical with the specified string

Return Value:

The escaped string.

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

Unescapes the specified string according to the specified option.

Parameters:

S
The string to unescape.
Opt
Specifies how aliases are applied when unescaping a string. Valid values are:
- aoOff: No aliases are applied. The returned string is identical with the specified string.
- aoFull: The first alias definition with an alias part matching the specifed string is used to unescape the string. The resulting unescaped string is the key part of the matching alias definition. If no matching alias definition was found the returned string is identical with the specified string.
- aoPrefix: The first alias definition with an alias part matching the beginning of the specifed string is used to unescape the string. The resulting unescaped string consists of the specified string with its beginning replaced by the key part of the matching alias definition. If no matching alias definition was found the returned string is identical with the specified string

Return Value:

The unescaped string.

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:

Key
The key part of the key-alias pair.
Alias
The alias part of the key-alias pair.

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:

FileName
The source file containing the definitions to add.

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:

Stream
The source stream containing the definitions to add.

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

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

Parameters:

S
The alias of the key-alias pair to remove.

Return Value:

'True' if a key-alias pair with the specified alias was removed; 'False' otherwise.

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

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

Parameters:

S
The key of the key-alias pair to remove.

Return Value:

'True' if a key-alias pair with the specified key was removed; 'False' otherwise.

procedure SaveToFile(const FileName: string); override;

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

Parameters:

FileName
The target file to store the alias list.

procedure SaveToStream(Stream: TStream); override;

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

Parameters:

Stream
The target stream to store the alias list.