FILE: Listarr.exe: Using Arrays For List Box Row Sources

Last reviewed: January 16, 1998
Article ID: Q179173

The information in this article applies to:

Microsoft Visual FoxPro for Windows, versions 3.0, 3.0b, 5.0, 5.0a
Microsoft Visual FoxPro for Macintosh, version 3.0b

SUMMARY

The two files listed in the MORE INFORMATION section illustrate various features of list boxes when using an array as the RowSourceType for a list box.

This article addresses undocumented features and behaviors of list boxes when using an array as the RowSourceType. There may be other ways to accomplish the results described in this article by using other RowSourceTypes, but the article focuses on arrays.

MORE INFORMATION

The following files are available for download from the Microsoft Software Library:

 ~ listarr.exe (size: 43244 bytes) 
 ~ listarr.hqx (size: 62456 bytes)

For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q119591
   TITLE     : How to Obtain Microsoft Support Files from Online Services

Microsoft has no plans to intentionally change the behaviors described in this article. However, if some of these features do not work for your application, a different approach is probably needed.

The sample files presented here are complex. Microsoft Product Support Engineers will not know all the issues presented in this article without spending some time working with the sample files. Please remember this if asking questions about the attached files.

The sample files used in this article were created with the Visual FoxPro Form Designer. This is assumed to be the working environment in all the information presented below.

The lists on the sample forms have the following properties set:

   RowSource = Thisform.listarray
   RowSourceType = 5-Array

Thisform.listarray is a custom property of the form. To create the custom property, follow these steps:

On the Form menu, click New Property.
Type "listarray[1,1]" (without the quotes) in the Name box of the New Property dialog box.

One advantage to using arrays as the RowSourceType of a list box is speed. A SELECT - SQL statement can be executed once when the form loads to populate the array and then the FirstElement and NumberOfElements properties of the list box can be used to control what elements of the array are displayed in the list box. The query does not need to be rerun. Even though Visual FoxPro executes queries quickly, if the query is complex or is being run on a slow computer, it can be much slower than manipulating an array.

The FirstElement and NumberOfElements Properties

Run the sample form, Listarr1.scx while reading this section. The form uses the TestData!Customer sample table. It will be useful to open the sample table and become familiar with the data in the table.

The FirstElement and NumberOfElements properties are specifically designed for use when the RowSourceType is 5-Array. With a one column (one dimensional) array, the items in the array are exactly what they say they are, the first element and number of elements.

The Listarr1.scx form uses a one column array when it is first loaded. The one column is based on the Company field in the Customer table. Fill in values for the First Element and Number of Elements text boxes and click the Refresh List box button to see the effect of changing these properties.

When the array is more than one column, the FirstElement property determines what column of the array is shown in the list box in addition to the first item from that column. In the sample form, click the "Use Three Column Array" option button. This requeries the array to be three columns; Customer.Cust_id, Customer.Company and Customer.Contact. The following table lists what array column is displayed for various settings of the FirstElement property:

   FirstElement            Table Column Displayed
   ----------------------------------------------
   1                       Customer.Cust_id
   2                       Customer.Company
   3                       Customer.Contact
   4                       Customer.Cust_id (starting with 2nd cust_id)
   7                       Customer.Cust_id (starting with 3rd cust_id)
   10                      Customer.Cust_id (starting with 4th cust_id)
   5                       Customer.Company (starting with 2nd company)
   8                       Customer.Company (starting with 3rd company)
   11                      Customer.Company (starting with 4th company)
   6                       Customer.Contact (starting with 2nd contact)
   9                       Customer.Contact (starting with 3rd contact)
   12                      Customer.Contact (starting with 4th contact)

NOTE: When you use a two dimensional array, the FirstElement property is going to use element numbers to determine what column and with which item in that column to start the list.

To change the first item shown for an array column to start with another item, add or subtract the number of array columns from the current FirstElement setting. As shown in the table above, to start the list on the second cust_id, add 3 to the FirstElement value of 1 to set the FirstElement property of the list to 4.

Lists and drop-down list boxes can display more than one column. If more than one column is displayed in a list box, the FirstElement and NumberOfElement properties no longer function as described above. Run the attached sample form named Listprob.scx to see an illustration of this behavior.

The Listprob.scx form manually loads two, 2-column arrays in the Load method of the form. One array is for the list box, the other array is for the drop-down list. The first array column contains colors, and the second a list of fruits. With the First Element text box set to 1, click the Two Columns option button to see the complete contents of the array in the list box.

NOTE: When the One Column option button is selected, both the list box and the drop-down list box work the same as the Listarr1.scx form. When the Two Columns option button is selected, the FirstElement property no longer has any effect on the array items displayed in the list box.

In Visual FoxPro version 3.0x (both the Windows and Macintosh versions), if the Two Columns option button is selected and then changed back to the One Column option button, the FirstElement property no longer has any effect. This does not happen in Visual FoxPro version 5.0x.

Referencing Items in Non-Displayed Array Columns

The BoundColumn property can be used to store data to the Value property of a control from any column of a list that contains more than one column whose RowSourceType is not 5-Array. The items displayed in the list are stored in the DisplayValue property of the list.

However, when the RowSourceType of a list is set to 5-Array, and the BoundColumn property is set to any column other than the first column, the FirstElement and NumberOfElements properties no longer function. To obtain the corresponding data for a list item from another column of a two dimensional array, use one of the techniques described below. Look in the Click method of the list on the Listarr1.scx form to see these techniques in use.

Using Array Subscripts

Here is an example:

   Thisform.listarray(INT(This.FirstElement/ ;
   ALEN(Thisform.listarray,2))+This.ListIndex,2)

The number 2 represents the array column choice. In the sample form, the array has 3 columns. If the contents of the third array column were needed, the 2 would be changed to a 3.

The ALEN(Thisform.listarray,2) returns the number of columns in the array so this could be coded to 3 in the sample form. Also important to note here is that the FirstElement property should be set so that the first column of the array is displayed in the list.

Using Array Elements

Here is an example:

   Thisform.listarray(ASCAN(Thisform.listarray,This.ListItem ;
   (This.ListIndex))+1)

In the line of code above, the ListItem() method returns the DisplayValue of the list given a ListIndex number. The array is then ASCANed for this item. ASCAN() returns a number representing the element number of the item. Since the array column displayed is the first column, the next element of the array would represent the value in the second column of the array. Therefore a 1 is added to the array element number that ASCAN() returns. Add a 2 if information in the third column is desired. Again, remember that the first column of the array should be displayed in the list. Although, if it was not displayed, a 1 or a 2 could be subtracted from the number that ASCAN() returns to identify previous array columns.

REFERENCES

For more information on array element numbers, see the AELEMENT() function in the Visual FoxPro Online Help.

Keywords          : FxprgClassoop FxprgGeneral FxtoolFormdes VFoxMac vfoxwin
Version           : MACINTOSH:3.0b; WINDOWS:3.0,3.0b,5.0,5.0a
Platform          : MACINTOSH WINDOWS
Issue type        : kbfile

================================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: January 16, 1998
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.