Keyed Collection (PRIM_KCOL)
Ordered collection of component and value pairs typically used to allow objects to be found via a key value
Ancestors - Collection (PRIM_COLL)Object (PRIM_OBJT)
Details
A Keyed collection is an unordered sequence of components instances identified by a key value. No duplicates of the key value are allowed. A keyed collection is keyed by a repository defined field, giving each collection item a unique identifier. Unlike all other collection types which require an instance to be created before it can be stored, Keyed collection can automatically create their contents simply by refering to the key value.
Examples
Defining a keyed collection. This collection stores instances of any component that inherits from Prim_Form, identified by a number.
Define_Com Class(#Prim_kcol<#Prim_form #Std_num>) Name(#Forms)
Collection items can be accessed using any value that matches the data type specified as the key. If the Style property is Factory, this will also create the collection item instance if it doesn't yet exist.
#Forms<123>.Caption := "Form 123"
or using another variable
#Forms<#ID>.Caption := "Form 123"
All collection items can be addressed as follows. Here, all the forms in the collection are being closed.
#Forms<>.Close
The FOR command can also be used to iterate over the collection contents. The items will be returned in the order of the key value, in this case numeric sequence.
For each(#Form) in (#Forms) ... Endfor
To monitor for an event from any instance in the collection, <> can be appended to an EVTROUTINE. The COM_SENDER parameter will provide access to the instance firing the event.
Evtroutine Handling(#Forms<>.Closing) Com_Sender(#Sender)
#Com_owner.AddEvent(("&1 closed").Substitute(#Sender.Caption))
Endroutine
Properties
| Name | Description |
|---|---|
| AllowsDuplicates | AllowsDuplicates indicates whether the collection allows duplicates Inherited from Collection (PRIM_COLL) |
| Collects | The class of object to be collected |
| ComponentClassName | ComponentClassName is the name of the component's class. Inherited from Object (PRIM_OBJT) |
| ComponentMembers | ComponentMembers provides access to all the member components of this component Inherited from Object (PRIM_OBJT) |
| ComponentPatternName | ComponentPatternName is used to qualify the class of the component. Inherited from Object (PRIM_OBJT) |
| ComponentTag | Generic space allowing a value to be stored for the instance Inherited from Object (PRIM_OBJT) |
| ComponentType | ComponentType gives you access to the type information about the component Inherited from Object (PRIM_OBJT) |
| ComponentTypeName | ComponentTypeName is the fully qualified name of the component's class. Inherited from Object (PRIM_OBJT) |
| IsEmpty | IsEmpty indicates whether the collection contains any items. Inherited from Collection (PRIM_COLL) |
| IsOrdered | IsOrdered indicates whether the collection is ordered. Inherited from Collection (PRIM_COLL) |
| Item | Provides access to a particular item in a collection |
| ItemCount | ItemCount is the number of items in a collection Inherited from Collection (PRIM_COLL) |
| KeepLast | KeepLast specifies how many instances of a component are maintained |
| KeyedBy | KeyedBy specifies the field used to identify a form instance |
| KeyOf | KeyOf returns the key of an item in a collection |
| Name | Name identifies the component Inherited from Object (PRIM_OBJT) |
| Owner | Owner owns this component Inherited from Object (PRIM_OBJT) |
| Parent | The component instance to which this instance is attached. The visual container for a control or the collector of a set of child instances Inherited from Object (PRIM_OBJT) |
| Style | Style specifies what happens when the collection is accessed with a key that does not exist |
Events
| Name | Description |
|---|---|
| CreateInstance | CreateInstance is signalled when an instance of a component is created Inherited from Keyed Collection (PRIM_KCOL) |
| DestroyInstance | DestroyInstance is signalled when an instance of a component is about to be destroyed Inherited from Keyed Collection (PRIM_KCOL) |
Methods
| Name | Description |
|---|---|
| CalculateHash | CalculateHash calculates a hash value Inherited from Collection (PRIM_COLL) Result, Value |
| CreateAccessor | CreateAccessor creates an accessor component that provides read-only access to the collection
Result |
| CreateIterator | CreateIterator method creates an iterator component that enables iteration through the collection
Result |
| Remove | Remove method removes an item
Result, Key |
| RemoveAll | RemoveAll removes all items in the collection |
See also
LANSA Version 15, April 2020