Introduction
Events are an OpenInsight programmer’s way of life. We spend thirty seconds placing a control onto a window and the next several minutes or hours responding to its various behaviors. Advanced programmers refine the process to a perfect efficiency. The elite among them use Promoted Events.
Promoted Events are available in all versions of OpenInsight, so take some time to see what this white paper has to offer. The first few sections provide a general background on events then defines Promoted Events. The remaining sections detail the process of implementing them. The final sections will share some advantages to using Promoted Events and dangers they inherit. But first, let’s start with a little clarification.
Events and Their Handlers
Events and Event Handlers are not one and the same. Events are just arbitrarily named notifications. The CLOSE event could be called anything, like the SHUTDOWN event or the GOODBYE event. Furthermore, the CLOSE event does absolutely nothing. You heard right, the event does nothing at all. Let’s say I have a hypothetical event called A_BUS_IS_HEADING_RIGHT_FOR_YOU, and you receive this event while crossing the street. By itself the event causes no change to the situation; it’s merely a notification. It’s up to you, the event handler, to respond to the event by running out of the way.
Event handlers are the modules designed to react to certain events. Using the CLOSE event as an example, there must be an event handler somewhere in your program that closes the window whenever it receives a CLOSE notification. You might say, “Okay, but I never write code to explicitly close a window in OpenInsight. It does so automatically. If you claim that the CLOSE event by itself does nothing, then how does the window get closed?” Easy, OpenInsight already has an event handler for the CLOSE event. In fact, OpenInsight has default event handlers for many of its events, and they’re designed to carry out very basic functions respective to the events to which they respond. These event handlers in OpenInsight are referred to as System Event handlers. But there other types of event handlers in OpenInsight as well.
A Series of Events
Every event is passed through a chain of event handlers in the following order: Script Event handlers, System Event handlers, and Quick Event handlers.
- Script Event handlers are modules you write within the Form Designer’s Event Handler editor, and they are stored in the SYSREPOSEVENTS (source) and SYSREPOSEVENTEXES (object) tables.
- System Event handlers are the ones mentioned in the previous section; they perform default actions on events. These are hard coded into OpenInsight and cannot be modified. (Technically speaking this isn't true. However, as will be discussed later, modifying or replacing them will create unexpected behavior and an unstable environment. Therefore, they should be left alone.)
- Quick Event handlers are pre-defined handlers you specify in the Form Designer’s Quick Event Builder tool. These types of handlers have there own strengths, but that is for another white paper.
Order is important in the chain of events:
Script Event handlers are called first, which are followed by System Event handlers, and then Quick Event handlers. Furthermore, an event handler returns 1 to allow the event to continue to the next handler or 0 to halt the event chain. This means that Script Event handlers can prevent default behavior by returning 0. For instance, to cancel the closing of a window, the Script Event handler for the CLOSE event returns 0. It is not possible for a Quick Event handler to cancel the closing of a window because it handles the event after the window is closed by the System Event handler.
Anatomy of a Script Event
As previously mentioned, Script Event handlers are written in the Form Designer’s Event Handler editor and the compiled code is stored in the SYSREPOSEVENTEXES table. Each handler in the table is identified by the following key structure:
APPNAME*EVENTTYPE*FORMNAME.CONTROLNAME
As an example, let’s say you are working in the MYAPP application. You have a window called FOOBAR with a few controls. You create a Script Event handler for an edit line’s GOTFOCUS event, and the name of the edit line is MY_EDITLINE. The SYSREPOSEVENTEXES key would be:
MYAPP*GOTFOCUS*FOOBAR.MY_EDITLINE
Furthermore, you also create a Script Event handler for that same window’s CREATE event. Its key would be:
MYAPP*CREATE*FOOBAR. Note that window based events keep the period in the key.
Now, the simple existence of such events within the SYSREPOSEVENTEXES table is not sufficient to complete the connection between the event and its handler. OpenInsight does not automatically search the SYSREPOSEVENTEXES table for matching events, which is fortunate because such a search could take a long time—something you don’t want when events are frequently being fired. To increase performance, a control or window’s event handler is stored within the window’s object code so OpenInsight knows exactly where to find its event handlers. Below is a snippet of a window’s object code record:
