Constructors & DestructorThe IEvent class is the base-event information class. You can query event parameters and set event results. Additional functions are provided by the event classes derived from IEvent.
The Open Class Library-supported event types (IEvent and derived classes) provide portable accessors to obtain event details, and they modify event data where appropriate. The responsibility for the portable access to event details generally lies with derived IEvent classes and handlers, which process the events. The implementations of these classes vary by event type and platform, but they use the consistent definition of the base IEvent structure. The library also provides nonportable accessors to access the raw event data. This facilitates both implementation of the library as well as extensions to it. The raw event data is presented in essentially the same way the underlying system represents it.
There are three sources of events on AIX; a Motif callback, an X event and an Open Class Library event. The event ids for these three type events overlap so an offset is introduced to eliminate the ambiguity. The offset is added to the event id so that a range is set up for each type of event. The event ranges are as follows:
Note that if you register your own callback on a Widget or add an Xt handler to an X Window, the client data should be the IWindow * that wrappers the widget. IWindow::dispatch uses the client data to determine which IWindow the event was generated for an then dispatches the event to the handlers added to that IWindow..
This rest of this section describes how X-Motif events and their data are used to construct IEvent objects. This information is primarily for those who want to perform X-Motif-unique extensions or integrate custom widgets.
The basic Motif callback function signature is as follows:
void callbackFn(
Widget widget, /* widget that triggered callback */
caddr_t client_data, /* client data */
caddr_t call_data); /* data from the widget */
On a callback, call_data is always a pointer to a structure. This structure contains at least the following fields:
int reason; /* reason defined by Motif */ XEvent* event /* pointer to X event */
Depending on the reason and widget, additional fields may exist in the structure. You can use XmAnyCallbackStruct to refer to the preceding structure.
An Xt event registration callback function signature is as follows:
void eventHandlerFn(
Widget widget, /* widget in whose window event occurred*/
caddr_t client_data, /* client data */
XEvent *event, /* event data */
::Boolean continue_to_dispatch);
The XEvent structure is a union of different structures, one for each set of events with different attributes. The xany variant can be used to access the following common fields:
int type; /* type of event */ unsigned long serial; /* serial of last request processed*/ Bool send_event; /* true if from client (XSendEvent)*/ Display *display; /* display where occurred */ Window window; /* window where requested */
See O'Reilly Volume 6B or any other book on X/Motif for further details.
Constructors & DestructorYou can construct, destruct, copy, and assign objects of this class.
![[view class]](../images/viewcls1.gif) |
public:
virtual ~IEvent()
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
IEvent( const IWindowHandle& handle, unsigned long eventId, const IEventParameter1& parameter1, const IEventParameter2& parameter2 )
Create an event using the specified IWindowHandle object, event ID, IEventParameter1 object, and IEventParameter2 object.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
IEvent( IWindow* window, unsigned long eventId, const IEventParameter1& parameter1, const IEventParameter2& parameter2 )
Create an event using the specified IWindow object, event ID, IEventParameter1 object, and IEventParameter2 object.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
In AIX, the IEvent constructor interprets its parameters as follows:
public:
IEvent(const IEvent& event)
Create an event from another IEvent object.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
IEvent& operator =(const IEvent& event)
Assigns the value of one event object to another.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Event DataUse these members to set or query data for an event object, such as its event parameters and event result.
|
public:
IEvent& decrementOwnerLevels()
This member function helps control how many levels up the owner chain an event will propagate. The level is decremented by IWindow::dispatch everytime the event is passed up to the owner. There is no need for a user program to call this member function.
| Windows | OS/2 | AIX |
| No | No | Yes |
|
public:
unsigned long eventId() const
Returns the ID for the event.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
The event id on AIX has three ranges set up for determining how the event was generated. The ranges are as follows:
|
public:
IEventParameter1 parameter1() const
Returns the first event parameter.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
IEventParameter2 parameter2() const
Returns the second event parameter.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
The return value is a pointer to the XEvent structure if the IEvent object is a wrapper of an XEvent or a Motif callback. The return value Open Class Library messages are filled in like Windows and OS/2.
|
public:
bool passToOwner() const
IWindow::dispatch calls this member function to determine if an IEvent object can be passed up the owner chain. There are two criteria for returning true. The first is that the event has been set to be passed up the owner chain by calling IEvent::setPassToOwner with a value of true. The second is that the levels that the event can go up has not been decremented to 0.
| Windows | OS/2 | AIX |
| No | No | Yes |
|
public:
IEventResult result() const
Returns the event result.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
IEvent& setNumberOfLevels(int levels = - 1)
This member function is used to control how many levels an event can propagate up the owner chain. There are really only two values for the level that are used. The first is -1, which will allow the event to go all the way up the owner chain until it is handled. The second supported value is 2 which will allow the event to go up two levels. This value helps support the scenerio where the event can only go to the control and its owner. In general, the user should have not need to call this member function. The owner levels are set when the event is created.
| Windows | OS/2 | AIX |
| No | No | Yes |
|
public:
IEvent& setPassToOwner(bool passOn = true)
Controls whether or not the IEvent object can propagate up the owner chain.
| Windows | OS/2 | AIX |
| No | No | Yes |
|
Sets the event result.
public:
IEvent& setResult(bool eventResult)
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
IEvent& setResult(const IEventResult& eventResult)
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Event WindowUse these members to set or query the windows associated with an event object.
|
public:
IWindowHandle controlHandle() const
Returns the IWindowHandle object for the presentation window that originated the event. If a valid object cannot be returned, 0 is returned.
Typically, this is a control, such as a button. For example, when an event has just been dispatched from an ICheckBox to an IHandler, the return value is the same as that for dispatchingWindow. If the event has been owner-routed and dispatched from the owner of the ICheckBox, the return value is different. controlWindow returns the ICheckBox, while dispatchingWindow returns the owner.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Since messages are propagated up the owner chain within Open Class Library the control handle and handle are always the same.
|
public:
virtual IWindow* controlWindow() const
Returns a pointer to the IWindow object that originated the event. If a valid object cannot be returned, 0 is returned.
Typically, this is a control, such as a button. For example, when an event has just been dispatched from an ICheckBox to an IHandler, the return value is the same as that for dispatchingWindow. If the event has been owner-routed and dispatched from the owner of the ICheckBox, the return value is different. controlWindow returns the ICheckBox, while dispatchingWindow returns the owner.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
On AIX, this function returns a valid value for all event types.
|
public:
virtual IWindow* dispatchingWindow() const
Returns a pointer to the IWindow object from which this event was just dispatched. The pointer can represent any of the following:
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
IWindowHandle handle() const
Returns an IWindowHandle object for the IWindow object the event has been dispatched to. The value returned by this member function can vary among platforms and therefor its use may result in nonportable code; use controlHandle instead. The differences occur with messages that are dispatched by the OS to the owner of the control, instead of the control itself. Open Class Library dispatches some of these messages down to the control first, and then to the owner.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
IEvent& setControlHandle(const IWindowHandle& handle)
Sets the IWindowHandle object for the presentation window that originated the event. This is initialized to the handle value passed in on the IEvent constructor. If a valid object cannot be set, 0 should be set.
Typically, this is a control, such as a button. For example, when an event has just been dispatched from an ICheckBox to an IHandler, this value should be the same as that for dispatchingWindow. If the event has been owner-routed and dispatched from the owner of the ICheckBox, this value should be the ICheckBox, while dispatchingWindow returns the owner.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
IEvent& setDispatchingHandle(const IWindowHandle& handle)
Sets the IWindowHandle object for the IWindow object from which this event was just dispatched. This value is set by IWindow during the event-dispatching process. The value can represent any of the following:
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
IEvent& setDispatchingWindow(IWindow* window)
Sets the pointer to IWindow for which the event was dispatched to. See setDispatchingHandle
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
IEvent& setHandle(const IWindowHandle& handle)
Sets the IWindowHandle object for the IWindow object the event has been dispatched to. This value is set by IWindow during the event-dispatching process. Use of this function may result in nonportable code; use setControlHandle or setDispatchingHandle instead.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual IWindow* window() const
Returns a pointer to the IWindow object the event has been dispatched to. Use of this function may result in nonportable code; use controlWindow or dispatchingWindow instead.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
