DOCUMENT:Q129329 25-AUG-1999 [foxpro] TITLE :HOWTO: Populate a Form's List Box Object from an Array PRODUCT :Microsoft FoxPro PROD/VER:WINDOWS:3.0,3.0b,5.0,6.0 OPER/SYS: KEYWORDS:kbDesigner kbvfp300 kbvfp500 kbvfp600 ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Visual FoxPro for Windows, versions 3.0, 3.0b, 5.0, 6.0 ------------------------------------------------------------------------------- SUMMARY ======= This article shows how to populate a ListBox object from an array. MORE INFORMATION ================ In Visual FoxPro, in addition to the usual single-column list, you can now have multiple-column lists. Additionally, the ListBox object also supports the multiple-select and mover capabilities. The ListBox object has several properties that control the displayed output. Some of these properties are covered in this article. For more information, please see Chapter 11 of the Developer's Guide or the "ListBox Control" topic in the Help menu. ListBox Control Properties and Display Attributes ------------------------------------------------- The following two tables describes several of the data properties and display attributes of the ListBox control: Data Property Description ---------------------------------------------------------------- ColumnCount Number of columns contained in the ListBox object. RowSource Source of the values displayed in the ListBox object. RowSourceType Data type of the values. For example, fields, array, list, files, and list of fields are all valid data types. ControlSource Where the value chosen by the user is stored. For example, the value may be stored in a variable. BoundColumn The column of a multiple-column array to return when the user selects an object from the ListBox object. Display Attribute Description --------------------------------------------------------------------- Moverbars Allows the rearrangement of values displayed in the ListBox object. Multiselect Allows users to choose multiple items from the ListBox object. FontName The font used in displaying the ListBox control's data. FontItalic Turns on italic mode for the font specified in the FontName property. Step-by-Step Example -------------------- The following steps show how to create and add an array-driven ListBox to a form. 1. In the Command window, type: CREATE FORM LISTTEST 2. Adjust the form size so you have some working room. Click the form to select it. Then right-click to bring up the Form sub-menu. 3. Select the Data Environment menu pad. Right-click the Data Environment window, and choose Add. In the Add Table or View dialog, choose Other. From the SAMPLES\DATA directory, choose Customer, and click OK in the Open dialog box. The Customer table should now be in the data environment for the form. You can close the Data Environment for this form. 4. From the Form menu, choose New Property. Type in the array name as "MYARRAY(1)" (without the quotation marks). The array will now become a new property of the form. For more information on adding properties scoped to a form or form set, please see the topic "properties, scoped to form sets" in the Help menu. 5. If the Form Properties sheet is not already on the screen, click the form to select it. Then right-click to bring up the property sheet. a. Choose the Methods tab for the Form Properties sheet. b. Place the following SQL statement in the Form Load event: SELECT cust_id, contact, phone FROM customer INTO ARRAY Thisform.myarray NOTE: The prefix "Thisform" in front of the array name is a Critical and subtle point to remember about the scoping of member arrays and variables within a form. If the SELECT statement is simply done INTO ARRAY myarray, the array created by the SQL statement will not have scope within the form itself. By prefacing the array name with the "Thisform" clause, the results of the SQL statement are directed into the array named myarray, which is part of the form definition. c. Close the FORM1.LOAD screen. 6. From the Form Controls toolbar, click the ListBox object and drag the ListBox object onto the new form. Size the ListBox to occupy most of the screen. 7. With the ListBox selected, right-click the ListBox object, and choose Properties. 8. Select the Data tab, and set the following properties: - BoundColumn = 1 This property governs which column of a multiple-element array is returned to the List1.Value data element when a user selects a record in the ListBox. In this example, you are creating a three-column array, so you can use a value of 1, although 2 or 3 are also valid entries for this property. - NumberOfElements=ALEN(THISFORM.MYARRAY,1) This property governs the total number of elements that will be displayed in the ListBox. It is valid only for a RowSourceType of 5. By using the =ALEN(THISFORM.MYARRAY,1) expression, you are telling FoxPro to display all the values in the array as opposed to limiting how many elements are displayed. Note that you must type the leading equals sign. The following information from the Visual FoxPro Help menu explains the second, optional parameter used by the ALEN() function: The second property of the ALEN() determines if ALEN() returns the number of elements, rows or columns in the array. nArrayAttribute can be 0, 1, or 2: a. 0 specifies to return the number of elements in the array. Omitting nArrayAttribute is identical to specifying 0. b. 1 specifies to return the number of rows in the array. c. 2 specifies to return the number of columns in the array. If the array is a one-dimensional array, ALEN() returns 0 (no columns). - RowSource = THISFORM.MYARRAY This RowSource property tells Visual FoxPro that the data will be coming from an object called MYARRAY. - RowSourceType = 5 - Array This RowSourceType property tells Visual FoxPro that the type of object that contains the data is an array. 9. From the ListBox Properties sheet, select the Layout tab, and set the following properties: - ColumnCount=3 This property governs how many elements of the array will be displayed. Because the array that will drive this ListBox contains three columns, the value of 3 is used. Array elements are displayed in the order they appear in the array. For example, say you issue an SQL SELECT statement such as this: SELECT cust_id, contact, phone FROM CUSTOMER Then the data in the ListBox will be displayed in that order (cust_id, contact, phone). - ColumnLines = .T. This property determines whether or not to display bars between the columns displayed in the array. NOTE: Column lines are represented on the form during design time as vertical bars. Because this is both a run-time and design-time property, if this value is set to false, there will be NO visual indicator of the number of columns defined for the ListBox object. - ColumnWidths = 60,220,90 By default, the pixel is the unit of measurement on a Form. 10. From the ListBox Properties sheet, select the Methods tab. Double-click the word [Default] next to the words DblClick Event. This should open up an editing window for the DblClick event. In the editing window, type this command: =MESSAGEBOX(THISFORM.LIST1.VALUE,64) When you double-click an item in the list, your selection will be shown in a message box with an OK button. 11. Place a CommandButton control on the form. Place the following command in the CLICK event: RELEASE THISFORM Change the caption to Quit. 12. Save and run your form. To get a feel for changing some of the properties on an active form, you might want to try some of the following commands in the Command window: LISTTEST.LIST1.MultiSelect=.T. && Turn on multiselect property. LISTTEST.LIST1.FontName="MS Sans Serif" && Change font for ListBox. LISTTEST.LIST1.FontItalic=.T. && Make the text italic. LISTTEST.List1.BoundColumn=3 && Alter what column's data is && returned to List1.Value. && When you change this and then && double-click a record, the && data from the third column will && be returned to LIST1.VALUE. Additional query words: Multiselect multicolumn multi-select multi-column ====================================================================== Keywords : kbDesigner kbvfp300 kbvfp500 kbvfp600 Technology : kbVFPsearch kbAudDeveloper kbVFP300 kbVFP300b kbVFP500 kbVFP600 Version : WINDOWS:3.0,3.0b,5.0,6.0 Issue type : kbhowto ============================================================================= 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. Copyright Microsoft Corporation 1999.