User Events

Inside Macintosh: OpenDoc Class Reference / Part 2 - Types and Constants

User Events
This section describes the types and constants used in handling user events.

Focus Types
The following type and constants represent focus types that frames may own.

ODFocusType
A string of type ODType (page 876) used to identify a focus type.
Constants of this type

kODClipboardFocus
The frame with the clipboard focus has access to the clipboard.
kODKeyFocus
The frame with the keyboard focus receives keyboard events (excluding page-movement key events).
kODMenuFocus
The frame with the menu focus receives menu events.
kODModalFocus
The frame with the modal focus is notifying other frames that it is the only currently modal frame.
kODMouseFocus
The frame with the mouse focus receives all mouse-up and mouse-down events; it also receives mouse-within events independent of the facet in which the cursor is located.
kODScrollingFocus
The frame with the scrolling focus receives page-movement key events (such as Page Up). This frame need not own keyboard focus.
kODSelectionFocus
The frame with the selection focus receives modified mouse-click events (Shift-click and Command-click). OpenDoc draws the active frame border around all facets of this frame.

OpenDoc methods use the tokenized form of the focus type constants. You can call the session object's Tokenize method (page 622) to obtain a token corresponding to one of these constants.

Events
The following types represent information about user events.

ODEventData
A platform-specific structure representing an event. On the Mac OS, it is defined as a Mac OS event record.
            struct EventRecord {
               short          what;
               long           message;
               long           when;
               Point          where;
               short          modifiers;
            };
Field descriptions

what
The type of event received.
message
Additional information associated with the event.
when
The time when the event was posted.
where
For mouse events, the location of the cursor (in global coordinates) at the time the event was posted. This field is a QuickDraw Point structure, not an ODPoint structure.
modifiers
Information about the state of the modifier keys and the mouse button at the time the event was posted. For activate events, this field also indicates whether the window should be activated or deactivated.

ODEventInfo
A structure containing context-specific event information.
            struct ODEventInfo {
               ODFrame        embeddedFrame;
               ODFacet        embeddedFacet;
               ODPoint        where;
               ODBoolean      propagated;
            };
Field descriptions

embeddedFrame
The frame within which the event occurred. Only relevant for events that are delivered to the containing part.
embeddedFacet
The facet within which the event occurred. Only relevant for events that are delivered to the containing part.
where
The position in local (frame) coordinates where the event occurred. Only relevant for mouse-related events.
propagated

kODTrue if the event occurred in an embedded frame that propagates events and if that frame's part did not handle the event.
ODEventType
A 16-bit platform-specific code specifying an event type. The section "Event Types" on page 892 describes event-type constants defined for the Mac OS platform.
ODIdleFrequency
A 32-bit unsigned number representing the frequency, in ticks or 60ths of a second, at which null events are sent during idle times.

Event Types
This section describes the constants of type ODEventType (page 892) used on the Mac OS platform to specify the event types; some of these constants may be used on other platforms as well. The constants that correspond to the standard Mac OS event types are equivalent to the standard Mac OS event codes.
Standard Mac OS event types

kODEvtActivate
An activate event, which indicates that a window was activated or deactivated.
kODEvtAutoKey
An autokey event, which indicates that the user has held down a key for a certain amount of time.
kODEvtDisk
A disk event.
kODEvtKeyDown
A key-down event.
kODEvtKeyUp
A key-up event.
kODEvtMouseDown
A mouse-down event.
kODEvtMouseUp
A mouse-up event.
kODEvtNull
A null event, which indicates idle time.
kODEvtOS
An OS event (a suspend/resume event or a mouse-moved event).
kODEvtUpdate
An update event.
OpenDoc-specific event types

kODEvtBGMouseDown
A mouse-down event while the process is inactive.
kODEvtBGMouseDownEmbedded
A mouse-down event in an embedded frame while the process is inactive. This event is sent to the containing part.
kODEvtMenu
An adaptation of a mouse-down event in the menu bar or the equivalent Command-key combination. On the Mac OS, the message field of the event record contains the menu in the high word and the item in the low word. Other fields of the event record are the same as for a mouse-down or key-down event.
kODEvtMouseDownBorder
A mouse-down event in the active border (around facets of the frame with the selection focus). On the Mac OS, the message field of the event record contains the embedded facet. Other fields of the event record are the same as for a mouse-down event.
kODEvtMouseDownEmbedded
A mouse-down event in an embedded facet. This event is sent to the containing facet. On the Mac OS, the message field of the event record contains the embedded facet. Other fields of the event record are the same as for a mouse-down event.
kODEvtMouseEnter
Sent when the mouse first enters a frame (with the mouse button up). The where field of the ODEventInfo structure specifies the mouse location in local (frame) coordinates.
kODEvtMouseLeave
Sent when the mouse moves out of a frame (with the mouse button up). The where field of the ODEventInfo structure specifies the mouse location in local (frame) coordinates.
kODEvtMouseUpEmbedded
A mouse-up event in an embedded facet. This event is sent to the containing facet. On the Mac OS, the message field of the event record contains the embedded facet. Other fields of the event record are the same as for a mouse-up event.
kODEvtMouseWithin
Sent when the mouse moves within a frame (with the mouse button up). An ODEventInfo structure specifies the mouse location in local (frame) coordinates.
kODEvtWindow
An adaptation of a mouse event in the title bar of a window. On the Mac OS, the message field of the event record contains the part code returned by the FindWindow routine. Other fields of the event record are the same as for a mouse-down event.

Mouse Location
The following constants of type ODSShort (page 874) classify the location where a mouse-up or mouse-down event occurred; they are equivalent to the codes returned by the Mac OS routine FindWindow. OpenDoc uses these codes internally to decide how to dispatch mouse events. Constants marked [M] are specific to the Mac OS platform.

kODMDInContent [M]
In the content region of an application window.
kODMDInDesk [M]
In the desktop.
kODMDInDrag [M]
In the drag region.
kODMDInGoAway [M]
In the close box of a window.
kODMDInGrow [M]
In the size box of a window.
kODMDInMenuBar [M]
In the menu bar.
kODMDInSysWindow [M]
In a system window.
kODMDInZoomIn [M]
In the zoom box of a zoomed-out window.
kODMDInZoomOut [M]
In the zoom box of a zoomed-in window.