when

Topic group Related topics

Event fired when attempting to give focus to an object; return value determines if object gets focus.

Parameters

<form open expL>

true for when the when event handler is called when the form is opened; false from then on.

Property of

All form components that can get focus (except NoteBook)

Description

Use when to conditionally prevent an object, that has not been disabled, from getting focus. If you set an object’s enabled property to false, the object will appear grayed-out and disabled. This is a visual indication that the object cannot get focus. The object is removed from the tab sequence and clicking the object has no effect.

If an object is enabled, you may define a when event handler to determine if an object is available. The event handler must return true to allow the object to get focus. If it returns false, the object does not get focus. If the object was clicked, focus remains on the object that previously had focus. If Tab or Shift+Tab was pressed, the focus goes to the next control in the tab sequence.

Using when gives you the flexibility of displaying a message or taking some other action when the focus is not allowed. But in most cases, it’s better to conditionally disable controls so that they are clearly not available. For example, if you have a checkbox to echo output to a file and an entryfield for the file name, you can disable the entryfield when the checkbox is unchecked in the checkbox’s onChange event handler.

If the when event handler returns true, or there is no when event handler, onGotFocus fires after the object receives focus.

The when event for all controls is fired when the form first opens. Use the <form open expL> parameter if necessary to distinguish that event from all other normal focus attempts.

Calling an object's setFocus( ) method invokes a call to the when event handler, and the when event's return value determines the success of the setFocus( ). The success or failure of the setFocus( ) method is not, however, returned to the calling routine.

The firing order for Events when opening a form:

1. The form's open( ) method is called

• The when event for each control is fired according to the z-order

• The form's onOpen event is fired

• The onOpen event for each control is fired according to the z-order

The firing order for Form object Events:

Clicking on a form object will result in the following events firing in this order;

2. The when event

• The onGotFocus event

• A mouse event such as, onLeftDblClick

Navigating to a form object by using the Tab key will result in the following events firing in this order;

3. The when event

• The onGotFocus event

Tip: ON KEY LABEL TAB <command> will perform an action (<command>) when the user presses the TAB key (See ON KEY). However, even though ON KEY LABEL TAB is set to perform <command>, pressing Shift-Tab will still move to another form object (the preceding one in the z-order) and fire it's events in the above order.