This is NSEvent.rtf in view mode; [Download] [Up]
paperh18648 margl-907 margr0 margt0 margb0 fi0 ri0 ql sb0 f1 fs24 Copyright f3 'e3f1 1994 by NeXT Computer, Inc. All Rights Reserved.
s4 li100 fi0 ri1007 ql f0 b fs36 fs100
fs36 NSEvent
pard s11 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSObject
fs20
fs28 s6 f0 b fs24 Conforms To:tab b0 fs28 f1 NSCoding, NSCopying
fi0 NSObject (NSObject)
fs20
fs28 s7 fi-2771 f0 b fs24 Declared In:tab b0 fs28 f1 AppKit/NSEvent.h
fs20
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs28 fs20
fs28 Class Description
fs14
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs2
fs28 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'd0such as which character was typed and where the mouse was located'd0is collected in an NSEvent object and made available to the application. As events are received in the application, they'27re temporarily placed in storage called the event queue. When the application is ready to process an event, it takes an NSEvent from the queue.
fs16
fs28 NSEvents are typically passed to the responder chain'd0a set of objects within the window that inherit from NSResponder. For example, NSResponder'27s b mouseDown:b0 and b keyDown:b0 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 b keyDown:b0 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 b mouseDown:b0 message is sent to the NSView in which the user clicked the mouse, which relays the message to its next responder if it can'27t handle the message itself.
fs16
fs28 Most events follow this same path: from the window system to the application'27s 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'27s rare for an i applicationi0 to create an event directly, but it'27s possible, using NSEvent class methods. The newly created events can be added to the event queue by invoking NSWindow'27s (or NSApplication'27s) b postEvent:atStart:b0 method.
fs16
fs28 Events are retrieved from the event queue by calling the NSWindow methodb nextEventMatchingMask:untilDate:inMode:dequeue:b0 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'd0b typeb0 , b windowb0 , and so forth. All types of events are associated with a window. The corresponding NSWindow object can be gotten by invoking b windowb0 . The location of the event within the window'27s coordinate system is obtained from b locationInWindowb0 , and the time of the event is gotten from b timestampb0 . The b modifierFlagsb0 method returns an indication of which modifier keys (Command, Control, Shift, and so forth) were held down while the event occurred.
fs16
fs28 The b type b0 method returns an NSEventType, a constant that identifies the sort of event. The different types of events fall into five groups:
fs16
fs28 pard s3 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 'b7tab Keyboard events
fs16
fs28 'b7tab Mouse events
fs16
fs28 'b7tab Tracking-rectangle events
fs16
fs28 'b7tab Periodic events
fs16
fs28 'b7tab Cursor-update events
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 Some of these groups comprise several NSEventType constants; others only one. The following sections discuss the groups, along with the corresponding NSEventType constants.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Keyboard Events
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 Among the most common events sent to an application are direct reports of the user's keyboard actions, identified by these three NSEventType constants:
fs16
fs28 pard s3 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 'b7tab NSKeyDown: The user generated a character by pressing a key.
fs16
fs28 'b7tab NSKeyUp: The key was released.
fs16
fs28 'b7tab NSFlagsChanged: The user pressed or released a modifier key, or turned Alpha Lock on or offi .
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 i0 Of these, key-down events are the most useful to the application. When the b type b0 method returns NSKeyDown, your next step is typically to determine the character or characters generated by the key-down, by sending the NSEvent a b charactersb0 message.
fs16
fs28 Key-up events are less used since they follow almost automatically when there has been a key-down event. And because NSEvent'27sb modifierFlagsb0 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.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Mouse Events
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 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:
fs16
fs28 pard s3 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 'b7tab NSLeftMouseDown, NSLeftMouseUp, NSRightMouseDown, NSRightMouseUp: Two sets of mouse-down and mouse-up events, one for the left mouse button and one for the right. 'aaMouse-down'ba means the user pressed the button; 'aamouse-up'ba means the button was released. If the mouse has just one button, only left mouse events are generated. By sending a b clickCount b0 message to the NSEvent, you can determine whether the mouse event was a single-click, double-click, and so on.
fs16
fs28 'b7tab NSLeftMouseDragged, NSRightMouseDragged: Two types of mouse-dragged events'd0one 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.
fs16
fs28 'b7tab NSMouseMoved: The user moved the mouse without holding down either mouse button.
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 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.
fs16
fs28 pard s12 li477 fi0 ri1007 ql f0 b fs24 Note: b0 fs28 f1 OpenStep doesn'27t specify facilities for the third button of a three-button mouse.
fs14
fs28 s15 f0 b fs24 fs6
fs24 Tracking-Rectangle Events
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 NSMouseEntered and NSMouseExited events are like the 'aaMouse Events'ba listed previously, in that they'27re dependent on mouse movements. However, unlike the others, they'27re 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 b trackingNumberb0 identifies which rectangle was entered or exited.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Periodic Events
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 An event of type NSPeriodic simply notifies an application that a certain time interval has elapsed. By using the NSEvent class method b startPeriodicEventsAfterDelay:withPeriod:b0 , 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 b stopPeriodicEventsb0 . An application can'27t have more than one stream of periodic events active at a time.i i0 Unlike keyboard and mouse events, periodic events aren'27t dispatched to an NSWindow.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Cursor-Update Eventsi
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 i0 fs28 fs16
fs28 Events of type NSCursorUpdate are used to implement NSView'27s 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.
fs16
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs24
fs28 Creating NSEvent Objects
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSEvent *)b enterExitEventWithType:b0 (NSEventType)i typei0 tab
s9 li7030 fi-6553 fi-5796 b location:b0 (NSPoint)i locationi0 tab Returns an NSEvent object initialized with general event
b modifierFlags:b0 (unsigned int)i flagsi0 tab tab data and information specific to mouse tracking
b timestamp:b0 (NSTimeInterval)i timei0 tab tab (i eventNum,i0 i trackingNum,i0 i userData)i0 .
b windowNumber:b0 (int)i windowNumi0 tab
b context:b0 (NSDPSContext *)i contexti0 tab
b eventNumber:b0 (int)i eventNumi0 tab
b trackingNumber:b0 (int)i trackingNumi0 tab
b userData:b0 (void *)i userDatai0 tab
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (NSEvent *)b keyEventWithType:b0 (NSEventType)i typei0 tab
s9 li7030 fi-6553 fi-5796 b location:b0 (NSPoint)i locationi0 tab Returns an NSEvent object initialized with general event
b modifierFlags:b0 (unsigned int)i flagsi0 tab tab data and information specific to keyboard events (i keys,
i0 b timestamp:b0 (NSTimeInterval)i timei0 tab tab i repeatKey,i0 i codei0 , i ukeysi0 ). (i ukeysi0 sets the unmodified
b windowNumber:b0 (int)i windowNumi0 tab tab character string.)
b context:b0 (NSDPSContext *)i contexti0 tab
b characters:b0 (NSString *)i keysi0 tab
b charactersIgnoringModifiers:b0 (NSString *)i ukeys
i0 b isARepeat:b0 (BOOL)i repeatKeyi0 tab
b keyCode:b0 (unsigned short)i codei0 tab
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (NSEvent *)b mouseEventWithType:b0 (NSEventType)i typei0 tab
s9 li7030 fi-6553 fi-5796 b location:b0 (NSPoint)i locationi0 tab Returns an NSEvent object initialized with general event
b modifierFlags:b0 (unsigned int)i flagsi0 tab tab data and information specific to mouse events
b timestamp:b0 (NSTimeInterval)i timei0 tab tab (i eventNum, clickNum,i0 i pressureValue)i0 .
b windowNumber:b0 (int)i windowNumi0 tab
b context:b0 (NSDPSContext *)i contexti0 tab
b eventNumber:b0 (int)i eventNumi0 tab
b clickCount:b0 (int)i clickNumi0 tab
b pressure:b0 (float)i pressureValuei0 tab
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (NSEvent *)b otherEventWithType:b0 (NSEventType)i typei0 tab
s9 li7030 fi-6553 fi-5796 b location:b0 (NSPoint)i locationi0 tab Returns an NSEvent object initialized with general event
b modifierFlags:b0 (unsigned int)i flagsi0 tab tab data and information specific to kit-defined events
b timestamp:b0 (NSTimeInterval)i timei0 tab tab (i subType,i0 i data1,i0 i data2)i0 .
b windowNumber:b0 (int)i windowNumi0 tab
b context:b0 (NSDPSContext *)i contexti0 tab
b subtype:b0 (short)i subTypei0 tab
b data1:b0 (int)i data1i0 tab
b data2:b0 (int)i data2i0 tab
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Getting General Event Information
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSDPSContext *)b contextb0 tab Returns the Display PostScript context of the event.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSPoint)b locationInWindowb0 tab Returns the event'27s location in the base coordinate system of its window.
fi-6552 fs16
fs28 fi-6552 {f3 -} (unsigned int)b modifierFlagsb0 tab Returns an integer bitfield containing modifier-key flags.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSTimeInterval)b timestampb0 tab Returns the time the event occurred in seconds since system startup.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSEventType)b typeb0 tab Returns the type of the event (left-mouse-up, right-mouse-dragged, key-down, etc.).
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSWindow *)b windowb0 tab Returns the window object associated with the event.
fi-6552 fs16
fs28 fi-6552 {f3 -} (int)b windowNumberb0 tab Returns the number of the window associated with the event.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Getting Key Event Information
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSString *)b charactersb0 tab Returns the character code (a string of characters generated by the key event).
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b charactersIgnoringModifiersb0 tab Returns the string of characters generated by the key event as if no modifier key had been pressed (except for Shift).
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b isARepeatb0 tab Returns whether the key event is being repeated (user is holding down the key).
fi-6552 fs16
fs28 fi-6552 {f3 -} (unsigned short)b keyCodeb0 tab Returns the code that maps to a key on the keyboard.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Getting Mouse Event Information
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (int)b clickCountb0 tab Returns the number of mouse clicks associated with the mouse event.
fi-6552 fs16
fs28 fi-6552 {f3 -} (int)b eventNumberb0 tab Returns the event number of the latest mouse-down event. This information is also useful for handling tracking events.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b pressureb0 tab Returns a value indicating the pressure applied to the input device (used for appropriate devices, not mice).
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Getting Tracking Event Information
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (int)b trackingNumberb0 tab Returns the number that identifies the tracking rectangle.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void *)b userDatab0 tab Returns data arbitrarily associated with the event.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Requesting Periodic Events
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (void)b startPeriodicEventsAfterDelay:b0 (NSTimeInterval)i delaySeconds
s9 li7030 fi-6553 fi-5796 i0 b withPeriod:b0 (NSTimeInterval)i periodSecondstab i0 Start generating periodic events with frequency i periodSecondsi0 after delayi delaySecondsi0 for current thread.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (void)b stopPeriodicEventstab b0 Stop generating periodic events for current thread, and discard any periodic events remaining in the queue.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Getting Information about Specially Defined Events
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (int)b data1b0 tab Returns special data associated with the event.
fi-6552 fs16
fs28 fi-6552 {f3 -} (int)b data2b0 tab Returns special data associated with the event.
fi-6552 fs16
fs28 fi-6552 {f3 -} (short)b subtypeb0 tab Returns the identifier of the specially defined event.
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.