### IEvent

  The 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.

#### Portability Considerations

  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.

#### AIX Considerations

  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:

  - Open Class Library events created by sendEvent/postEvent have a range from 0 to 65535 (0x0000 to 0xffff). This is the range used by Windows and OS/2 for message identifiers.
  - X Events have a range from 65536 to 131071 (0x10000 to 0x1ffff). The value of IEvent::eventId for an X event is determined by adding 0x10000 to the system defined X event type value.
  - Motif callback reason codes have the range beginning at 131072 (0x20000) to UINT_MAX. Similar to X events, the value of IEvent::eventId for a Motif callback is determined by adding 0x20000 to the system provided reason code value.
  The data in parameter 1 and 2 in the IEvent object depends on the type of event that is dispatched. If the IEvent object is generated from an X event or a Motif callback then parameter 2 is a pointer to the XEvent. If the IEvent object is generated from an Open Class Library message then parameter 1 and 2 have similar data that is used on the Windows and OS/2. The data is event dependant, so see the documentation for a specific IEvent derived class for more information.

  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.

### IEvent - Member Functions and Data by Group

### Constructors & Destructor

You can construct, destruct, copy, and assign objects of this class.

~IEvent

      public:
      virtual ~IEvent()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

IEvent

  Overload 1

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations

  In AIX, the IEvent constructor interprets its parameters as follows:

  window
    The widget parameter, as passed to the callback or event-handler function.
  eventId
    The "reason" from a Motif callback, or the type value from an Xt event registration. There is an exception to this in the IEvent generated by using sendEvent and postEvent.
  parameter1
    This parameter may contain either of the following:
    - The call_data parameter from a Motif callback
    - NULL, indicating an Xt event registration callback
    Note: Because the eventIds from either type of callback might be the same value, you must use parameter1 to distinguish whether the IEvents result from a Motif callback or from an Xt event registration.
  parameter2
    The XEvent* parameter associated with the callback. For a Motif callback, the value is call_data->event. For an Xt event registration callback, the value is the event parameter on the callback routine as passed to the event-handler routine.

  Overload 3

      public:
      IEvent(const IEvent& event)

  Create an event from another IEvent object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

operator =

      public:
      IEvent& operator =(const IEvent& event)

  Assigns the value of one event object to another.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Event Data

Use these members to set or query data for an event object, such as its event parameters and event result.

decrementOwnerLevels

      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.

Supported Platforms

  Windows | OS/2 | AIX
  No | No | Yes

eventId

      public:
      unsigned long eventId() const

  Returns the ID for the event.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations

  The event id on AIX has three ranges set up for determining how the event was generated. The ranges are as follows:

  - Open Class Library events created by sendEvent/postEvent have a range from 0 to 65535 (0x0000 to 0xffff). This is the range used by Windows and OS/2 for message identifiers.
  - X Events have a range from 65536 to 131071 (0x10000 to 0x1ffff). The value of IEvent::eventId for an X event is determined by adding 0x10000 to the system defined X event type value.
  - Motif callback reason codes have the range beginning at 131072 (0x20000) to UINT_MAX. Similar to X events, the value of IEvent::eventId for a Motif callback is determined by adding 0x20000 to the system provided reason code value.

parameter1

      public:
      IEventParameter1 parameter1() const

  Returns the first event parameter.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

parameter2

      public:
      IEventParameter2 parameter2() const

  Returns the second event parameter.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations

  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.

passToOwner

      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.

Supported Platforms

  Windows | OS/2 | AIX
  No | No | Yes

result

      public:
      IEventResult result() const

  Returns the event result.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setNumberOfLevels

      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.

Supported Platforms

  Windows | OS/2 | AIX
  No | No | Yes

setPassToOwner

      public:
      IEvent& setPassToOwner(bool passOn = true)

  Controls whether or not the IEvent object can propagate up the owner chain.

Supported Platforms

  Windows | OS/2 | AIX
  No | No | Yes

setResult

  Sets the event result.

  Overload 1

      public:
      IEvent& setResult(bool eventResult)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      IEvent& setResult(const IEventResult& eventResult)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Event Window

Use these members to set or query the windows associated with an event object.

controlHandle

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations

  Since messages are propagated up the owner chain within Open Class Library the control handle and handle are always the same.

controlWindow

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations

  On AIX, this function returns a valid value for all event types.

OS/2 Considerations
  The following are events that the OS sends to the owner of control, but Open Class Library dispatches to the control first. The event is then dispatched to the owner's handlers only if the control's handlers do not handle the event.
  - WM_CONTROL
  - WM_DRAWITEM
  - WM_MEASUREITEM
  - WM_CONTROLPOINTER
  - WM_VSCROLL
  - WM_HSCROLL

Windows Considerations
  The following are events that the OS sends to the owner of control, but Open Class Library dispatches to the control first. The event is then dispatched to the owner's handlers only if the control's handlers do not handle the event.
  - WM_CONTROL
  - WM_DRAWITEM
  - WM_MEASUREITEM
  - WM_NOTIFY
  - WM_CTLCOLOREDIT
  - WM_CTLCOLORSTATIC
  - WM_CTLCOLORLISTBOX
  - WM_CTLCOLORSCROLLBAR
  - WM_CTLCOLORBTN
  - WM_VSCROLL
  - WM_HSCROLL

dispatchingWindow

      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:

  - The original object that originated the event
  - The owner of that object if the event is owner-routed
  - The owner's owner
  This function gives consistent results across all systems so you can write portable code.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

handle

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setControlHandle

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setDispatchingHandle

      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:

  - The original object that originated the event
  - The owner of that object if the event is owner-routed
  - The owner's owner
  This function gives consistent results across all systems so you can write portable code.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setDispatchingWindow

      public:
      IEvent& setDispatchingWindow(IWindow* window)

  Sets the pointer to IWindow for which the event was dispatched to. See setDispatchingHandle

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setHandle

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

window

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IEvent - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None