Programmer's Reference

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:

trackBar
   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:

updateValue
   "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:

Hence, a handler for this event is registered for the track bar OCX using:

trackBar
   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:

trackBar
   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 DISPID User action Parameters (in order) Description
Click DispidClick Presses and releases a mouse button over the OCX. For some OCXs, the event is sent when the value of the OCX changes. None
DblClick DispidDblclick Double-clicks in the OCX None
KeyDown DispidKeydown 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
KeyUp
Releases a key when the OCX has focus Key Code Shift See KeyDown
MouseDown DispidMousedown 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
MouseMove DispidMousemove Moves the mouse over an OCX Button Shift X Y See MouseDown
MouseUp DispidMouseup Releases the mouse button over an OCX Button Shift X Y See MouseDown


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]