Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSEvent 

Inherits From:	NSObject

Conforms To:	NSCoding, NSCopying
NSObject (NSObject)

Declared In:	AppKit/NSEvent.h 

Class Description

An NSEvent object contains information about an event such as a mouse-click or a key-down. The window system  associates each such user action with a window, reporting the event to the application that created the window. Pertinent information about each eventÐsuch as which character was typed and where the mouse was locatedÐis collected in an NSEvent object and made available to the application. As events are received in the application, they're temporarily placed in storage called the event queue. When the application is ready to process an event, it takes an NSEvent from the queue. 

NSEvents are typically passed to the responder chainÐa set of objects within the window that inherit from NSResponder. For example, NSResponder's mouseDown: and keyDown: methods take an NSEvent as an argument. When an NSApplication retrieves an NSEvent from the event queue, it dispatches it to the appropriate NSWindow (which is itself an NSResponder) by invoking keyDown: or a similar message. The NSWindow in turn passes the event to the first responder, and the event gets passed on down the responder chain until some object handles it. In the case of a mouse-down, a mouseDown: message is sent to the NSView in which the user clicked the mouse, which relays the message to its next responder if it can't handle the message itself.

Most events follow this same path: from the window system to the application's event queue, and from there, to the appropriate objects of the application. However, the Application Kit can create an NSEvent from scratch and insert it into the event queue for distribution, or send it directly to its destination. (It's rare for an application to create an event directly, but it's possible, using NSEvent class methods. The newly created events can be added to the event queue by invoking NSWindow's (or NSApplication's) postEvent:atStart: method.

Events are retrieved from the event queue by calling the NSWindow method nextEventMatchingMask:untilDate:inMode:dequeue: or a similar NSApplication method. These methods return an instance of NSEvent. The nature of the retrieved event can then be ascertained by invoking NSEvent instance methodsÐtype, window, and so forth. All types of events are associated with a window. The corresponding NSWindow object can be gotten by invoking window. The location of the event within the window's coordinate system is obtained from locationInWindow, and the time of the event is gotten from timestamp. The modifierFlags method returns an indication of which modifier keys (Command, Control, Shift, and so forth) were held down while the event occurred. 

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

·	Keyboard events

·	Mouse events

·	Tracking-rectangle events

·	Periodic events

·	Cursor-update events 

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 three NSEventType constants:

·	NSKeyDown: The user generated a character by pressing a key.

·	NSKeyUp: The key was released.

·	NSFlagsChanged: The user pressed or released a modifier key, or turned Alpha Lock on or off. 

Of these, key-down events are the most useful to the application. When the type method returns NSKeyDown, your next step is typically to determine the character or characters generated by the key-down, by sending the NSEvent a characters message. 

Key-up events are less used since they follow almost automatically when there has 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 continuously.

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:

·	NSLeftMouseDown, NSLeftMouseUp, NSRightMouseDown, NSRightMouseUp: Two sets of mouse-down and mouse-up events, one for the left mouse button and one for the right. ªMouse-downº means the user pressed the button; ªmouse-upº means the button was released. If the mouse has just one button, only left mouse events are generated. By sending a clickCount message to the NSEvent, you can determine whether the mouse event was a single-click, double-click, and so on.

·	NSLeftMouseDragged, NSRightMouseDragged: Two types of mouse-dragged eventsÐone for when the mouse is moved with its left mouse button down, or with both buttons down, and one for when it's moved with just the right button down. A mouse with a single button generates only left mouse-dragged events. As the mouse is moved with a button down, a series of mouse-dragged events is produced. The series is always preceded by a mouse-down event and followed by a mouse-up event.

·	NSMouseMoved: The user moved the mouse without holding down either mouse button.

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

Note:  OpenStep doesn't specify facilities for the third button of a three-button mouse. 

Tracking-Rectangle Events

NSMouseEntered and NSMouseExited events are like the ªMouse Eventsº listed previously, in that they're dependent on mouse movements. However, unlike the others, they're generated only if the application has asked the window system to set a tracking rectangle in a window. An NSMouseEntered or NSMouseExited event is created when the cursor has entered the tracking rectangle or left it. A window can have any number of tracking rectangles; the NSEvent method trackingNumber identifies which rectangle was entered or exited.

Periodic Events

An event of type NSPeriodic simply notifies an application that a certain time interval has elapsed. By using the NSEvent class method startPeriodicEventsAfterDelay:withPeriod:, an application can register that it wants periodic events and that they should be 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't have more than one stream of periodic events active at a time. Unlike keyboard and mouse events, periodic events aren't dispatched to an NSWindow.

Cursor-Update Events 

Events of type NSCursorUpdate are used to implement NSView's cursor-rectangle methods. An NSCursorUpdate event is generated when the cursor has crossed the boundary of a predefined rectangular area. The application can respond by updating the cursor's shape. 

Creating NSEvent Objects 

+ (NSEvent *)enterExitEventWithType:(NSEventType)type	
location:(NSPoint)location	Returns an NSEvent object initialized with general event
modifierFlags:(unsigned int)flags		data and information specific to mouse tracking
timestamp:(NSTimeInterval)time		(eventNum, trackingNum, userData).
windowNumber:(int)windowNum	
context:(NSDPSContext *)context	
eventNumber:(int)eventNum	
trackingNumber:(int)trackingNum	
userData:(void *)userData	 

+ (NSEvent *)keyEventWithType:(NSEventType)type	
location:(NSPoint)location	Returns an NSEvent object initialized with general event
modifierFlags:(unsigned int)flags		data and information specific to keyboard events (keys,
timestamp:(NSTimeInterval)time		repeatKey, code, ukeys). (ukeys sets the unmodified 
windowNumber:(int)windowNum		character string.)
context:(NSDPSContext *)context	
characters:(NSString *)keys	
charactersIgnoringModifiers:(NSString *)ukeys
isARepeat:(BOOL)repeatKey	
keyCode:(unsigned short)code	 

+ (NSEvent *)mouseEventWithType:(NSEventType)type	
location:(NSPoint)location	Returns an NSEvent object initialized with general event
modifierFlags:(unsigned int)flags		data and information specific to mouse events 
timestamp:(NSTimeInterval)time		(eventNum, clickNum, pressureValue).
windowNumber:(int)windowNum	
context:(NSDPSContext *)context	
eventNumber:(int)eventNum	
clickCount:(int)clickNum	
pressure:(float)pressureValue	 

+ (NSEvent *)otherEventWithType:(NSEventType)type	
location:(NSPoint)location	Returns an NSEvent object initialized with general event
modifierFlags:(unsigned int)flags		data and information specific to kit-defined events
timestamp:(NSTimeInterval)time		(subType, data1, data2).
windowNumber:(int)windowNum	
context:(NSDPSContext *)context	
subtype:(short)subType	
data1:(int)data1	
data2:(int)data2	 

Getting General Event Information

- (NSDPSContext *)context	Returns the Display PostScript context of the event.

- (NSPoint)locationInWindow	Returns the event's location in the base coordinate system of its window.

- (unsigned int)modifierFlags	Returns an integer bitfield containing modifier-key flags.

- (NSTimeInterval)timestamp	Returns the time the event occurred in seconds since system startup.

- (NSEventType)type	Returns the type of the event (left-mouse-up, right-mouse-dragged, key-down, etc.).

- (NSWindow *)window	Returns the window object associated with the event.

- (int)windowNumber	Returns the number of the window associated with the event.

Getting Key Event Information

- (NSString *)characters	Returns the character code (a string of characters generated by the key event).

- (NSString *)charactersIgnoringModifiers	Returns the string of characters generated by the key event as if no modifier key had been pressed (except for Shift).

- (BOOL)isARepeat	Returns whether the key event is being repeated (user is holding down the key).

- (unsigned short)keyCode	Returns the code that maps to a key on the keyboard.

Getting Mouse Event Information

- (int)clickCount	Returns the number of mouse clicks associated with the mouse event.

- (int)eventNumber	Returns the event number of the latest mouse-down event. This information is also useful for handling tracking events.

- (float)pressure	Returns a value indicating the pressure applied to the input device (used for appropriate devices, not mice).

Getting Tracking Event Information

- (int)trackingNumber	Returns the number that identifies the tracking rectangle.

- (void *)userData	Returns data arbitrarily associated with the event.

Requesting Periodic Events

+ (void)startPeriodicEventsAfterDelay:(NSTimeInterval)delaySeconds
withPeriod:(NSTimeInterval)periodSeconds	Start generating periodic events with frequency periodSeconds after delay delaySeconds for current thread.

+ (void)stopPeriodicEvents	Stop generating periodic events for current thread, and discard any periodic events remaining in the queue. 

Getting Information about Specially Defined Events

- (int)data1	Returns special data associated with the event.

- (int)data2	Returns special data associated with the event.

- (short)subtype	Returns the identifier of the specially defined event.