Introduction
Whenever a user does something with the keyboard or the mouse, Windows will generate an event giving the details of exactly what the user did and which form or control he did it to. These events are processed by the TrueGUI system and are passed on to the application program in a controlled manner.
Windows is an "Event-driven" programming model and traditional application programming languages, such as AlphaBASIC, are a "Controlled-flow" programming model. Since events can be generated at any time by the user, these events could come at a time when it is not convenient for the application program to handle them. As an example, suppose the user had just finished filling out a form and has clicked on the "Submit" button. Your application program may then need to harvest all the information from the various text controls on the form and store them in a database or file. During the time you are processing this data, the user may then click on a menu item that will move him on to the next task at hand. Since you may still be processing the form data, the TrueGUI system cannot just interject these asynchronous events into your data stream. Enter the event queue.
Receiving events and the event queue
Each time an event is generated, that event is placed into an event queue on the client side. Events are not forwarded on to your application program until you request them with an event request command.
Events return a single ASCII text line as follows:
3EventName,ControlName <CR>
The first character is the message type code of 3 which identifies this as an event message
EventName specifies the event that occurred (Click, KeyPress, Mouse Hover etc.)
Control Name is the fully-qualified control name such as "MyForm.button2"
An event request has the following format:
INPUT LINE "{ TrueGui.NextEvent? }", TgReply$
Alternatively, the event request command could be sent out as a PRINT statement followed by an INPUT LINE statement without a prompt, if this is more convenient. Thus, the following two statements would have the same result as the above INPUT LINE statement:
PRINT "{ TrueGui.NextEvent? }"
INPUT LINE TgReply$
You can also query the TrueGUI global object for the number of events currently waiting in the event queue with the following command:
INPUT LINE "{ TrueGui.EventCount? }", TgReply$
This would allow you to continue background processing if no events are pending.
Selectively adding and removing events
There are hundreds of various events which can be generated by the multitude of controls defined in the .NET framework. Add to that the ever-increasing number of third-party controls that are becoming available and you have a huge number of events that can be generated by even a simple form. To prevent your program from becoming congested with events that you are not interested in, the TrueGUI system incorporates several commands that allow your program to add and remove specific events. Specific events can be added to individual controls, to a group of controls defined by their type, or to all controls on a specific form. Events can be removed in the same manner.
When an event is added to a control, that control will generate those events whenever the user performs the specific action defined by the event that was added. When the event is removed from the control, that control will no longer generate events for that action.
Events may be added and removed using several related commands depending on the controls that you wish the events to be added to or removed from. There must be one command for each different type of event you wish to add or remove but that same event may be applied to a single control or to many controls on the same form. Commands that add an event to controls whose name or type match a specific criteria take a regular expression to specify to names or types of the control to match against. All commands take the event name (such as "Click" or "KeyDown") as the first argument. The second argument is the control name for single events or the form name for multiple events. Commands that add/remove events based on matching the name or control type take a regular expression as the third argument.
The following examples show the different commands used to add or remove events from forms and controls.
1. To add or remove a "Double Click" event from a single form or control:
PRINT "{ AddEvent(`DoubleClick`, button1) }"
PRINT "{ RemoveEvent(`DoubleClick`, button1) }"
2. To add or remove a "DoubleClick" event from all controls on a form:
PRINT "{ AddEventsByForm(`DoubleClick`, MyForm) }"
PRINT "{ RemoveEventsByForm(`DoubleClick`, MyForm) }"
3. To add or remove a "KeyDown" event from all controls on MyForm whose name contains either "ABC" or "Data":
PRINT "{ AddEventsByName(`KeyDown`, MyForm, `ABC|Data`) }"
PRINT "{ RemoveEventsByName(`KeyDown`, MyForm `ABC|Data`) }"
4. To add or remove a "Click" event from all controls on MyForm whose type contains "Button", "Check", "Tool" or "Menu":
PRINT "{ AddEventsByType(`Click`, MyForm, `Button|Check|Tool|Menu`) }"
PRINT "{ RemoveEventsByType(`Click`, MyForm, `Button|Check|Tool|Menu`) }"
Remember, the third argument in the above examples is a regular expression defined in the .NET framework Regex class. Any regular expression can be substituted for matching on the name or type of a control.
When you first load a form, the following two default commands are executed automatically to activate common events for all controls on the form:
PRINT "{ AddEventsByType(`Click`, MyForm, `Button|Check|Tool|Menu`) }"
PRINT "{ AddEventsByType(`Leave`, MyForm, `Text|List|Combo|Date`) }"
All other events that your program requires must be loaded manually by your application program before they will be generated. Note that all events will be automatically removed when the form is closed or the program exits. It is not necessary to manually remove events that you have added unless you want them deactivated prior to program end.
The ability to selectively add events by name or type is required to implement third-party controls that may generate events of a custom nature.
Harvesting data from an event
Some events, such as a button "Click" event, need no additional data because the event itself along with the control's name tell the whole story. Most events, however, require additional data to fully define the details of the event. Key presses, for example, would be meaningless without some way to tell which key had been pressed. Mouse movement events require the screen coordinates to fully define the movement. All events generate a block of data that is derived from the .NET EventArgs class and each different type has different data that can be read from the specific EventArgs data block. This data block is passed to the TrueGUI interface when the event is generated. TrueGUI then stores the event in the event queue along with the event name and sending control for later NextEvent? requests from the server program.
To avoid having to define each different EventArgs type (there are almost 200 of them in the .NET framework alone), TrueGUI uses a single property called TrueGui.EventData for harvesting the data in the specific EventArgs block. The EventData property gets loaded with the specific EventArgs block associated with each event when that event is delivered to the application program in response to a NextEvent? data request. This data is valid for one or more data requests until the following NextEvent? command acquires the following event.
As an example, the KeyDown event generates a KeyEventArgs data block that contains 8 properties with all sorts of information about the key that was pressed and the state of the keyboard flags when the key was pressed. One of these KeyEventArgs properties is called KeyCode that contains the code of the key that was pressed. To get the KeyCode after a KeyDown event is received by the application program you would use the following command:
INPUT LINE "{ EventData.KeyDown? }", TgReply$
The Microsoft .NET help file must be referenced to learn what data is available for each different EventArgs block type. If a third-party control has been acquired, the associated help file must be referenced to learn the events that are generated by each control and the associated EventArgs data block that it returns.