Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSEvent


Inherits from:
NSObject
Package:
com.apple.yellow.application


Class Description


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

NSEvents are typically passed up the application's responder chain, a series of objects that stand in line for event messages and untargeted action messages, as described in the NSResponder class specification. When the NSApplication object retrieves an event from the event queue, it dispatches the event to the appropriate NSWindow by invoking sendEvent. The NSWindow then passes the event to its first responder in an event message such as mouseDown or keyDown, and the event gets passed on up the responder chain until some object handles it. In the case of a mouse-down event, a mouseDown message is sent to the NSView where the user clicked the mouse; if it doesn't handle the event itself, the NSView relays the message to its next responder.

Most events follow this same path: from the windowing system to the application's event queue, and from there to the appropriate objects in the application. Though it rarely need do so, an application can also create an event from scratch and insert it into the event queue for distribution, or send it directly to its destination in an event message. The newly created events can be added to the event queue by invoking NSWindow's (or NSApplication's) postEvent method.

While most events are distributed automatically through the responder chain, sometimes an object needs to retrieve events explicitly-for example, while handling mouse-dragged events. NSWindow and NSApplication define the method nextEventMatchingMask:untilDate:inMode:dequeue:, which allows an object to retrieve events of specific types. The nature of the retrieved event can then be ascertained by invoking NSEvent instance methods- type, window, and so on. All types of events are associated with an NSWindow; the window method returns this object. The location of a mouse event within the window's coordinate system is given by locationInWindow, and the time of the event by timestamp. The modifierFlags method returns an indication of which modifier keys (Command, Control, Shift, and so on) the user held down while the event occurred.

The type method returns an NSEventType value that identifies the sort of event. The different types of events fall into five groups:

Some of these groups comprise several NSEventType constants, others only one. The following sections discuss the groups, along with the corresponding NSEventType constants.


Keyboard Events


Among the most common events sent to an application are direct reports of the user's keyboard actions, identified by these NSEventType constants:

Of these, key-down events are the most useful to an application. When a type message returns KeyDown, the next step is typically to get the characters generated by the key-down using the characters method.

Key-up events are used less frequently since they follow almost automatically when there's been a key-down event. And because NSEvent's modifierFlags method returns the state of the modifier keys regardless of the type of event, applications normally don't need to receive flags-changed events; they're useful only for applications that have to keep track of the state of these keys at all times.

For more information on keyboard events, see "Key Events" under the Class Description in the NSResponder class specification and "Input Management" (page 1567) in the NSTextView class specification.


Mouse Events


Mouse events are generated by changes in the state of the mouse buttons and by changes in the position of the mouse cursor on the screen. This category consists of:

Mouse-dragged and mouse-moved events are generated repeatedly as long as the user keeps moving the mouse. If the mouse is stationary, neither type of event is generated until the mouse moves again.


Note: Neither the OpenStep specification nor the Cocoa implementation specifies facilities for the third button of a three-button mouse.

See "Mouse Events" in the NSView class specification for more information on mouse events.


Tracking-Rectangle and Cursor-Update Events


Because following the mouse's movements precisely is an expensive operation, the Application Kit provides a less intensive mechanism for tracking the location of the mouse. It does this by allowing the application to define regions of the screen, called tracking rectangles, that generate events when the cursor enters or leaves them. The event types are MouseEntered and MouseExited, and they're generated when the application has asked the Window Server to set a tracking rectangle in a window, typically by using NSView's addTrackingRect:owner:userData:assumeInside: method. A window can have any number of tracking rectangles; NSEvent's trackingNumber method identifies the rectangle that triggered the event.

A special kind of tracking event is the CursorUpdate event. This type is used to implement NSView's cursor-rectangle mechanism. An CursorUpdate event is generated when the cursor has crossed the boundary of a predefined rectangular area. Applications rarely use CursorUpdate events directly, instead using NSView's far more convenient methods.

See "Tracking Rectangles and Cursor Rectangles" in the NSView class specification for more information.


Periodic Events


An event of type Periodic simply notifies an application that a certain time interval has elapsed. By using the NSEvent class method startPeriodicEvents, an application can register to receive periodic events and have them placed in its event queue at a certain frequency. When the application no longer needs them, the flow of periodic events can be turned off by invoking stopPeriodicEvents. An application can have only one stream of periodic events active for each thread. Unlike keyboard and mouse events, periodic events aren't dispatched to an NSWindow. The application must retrieve them explicitly using nextEventMatchingMask:untilDate:inMode:dequeue:, typically in a modal loop.

Periodic events are particularly useful in situations where input events aren't generated. For example, when the user holds the mouse down over a scroll button but doesn't move it, no events are generated after the mouse-down event. The scrolling mechanism then has to start and use a stream of periodic events to keep the document scrolling at a reasonable pace until the user releases the mouse. When a mouse-up event occurs, the scrolling mechanism terminates the periodic event stream.


Other Events


The remaining event types-AppKitDefined, SystemDefined, and ApplicationDefined-are less structured, containing only generic subtype and data fields. These three types are extensions to the OpenStep specification, so you shouldn't use them in portable code (periodic events are also implemented in this manner, but are in the specification). Of the three miscellaneous event types, only ApplicationDefined is of real use to application programs. It allows the application to generate totally custom events and insert them into the event queue. Each such event can have a subtype and two additional codes to differentiate it from others. otherEvent creates one of these events, and the subtype, data1, and data2 methods return the information specific to these events.




Constants


These constants represents various kinds of events. They are returned by type , and are used as the first argument to the methods keyEvent, mouseEvent, and otherEvent.


Constant Description
LeftMouseDown See "Mouse Events"
LeftMouseUp See "Mouse Events"
RightMouseDown See "Mouse Events"
RightMouseUp See "Mouse Events"
MouseMoved See "Mouse Events"
LeftMouseDragged See "Mouse Events"
RightMouseDragged See "Mouse Events"
MouseEntered See "Tracking-Rectangle and Cursor-Update Events"
MouseExited See "Tracking-Rectangle and Cursor-Update Events"
CursorUpdate See "Tracking-Rectangle and Cursor-Update Events"
KeyDown See "Keyboard Events"
KeyUp See "Keyboard Events"
FlagsChanged See "Keyboard Events"
AppKitDefined See "Other Events"
SystemDefined See "Other Events"
ApplicationDefined See "Other Events"
Periodic See "Periodic Events"

These constants are masks for different kinds of events. Pass them to the NSCell method setEventMaskForSendingAction to specify when an NSCell should send its action message.


Constant Description
LeftMouseDownMask Description forthcoming.
LeftMouseUpMask Description forthcoming.
RightMouseDownMask Description forthcoming.
RightMouseUpMask Description forthcoming.
MouseMovedMask Description forthcoming.
LeftMouseDraggedMask Description forthcoming.
RightMouseDraggedMask Description forthcoming.
MouseEnteredMask Description forthcoming.
MouseExitedMask Description forthcoming.
KeyDownMask Description forthcoming.
KeyUpMask Description forthcoming.
FlagsChangedMask Description forthcoming.
AppKitDefinedMask Description forthcoming.
SystemDefinedMask Description forthcoming.
ApplicationDefinedMask Description forthcoming.
PeriodicMask Description forthcoming.
CursorUpdateMask Description forthcoming.
AnyEventMask Description forthcoming.

These are device-independent bits found in event modifier flags.


Constant Description
AlphaShiftKeyMask Description forthcoming.
ShiftKeyMask Description forthcoming.
ControlKeyMask Description forthcoming.
AlternateKeyMask Description forthcoming.
CommandKeyMask Description forthcoming.
NumericPadKeyMask Description forthcoming.
HelpKeyMask Description forthcoming.
FunctionKeyMask Description forthcoming.

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


Constant Description
UpArrowFunctionKey Description forthcoming.
DownArrowFunctionKey Description forthcoming.
LeftArrowFunctionKey Description forthcoming.
RightArrowFunctionKey Description forthcoming.
F1FunctionKey Description forthcoming.
F2FunctionKey Description forthcoming.
F3FunctionKey Description forthcoming.
F4FunctionKey Description forthcoming.
F5FunctionKey Description forthcoming.
F6FunctionKey Description forthcoming.
F7FunctionKey Description forthcoming.
F8FunctionKey Description forthcoming.
F9FunctionKey Description forthcoming.
F10FunctionKey Description forthcoming.
F11FunctionKey Description forthcoming.
F12FunctionKey Description forthcoming.
F13FunctionKey Description forthcoming.
F14FunctionKey Description forthcoming.
F15FunctionKey Description forthcoming.
F16FunctionKey Description forthcoming.
F17FunctionKey Description forthcoming.
F18FunctionKey Description forthcoming.
F19FunctionKey Description forthcoming.
F20FunctionKey Description forthcoming.
F21FunctionKey Description forthcoming.
F22FunctionKey Description forthcoming.
F23FunctionKey Description forthcoming.
F24FunctionKey Description forthcoming.
F25FunctionKey Description forthcoming.
F26FunctionKey Description forthcoming.
F27FunctionKey Description forthcoming.
F28FunctionKey Description forthcoming.
F29FunctionKey Description forthcoming.
F30FunctionKey Description forthcoming.
F31FunctionKey Description forthcoming.
F32FunctionKey Description forthcoming.
F33FunctionKey Description forthcoming.
F34FunctionKey Description forthcoming.
F35FunctionKey Description forthcoming.
InsertFunctionKey Description forthcoming.
DeleteFunctionKey Description forthcoming.
HomeFunctionKey Description forthcoming.
BeginFunctionKey Description forthcoming.
EndFunctionKey Description forthcoming.
PageUpFunctionKey Description forthcoming.
PageDownFunctionKey Description forthcoming.
PrintScreenFunctionKey Description forthcoming.
ScrollLockFunctionKey Description forthcoming.
PauseFunctionKey Description forthcoming.
SysReqFunctionKey Description forthcoming.
BreakFunctionKey Description forthcoming.
ResetFunctionKey Description forthcoming.
StopFunctionKey Description forthcoming.
MenuFunctionKey Description forthcoming.
UserFunctionKey Description forthcoming.
SystemFunctionKey Description forthcoming.
PrintFunctionKey Description forthcoming.
ClearLineFunctionKey Description forthcoming.
ClearDisplayFunctionKey Description forthcoming.
InsertLineFunctionKey Description forthcoming.
DeleteLineFunctionKey Description forthcoming.
InsertCharFunctionKey Description forthcoming.
DeleteCharFunctionKey Description forthcoming.
PrevFunctionKey Description forthcoming.
NextFunctionKey Description forthcoming.
SelectFunctionKey Description forthcoming.
ExecuteFunctionKey Description forthcoming.
UndoFunctionKey Description forthcoming.
RedoFunctionKey Description forthcoming.
FindFunctionKey Description forthcoming.
HelpFunctionKey Description forthcoming.
ModeSwitchFunctionKey Description forthcoming.



Method Types


Constructors
NSEvent
Creating events
eventMaskFromType
keyEvent
mouseEvent
otherEvent
Requesting and stopping periodic events
startPeriodicEvents
stopPeriodicEvents
Getting general event information
context
locationInWindow
modifierFlags
timestamp
type
window
windowNumber
Getting key event information
characters
charactersIgnoringModifiers
isARepeat
keyCode
Getting mouse event information
clickCount
eventNumber
pressure
Getting tracking-rectangle event information
eventNumber
trackingNumber
Getting custom event information
data1
data2
subtype


Constructors



NSEvent

public NSEvent()

Description forthcoming.


Static Methods



eventMaskFromType

public static final int eventMaskFromType(int type)

Description forthcoming.

keyEvent

public static NSEvent keyEvent( int type, NSPoint location, int flags, double time, int windowNum, NSGraphicsContext context, String characters, String unmodCharacters, boolean repeatKey, short code)

Returns a new NSEvent object describing a key event. type must be one of the following, else an InvalidArgumentException is thrown:

location is the mouse location in the base coordinate system of the window specified by windowNumber.

flags is an integer bit field containing any of the modifier key masks described in "Constants" , combined using the C bitwise OR operator.

time is the time the event occurred in seconds since system startup.

windowNumber identifies the window device associated with the event, which is associated with the NSWindow that will receive the event.

context is the display context of the event.

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

unmodCharacters is the string of characters generated by the key event as if no modifier key had been pressed (except for Shift). This is useful for getting the "basic" key value in a hardware-independent manner.

repeatKey is true if the key event is a repeat caused by the user holding the key down, false if the key event is new.

code identifies the keyboard key associated with the key event. Its value is hardware-dependent.

See Also: characters, charactersIgnoringModifiers, isARepeat, keyCode



mouseEvent

public static NSEvent mouseEvent( int type, NSPoint location, int flags, double time, int windowNum, NSGraphicsContext context, int eventNumber, int clickNumber, float pressure)

Returns a new NSEvent object describing a mouse-down, -up, -moved, or -dragged event. type must be one of the modifier key masks described in "Constants" , else an InvalidArgumentException is thrown.

location, flags, time, windowNumber, and context are as described under keyEvent.

eventNumber is an identifier for the new event. It's normally taken from a counter for mouse events, which continually increases as the application runs.

clickNumber is the number of mouse clicks associated with the mouse event.

pressure 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: clickCount, eventNumber, pressure



otherEvent

public static NSEvent otherEvent( int type, NSPoint location, int flags, double time, int windowNum, NSGraphicsContext context, short subtype, int data1, int data2)

Returns a new NSEvent object describing a custom event. type must be one of the values below, else an InvalidArgumentException is thrown. Your code should only create events of type ApplicationDefined.

location, flags, time, windowNumber, and context are as described under keyEvent. Arguments specific to custom events are:

See Also: subtype, data1, data2



startPeriodicEvents

public static void startPeriodicEvents( double delaySeconds, double delaySeconds)

Begins generating periodic events for the current thread every periodSeconds, after a delay of delaySeconds. 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



stopPeriodicEvents

public static void stopPeriodicEvents()

Stops generating periodic events for the current thread and discards any periodic events remaining in the queue. This message is ignored if periodic events aren't currently being generated.

See Also: startPeriodicEvents




Instance Methods



characters

public String characters()

Returns the characters associated with the receiving key-up or key-down event. 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.

See Also: charactersIgnoringModifiers, keyEvent



charactersIgnoringModifiers

public String charactersIgnoringModifiers()

Returns the characters generated by the receiving key event as if no modifier key (except for Shift) applies. Throws an InternalInconsistencyException if sent to a non-key event. The return value of this method is meaningless for an FlagsChanged event.

This method is useful for determining "basic" key values in a hardware-independent manner, enabling such features as keyboard equivalents and mnemonics 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: characters, modifierFlags, keyEvent



clickCount

public int clickCount()

Returns the number of mouse clicks associated with the receiver, a mouse-down or -up event. Throws an InternalInconsistencyException if sent to a non-mouse event.

The return value of this method is meaningless for events other than mouse-down or -up events.

See Also: mouseEvent



context

public NSGraphicsContext context()

Returns the display context of the receiving event.

data1

public int data1()

Returns additional data associated with the receiving 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, subtype, otherEvent



data2

public int data2()

Returns additional data associated with the receiving 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: data1, subtype, otherEvent



eventNumber

public int eventNumber()

Returns the counter value of the latest mouse or tracking-rectangle event; every system-generated mouse and tracking-rectangle event increments this counter. Throws an InternalInconsistencyException if sent to any other type of event.

See Also: mouseEvent



isARepeat

public boolean 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. Throws an InternalInconsistencyException if sent to a non-key event.

The return value of this method is meaningless for FlagsChanged events.

See Also: keyEvent



keyCode

public short keyCode()

Returns the code for the keyboard key associated with the receiving key event. Its value is hardware-dependent. Throws an InternalInconsistencyException if sent to a non-key event.

See Also: keyEvent



locationInWindow

public NSPoint locationInWindow()

Returns the receiving event's location in the base coordinate system of the associated window.

See Also: window



modifierFlags

public int modifierFlags()

Returns an integer bit field indicating the modifier keys in effect for the receiving event. You can examine individual flag settings using the C bitwise AND operator with the predefined key masks described in "Constants" .

pressure

public float pressure()

Returns a value between 0.0 and 1.0 indicating the pressure applied to the input device (used for appropriate devices). For devices that aren't pressure-sensitive, the value is either 0.0 or 1.0. Throws an InternalInconsistencyException if sent to a non-mouse event.

See Also: mouseEvent



subtype

public short subtype()

Returns the subtype of the receiving custom 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: data1, data2, otherEvent



timestamp

public double timestamp()

Returns the time the event occurred in seconds since system startup.

trackingNumber

public int trackingNumber()

Returns the identifier of the tracking rectangle for a tracking-rectangle event. Throws an InternalInconsistencyException if sent to any other type of event.

type

public int type()

Returns the type of the receiving event. The type must be one of:

window

public NSWindow window()

Returns the window object associated with the event. A periodic event, however, has no window; in this case the return value is undefined.

See Also: windowNumber



windowNumber

public int windowNumber()

Returns the identifier for the window device associated with the event. A periodic event, however, has no window; in this case the return value is undefined.

See Also: window




Table of Contents