Example 1: Create a Keyed Collection

This example form shows how to create a collection of employees and  to add items to the collection. In this example the collection is used simply like an array.

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.

When the application ends, the entries in the collection are cleared.

Define the Collection

The collection to store employee names is defined like this:

Define_Com Class(#Prim_kCol<#FullName #Std_Num>) Name(#Employee)

• The #FullName value indicates the collection contains #FullName fields

• The #STD_NUM parameter specifies this repository field used as the key to the collection (a packed (7,0) number)

• The Name of the collection is #Employee.

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:

 

Change Field(#LISTCOUNT) To('#Employee.ItemCount + 1')

Set Com(#Employee<#ListCount>) Value(#FullName.Value)

In the above note that:

• The keyed collection property ItemCount (the number of items in the collection) is used to compute the next available key

• When you work with an item in a collection, you refer to it with the name of the collection and the key field: #Employee<#ListCount>

• You create the item in the collection simply by setting its value

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  #FullName of the individual employees to a message box:

 

For Each(#EmployeeFullName) In(#Employee)

Use Builtin(MESSAGE_BOX_ADD) With_Args('Employee' #EMPLOYEEFULLNAME.VALUE 'was found in the collection.')

Endfor

Source Code for Collection Example 1

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(88) Clientwidth(363) Height(115) Left(269) Top(185) Visualstyle(#VS_NORM) Width(371)

* Using a Keyed Collection (PRIM_KCOL) as a simple array.

* Define the keyed collection to be used to store employee names.

* The collection is named #Employee and it collects #FullNames.

* It is indexed (or more correctly, keyed by) #Std_Num ie: a packed (7,0) number.

Define_Com Class(#Prim_kCol<#FullName #Std_Num>) Name(#Employee)

* Define the form.

* #FULLNAME allows employee names 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(#FULLNAME.Visual) Name(#FULLNAME) Displayposition(1) Height(19) Left(16) Parent(#COM_OWNER) Tabposition(1) Top(16) Width(329)

Define_Com Class(#PRIM_PHBN) Name(#PHBN_SAVE) Buttondefault(True) Caption('Save ') Displayposition(2) Left(152) Parent(#COM_OWNER) Tabposition(2) Top(51) Width(97)

Define_Com Class(#PRIM_PHBN) Name(#PHBN_SHOW) Caption('Show ') Displayposition(3) Left(264) Parent(#COM_OWNER) Tabposition(3) Top(51)

* -------------------------------------------------------------------------

* #PHBN_SAVE.Click : Save the detail on an employee in the keyed collection

* -------------------------------------------------------------------------

Evtroutine Handling(#PHBN_SAVE.Click)

* Save the employee's full name into the keyed collection in the next slot.

* Use the keyed collection property ItemCount to compute the next slot

Change Field(#LISTCOUNT) To('#Employee.ItemCount + 1')

Set Com(#Employee<#ListCount>) Value(#FullName.Value)

* Clear the full name field ready for input of the next name

Change Field(#FULLNAME) To(*NULL)

Endroutine

* -------------------------------------------------------------

* #PHBN_SHOW.Click : Build a message of all the employees saved

* -------------------------------------------------------------

Evtroutine Handling(#PHBN_SHOW.Click)

Define Field(#LOOPINDEX) Reffld(#STD_NUM)

* Iterate through the collection referencing each entry in the

* collection as an object by using a for / end for loop.

For Each(#EmployeeFullName) In(#Employee)

Use Builtin(MESSAGE_BOX_ADD) With_Args('Employee' #EMPLOYEEFULLNAME.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