Dock

UIEnable

This event gives you a hook into the controls on a page when the page is activated or deactivated. It fires for each control on the page on the way into and on the way out of the page. It took us awhile to "get" this one, but it's actually pretty cool.

Usage

PROCEDURE oObject.UIEnable LPARAMETERS [ nControlIndex ,] lComingIn

Parameter	Value	Meaning
nControlIndex	Numeric	If the control is contained in an array, indicates which element of the array fired the event.
	Omitted	The control is not part of a control array.
lComingIn	.T.	The event fired because the page containing this control is being activated.
	.F.	The event fired because the page containing this control is being deactivated.

The firing of this event is tricky. First, it fires not for the page frame, nor for the page (in fact, pages don't even have a UIEnable event), but for the controls contained on the page becoming active or inactive. That is, when a page comes to the top, the UIEnable events of the controls for the page that was on top fire, then the UIEnable events for the controls on the page that's now on top fire.

In addition, UIEnable fires only on changes to the active page. If focus leaves the page frame, it doesn't fire. Nor does it fire when focus returns to the page frame. It fires only when a different page of the page frame comes to the top.

When would you use this event? When you want to check something about some control whenever its page comes to the top. If a control on one page depends on several other controls in the page frame, UIEnable lets you update it once—when you need it to be right. For example, suppose a list is based on a view and the view parameters are specified on the other pages. You don't want to requery the view and the list every time one of the parameters changes—that would be horribly slow. Instead, you can put the calls to the REQUERY() function to update the view and the Requery method to update the list in the UIEnable method of the list and it'll be updated whenever that page comes to the top.

You might also take advantage of this event to refresh pages when they come to the top. Many folks add a custom object to each page in a page frame with the UIEnable method set to call the page's Refresh method on the way in. (The adding is done in the Init method.)

This event is really elegant. On the other hand, we can't figure where its name came from. Probably from some other Microsoft language. We think PageActivate and PageDeactivate (or OnPageActivate and OnPageDeactivate) would be just a wee bit more intuitive.

Example

* In a simplified version of the example above, * assume one page of a page frame contains a list * based on a query (RowSourceType=3) and that * the query conditions include some variables, * which are the ControlSources of controls * on other pages. * To update the list when its page comes to * the top, you'd have the following in * the list's UIEnable event: IF lEnable   && Only on the way in   This.Requery() ENDIF

See Also

Page, PageFrame, Refresh

View Updates

Copyright © 2002 by Tamar E. Granor, Ted Roche, Doug Hennig, and Della Martin. All Rights Reserved.