Implementing event handlers
Every OCX has a set of event notifications that it can send to its container. OCX events encompass both event and callback notions of Common Widgets. That is, OCX events can be fine-grained (such as mouse-clicks or key-presses), or they can be notifications of some higher-level action (such as a Cancel button being selected). The events that a particular OCX support are normally described in the OCX's type library or in the documentation that is shipped with it. Each event that is supported by an OCX is identified by a unique name and a unique DISPID.
An OCX container must register a method for each OCX event it will handle. The name of the event, the selector of the event-handler method, and the object that receives the notification are registered with an OleControl through its addOleEventHandler:receiver:selector: instance method. For example, the track bar OCX sends an event called 'Change' whenever the user moves its slider. The handler for this event is registered using:
addOleEventHandler: 'Change'
receiver: self selector: #updateValue.
Here, the 'Change' event passes no parameters to the event handler, so its implementation must request the current 'Value' property from the OCX. For example:
"Update the track bar's label with the current value of the track bar."
self updateTrackLabel: (trackBar propertyAt: 'Value')
Many OCX events pass one or more parameters to their container along with the event notification. Therefore, the event-handler method selectors must accommodate the required number of parameters. For example, an OCX's mouse-down event passes four parameters to its container's event handler:
The mouse button that was pressed
The state of the shift key
The mouse pointer X location
The mouse pointer Y location.
Hence, a handler for this event is registered for the track bar OCX using:
addOleEventHandler: 'MouseDown'
receiver: self selector: #eventMouseDown:shift:x:y:.
where the implementation of this event handler is:
eventMouseDown: button shift: shift x: nX y: nY
"Private - Processes the OLE Track bar MouseDown event."
An OLE event handler is deregistered from an OleControl through its instance method removeOleEventHandler:receiver:selector:.
There is a set of predefined OLE event names and DISPIDs for the base mouse and keyboard events that are used by most OCXs. These predefined events overlap the Common Widgets event masks that are inherited by OleControl. As a convenience, OleControl registers handlers for the corresponding OLE predefined events and automatically reroutes them through the Common Widgets event-handler mechanism. For example, the mouse-down OLE event handler registered in the previous example can be rewritten to use a Common Widgets event handler:
addEventHandler: ButtonPressMask
receiver: self
selector: #value:clientData:callData:
clientData: nil.
OleControl registers OLE event handlers for these predefined events:
If a container registers for one of the predefined OLE events using addOleEventHandler:receiver:selector:, its handler supersedes the OleControl widget's registered predefined event.
Predefined OLE event name
User action
Parameters (in order)
Presses and releases a mouse button over the OCX. For some OCXs, the event is sent when the value of the OCX changes.
Double-clicks in the OCX
Presses a key when the OCX has focus
Key Code Shift
The key code for the key pressed A bit mask detailing the state of the Ctrl, shift, and Alt keys
Releases a key when the OCX has focus
Key Code Shift
See KeyDown
Presses a mouse button while over an OCX
Button Shift X Y
A bit mask identifying which button is down A bit mask detailing the state of the Ctrl, shift, and Alt keys The current X location of the mouse The current Y location of the mouse
Moves the mouse over an OCX
Button Shift X Y
See MouseDown
Releases the mouse button over an OCX
Button Shift X Y
See MouseDown
Last modified date: 01/29/2015