An important part of programming dialogs is replying to the event notifications sent by the operating system. In the original implementation of ooDialog, it was not possible to do this.
Beginning with ooDialog 4.2.0, it is now possible to reply to the event notifications. All new event connection methods, that is those methods that did not exist prior to 4.2.0, have as the last argument, an optional 'willReply' argument. This gives the programmer some control over whether the event handler will reply or not.
I'm using the term reply to mean return a value that the interpreter waits for in the window message processing loop.
In typical window application programming, the operating system sends a message to the window processing loop, the programmer returns a value to the operating system, and the operating system sends the next message. In the original ooDialog, when the ooDialog framework got a message from the operating system, it immediately returned a value to the operating system, and then passed the message on to the ooDialog dialog object. The reply from the dialog object, if any, was simply discarded.
This skewed the way things worked. Since the framework replied immediately to the OS, in a series of messages 1 2 3 4 5 6 7 8, by the time the dialog object got message 2, the operating system could already be sending message 8.
Having the interpreter wait for each reply to each message is very important in correctly programming dialogs.
If we were starting from scratch, every event handling method would have to return a value, the interpreter would wait for that value, and then return it to the operating system.
Since we are not starting from scratch, and existing code has event handlers that did not return a value, or may not have returned at all in a timely manner, that behavior needs to be preserved. But, for existing event connection methods, it is important that programmers are able to program correctly. Either when writing new code, or that they are able to fix existing code.
For some window messages, the operating system expects a certain value to be returned, which controls what the operating system does. For other messages, the operating system ignores the value returned. This gives us 3 cases for how the ooDialog framework handles the messages in the message processing loop:
1.) Immediately return a value to the operating system and then send the message on to the Rexx dialog. (Required to preserver old behavior.)
2.) Send the message to the Rexx dialog, wait for the return value from the event handler, and then send that value to the operating system. (The correct way to program windows.)
3.) Send the message to the Rexx dialog, wait for the return from the event handler, but ignore the return value, and return 0 to the operating system. (Useful if the OS ignores the returned value anyway, but keeps things in sync. Doesn't require the programmer to actually return a value from the event handler.)
So, all event connection methods should have an optional 'willReply' argument, with 3 values. .false for case #1. .true for case #2. The keyword 'sync' for case #3.
Existing event connection methods should have the optional argument added to the end of the existing argument list. This does not require any changes to existing code, but gives programmers the ability to fix their existing code if they want to.
Note, the implementation is done, just needs to be documented.