Page History
...
Just like our Script Event example earlier, we see an entry telling OpenInsight to look for a promoted event handler (SYSPROG*..OIWIN) and pass it 11 parameters when the CREATE event fires. This way, OpenInsight doesn’t have to search for the highest level Promoted Event handler (see Figure 3). In fact, only one entry is stored in the window’s object code for each event, and that entry represents the first handler to be executed in the chain. For example, if we recompiled a form that already had a Script Event handler for the CREATE event, we would see this:
Notice that this entry is exactly the same as the one in Figure 2, but our Promoted Event will still fire because OpenInsight will look for any lower level handlers in the order shown in Figure 3. You can guess, then, that forms already containing a higher level handler than your new Promoted Event handler do not need to be recompiled. But forms with lower level handlers (or none at all) do need to be recompiled. The safest course of action is to recompile all your forms.
Okay, once you’ve recompiled your windows you are done. There are no more tricks left; your Promoted Event is now ready to serve the greater good. Seriously, you’re done. But if you’re looking for more, read ahead on how to deploy your Promoted Event handlers.
Giving Promoted Events their Marching Orders
If you need to deploy your Promoted Event handlers to other applications, or if you use RDKs to update your application at a client site, then it’s important to know how to add your Promoted Event handlers to your RDKs. Unfortunately, there is no “Promoted Event” entity, so we have to find another way to deploy our Promote Event handlers.
Application Row entities are generic entity types useful for deploying records in a table. So this is our best option for deploying Promoted Event handlers. Start by opening the “Create New Entity” window from the Application Manager—select the Entity menu, then New. Then select “General” and click OK.
Now, when the New Entity window appears, select Application Rows in the Type/Class list box. In the Entity field below the Type/Class box, we need to specify the table and record in a special format:
| Code Block |
|---|
TABLENAME:KEY (where all asterisks are replaced with underscores) |
...
In our example, we would set the Entity to SYSREPOSEVENTEXES:MYAPP_CREATE..OIWIN_. Next, set the Title to whatever is meaningful to you—“MYAPP’s Promoted Create Event” for example—and set the Sub-Key field to the actual key in SYSREPOSEVENTEXES. In our case, we’ll set it to MYAPP*CREATE..OWIN* as you can see below:
Now you have an entity for your Promoted Event handler. All you need to do now is add the entity to your RDK and you’re all set. There’s no need to worry about enforcing promoted events on your target application because, remember, the necessary pointers to the Promoted Event handlers are already embedded in your windows. (Note: This won’t be true for windows which were last compiled before you introduced your promoted events. In this case, you will need to recompile your windows and deploy them as well before they will take advantage of any Promoted Event handlers.)
Demoting Events
Sometimes you will need to stop an event from being promoted. This happens if you accidentally import a window with Promoted Event references into an application that doesn’t have any Promoted Event handlers; or maybe you just changed your mind about using them. In any case, removing them is simple.
...
- Open the Event Designer
- Find the event you wish to demote
- Set the Enforce flag to No
- Restart OpenInsight
- Recompile all windows that were using that Promoted Event
- If you have an Application Row entity for your Promoted Event handler, you may choose to delete it by selecting Delete from the Application Manager’s Entity menu.
- Finally, you will want to delete the record from the SYSREPOSEVENTEXES table. This will prevent OpenInsight from automatically executing these events if the form already has a Script Event handler for the same event type.
With Great Power Comes Great Responsibility
...
There is a saying, “Just because you can do something, doesn’t mean that you should.” This is true with Promoted Events. Here are some things to consider before venturing down this path:
- Keep them generic. Promoted Events benefit you by providing a means for enhancing the global behavior of your application. Control or window specific event handling should be in that window’s commuter module or Script Event handlers, not in the Promoted Event handler.
- Exceptions are okay. It’s okay to have exceptions in your Promoted Event handler so long as the exceptions are generic. Skipping controls or windows based on a naming convention or a user-defined property is okay. Skipping controls or windows by name is not. The reason is simple, the less generic your Promoted Event handler becomes, the harder it is to track down bugs.
- Alternative source of “Pre” events. As mentioned in this white paper, some events can be processed before the system processes them. Without promoted events, Script Event handlers are the only means to this end. However, you can now use Control Type Specific Promoted Event handlers instead—avoiding the need to maintain and deploy hundreds of individual Script Event handlers.
- Never rely on Promoted Events when writing third-party tools. Remember, you’ll be deploying these onto who-knows-whose machine, so you don’t want to clobber their Promoted Event handlers by overwriting them with your own. Note that OpenInsight promotes the CLOSE and OMNIEVENT events by default, so be sure to demote those in your third-party tool development environment.
- Useful for global configurations. While it’s possible to change the font of every control and window manually or by writing some automation routine, you could also set the font for every control during a promoted CREATE event. Then, if you need to change the font application-wide, you just change it in one place and recompile.
- OpenInsight bug or Promoted Events bug? If you are just mind-boggled as to why your control or window is behaving funny, don’t assume right away it’s a problem with OpenInsight. A Promoted Event handler could be the cause. Worse yet, it could be a Promoted Event handler from an inherited application. Don’t fall into the trap of letting those Promoted Event handlers become out of sight and out of mind.
References
...
- OpenInsight 7.0 Programmers Reference Manual, Chapter 10: Programming Techniques,
...
- Promoted Events.
- The X Events – Andrew P. McAuley, Sprezzatura Ltd., S/ENL Volume 1 Issue 7,
...
...
- Creating a Custom Event – Don Bakke, SRP Computer Solutions, Inc.
...
