&<img src="../resources/images/opentocr.png" title="Open Contents list" border="0"&>
You are here:

Example 2: Collections do NOT need to Be Keyed by Index

Unlike an array, a keyed collection does not have to be keyed by an index. This example is otherwise the same as Example 1 except that the collection of employees is keyed by the #Surname field instead of a number.
When you type in an employee name and click on the Save button, the employee name is saved in a collection.

When you click on the Show button, all employees entered in the collection are displayed in a message box.

The collection is uniquely keyed by #SurName so a duplicate name will update the existing item in the collection.
Define the Collection
The collection to store employee names is defined like this:
 
Define_Com Class(#Prim_kCol<#GiveName #SurName>) Name(#Employee)

• The collection is named #Employee.
• It collects an employee's #GiveName (given or first name).
• It is uniquely keyed an employee's #SurName (last name or surname).

Example 2: Collections do not Need to Be Keyed by Index
Add Items to the Collection

The code to save the employee's full name into the keyed collection is contained in the Click event of the Save button:
 
Set Com(#Employee<#SurName>) Value(#GiveName)
In the above note that there is no need to compute the next available key for the collection item as in Example 1 because the collection is keyed by the #Surname field.
Example 2: Collections do not Need to Be Keyed by Index
Work with the Collection Items

Individual items in the collection are accessed using a For/EndFor loop.
The click event of the Show button iterates through the collection referencing each entry in the collection by using a For/EndFor loop to retrieve the value of  #GiveName and #Surname of the individual employees to a message box:
For Each(#Employee_GiveName) In(#Employee) Key(#Employee_SurName)
Use Builtin(MESSAGE_BOX_ADD) With_Args('Employee' #EMPLOYEE_GIVENAME.VALUE #EMPLOYEE_SURNAME.VALUE 'was found in the collection.')
Endfor
In the above note that:

• The For/EndFor loop specifies a name for the Key (#Employee_SurName) to access the key of the current component each time the variable name (#Employee_GiveName) is referenced. In this way the value of the #Surname field can be retrieved to the message.

Example 2: Collections do not Need to Be Keyed by Index
Source Code for Collection Example 2
To see how a collection is created, copy and paste this code to a form and then compile and execute the form.
Function Options(*DIRECT)
Begin_Com Role(*EXTENDS #PRIM_FORM) Clientheight(124) Clientwidth(363) Height(151) Left(269) Top(185) Visualstyle(#VS_NORM) Width(371)

• Using a Keyed Collection (PRIM_KCOL) as a keyed array.
• Define the keyed collection to be used to store employee names.
• The collection is named #Employee.
• It collects an employee's #GiveName (given or first name).
• It is uniquely keyed an employee's #SurName (last name or surname).
  Define_Com Class(#Prim_kCol<#GiveName #SurName>) Name(#Employee)
• Define the form.
• Field #GIVENAME allows the employee's given/first name to be input.
• Field #SURNAME  allows the employee's last or surname to be input.
• Button #PHBN_SAVE saves employee names into the collection.
• Button #PHBN_SHOW shows the details of all the employees in the collection.
  Define_Com Class(#GiveName.Visual) Name(#GiveName) Displayposition(2) Height(19) Left(16) Parent(#COM_OWNER) Tabposition(1) Top(16) Width(329)
  Define_Com Class(#SurName.Visual) Name(#SurName) Displayposition(1) Height(19) Left(16) Parent(#COM_OWNER) Tabposition(2) Top(40) Width(329)
  Define_Com Class(#PRIM_PHBN) Name(#PHBN_SAVE) Buttondefault(True) Caption('Save ') Displayposition(3) Left(152) Parent(#COM_OWNER) Tabposition(3) Top(80) Width(97)
  Define_Com Class(#PRIM_PHBN) Name(#PHBN_SHOW) Caption('Show ') Displayposition(4) Left(264) Parent(#COM_OWNER) Tabposition(4) Top(80)
• -------------------------------------------------------------------------
• #PHBN_SAVE.Click : Save the detail on an employee in the keyed collection
• -------------------------------------------------------------------------
  Evtroutine Handling(#PHBN_SAVE.Click)
• Save the employee's name into the keyed collection.
• The collection is uniquely keyed by #SurName so a duplicate
• name will update the existing item in the collection. Try putting
• in 2 employees with the same surname (eg: JONES).
  Set Com(#Employee<#SurName>) Value(#GiveName)
• Clear the name fields ready for input of the next name
• and reset the focus to the first name field
  Change Field(#GIVENAME #SURNAME) To(*NULL)
  Invoke Method(#GiveName.SetFocus)
  Endroutine
• -------------------------------------------------------------
• #PHBN_SHOW.Click : Build a message of all the employees saved
• -------------------------------------------------------------
  Evtroutine Handling(#PHBN_SHOW.Click)
• Iterate through the collection referencing each entry in the
• collection as an object by using a for / end for loop.
  For Each(#Employee_GiveName) In(#Employee) Key(#Employee_SurName)
  Use Builtin(MESSAGE_BOX_ADD) With_Args('Employee' #EMPLOYEE_GIVENAME.VALUE #EMPLOYEE_SURNAME.VALUE 'was found in the collection.')
  Endfor
• Show the employee count and final results
  Use Builtin(MESSAGE_BOX_ADD) With_Args('There are' #EMPLOYEE.ITEMCOUNT 'employees currently in the collection.')
  Use Builtin(MESSAGE_BOX_SHOW) With_Args(OK OK INFO *COMPONENT)
  Endroutine
  End_Com
  Example 2: Collections do not Need to Be Keyed by Index
  &<img src="../resources/images/opentoc-dark.png" title="Open Contents List" border="0"&>