IEvent Class Reference

#include <IEvent.h>

Inheritance diagram for IEvent:

Public Types
enum	ScrollUnits { kLines, kPixels }
enum	BaseEventHandledState { kShouldCall, kDontCall, kHasCalled }
enum	IEventType {   kFirstEventType = 1, kMouseMove = kFirstEventType, kMouseExit, kMouseDrag,   kLButtonDn, kRButtonDn, kMButtonDn, kLButtonUp,   kRButtonUp, kMButtonUp, kDoubleClick, kTripleClick,   kQuadrupleClick, kQuintupleClick, kMouseWheel, kControlCmd,   kKeyDown, kKey, kKeyUp, kTabletEvent,   kGestureEvent, kMultiTouchEvent, kSuspend, kResume,   kActivate, kDeactivate, kNull, kInvalid,   kEndOfEventTypes }
enum	GestureType {   kGestureNone = 0, kGestureBegin, kGestureEnd, kGestureRotation,   kGestureMagnify, kGestureSwipe, kGesturePan, kEndOfGestureTypes }
enum	SwipeDirection {   kSwipeDirectionNone = 0, kSwipeDirectionLeft, kSwipeDirectionRight, kSwipeDirectionUp,   kSwipeDirectionDown }
enum	TabletAction { kTabletActionNone = 0, kTabletActionProximity, kTabletActionPen, kEndOfTabletActions }
typedef BaseEventHandledState	UI_DoEventHandledState
typedef enum IEvent::IEventType	EventType

Public Member Functions
virtual bool16	LButtonDn () const =0
virtual bool16	OptionAltKeyDown () const =0
virtual bool16	CmdKeyDown () const =0
virtual bool16	ShiftKeyDown () const =0
virtual bool16	ShiftLockKeyDown () const =0
virtual bool16	MacCtrlDown () const =0
virtual bool16	LeftAltDown () const =0
virtual bool16	RightAltDown () const =0
virtual bool16	LeftControlDown () const =0
virtual bool16	RightControlDown () const =0
virtual SysChar	GetChar () const =0
virtual void	SetChar (SysChar theChar)=0
virtual VirtualKey	GetVirtualKey () const =0
virtual bool16	IsAltGrChar () const =0
virtual bool16	IsRepeatKey () const =0
virtual GSysPoint	GlobalWhere () const =0
virtual PMPoint	GetMouseScrollDelta (ScrollUnits units=kLines) const =0
virtual PMReal	GetTime () const =0
virtual void	SetUI_DoEventHandledState (UI_DoEventHandledState)
virtual UI_DoEventHandledState	GetUI_DoEventHandledState () const
virtual EventType	GetType () const =0
virtual void	SetType (const EventType theType)=0
virtual GestureType	GetGestureType () const
virtual float	GetRotationInDegrees () const
virtual float	GetMagnificationAmount () const
virtual SwipeDirection	GetSwipeDirection () const
virtual TabletAction	GetTabletAction () const

Detailed Description

Core Event Interface. System for encoding a single event in a core manner. Edge specific access is in MEvent or WEvent.

Member Typedef Documentation

typedef enum IEvent::IEventType IEvent::EventType

ID's for the different types of events. Note an EventType of 0 is used to mean all EventTypes in the EventWatcher API I.e., zero shouldn't be used as a real EventType. I probably should add an enumerator here...<sheridan>

Member Enumeration Documentation

enum IEvent::BaseEventHandledState

EventHandledState: With the droverized (non-platform) widget set in CS6.5, we have replaced IEvent's SystemHandledState with the (similar but distinct) notion of whether or not the event has been or should be processed by the underlying drover widget/ui_node.

While there are similarities between how SystemHandledState was used prior to droverization and how UI_DoEventHandledState is now used, they are different enough that we could not just reuse SystemHandledState. The key difference: UI_DoEventHandledState applies on a per widget basis, while SystemHandledState was applied once per event. We will deprecate/remove SystemHandledState before shipping to force clients to revisit Set/GetSystemHandledState call-sites to determine the appropriate conversion.

For pointer (mouse, touch and gesture) and keyboard events delivered to the widget via our widget event hook (DVEventHandler::DVPointerEvent), the process is as follows: 0) In DVEventHandler::DVPointerEvent, after the DVEvent is created, it's state is set to kShouldCall prior to sending the event on to the IEventHandler.

1) If MyWidgetEH::HandlerMethod returns kTrue: HandlerMethod has handled the event, no further processing is performed. HandlerMethod may choose to call inherited::HandlerMethod which calls the underlying drover widget/ui_node's UI_DoMouseEvent/UI_DoKeyboardEvent method.

