MODIFY STRUCTURE | Hackers Guide to Visual FoxPro 7.0

Requery

This method of list and combo boxes lets you update their contents when the underlying data source has changed.

Usage

oObject.Requery()

Sometimes the data item on which a list or combo is based changes. For example, a list based on an array might contain all the Employees in a particular country. If another control on the form lets the user change countries, we need to refill the array (probably using SELECT), then update the list. The update part is done by calling the list's Requery method.

If the list or combo is based on a SQL Statement or Query, the Requery call is even more important. In that case, Requery both re-executes the query and repopulates the list.

In general, you need to call Requery any time something has happened in the application that might have changed the data that the list or combo is based on. Requery repopulates the list or combo and refreshes its display.

Most of the time, you won't put any code in the Requery method. (In fact, we find that we rarely put code in any method that isn't tied to an event.) But Requery has a cool feature. Say your list or combo is based on a query and the query has a macro, maybe for the ORDER BY or GROUP BY clause. You can't reference a property (like the Value of a combo box, perhaps) in a macro. Instead, in the Requery method, you can copy the property to a local variable, which is used by the macro. Since the custom code in Requery is executed before the default behavior of updating the list or combo, this works out neatly. In fact, in general, when a query needs to execute in order to refill a list or combo, we like to put the query in Requery, thus encapsulating the whole refresh in one method. That way, other controls don't have to know anything about the list or combo's RowSourceType.

Here's an example. Say your form has a list of Customers and a combo, called cboOrderBy, which lists the existing tags for Customer. (Yeah, in a real app, we'd make it more user-friendly.) The list could have RowSourceType = 3 (SQL Statement) with RowSource set to:

SELECT First_Name,Last_Name FROM Customer ORDER BY &cTag

Then, Requery would contain:

LOCAL cTag cTag = ThisForm.cboOrderBy.Value DODEFAULT()  && call any inherited behavior and perform the base behavior              && of refilling the list

When you call the list's Requery method, the combo's value is copied to cTag and used in the ORDER BY clause.

Don't confuse this Requery method with the REQUERY() function used with views. While they have a similar function, they're independent of each other. (There are times, in fact, when you'll need to call REQUERY(), then follow it with a call to a control's Requery method.)

Example

* If lstEmployee shows all the Employees in cCountry, based on a * SQL Statement,and cCountry is entered via cboCountry, put code * like this in cboCountry's Valid method:   ThisForm.lstEmployee.Requery()