Our last blog article dealt with promoting a help event so that dictionary help could be displayed when the user pressed F1 on a prompt. This was well received but it was pointed out that the technique crashed and burned when used from a multi-column edit table.

The reason for this is obvious - if an edit table has more than one column then it will logically also have more than one data dictionary item associated with it. So we need to determine which edit table column we are currently on and use this information to determine the correct dictionary item to use.

When we ask for the COLUMN property of an edit table, what we are provided with is a sub-value mark delimited array of all of the columns in the edit table. (The reason for this using such an unusual delimiter is simply that the columns property is derived from a larger array maintained by the system behind the scenes - the "control semantics"). Then to establish what column we're currently on we simply get the DEFPOSPROP property. (We could just get the CARETPOS property - but having been bitten once by not considering all possible permutations, we're now allowing for the possibility that a custom OLE control (which supports multiple columns) might not expose the current column using CARETPOS. So we use DEFPOSPROP which will always return the current column position regardless of how it is exposed. This assumes that the OLE control has been configured correctly using the New OLE Entity window described in this blog entry).

So without further ado we present the revised promoted event script!

A recent query on the Works forum from a new OI user provided us with the perfect excuse to visit a useful tool introduced into OI 10. Those of you who've been developing for a while can probably guess what it is but those of you who haven't will just have to wait for the reveal at the end of the article!

The query was how to emulate the AREV catalyst H,HD command. I'm sure that's instantly recognisable to all die-hard AREV programmers - it displays the dictionary description for the column associated with a prompt as a help message. OI lost some of the cooler features of AREV during the rewrite and regretfully this feature didn't make it. I imagine the initial thought back then was that people would expect proper Windows Help files, so it wasn't worth duplicating this.

Anyway, implementing this in OI 10 was actually a relatively straightforward exercise so we thought we'd document it here to give us an excuse to show off... you know what!

So thinking of the steps involved here, we need to create a HELP event script that reads the dictionary to get the help, then displays a message containing that help. (Commercially we'd probably call a commuter module containing all of our promoted events from the script but for simplicity we'll stick with this).

We also need to add a hidden menu item to trigger the event (of course you could have this on your MDI frame so that you didn't need to do this, but for the purposes of this example...).

So let's illustrate this using the OI 10 EXAMPLES app... we'll use the CUST_ENTRY window


Firstly let's do the easy bit and create our help message to display, by creating a new message entity.


Now let's add the "Help" menu item to the CUST_ENTRY form



We'll add a script to the HELP event for the ID_FIX editline which uses the ID dictionary in CUSTOMERS.



and we make sure that the dictionary actually has help defined



Yes, it has. So putting it all together, we run the Window and press F1 in the Record Id prompt and


Works like a dream - of course... but we're going to want this on every prompt on the Window - and that's going to be tedious. If only there were a way to tell OI that we want to use the same method EVERY time a HELP event is triggered.

Obviously there IS a way or this paragraph'd be an outro so... you're probably already familiar with the concept of "Promoted Events" but what you may not have realised is just how easy OI 10 makes them! (If you're not familiar with promoted events -  the event chaining logic in OI firstly looks for a script associated with the control in question but it then looks for increasingly generic event handlers, including for example a script to be run for all HELP events for EDITLINES in this Window, or HELP for all HELP events for all EDITLINEs in this application, or a script to be run for all HELP events for all controls in any Window in this application. Before 10 this was achieved by copying the initial event script around to carefully named EVENTEXES - cumbersome at best AND OI didn't keep track of them in the repository so they were a bear to deploy).

There's a new Window in OI 10 found here...

that allows us to edit a promoted event directly. The dialog prompts us for the control type, then event type and the form for which to create a promoted event. We wish to create a promoted HELP event for all controls in all windows, so we select ,  Help and


and then we copy the code from our original edit line help into here. (Note that we've also included the event shorthand versions of get and set_property as comments. Shorthand has been extended in 10 and makes it possible to use in pretty much any situation. This makes the code easier to read for some developers and is faster to develop with).


We save and compile the code, then return to our original CUST_ENTRY window and clear down the original event code. It is no longer needed as our promoted event will do the work for us.

There is however one last step required before our promoted event can be used. We have to tell the system that we actually want this to happen. Y'see when you compile a form, the system goes off and compiles into the executable version of the form ALL of the events used by the form, but as a rule it only checks for specific categories of promoted event to make the compilation process as quick as possible. We need to tell it to look for our promoted help event. We do this using the Window found under Tools/Form Designer/Event Configuration...


We select the edit line control and we check that we'd like our promoted event to be enforced.

Once we have saved this row (and depending on your version of OI you might have to go to SYSPROG to do this) we can compile our Window. This adds our promoted event into every edit line on our Window (remember other Windows will need to be recompiled for these changes to be reflected so it make sense to plan promoted events in advance at the start of development). Now we can press F1 on a prompt we hadn't previously even looked at (Company) and receive help from the dictionary.


As the pièce de résistance we can even select these promoted events when defining RDK modules!


Of course, being programmers we always want stuff for free - so what'd be really nice was if the Promoted Event Designer actually updated the Event Configuration window for you - I mean, it's unlikely you're going to be promoting something and NOT want to use it - but for now this has made working with Promoted Events an order of magnitude easier - thank you Rev!