Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
NSEvent
| Inherits from | |
| Implements | |
| Package | com.apple.cocoa.application |
| Companion guide |
Overview
An NSEvent object, or simply an event, contains information about an input action such as a mouse click or a key down. The Application Kit associates each such user action with a window, reporting the event to the application that created the window. The NSEvent object contains pertinent information about each event, such as where the cursor was located or which character was typed. As the application receives events, it temporarily places them in a buffer called the event queue. When the application is ready to process an event, it takes one from the queue.
Beginning with Mac OS X version 10.4, NSEvent objects can represent tablet-pointing and tablet-proximity events. A tablet-proximity event is generated when a pointing device enters or leaves proximity of its tablet; such event objects have a type of TypeProximity or a mouse subtype of TabletProximityEventSubtype. A tablet-pointing event is generated when a pointing device changes state, such as location, pressure, or tilt; such event objects have a type of TypePoint or a mouse subtype of TabletPointEventSubtype. The Application Kit reports all pure tablet events to responder objects through the NSResponder methods tabletPoint and tabletProximity. Mouse events can also contain tablet data (as event subtypes), so you can handle these events by overriding the NSResponder methods mouseDown, mouseDragged, and mouseUp.
Tasks
Constructors
Creating Events
Requesting and Stopping Periodic Events
Getting General Event Information
Getting Key Event Information
Getting Mouse Event Information
Getting Tracking-rectangle Event Information
Getting Custom Event Information
Getting Scroll Wheel Event Information
Getting Tablet Proximity Information
-
capabilityMask
-
deviceID
-
isEnteringProximity
-
pointingDeviceID
-
pointingDeviceSerialNumber
-
pointingDeviceType
-
systemTabletID
-
tabletID
-
uniqueID
-
vendorID
-
vendorPointingDeviceType
Getting Tablet Pointing Information
Static Methods
eventMaskFromType
Returns the event mask for the given eventType.
public static final int eventMaskFromType(int eventType)
Discussion
Event masks and event types are described in “Constants.”
keyEvent
Returns a new NSEvent object describing a key event.
public static NSEvent keyEvent(int type, NSPoint location, int flags, double time, int windowNum, NSGraphicsContext context, String characters, String unmodCharacters, boolean repeatKey, short code)
Discussion
type must be one of the following, or an InternalInconsistencyException is thrown:
KeyDownKeyUpFlagsChanged
The location argument is the cursor location in the base coordinate system of the window specified by windowNum.
The flags argument is an integer bit field containing any of the modifier key masks described in “Constants,” combined using the C bitwise OR operator.
The time argument is the time the event occurred in seconds since system startup.
The windowNum argument identifies the window device associated with the event, which is associated with the NSWindow that will receive the event.
The context argument is the display context of the event.
The characters argument is a string of characters associated with the key event. Though most key events contain only one character, it is possible for a single keypress to generate a series of characters.
The unmodCharacters argument is the string of characters generated by the key event as if no modifier key had been pressed (except for Shift). This argument is useful for getting the “basic” key value in a hardware-independent manner.
The repeatKey argument is true if the key event is a repeat caused by the user holding the key down, false if the key event is new.
The code argument identifies the keyboard key associated with the key event. Its value is hardware-independent.
See Also
mouseEvent
Returns a new NSEvent object describing a mouse-down, -up, -moved, or -dragged event.
public static NSEvent mouseEvent(int type, NSPoint location, int flags, double time, int windowNum, NSGraphicsContext context, int eventNumber, int clickNumber, float pressure)
Discussion
type must be one of the modifier key masks described in “Constants,” or an InternalInconsistencyException is thrown.
The location, flags, time, windowNum, and context arguments are as described under keyEvent.
The eventNumber argument is an identifier for the new event. It’s normally taken from a counter for mouse events, which continually increases as the application runs.
The clickNumber argument is the number of mouse clicks associated with the mouse event.
The pressure argument is a value from 0.0 to 1.0 indicating the pressure applied to the input device on a mouse event, used for an appropriate device such as a graphics tablet. For devices that aren’t pressure-sensitive, the value should be either 0.0 or 1.0.
See Also
mouseLocation
Exports the current mouse position, in screen coordinates. S
public static NSPoint mouseLocation()
Discussion
imilar to NSWindow’s mouseLocationOutsideOfEventStream, this method returns the location regardless of the current event or pending events. The difference between these methods is that mouseLocationOutsideOfEventStream returns a point in the receiving window’s coordinates and mouseLocation returns the same information in screen coordinates.
otherEvent
Returns a new NSEvent object describing a custom event.
public static NSEvent otherEvent(int type, NSPoint location, int flags, double time, int windowNum, NSGraphicsContext context, short subtype, int data1, int data2)
Discussion
type must be one of the values below, or an InternalInconsistencyException is thrown. Your code should only create events of type ApplicationDefined.
AppKitDefinedSystemDefinedApplicationDefinedPeriodic
The location, flags, time, windowNum, and context arguments are as described under keyEvent. Arguments specific to custom events are:
The subtype argument further differentiates custom events of types
AppKitDefined,SystemDefined, andApplicationDefined.Periodicevents don’t use this attribute.The data1 and data2 arguments contain additional data associated with the event.
Periodicevents don’t use these attributes.
See Also
startPeriodicEvents
Begins generating periodic events for the current thread every periodSeconds, after a delay of delaySeconds.
public static void startPeriodicEvents(double delaySeconds, double periodSeconds)
Discussion
Throws an InternalInconsistencyException if periodic events are already being generated for the current thread. This method is typically used in a modal loop while tracking mouse-dragged events.
See Also
stopPeriodicEvents
Stops generating periodic events for the current thread and discards any periodic events remaining in the queue.
public static void stopPeriodicEvents()
Discussion
This message is ignored if periodic events aren’t currently being generated.
See Also
Instance Methods
absoluteX
Reports the absolute x coordinate of a pointing device on its tablet at full tablet resolution.
public int absoluteX()
Discussion
For the coordinate to be valid, the receiver should represent an event generated by a tablet pointing device (otherwise 0 is returned). This method is valid only for mouse events with a subtype of TabletPointEventSubtype and for events of type TabletPoint. Use this value if you want to scale from tablet location to screen location yourself; otherwise use the class method mouseLocation or the instance method locationInWindow.
Availability
- Available in Mac OS X v10.4 and later.
See Also
absoluteY
Reports the absolute y coordinate of a pointing device on its tablet at full tablet resolution.
public int absoluteY()
Discussion
For the coordinate to be valid, the receiver should represent an event generated by a tablet pointing device (otherwise 0 is returned). This method is valid only for mouse events with a subtype of TabletPointEventSubtype and for events of type TabletPoint. Use this value if you want to scale from tablet location to screen location yourself; otherwise use the class method mouseLocation or the instance method locationInWindow.
Availability
- Available in Mac OS X v10.4 and later.
See Also
absoluteZ
Reports the absolute z coordinate of pointing device on its tablet at full tablet resolution.
public int absoluteZ()
Discussion
For the coordinate to be valid, the receiver should represent an event generated by a tablet pointing device (otherwise 0 is returned). The z coordinate does not represent pressure. It registers the depth coordinate returned by some tablet devices with wheels; if the device is something other than these, 0 is returned. This method is valid only for mouse events with a subtype of TabletPointEventSubtype and for events of type TabletPoint.
Availability
- Available in Mac OS X v10.4 and later.
See Also
buttonMask
Returns a bit mask identifying the buttons pressed when the tablet event represented by the receiver was generated.
public int buttonMask()
Discussion
Use one or more of the button-mask constants described in “Constants” to determine which buttons of the pointing device are pressed. This method is valid only for mouse events with a subtype of TabletPointEventSubtype and for events of type TabletPoint.
Availability
- Available in Mac OS X v10.4 and later.
buttonNumber
Returns the button number for the mouse button that generated an “OtherMouse” event.
public int buttonNumber()
Discussion
This method is intended for use with the “OtherMouse” events, but will return values for LeftMouse and RightMouse events, also.
capabilityMask
Returns a mask whose set bits indicate the capabilities of the tablet device that generated the event represented by the receiver.
public int capabilityMask()
Discussion
These bits are vendor-defined. This method is valid only for mouse events with a subtype of TabletProximityEventSubtype and for events of type TabletProximity.
Availability
- Available in Mac OS X v10.4 and later.
characters
Returns the characters associated with the receiving key-up or key-down event.
public String characters()
Discussion
These characters are derived from a keyboard mapping that associates various key combinations with Unicode characters. Throws an InternalInconsistencyException if sent to any other kind of event.
This method will return an empty string for dead keys, such as option-E.
See Also
charactersIgnoringModifiers
Returns the characters generated by the receiving key event as if no modifier key (except for Shift) applies.
public String charactersIgnoringModifiers()
Discussion
Throws an InternalInconsistencyException if sent to a nonkey event.
This method will return an empty string for dead keys, such as option-E.
This method is useful for determining “basic” key values in a hardware-independent manner, enabling such features as keyboard equivalents defined in terms of modifier keys plus character keys. For example, to determine if the user typed Alt-S, you don’t have to know whether Alt-S generates a German double ess, an integral sign, or a section symbol. You simply examine the string returned by this method along with the event’s modifier flags, checking for “s” and AlternateKeyMask.
See Also
clickCount
Returns the number of mouse clicks associated with the receiver, a mouse-down or -up event.
public int clickCount()
Discussion
Throws an InternalInconsistencyException if sent to a nonmouse event.
Returns 0 for a mouse-up event if a time threshold has passed since the corresponding mouse-down event. This is because if this time threshold passes before the mouse button is released, it is no longer considered a mouse click, but a mouse-down event followed by a mouse-up event.
The return value of this method is meaningless for events other than mouse-down or -up events.
See Also
context
Returns the display context of the receiver.
public NSGraphicsContext context()
data1
Returns additional data associated with the receiver.
public int data1()
Discussion
The value returned by this method is dependent on the event type, and is defined by the originator of the event. Throws an InternalInconsistencyException if sent to an event not of type AppKitDefined, SystemDefined, ApplicationDefined, or Periodic.
Periodic events don’t use this attribute.
See Also
data2
Returns additional data associated with the receiver.
public int data2()
Discussion
The value returned by this method is dependent on the event type, and is defined by the originator of the event. Throws an InternalInconsistencyException if sent to an event not of type AppKitDefined, SystemDefined, ApplicationDefined, or Periodic.
Periodic events don’t use this attribute.
See Also
deltaX
Returns the change in x for a scroll wheel, mouse-move, or mouse-drag event.
public float deltaX()
See Also
deltaY
Returns the change in y for a scroll wheel, mouse-move, or mouse-drag event.
public float deltaY()
See Also
deltaZ
Returns the change in z for a scroll wheel, mouse-move, or mouse-drag event.
public float deltaZ()
Discussion
This value is typically 0.0.
See Also
deviceID
Returns a special identifier that is used to match tablet-pointer events with the tablet-proximity event represented by the receiver.
public int deviceID()
Discussion
All tablet-pointer events generated in the period between the device entering and leaving tablet proximity have the same device ID. This message is valid only for mouse events with subtype TabletPointEventSubtype or TabletProximityEventSubtype, and for TabletPoint and TabletProximity events.
Availability
- Available in Mac OS X v10.4 and later.
See Also
eventNumber
Returns the counter value of the latest mouse or tracking-rectangle event; every system-generated mouse and tracking-rectangle event increments this counter.
public int eventNumber()
Discussion
Throws an InternalInconsistencyException if sent to any other type of event.
See Also
isARepeat
Returns true if the receiving key event is a repeat caused by the user holding the key down, false if the key event is new.
public boolean isARepeat()
Discussion
Throws an InternalInconsistencyException if sent to a FlagsChanged event or other nonkey event.
See Also
isEnteringProximity
Returns true to indicate that a pointing device is entering the proximity of its tablet and NO when it is leaving it.
public boolean isEnteringProximity()
Discussion
This method is valid for mouse events with subtype TabletProximityEventSubtype and for TabletProximity events.
Availability
- Available in Mac OS X v10.4 and later.
keyCode
Returns the virtual key code for the keyboard key associated with the receiving key event.
public short keyCode()
Discussion
Its value is hardware-independent. The value returned is the same as the value returned in the kEventParamKeyCode when using Carbon Events.
Throws an InternalInconsistencyException if sent to a non-key event.
See Also
locationInWindow
Returns the receiver’s location in the base coordinate system of the associated window.
public NSPoint locationInWindow()
Discussion
For nonmouse events the return value of this method is undefined.
In a method of a custom view that handles mouse events, you commonly use the locationInWindow method in conjunction with the NSView method convertPointFromViewto get the mouse location in the view’s coordinate system. For example:
NSPoint event_location = [theEvent locationInWindow]; |
NSPoint local_point = [self convertPoint:event_location fromView:nil]; |
See Also
modifierFlags
Returns an integer bit field indicating the modifier keys in effect for the receiver.
public int modifierFlags()
Discussion
You can examine individual flag settings using the C bitwise AND operator with the predefined key masks described in “Constants.” The lower 16 bits of the modifier flags are reserved for device-dependent bits.
pointingDeviceID
Returns the index of the pointing device currently in proximity with the tablet.
public int pointingDeviceID()
Discussion
This index is significant for multimode (or Dual Tracking) tablets that support multiple concurrent pointing devices; the index is incremented for each pointing device that comes into proximity. Otherwise, zero is always returned. The receiver of this message should be a mouse event object with subtype TabletProximityEventSubtype or an event of type TabletProximity.
Availability
- Available in Mac OS X v10.4 and later.
See Also
pointingDeviceSerialNumber
Returns the vendor-assigned serial number of a pointing device of a certain type.
public int pointingDeviceSerialNumber()
Discussion
Devices of different types, such as a puck and a pen, may have the same serial number. The receiver of this message should be a mouse event object with subtype TabletProximityEventSubtype or an event of type TabletProximity.
Availability
- Available in Mac OS X v10.4 and later.
See Also
pointingDeviceType
Returns a constant indicating the kind of pointing device associated with the receiver.
public int pointingDeviceType()
Discussion
For example, the device could be a pen, eraser, or cursor pointing device. This method is valid for mouse events with subtype TabletProximityEventSubtype and for TabletProximity events. See “Constants” for descriptions of valid constants.
Availability
- Available in Mac OS X v10.4 and later.
See Also
pressure
Returns a value from 0.0 through 1.0 indicating the pressure applied to the input device (used for appropriate devices).
public float pressure()
Discussion
For devices that aren’t pressure-sensitive, the value is either 0.0 or 1.0. Throws an InternalInconsistencyException if sent to a nonmouse event.
For tablet pointing devices that are in proximity, the pressure value is 0.0 if they are not actually touching the tablet. As the device is pressed into the tablet, the value is increased.
See Also
rotation
Returns the rotation in degrees of the tablet pointing device associated with the receiver.
public float rotation()
Discussion
Many devices do not support rotation, in which case the returned value is 0.0. This method is valid only for mouse events with subtype TabletPointEventSubtype and for TabletPoint events.
Availability
- Available in Mac OS X v10.4 and later.
See Also
subtype
Returns the subtype of the receiving custom event.
public short subtype()
Discussion
Throws an InternalInconsistencyException if sent to an event not of type AppKitDefined, SystemDefined, ApplicationDefined, or Periodic.
Periodic events don’t use this attribute.
See Also
systemTabletID
Returns the index of the tablet device connected to the system.
public int systemTabletID()
Discussion
If multiple tablets are connected to the system, the system-tablet ID is incremented for each subsequent one. If there is only one tablet device, its system-tablet ID is zero. The receiver of this message should be a mouse event object with subtype TabletProximityEventSubtype or an event of type TabletProximity.
Availability
- Available in Mac OS X v10.4 and later.
See Also
tabletID
Returns the USB model identifier of the tablet device associated with the receiver.
public int tabletID()
Discussion
This method is valid for mouse events with subtype TabletProximityEventSubtype and for TabletProximity events.
Availability
- Available in Mac OS X v10.4 and later.
See Also
tangentialPressure
Reports the tangential pressure on the device that generated the event represented by the receiver.
public float tangentialPressure()
Discussion
The value returned can range from -1.0 to 1.0. Tangential pressure is also known as barrel pressure. Only some pointing devices support tangential pressure. This method is valid for mouse events with subtype TabletPointEventSubtype and for TabletPoint events.
Availability
- Available in Mac OS X v10.4 and later.
See Also
tilt
Reports the scaled tilt values of the pointing device that generated the event represented by the receiver.
public NSPoint tilt()
Discussion
The value returned can range from -1.0 to 1.0 for both axes. A x value that is negative indicates a tilt to the left and a positive value indicates a tilt to the right; a y value that is negative indicates a tilt to the top and a positive value indicates a tilt to the bottom. If the device is perfectly perpendicular to the table surface, the values are 0.0 for both axes. This method is valid for mouse events with subtype TabletPointEventSubtype and for TabletPoint events.
Availability
- Available in Mac OS X v10.4 and later.
See Also
timestamp
Returns the time the receiver occurred in seconds since system startup.
public double timestamp()
trackingNumber
Returns the identifier of the tracking rectangle for a tracking-rectangle event.
public int trackingNumber()
Discussion
Throws an InternalInconsistencyException if sent to any other type of event.
type
Returns the type of the receiving event.
public int type()
Discussion
The type must be one of the following:
LeftMouseDownLeftMouseUpRightMouseDownRightMouseUpOtherMouseDownOtherMouseUpMouseMovedLeftMouseDraggedRightMouseDraggedOtherMouseDraggedMouseEnteredMouseExitedKeyDownKeyUpFlagsChangedAppKitDefinedSystemDefinedApplicationDefinedPeriodicCursorUpdateScrollWheel
uniqueID
Returns the unique identifier of the pointing device that generated the event represented by the receiver.
public int uniqueID()
Discussion
Also known as tool ID, this is a unique number recorded in the chip inside every pointing device. The unique ID makes it possible to assign a specific pointing device to a specific tablet. You can also use it to “sign” documents or to restrict access to document layers to a specific pointing device. This method is valid for mouse events with subtype TabletProximityEventSubtype and for TabletProximity events.
Availability
- Available in Mac OS X v10.4 and later.
See Also
vendorDefined
Returns an array of three vendor-defined NSNumber objects associated with the pointing-type event represented by the receiver.
public Object vendorDefined()
Discussion
The NSNumbers encapsulate short values that vendors may return for various reasons; see the vendor documentation for details.This method is valid for mouse events with subtype TabletPointEventSubtype and for TabletPoint events.
Availability
- Available in Mac OS X v10.4 and later.
vendorID
Returns the vendor identifier of the tablet associated with the receiver.
public int vendorID()
Discussion
The tablet is typically a USB device. This method is valid only for mouse events with subtype TabletProximityEventSubtype and for TabletProximity events.
Availability
- Available in Mac OS X v10.4 and later.
See Also
vendorPointingDeviceType
Returns a coded bit field whose set bits indicate the type of pointing device (within a vendor selection) associated with the receiver.
public int vendorPointingDeviceType()
Discussion
See the vendor documentation for an interpretation of significant bits. This method is valid only for mouse events with subtype TabletProximityEventSubtype and for TabletProximity events.
Availability
- Available in Mac OS X v10.4 and later.
See Also
window
Returns the window object associated with the receiver.
public NSWindow window()
Discussion
A periodic event, however, has no window; in this case the return value is undefined.
See Also
windowNumber
Returns the identifier for the window device associated with the receiver.
public int windowNumber()
Discussion
A periodic event, however, has no window; in this case the return value is undefined.
See Also
Constants
These constants represent various kinds of events. They are returned by type and are used as the first argument to the methods keyEvent, mouseEvent, and otherEvent.
These constants are masks for the events listed above. Pass them to the NSCell method setEventMaskForSendingAction to specify when an NSCell should send its action message.
The following constants represent pointing-device types for TabletProximity events or mouse events with subtype TabletProximityEventSubtype. The pointingDeviceType method returns one of these constants.
The following constants represent button masks for TabletPoint events or mouse events with subtype TabletPointEventSubtype. The buttonMask method returns a bit mask, which you test with one or more of these constants to determine the state of the buttons on a tablet pointing device.
The following constants represent mouse-event subtypes for mouse and tablet events (accessed with the subtype method).
The following constants (except for DeviceIndependentModifierFlagsMask) represent device-independent bits found in event modifier flags:
These constants represent Unicode characters (0xF700–0xF8FF) that are reserved for function keys on the keyboard. Combined in Strings, they are the return values of the NSEvent methods characters and charactersIgnoringModifiers and may be used in some parameters in the NSEvent method keyEvent.
Note that some function keys are handled at a lower level and are never seen by your application. They include the Volume Up key, Volume Down key, Volume Mute key, Eject key, and Function key found on many iBook and PowerBook computers.
© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)