ECLKeyNotify Class
ECLKeyNotify is an abstract base class. An application cannot create an instance of this class directly. To use this class, the application must define its own class which is derived from ECLKeyNotify. The application must implement the NotifyEvent() member function in its derived class. It may also optionally implement NotifyError() and NotifyStop() member functions.
The ECLKeyNotify class is used to allow an application to be notified of keystroke events. The application can also choose to filter (remove) the keystrokes so they are not sent to the host screen, or replace them with other keystrokes. Keystroke notifications are queued so that the application will always receive a notification for each and every keystroke. Only keystrokes made by the real physical keyboard are detected by this object; keystrokes sent to the host by other ECL objects (such as ECLPS::SendKeys) do not cause keystroke notification events.
- Define a class derived from ECLKeyNotify.
- Implement the derived class and implement the NotifyEvent() member function.
- Optionally implement the NotifyError() and/or NotifyStop() functions.
- Create an instance of the derived class.
- Register the instance with the ECLPS::RegisterKeyEvent() function.
The example shown demonstrates how this may be done. When the above steps are complete, each keystroke in the emulator window will cause the applications NotifyEvent() member function to be called. The function is passed parameters indicating the type of keystroke (plain ASCII key, or special function key), and the value of the key (a single ASCII character, or a keyword representing a function key). The application may perform any functions required in the NotifyEvent() procedure, including calling other ECL functions such as ECLPS::SendKeys(). The application returns a value from NotifyEvent() to indicate if the keystroke is to be filtered or not (return 1 to filter (discard) the keystroke, return 0 to have it processed normally).
If an error is detected during keystroke event generation, the NotifyError() member function is called with an ECLErr object. Keystroke events may or may not continue to be generated after an error, depending on the nature of the error. When event generation terminates (either due to an error, by calling ECLPS::UnregisterKeyEvent, or by destruction of the ECLPS object) the NotifyStop() member function is called. However event notification is terminated, the NotifyStop() member function is always called, and the application object is unregistered.
If the application does not provide an implementation of the NotifyError() member function, the default implementation is used (a simple message box is displayed to the user). The application can override the default behavior by implementing the NotifyError() function in the applications derived class. Likewise, the default NotifyStop() function is used if the application does not provide this function (the default behavior is to do nothing).
Note that the application can also choose to provide its own constructor and destructor for the derived class. This can be useful if the application wants to store some instance-specific data in the class and pass that information as a parameter on the constructor. For example, the application may want to post a message to an application window when a keystroke occurs. Rather than define the window handle as a global variable (so it would be visible to the NotifyEvent() function), the application can define a constructor for the class which takes the window handle and stores it in the class member data area.
The application must not destroy the notification object while it is registered to receive events.
The same instance of a keystroke notification object can be registered with multiple ECLPS objects to receive keystrokes for multiple connections. Thus an application can use a single instance of this object to process keystrokes on any number of sessions. The member functions are passed a pointer to the ECLPS object for which the event occurred so an application can distinguish between events on different connections. The sample shown uses the same object to process keystrokes on two connections.
Implementation Restriction: Currently the ECLPS object allows only one notification object to be registered for a given connection. The ECLPS::RegisterKeyEvent will throw an error if a notify object is already registered for that ECLPS object.