IB Statements/eventsub

From CometWiki

---

Revision as of 10:48, 21 May 2009

EVENTSUB statement

Syntax: EVENTSUB statement-label,event-string$,source-string$

where:

statement-label is the label of a statement in the current program where control is transferred when an event occurs. In this regard, the EVENTSUB statement is similar to the MESSAGESUB, ERRORSUB, and ESCAPESUB statements.

event-string$ is a string variable whose value is assigned by the object that caused the action to occur. For example, this could be the value of the LinkAction$ field in a Comet hyperlink.

source-string$ is reserved for future use

Discussion: The EVENTSUB statement defines an event handling subroutine. Such a routine provides a way for your program to determine what to do when an event occurs.

For example, an event occurs when the user clicks on the Comet hyperlink. For a detailed discussion of this topic, see Comet hyperlinks.

Note: To remove an eventsub trap, issue the statement without parameters, as follows:

EVENTSUB

Some important notes: Bold text

An event handling subroutine ends with a RETURN statement. This returns the program to the statement that was being executed when the event occurred. Thus, the normal program flow is maintained after an event has been processed.

When your program is in an event handling subroutine, it can still receive events (e.g., the user can click on a second hyperlink while your program is still processing their first click). These events are queued by Comet. When your program re-sets the eventsub trap, it immediately processes any events that have been added to the queue. For this reason, we recommend re-setting the eventsub trap just prior to the Return statement.

If your program executes an EVENTSUB statement without parameters, event handling is disabled and Comet purges all events that are in the event queue.

It's acceptable to code multiple event handling subroutines in your program, although only one can be in effect at any given time. An event handling subroutine takes effect when the EVENTSUB statement is executed.

Example: The following code segment shows a Comet hyperlink and a related EVENTSUB statement. When the user clicks on the hyperlink, the program branches to the GetEvent label and assigns "LINK1" to Event$. The event handling subroutine then determines what action to take, which in this case is a Print statement. Notice that the EVENTSUB statement is re-issued at the bottom of the routine, just prior to the Return statement.

Print @(0,4);(Hyperlink="Chocolate","LINK1",0) 
!
EVENTSUB GetEvent,Event$,Source$
.
.
.
GetEvent:
If Event$ = "LINK1" Then
Print (WC);"Chocolate is a very good flavor."
Endif
EVENTSUB GetEvent,Event$,Source$
Return

Note: This program is an excerpt from the HyprLink.ibs program in the DMW directory.