2) If MyWidgetEH::HandlerMethod returns kFalse: HandlerMethod has declined to handle the event, further processing is performed. By default, we then pass the event to the underlying drover widget/ui_node's UI_DoMouseEvent/UI_DoKeyboardEvent method. However, if the HandlerMethod sets the event's BaseWidgetHandledState to kDontCall or kHasCalled, then base widget handling is skipped and the event continues on to the widget's parent for processing

For events delivered directly to an IEventHandler (event filters pushed on the dispatcher) or an IEventWatcher, the underlying drover widget/ui_node's UI_DoMouseEvent/UI_DoKeyboardEvent method will not be called.

NOTE: At this time this change has only been implemented for mouse events.

enum IEvent::GestureType

Gesture event subtypes

enum IEvent::IEventType

ID's for the different types of events. Note an EventType of 0 is used to mean all EventTypes in the EventWatcher API I.e., zero shouldn't be used as a real EventType. I probably should add an enumerator here...<sheridan>

Enumerator
kFirstEventType	0 reserved to mean all event types for event watcher API
kMouseMove	mouse has been moved outside the sensitive area
kMouseExit	mouse has exited the current control's bounds
kMouseDrag	mouse has been moved while mouse button is down
kLButtonDn	user has pressed left mouse button
kRButtonDn	user has pressed right mouse button
kMButtonDn	user has pressed middle mouse button
kLButtonUp	user has released left mouse button
kRButtonUp	user has released right mouse button
kMButtonUp	user has released middle mouse button
kDoubleClick	double click on any mouse button
kTripleClick	triple click on any mouse button
kQuadrupleClick	quadruple click on any mouse button
kQuintupleClick	quintuple click on any mouse button
kMouseWheel	mouse wheel moved
kControlCmd	control has been pushed (PC only)
kKeyDown	user pushed a key on the keyboard
kKey	user pushed a key on the keyboard that generates a character. Usually follows kKeyDown
kKeyUp	user released a key on the keyboard
kTabletEvent	tablet event. Proximity or Pen
kGestureEvent	tablet event. Begin/End, Rotate, Magnify. Swipe, Pan
kMultiTouchEvent	multi-touch event. lower-level than a gesture. Details under construction
kSuspend	application is being suspended (context switch to another application) - simulated as of CC
kResume	application resumed (context switch from another application back to Shuksan) - simulated as of CC
kActivate	a window is being activated - simulated as of CC (for palettes, documents and dialogs)
kDeactivate	a window is being deactivated - simulated as of CC (for palettes, documents and dialogs)
kNull	idle event. Periodically sent when there are no events pending in the queue - simulated
kInvalid	empty or unconverted event, should be ignored
kEndOfEventTypes	note if you add EventTypes so that the value of kEndOfEventType is pushed greater than 32, then IEventDispatcher::EventTypeList will have to be reimplemented not to mention that all EventHandlers will need additional methods... <sheridan> no event type constants can be greater than kEndOfEventTypes

enum IEvent::TabletAction

Tablet event subtypes - actions for want of a better word

Member Function Documentation

virtual bool16 IEvent::CmdKeyDown ( ) const

pure virtual

Check if command key down (Ctrl on PC)

Returns

kTrue if command/cntrl key was pressed when this event was generated.

Implemented in WEvent.

virtual SysChar IEvent::GetChar ( ) const

pure virtual

Return the ASCII key associated with the event. Valid only for key-related events.

Returns

the character associated with this key event.

Implemented in WEvent.

virtual GestureType IEvent::GetGestureType ( ) const

inlinevirtual

Get the gesture type of the event.

Returns

the gesture type of the event

virtual PMPoint IEvent::GetMouseScrollDelta ( ScrollUnits  units = kLines ) const

pure virtual

Return the scroll data for the event. Only valid for mouse wheel events.

Can contain an x and y scroll value on some devices (e.g. Apple's Mighty Mouse or some track pads).

Returns

distance user scrolled the wheel (in lines or pixels) with an x and y component. For kLines values, typically multiplied by the panorama's delta value to compute how much to scroll. For kPixels values, value may be used directly. Note the kPixels values can be 0, 0 for non-track pad/Mighty Mouse-like devices. Windows platform will return 0, 0 at this time since no platform pixel wheel return messages yet exist. If client code calls GetMouseScrollDelta with kPixels enum, and return value is kZeroPoint, client code should call again with kLines to get a true value (i.e. Scrolling device didn't support pixel return values).

Implemented in WEvent.

virtual float IEvent::GetRotationInDegrees ( ) const

inlinevirtual

Gesture data accessors

virtual TabletAction IEvent::GetTabletAction ( ) const

inlinevirtual

Get the gesture type of the event.

Returns

the gesture type of the event

virtual PMReal IEvent::GetTime ( ) const

pure virtual

Returns the time of the event, in SECONDS since startup. On Win, this is a DWORD, so it'll roll over after ~47 days

