RowSource, RowSourceType

Hacker’s Guide to Visual FoxPro
An irreverent look at how Visual FoxPro really works. Tells you the inside scoop on every command, function, property, event and method of Visual FoxPro.

RowSource, RowSourceType

These two properties combine to determine the contents of a list box or combo box. RowSourceType indicates the type of data contained, while RowSource contains either the actual data or a pointer to it.

Usage

oObject.RowSourceType = nSourceType
nSourceType = oObject.RowSourceType
oObject.RowSource = cSource
cSource = oObject.RowSource

There are 10 choices for nSourceType, from 0 to 9. The choice you make for RowSourceType determines the kind of value you specify for RowSource. This table shows the various options:

RowSourceType	Meaning	RowSource Contents
0	None	Nothing—combo or list data is added using either the AddItem or AddListItem methods or by directly populating List or ListItem.
1	Value	The actual items for the list or combo as a comma-separated list. If ColumnCount is more than 1, the items are distributed into all the columns going across one row at a time. Don't leave spaces after the commas; these are interpreted as the first character of the next item. No need to put quotes in the list, either, as they're also interpreted as part of the items.
2	Alias	The alias for an open table whose data is used to populate the list or combo. If ColumnCount is greater than 0, the first ColumnCount fields are shown. If ColumnCount is 0, you see the first field only, just as if ColumnCount were 1.
3	SQL Statement	A SELECT-SQL statement, the results of which populate the list or combo. ColumnCount is treated as with RowSourceType=2. Be sure to do something with the query results—if there's no INTO clause, a Browse appears when the query executes on the way into the form.
4	Query	The name of a QPR file. The query is run and the results populate the list or combo. ColumnCount is treated as with RowSourceType=2. Again, make sure you send the results INTO somewhere or you'll see the default Browse.
5	Array	The name of an array used to populate the list or combo. If the array is a property of an object, be sure to precede its name with a reference to the object (such as "This" or "ThisForm.") If ColumnCount is greater than 0, the first ColumnCount columns of the array are used.
6	Fields	A list of fields from a single table. Only the first field should be preceded by the alias of the table. Field names are comma-delimited. Normally, the number of fields in the list should equal ColumnCount.
7	Files	A file skeleton. The list or combo is populated with the names of files in the current directory matching the skeleton, plus items for navigating directories. Make sure ColumnCount = 1 or 0 or you'll get really weird results.
8	Structure	The alias of an open table. The list or combo is populated with the names of fields from the specified table. Field names occupy the first column. Any other columns are empty.
9	Popup	The name of a popup defined elsewhere. The popup's items are used to populate the list or combo.

The last three RowSourceTypes are really included only for compatibility with FoxPro 2.x. We can’t see a whole lot of reasons to use any of them. For a file list, you’re better off using GETFILE() or PUTFILE() or the Common Dialogs control. We didn’t use structure popups or lists in our 2.x apps—we’re not planning to start now. (The exception, of course, is for developers’ tools.) As for lists or combos based on popups, there were reasons to do it in 2.x, but we think RowSourceType=0 is a far better alternative. The only good arguments we’ve seen for using RowSourceType = 9 are to allow each element in a list or combo to be colored separately, something that’s occasionally useful, but not your run-of-the-mill technique.

Be careful with RowSourceTypes 2 and 6. They’re connected right to the underlying tables, and moving the cursor in the list moves the record pointer. Among other things, this means that you should never set the RowSource and the ControlSource of a type 6 combo to the same field.

It's not just making a choice in a combo that moves the record pointer. Simply passing the mouse over an item in a dropped combo so that the item is highlighted is enough to position the record pointer on that item. The pointer doesn't go back where it came from if you close the combo without making a selection.

Although RowSourceType 2 says you should only give the alias, it actually behaves like RowSourceType 6, if you specify a list of fields.

With RowSourceType set to 0, 1, or 5, you can disable an item in the list by preceding it with a backslash (“\”). To show an item beginning with a backslash, you need to use two backslashes.

Doubling the backslash doesn't work with RowSourceType 5. Once there's a backslash in front of the text, the item is disabled. A double backslash shows up as a disabled item that begins with a backslash.

You can add a horizontal divider to the list by specifying the text for an item as “-”, but this works only with RowSourceType 0, 1, or 9.

In VFP 7, divider lines don't hit either side of the list or combo. In earlier versions, divider lines correctly run from one edge to the other. It's likely that having the lines not go all the way to the edges is by design, but the actual implementation is still flawed—the lines simply don't go far enough.

We find that we use RowSourceTypes 0, 3, 5 and 6 the most. RowSourceType 1 is handy for situations where you know the list of choices can’t change.

Example

* This code in the Init for a list box populates
* an array that's a property of the form and
* sets the list to use the array.
SELECT Last_Name,First_Name,Employee_Id ;
  FROM Employee ;
  INTO ARRAY ThisForm.aEmps
This.RowSourceType = 5
This.RowSource = "ThisForm.aEmps"
This.ColumnCount = 2
This.ColumnWidths = "80,60"

* This code in the Init of a form
* populates a combo on that form
* with selected items from Customer.
* It assumes the combo's RowSourceType is
* set to the default 0.
ThisForm.cboFaxTo.ColumnCount=2
ThisForm.cboFaxTo.ColumnWidths="150,120"
SELECT Customer
SCAN FOR NOT EMPTY(Fax)
  WITH ThisForm.cboFaxTo
    .AddListItem(Company_Name,.NewItemId+1,1)
    .AddListItem(Contact_Name,.NewItemId,2)
  ENDWITH
ENDSCAN