CREATING A USER-DEFINED EVENT
   Home    •    Español  

In previous versions of QuickBasic, the only events that could be trapped were those already defined in the language: Com, Key, Pen, Play, Strig and Timer. There was no way to define your own event.

QuickBasic 4.5 allows you to define your own event trap. When the event occurs, Basic calls the routine that handles the trap, just as if the event were part of the QuickBasic language.

A user-defined event has three elements. The first is a routine that detects the event. The second is this routine's call to the Basic procedure SetUevent, which traps the event. The third is Basic's call to a routine that handles the event.

You create a user-defined event by writing two pieces of code. The first is the routine that detects the event. (The event could be a hardware interrupt, or perhaps an altered data value at a special memory location).

This routine can be written in Basic, or other languages, such as C and assembler. (Basic routines can be included in the main module. Code written in other languages must be separately compiled and added to a Quick Library).

The event-detecting routine must block; that is, it must sit waiting for the event. (A routine that does not block would have to be called repeatedly to see if the event has occurred.

This defeats the purpose of a user-defined event, as it is no different from conventional polling). When the event occurs, it calls the Basic routine SetUevent. It is this call that traps the event. Basic then calls the event handler.

The event handler is the second piece of code. The advantage of separating event trapping from event handling is that the handling can be tailored to the needs of the moment; the same event can be handled differently in different parts of the program.

Let's consider a simple example to see how this works. Our hypothetical programmer has designed an interface board for home monitoring and control. One of its features is a mailbox alarm: opening the mailbox door closes a switch that sets the most-significant bit at a specific buss address.

Here is a simple Basic routine to monitor this switch. (The segment and address quantities are for illustration only. They are in the video RAM space, and probably wouldn't be useful for other kinds of interfaces).

MailBoxOpened:
Def Seg = &h9000 'set the address segment
value% = Peek (&h1234) 'read value at address in that segment
IF value% Then Call SetUevent 'tell Basic event has occurred
Def Seg 'return to Basic data segment
Return

Value% is either zero, or has its MSB set. In the latter case it is logically "true" (indicating that the mailbox was opened), and the SetUevent routine is called. This routine (which is part of Basic) tells Basic that the expected event has occurred, and it is time to execute the event-handling routine. All event-detecting routines, regardless of the languages they are written in, must call SetUevent.

If the event-detecting routine is in a language other than Basic, the Quick Library containing it has to be loaded before a QuickBasic program that uses it can run or be compiled. Include a Declare Sub statement in the module calling the event-detection routine, so that Basic knows how to find it.

Now let's write an event-handling routine to tell our programmer his mail has arrived:

MailCame:
Print "Ta-Dah! Your day is made! The mail came!"
Return

All that's left is to tell Basic about the user-defined event handler, using the On Uevent statement. On Uevent works just like On Event; it associates the user-defined event with the event-handling routine:

'associate the handler routine with user event
On Uevent Gosub MailCame
Uevent On 'initiate user-event trapping
...
Call MailBoxOpened 'call the routine that looks for the event
...
End

Note that On Uevent deals only with the event-handler; it is not concerned with event-detection. Once the Uevent On statement has been executed, any call to SetUevent will trigger the specified event-handler, regardless of how or where the call is issued.

Here is a summary of the steps in creating and using a user-defined event handler:

(1).– Write the routine that detects the event. When the event occurs, the routine must call the Basic routine SetUevent.
(2).– If the event-detecting routine is in Basic, place it after the End statement in the module where it will be called.

If the event-detecting routine is not in Basic, compile it and include it in a Basic Quick Library. The modules that call this routine must include a Declare Sub statement so that Basic can find the routine.

(3).– Write the routine that handles the event.
(4).– Use the On Uevent statement to tell Basic the name of the event-handling routine associated with the user-defined event.

(5).– Use the Uevent On statement to initiate trapping. Uevent Off and Uevent Stop may be used to terminate or postpone trapping.

(6).– Call the event-detecting routine. When the event occurs, Basic will call the event-handling routine named in the On Uevent statement.