Returns

time of event.

Implemented in WEvent.

virtual EventType IEvent::GetType ( ) const

pure virtual

Get the type of the event.

Returns

the type of the event

Implemented in WEvent.

virtual UI_DoEventHandledState IEvent::GetUI_DoEventHandledState ( ) const

inlinevirtual

Set the base (drover) widget handledness for this event. IEvent constructors default to kDontCall.

Returns

the current system handled state of this event.

virtual VirtualKey IEvent::GetVirtualKey ( ) const

pure virtual

Return the virtual key associated with a kKeyDown event.@see KeyboardDefs.h for the various defines for virtual keys.

Returns

the virtual key for this event.

Implemented in WEvent.

virtual GSysPoint IEvent::GlobalWhere ( ) const

pure virtual

Return the location associated with the event. The validity of the contents depends on the type of event;

for events containing a location, we return the location of the mouse, in global coordinates, at the time of the event.

Platform details: On Win, only mouse related events contain a location, and this method returns nonsense for non-mouse events. However on OS X any event can have a location, and we will return it, in particular keyboard events contain a location.

Returns

mouse location at the time of this event.

Implemented in WEvent.

virtual bool16 IEvent::IsAltGrChar ( ) const

pure virtual

Returns kTrue if the event generates a valid unicode character or kFalse if the keystroke doesn't map to a unicode character. This function is used to figure out if AltGR (right-alt on non-US keyboards) should be treated as a shortcut or as a special character. The result of this function is only valid during a KeyDown event. On Macintosh, this function always returns false.

Returns

kTrue if this is an AltGR event.

Implemented in WEvent.

virtual bool16 IEvent::IsRepeatKey ( ) const

pure virtual

Returns kTrue if key event is an automatically repeating key (caused by holding a key down).

Implemented in WEvent.

virtual bool16 IEvent::LButtonDn ( ) const

pure virtual

Check if left mouse button down

Returns

kTrue if left mouse button was pressed when this event was generated.

Implemented in WEvent.

virtual bool16 IEvent::LeftAltDown ( ) const

pure virtual

Check if the left Alt/Option key on keyboard is down. Works on mac and windows both.

Returns

kTrue if the left alt key was pressed when this event was generated.

Implemented in WEvent.

virtual bool16 IEvent::LeftControlDown ( ) const

pure virtual

Check if the left Control key on Windows keyboard is down.

On Macintosh, returns TRUE if either Command key is down.

Returns

kTrue if the left(On windows, either on mac) control key was pressed when this event was generated.

Implemented in WEvent.

virtual bool16 IEvent::MacCtrlDown ( ) const

pure virtual

Check if the Control key on a Macintosh extended keyboard is down. Will always return false on Windows.

Returns

kTrue if mac control key was pressed when this event was generated.

Implemented in WEvent.

virtual bool16 IEvent::OptionAltKeyDown ( ) const

pure virtual

Check if option key down (Alt on PC)

Returns

kTrue if option/alt key was pressed when this event was generated.

Implemented in WEvent.

virtual bool16 IEvent::RightAltDown ( ) const

pure virtual

Check if the right Alt/Option key on keyboard is down. Works on mac and windows both.

Returns

kTrue if the right alt key was pressed when this event was generated.

Implemented in WEvent.

virtual bool16 IEvent::RightControlDown ( ) const

pure virtual

Check if the right Control key on Windows keyboard is down.

On Macintosh, returns TRUE if either Command key is down.

Returns

kTrue if the left(On windows, either on mac) control key was pressed when this event was generated.

Implemented in WEvent.

virtual void IEvent::SetChar ( SysChar  theChar )

pure virtual

Sets the ASCII key associated with the event. Valid only for key-related events.

Usually only done to indicate the event has been handled as a shortcut. Changing the char of a KeyDown cmd to 0 Prevents redispatching the event as a KeyCmd

Parameters

theChar

the new ascii character for this event.

Implemented in WEvent.

virtual void IEvent::SetType ( const EventType  theType )

pure virtual

Set the type of the event. Typically this is done by the EventConverter.

Parameters

the	event type

Implemented in WEvent.

virtual void IEvent::SetUI_DoEventHandledState ( UI_DoEventHandledState  )

inlinevirtual

Set the base (drover) widget handledness for this event. IEvent constructors default to kDontCall.

Parameters

state

new system handled state

virtual bool16 IEvent::ShiftKeyDown ( ) const

pure virtual

Check if shift key down

Returns

kTrue if shift key was pressed when this event was generated.

Implemented in WEvent.

virtual bool16 IEvent::ShiftLockKeyDown ( ) const

pure virtual

Check if shift lock is on

Returns

kTrue if shift lock(aka caps lock) was on when this event was generated.

Implemented in WEvent.