On Event statement (LotusScript® Language)

Binds an event-handling sub or function to an event associated with a IBM® software object, or breaks an existing binding.

Note: The IBM® software application may provide an empty sub or function for each object event, in which case you do not need to use On Event statements. You can enter a script in the appropriate sub or function, and the script automatically executes when the event occurs. For details, see the product documentation.

Syntax

On Event eventName From prodObject { Call handlerName | Remove [ handlerName ] }

Elements

eventName

The name of an event specified in the product class definition.

prodObject

An expression whose value is a reference to a product object. (Events cannot be specified in user-defined class definitions.)

Call

Binds the handlerName sub or function to the specified eventName from the specified prodObject.

handlerName

The name of an event-handling sub or function for the specified eventName and prodObject. Whenever the specified event happens on the specified object, handlerName is called.

Remove

Detaches the handlerName sub or function from the object-event pair. If no handlerName is specified, this statement detaches all event-handling subs from the object-event pair.

Usage

An event-handling sub or function is defined like any other sub or function, with the restriction that its first parameter must be a reference to the product object that can raise the event. The remaining parameters are defined by the event in the product class, and are used in the handler call.

You can specify multiple event-handling subs or functions for the same event from the same object, using multiple On Event statements. The order of execution of event-handling subs or functions bound to the same event is undefined.

A function is necessary only if the event requires a return value from the handler.

Note: Of the three types of objects LotusScript® understands (OLE/COM objects, LotusScript® product objects, and LotusScript® Native objects), only LotusScript® product objects can register events.

Example