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 eventsuch as which character was typed and where the mouse was locatedis 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 chaina 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 methodstype, 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 eventsone 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
+ (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