This is NSControl.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 NSControl
pard s14 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSView : NSResponder : NSObject
fs20
fs28 s7 f0 b fs24 Conforms To:tab b0 fs28 f1 NSCoding (NSResponder)
fi0 NSObject (NSObject)
fs20
fs28 s8 fi-2771 f0 b fs24 Declared In:tab b0 fs28 f1 AppKit/NSControl.h
fs20
fs28 pard s19 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 NSControl is an abstract superclass that provides three fundamental features for implementing user interface devices. First, as a subclass of NSView, NSControl allows the on-screen representation of the device to be drawn. Second, it receives and responds to user-generated events within its bounds by overriding NSResponder'27s b mouseDown:b0 method and providing a position in the responder chain. Third, it implements the b sendAction:to: b0 method to send an action message to the NSControl'27s target object. Subclasses of NSControl defined in the Application Kit are NSBrowser, NSButton (and its subclass NSPopUpButton), NSColorWell, NSMatrix (and its subclass NSForm), NSScroller, NSSlider, and NSTextField.
fs16
fs28 pard s18 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Target and Action
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 Target objects and action methods provide the mechanism by which NSControls interact with other objects in an application. A target is an object that an NSControl has effect over. The target class defines an action method to enable its instances to respond to user input. An action method takes only one argument: the b idb0 of the sender. The sender may be either the NSControl that sends the action message or another object that the target should treat as the sender. When it receives an action message, a target can return messages to the sender requesting additional information about its status. NSControl'27s b sendAction:to:b0 asks the NSApplication object, NSApp, to send an action message to the NSControl'27s target object. The method used for this is NSApplication'27s b sendAction:to:from:b0 . You can also set the target to b nilb0 and allow it to be determined at run time. When the target is b nilb0 , the NSApplication object must look for an appropriate receiver. It conducts its search in a prescribed order, by following the responder chain until it finds an object that can respond to the message:
fs16
fs28 pard s3 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 'b7tab It begins with the first responder in the key window and follows b nextResponderb0 links up the responder chain to the NSWindow object. After the NSWindow object, it tries the NSWindow'27s delegate.
fs16
fs28 'b7tab If the main window is different from the key window, it then starts over with the first responder in the main window and works its way up the main window'27s responder chain to the NSWindow object and its delegate.
fs16
fs28 'b7tab Next, it tries to respond itself. If the NSApplication object can'27t respond, it tries its own delegate. NSApp and its delegate are the receivers of last resort.
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 NSControl provides methods for setting and using the target object and the action method. However, these methods require that an NSControl have an associated subclass of NSCell that provides a target and an action, such as NSActionCell and its subclasses.
fs16
fs28 Target objects and action methods demonstrate the close relationship between NSControls and NSCells. In most cases, a user interface device consists of an instance of an NSControl subclass paired with one or more instances of an NSCell subclass. Each implements specific details of the user interface mechanism. For example, NSControl'27s b mouseDown:b0 method sends a b trackMouse:inRect:ofView:untilMouseUp:b0 message to an NSCell, which handles subsequent mouse and keyboard events; an NSCell sends an NSControl a b sendAction:to:b0 message in response to particular events. NSControl'27s b drawRect:b0 method is implemented by sending a b drawWithFrame:inView:b0 message to the NSCell. As another example, NSControl provides methods for setting and formatting its contents; these methods send corresponding messages to NSCell, which actually owns the contents.
fs16
fs28 See the NSActionCell class specification for more on the implementation of target and action behavior.
fs16
fs28 pard s18 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Changing the NSCell Class
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 Since NSControl uses the NSCell class to implement most of its actual functionality, you can usually implement a unique user interface device by creating a subclass of NSCell rather than NSControl. As an example, let'27s say you want all your application'27s NSSliders to have a type of cell other than the generic NSSliderCell. First, you create a subclass of NSCell, NSActionCell, or NSSliderCell. (Let'27s call it MyCellSubclass.) Then, you can simply invoke NSSlider'27s b setCellClass:b0 class method:
fs16
fs28 pard s6 li1231 fi0 ri1007 ql f2 fs20 [NSSlider setCellClass:[MyCellSubclass class]];
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 All NSSliders created thereafter will use MyCellSubclass, until you call b setCellClass:b0 again.
fs16
fs28 If you want to create generic NSSliders (ones that use NSSliderCell) in the same application as the customized NSSliders that use MyCellSubclass, there are two possible approaches. One is to invoke b setCellClass: b0 as above whenever you'27re about to create a custom NSSlider, resetting the cell class to NSSliderCell afterwards. The other approach is to create a custom subclass of NSSlider that automatically uses MyCellSubclass, as explained below.
fs16
fs28 pard s18 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Creating New NSControls
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 If you create a custom NSControl subclass that uses a custom subclass of NSCell, you should override NSControlb '27s cellClass b0 method:
fs16
fs28 pard s6 li1231 fi0 ri1007 ql f2 fs20 + (Class) cellClass
fi0 {
fi0 return [MyCellSubclass class];
fi0 }
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 NSControl'27s b initWithFrame:b0 method will use the return value of b cellClassb0 to allocate and initialize an NSCell of the correct type.
fs16
fs28 If you want to be able to change the type of cell that your subclass uses (without changing the type that its superclass uses), override b setCellClass:b0 to store the NSCell subclass in a global variable, and modify b cellClass b0 to return that variable:
fs16
fs28 pard s6 li1231 fi0 ri1007 ql f2 fs20
static id myStoredCellClass;
+ setCellClass:classId
fi0 {
fi0 myStoredCellClass = classId;
fi0 }
fi0 + (Class) cellClass
fi0 {
fi0 return (myStoredCellClass ? myStoredCellClass : [MyCellSubclass class]);
fi0 }
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 An NSControl subclass doesn'27t have to use an NSCell subclass to implement itself; NSScroller and NSColorWell are examples of NSControls that don'27t. However, such subclasses have to take care of details that NSCell would otherwise handle. Specifically, they have to override methods designed to work with an NSCell. What'27s more, the lack of an NSCell means you can'27t make use of NSMatrix'd0a subclass of NSControl designed specifically for managing multi-cell arrays such as radio buttons.
fs16
fs28 Override the designated initializer (b initWithFrame:b0 ) if you create a subclass of NSControl that performs its own initialization.
fs16
fs28 pard s19 li100 fi0 ri1007 ql f0 b fs24
fs28 Initializing an NSControl Object
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (id)b initWithFrame:b0 (NSRect)i frameRecti0 tab Initializes a new NSControl object in i frameRecti0 , and attempts to create a corresponding NSCell.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Setting the Control'27s Cell
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (Class)b cellClasstab b0 Returns b nilb0 ; overridden by subclasses.
fi-6552 fs16
fs28 fi-6552 + (void)b setCellClass:b0 (Class)i factoryIdi0 tab Implemented by subclasses to set the NSCell class used.
fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b cellb0 tab Returns the control'27s NSCell.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setCell:b0 (NSCell *)i aCelli0 tab Sets the control'27s NSCell to i aCelli0 .
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Enabling and Disabling the Control
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (BOOL)b isEnabledb0 tab Returns whether the control reacts to mouse events.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setEnabled:b0 (BOOL)i flagi0 tab Sets whether the control reacts to mouse events.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Identifying the Selected Cell
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (id)b selectedCellb0 tab Returns the control'27s selected NSCell.
fi-6552 fs16
fs28 fi-6552 {f3 -} (int)b selectedTagb0 tab Returns the tag of the control'27s selected cell.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Setting the Control'27s Value
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (double)b doubleValueb0 tab Returns the value of the control's selected cell as a b doubleb0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b floatValueb0 tab Returns the value of the control's selected cell as a b floatb0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (int)b intValueb0 tab Returns the value of the control's selected cell as a b intb0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setDoubleValue:b0 (double)i aDoublei0 tab Sets the value of the control's selected cell to i aDoublei0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setFloatValue:b0 (float)i aFloati0 tab Sets the value of the control's selected cell to i aFloati0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setIntValue:b0 (int)i anInti0 tab Sets the value of the control's selected cell to i anInti0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setNeedsDisplayb0 tab Set the NeedsDisplay flag.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setStringValue:b0 (NSString *)i aStringi0 tab Sets the value of the control's selected cell to i aStringi0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b stringValueb0 tab Returns the value of the control's selected cell as an NSString.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Interacting with Other Controls
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b takeDoubleValueFrom:b0 (id)i senderi0 tab Sets the receiving NSControl's selected cell to the value obtained by sending a b doubleValueb0 message toi senderi0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b takeFloatValueFrom:b0 (id)i senderi0 tab Sets the receiving NSControl's selected cell to the value obtained by sending a b floatValueb0 message toi senderi0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b takeIntValueFrom:b0 (id)i senderi0 tab Sets the receiving NSControl's selected cell to the value obtained by sending a b intValueb0 message toi senderi0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b takeStringValueFrom:b0 (id)i senderi0 tab Sets the receiving NSControl's selected cell to the value obtained by sending a b stringValueb0 message toi senderi0 .
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Formatting Text
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSTextAlignment)b alignmentb0 tab Returns the alignment of text in the control'27s cell.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSFont *)b fontb0 tab Returns the Font used to draw text in the control'27s cell.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setAlignment:b0 (NSTextAlignment)i modei0 tab Sets the alignment mode of the text in the control's cell to i modei0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setFont:b0 (NSFont *)i fontObjecti0 tab Sets the Font used to draw text in the control'27s cell to i fontObjecti0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setFloatingPointFormat:b0 (BOOL)i autoRangei0 tab Sets the display format for floating point values in the
s11 li7030 fi-6553 fi-5796 b left:b0 (unsigned)i leftDigitsi0 tab tab control'27s cell
b right:b0 (unsigned)i rightDigitsi0 tab
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Managing the Field Editor
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (BOOL)b abortEditingb0 tab Aborts editing of text displayed by the NSControl.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSText *)b currentEditorb0 tab Returns the object used to edit text in the control.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b validateEditingb0 tab Validates the user'27s changes to editable text.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Resizing the Control
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b calcSizeb0 tab Recalculates internal size information.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b sizeToFitb0 tab Resizes the control to fit its cell.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Displaying the Control and Cell
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b drawCell:b0 (NSCell *)i aCelli0 tab Redraws i aCelli0 if it'27s the control'27s cell.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b drawCellInside:b0 (NSCell *)i aCelli0 tab Redraws i aCelli0 '27s inside if it'27s the control'27s cell.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b selectCell:b0 (NSCell *)i aCelli0 tab Selects i aCelli0 if it'27s the control'27s cell.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b updateCell:b0 (NSCell *)i aCelli0 tab Redisplays i aCelli0 or marks it for redisplay.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b updateCellInside:b0 (NSCell *)i aCelli0 tab Redisplays the inside of i aCelli0 or marks it for redisplay.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Target and Action
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (SEL)b actionb0 tab Returns the NSControl'27s action method.
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b isContinuousb0 tab Returns whether the control'27s NSCell continuously sends its action.
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b sendAction:b0 (SEL)i theActioni0 tab Has the NSApplication object send i theActioni0 to i theTargeti0 .
s11 li7030 fi-6553 fi-5796 b to:b0 (id)i theTargeti0 tab
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (int)b sendActionOn:b0 (int)i maski0 tab Determines when the action is sent while tracking.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setAction:b0 (SEL)i aSelectori0 tab Sets the NSControl'27s action method to i aSelectori0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setContinuous:b0 (BOOL)i flagi0 tab Sets whether the control'27s NSCell continuously sends its action.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setTarget:b0 (id)i anObjecti0 tab Sets the NSControl'27s target object to i anObjecti0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (id)b targetb0 tab Returns the NSControl'27s target object.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Assigning a Tag
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b setTag:b0 (int)i anInti0 tab Sets the tag of the control'27s NSCell to i anInti0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (int)b tagb0 tab Returns the tag of the control'27s NSCell.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Tracking the Mouse
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b mouseDown:b0 (NSEvent *)i theEventi0 tab Invoked when the mouse button goes down while the cursor is within the bounds of the NSControl. This method highlights the NSControl'27s NSCell and sends it a b trackMouse:inRect:ofView:untilMouseUp:b0 message. Whenever the NSCell finishes tracking the mouse (for example, because the cursor has left the cell'27s bounds), the cell is unhighlighted. If the mouse button is still down and the cursor reenters the bounds, the cell is again highlighted and a new b trackMouse:inRect:ofView:untilMouseUp:b0 message is sent. This behavior repeats until the mouse button goes up.
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b ignoresMultiClickb0 tab Indicates whether multiple clicks are ignored.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setIgnoresMultiClickb0 :(BOOL)i flagi0 tab Sets whether multiple clicks are ignored, according to i flagi0 .
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Methods Implemented by the Delegate
fs14
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs2
fs28 NSControl itself doesn'27t have a delegate. These delegate methods are declared in b NSControl.hb0 but are intended for subclasses, such as NSTextField and NSMatrix, that do have delegates and that allow text editing.
fs16
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 {f3 -} (BOOL)b control:b0 (NSControl *)i controli0 tab Sent directly by i controli0 to the delegate; returns YES if the
s11 li7030 fi-6553 fi-5796 b textShouldBeginEditing:b0 (NSText *)i fieldEditori0 tab tab NSControl should be allowed to start editing the text.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b control:b0 (NSControl *)i controli0 tab Sent directly by i controli0 to the delegate; returns YES if the
s11 li7030 fi-6553 fi-5796 b textShouldEndEditing:b0 (NSText *)i fieldEditortab tab i0 tab tab NSControl should be allowed to end its edit session.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b controlTextDidBeginEditing:b0 (NSNotification *)i aNotification
s11 li7030 fi-6553 fi-5796 i0 tab Sent by the default notification center to the delegate; i aNotificationi0 is always NSControlTextDidBeginEditingNotification. If the delegate implements this method, it'27s automatically registered to receive this notification.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b controlTextDidEndEditing:b0 (NSNotification *)i aNotification
s11 li7030 fi-6553 fi-5796 i0 tab Sent by the default notification center to the delegate; i aNotificationi0 is always NSControlTextDidEndEditingNotification. If the delegate implements this method, it'27s automatically registered to receive this notification.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b controlTextDidChange:b0 (NSNotification *)i aNotification
s11 li7030 fi-6553 fi-5796 i0 tab Sent by the default notification center to the delegate; i aNotificationi0 is always NSControlTextDidChangeNotification. If the delegate implements this method, it'27s automatically registered to receive this notification.
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.