initCopyright ©1995 by NeXT Computer, Inc. All Rights Reserved.
| Button |
| Inherits From: | Control : View : Responder : Object | |
| Declared In: | appkit/Button.h |
| Class Description |
| Button is a subclass of Control that intercepts mouse-down events and sends an action message to a target object when it's clicked or pressed. By virtue of its ButtonCell, Button is a two-state Control--it's either "off" or "on"--and it displays its state depending on the configuration of the ButtonCell. Button acquires other attributes of ButtonCell. The state is used as the value, so Control methods like setIntValue: actually set the state (the methods setState: and state are provided for more conceptually accurate setting of the state). The Button can send its action continuously and display highlighting in several different ways. What's more, a Button can have a key equivalent that's eligible for triggering whenever the Button's Panel or Window is key.
Button and Matrix both provide a Control View needed to display a ButtonCell object. However, while Matrix requires you to access the ButtonCells directly, most of Button's methods are covers for identically declared methods in ButtonCell. The only ButtonCell methods that don't have covers relate to the font used to display the key equivalent, and to specific methods for highlighting or showing the Button's state (these last are usually set together with Button's setType: method).
Creating a Subclass of Button The initFrame:icon:tag:target:action:key:enabled: method is the designated initializer for Buttons that initially display only icons. Buttons that initially display only text have the designated initializer initFrame:text:tag:target:action:key:enabled:. Override one or both of these methods if you create a subclass of Button that performs its own initialization. In particular, if you want to use a custom ButtonCell subclass with your subclass of Button, you have to override the setCellClass: method as well as the designated initializers, as described in "Creating New Controls" in the Control class specification. See the ButtonCell class specification for more on Button's behavior. |
| Instance Variables |
| None declared in this class. |
| Method Types |
| Setting Button's Cell class | + setCellClass: | |
| Initializing a Button | init |
| initFrame: initFrame:icon:tag:target:action:key:enabled: initFrame:title:tag:target:action:key:enabled: |
| Setting the Button type | setType: | |
| Setting the state | setState: |
| state |
| Setting the repeat interval | setPeriodicDelay:andInterval: |
| getPeriodicDelay:andInterval: |
| Setting the titles | setTitle: |
| setTitleNoCopy: title setAltTitle: altTitle |
| Setting the icons | setIcon: |
| setIcon:position: icon setAltIcon: altIcon setImage: image setAltImage: altImage setIconPosition: iconPosition |
| Modifying graphic attributes | setTransparent: |
| isTransparent setBordered: isBordered |
| Displaying the Button | display |
| highlight: |
| Setting the key equivalent | setKeyEquivalent: |
| keyEquivalent |
| Handling events and action messages |
| acceptsFirstMouse performClick: performKeyEquivalent: |
| Setting the Sound | setSound: |
| sound |
| Class Methods |
| setCellClass: |
| + setCellClass:classId |
| Configures the Button class to use instances of classId for its Cells. classId should be the id of a subclass of ButtonCell, obtained by sending the class message to either the Cell subclass object or to an instance of that subclass. The default Cell class is ButtonCell. Returns self.
If this method isn't overridden by a subclass of Button, then when it's sent to that subclass, Button and any other subclasses of Button that don't override the methods mentioned below will use the new Cell subclass as well. To safely set a Cell class for your subclass of Button, override this method to store the Cell class in a static id. Also, override the designated initializer to replace the Button subclass instance's Cell with an instance of the Cell subclass stored in that static id. See "Creating New Controls" in the Control class specification's class description for more information. |
| Instance Methods |
| acceptsFirstMouse |
| (BOOL)acceptsFirstMouse |
| Returns YES. Buttons always accept the mouse-down event that activates a Window, regardless of whether the Button is enabled. |
| altIcon |
| (const char *)altIcon |
| Returns the name of the NXImage that appears on the Button when it's in its alternate state, or NULL if there is no alternate icon or the NXImage has no name. This NXImage is displayed only for Buttons that highlight or show their alternate state by displaying their alternate contents (as opposed to simply lighting or pushing in).
See also: |
| altImage |
| altImage |
| Returns the NXImage that appears on the Button when it's in its alternate state, or nil if there is no alternate NXImage. This Button only displays its alternate NXImage if it highlights or shows its alternate state by displaying its alternate contents.
See also: |
| altTitle |
| (const char *)altTitle |
| Returns the string that appears on the Button when it's in its alternate state, or NULL if there isn't one. The alternate title is only displayed if the Button highlights or shows its alternate state by displaying its alternate contents.
See also: |
| display |
| display |
| Displays the Button. This method is overridden from View so that displayFromOpaqueAncestor::: is invoked if the Button is not opaque. Returns self.
See also: |
| getPeriodicDelay:andInterval: |
| getPeriodicDelay:(float *)delay andInterval:(float *)interval |
| Returns self, and by reference the delay and interval periods for a continuous Button. delay is the amount of time (in seconds) that a continuous Button will pause before starting to periodically send action messages to the target object. interval is the amount of time (also in seconds) between those messages.
See also: |
| highlight: |
| highlight:(BOOL)flag |
| If the highlight state of the cell is not equal to flag, the Button is highlighted and the highlight state of the cell is set to flag. Highlighting may involve the Button appearing "pushed in" to the screen, displaying its alternate title or icon, or lighting. This method issues a flushWindow message after highlighting the Button. Returns self.
See also: |
| icon |
| (const char *)icon |
| Returns the name of the NXImage that appears on the Button when it's in its normal state, or NULL if there is no such NXImage or the NXImage doesn't have a name. A Button that doesn't display its alternate contents to highlight or show its alternate state will always display its normal icon.
See also: |
| iconPosition |
| (int)iconPosition |
| Returns the position of the icon (if any) on the Button. See setIconPosition: for the list of positions.
See also: |
| image |
| image |
| Returns the NXImage that appears on the Button when it's in its normal state, or nil if there is no such NXImage. This NXImage is always displayed on a Button that doesn't change its contents when highlighting or showing its alternate state.
See also: |
| init |
| init |
| Initializes and returns the receiver, a new Button instance, with a frame origin of (0, 0) and width and height of 50 units each. The new instance is enabled and displays the default title "Button" centered in its frame, but has no icon, tag, target, action, or key equivalent associated with it. The new Button is bordered, and is of type NX_MOMENTARYPUSH. One of the more specific initializers is usually used to initialize a Button.
See also: |
| initFrame: |
| initFrame:(const NXRect *)frameRect |
| Initializes and returns the receiver, a new Button instance, with default parameters in the given frame. The new instance is enabled and displays the default title "Button" centered in its frame, but has no icon, tag, target, action, or key equivalent. The new Button is bordered, and is of type NX_MOMENTARYPUSH. One of the more specific initializers is usually used to initialize a Button.
See also: |
| initFrame:icon:tag:target:action:key:enabled: |
| initFrame:(const NXRect *)frameRect |
| icon:(const char *)iconName tag:(int)anInt target:anObject action:(SEL)aSelector key:(unsigned short)charCode enabled:(BOOL)flag |
| Initializes and returns the receiver, a new Button instance that displays an icon. frameRect is the rectangle defining the Button's position and size in its superview. iconName is the name of an NXImage that will be used for the Button's icon. anInt is set as the Button's tag. anObject is set as the target, which will be sent aSelector when the Button is clicked or pressed. charCode is the new Button's key equivalent. flag determines whether the Button is enabled or not. The new Button is bordered, and is of type NX_MOMENTARYPUSH.
This method is the designated initializer for Buttons that display icons. A Button that displays an icon can be configured to also display a title with the setTitle: and setIconPosition: methods. See also: |
| initFrame:title:tag:target:action:key:enabled: |
| initFrame:(const NXRect *)frameRect |
| title:(const char *)aString tag:(int)anInt target:anObject action:(SEL)aSelector key:(unsigned short)charCode enabled:(BOOL)flag |
| Initializes and returns the receiver, a new Button instance that displays a text string. The arguments and operation of this method are identical to those of initFrame:icon:tag:target:action:key:enabled:, except that aString is the title that the Button will display instead of the name of an icon. The new Button is bordered, and is of type NX_MOMENTARYPUSH.
This method is the designated initializer for Buttons that display text. A Button that displays an icon can be configured to also display an icon with the setIcon:position: method, or a combination of setIcon: or setImage: and setIconPosition:. See also: |
| isBordered |
| (BOOL)isBordered |
| Returns YES if the Button has a border, NO otherwise. A Button's border isn't the single line of most other Controls' borders; instead, it's a raised bezel ("bezel" usually refers to a depressed bezel, as seen on FormCells, for example). You shouldn't use the setBezeled: method with a Button.
See also: |
| isTransparent |
| (BOOL)isTransparent |
| Returns YES if the Button is transparent, NO otherwise. A transparent Button never draws itself, but it receives mouse-down events and tracks the mouse properly.
See also: |
| keyEquivalent |
| (unsigned short)keyEquivalent |
| Returns the key equivalent character of the Button, or 0 if one hasn't been defined.
See also: |
| performClick: |
| performClick:sender |
| Highlights the Button, sends its action message to the target object, then unhighlights the Button. Invoke this method when you want the Button to behave exactly as if the user had clicked it with the mouse.
See also: |
| performKeyEquivalent: |
| (BOOL)performKeyEquivalent:(NXEvent *)theEvent |
| If the character in theEvent matches the Button's key equivalent, simulates the user clicking the Button by sending performClick: to self, and returns YES. Otherwise, does nothing and returns NO.
The Button won't perform the key equivalent if there's a modal panel present that the Button isn't on. See also: |
| setAltIcon: |
| setAltIcon:(const char *)iconName |
| Sets the Button's alternate icon by name; iconName is the name of the NXImage to be displayed. Doesn't display the Button even if autodisplay is on. Returns self.
A Button's alternate icon is only displayed if the Button highlights or shows its alternate state by changing its contents. See also: |
| setAltImage: |
| setAltImage:altImage |
| Sets the Button's alternate icon by id; altImage is the NXImage to be displayed. Returns self.
A Button displays its alternate NXImage only if it highlights or displays its alternate state by using its alternate contents. See also: |
| setAltTitle: |
| setAltTitle:(const char *)aString |
| Sets the title that the Button displays in its alternate state to aString. Returns self.
The alternate title is shown only if the Button changes its contents when highlighting or displaying its alternate state. See also: |
| setBordered: |
| setBordered:(BOOL)flag |
| If flag is YES, the Button displays a border; if NO, the Button doesn't display a border. A Button's border is not the single line or most other Controls' borders; instead, it's a raised bezel ("bezel" usually refers to a depressed bezel, as seen on FormCells, for example). This method redraws the Button if the bordered state changes. Returns self.
See also: |
| setIcon: |
| setIcon:(const char *)iconName |
| Sets the Button's icon by name; iconName is the name of the NXImage to be displayed. Redraws the Button's inside and returns self.
A Button's icon is displayed when the Button is in its normal state, or always if the Button doesn't highlight or show state by changing its contents. See also: |
| setIcon:position: |
| setIcon:(const char *)iconName position:(int)aPosition |
| Combines setIcon: and setIconPosition: into one message. Returns self.
See also: |
| setIconPosition: |
| setIconPosition:(int)aPosition |
| Sets the position of the icon when a Button simultaneously displays both text and an icon. aPosition can be one of the following constants: |
| NX_TITLEONLY | title only (no icon on the Button) | |
| NX_ICONONLY | icon only (no text on the Button) | |
| NX_ICONLEFT | icon is to the left of the text | |
| NX_ICONRIGHT | icon is to the right of the text | |
| NX_ICONBELOW | icon is below the text | |
| NX_ICONABOVE | icon is above the text | |
| NX_ICONOVERLAPS | icon and text overlap (text drawn over icon) |
| If the position is top or bottom, the alignment of the text will be changed to NX_CENTERED. This behavior can be overridden with a subsequent setAlignment: method. Redraws the Button's inside and returns self.
See also: |
| setImage: |
| setImage:image |
| Sets the Button's icon by id; image is the NXImage to be displayed. Redraws the Button's inside and returns self.
A Button's icon is displayed when the Button is in its normal state, or all the time for a Button that doesn't change its contents when highlighting or displaying its alternate state. See also: |
| setKeyEquivalent: |
| setKeyEquivalent:(unsigned short)charCode |
| Sets the key equivalent character of the Button, and redraws the Button's inside if there is no icon or alternate icon set for the Button. The key equivalent isn't displayed if the icon position is set to NX_TITLEONLY, NX_ICONONLY or NX_ICONOVERLAPS; that is, the Button must display both its title and its "icon" (the key equivalent in this case), and they must not overlap. Returns self.
To display a key equivalent on a Button, set the image and alternate image to nil, then set the key equivalent, and then set the icon position. See also: |
| setPeriodicDelay:andInterval: |
| setPeriodicDelay:(float)delay andInterval:(float)interval |
| Sets the message delay and interval for the Button. These two values are used if the Button is configured (by a setContinuous: message) to continuously send the action message to the target object while tracking the mouse. delay is the amount of time (in seconds) that a continuous Button will pause before starting to periodically send action messages to the target object. interval is the amount of time (also in seconds) between those messages. Returns self.
The maximum value allowed for both the delay and the interval is 60.0 seconds. See also: |
| setSound: |
| setSound:soundObject |
| Sets the Sound played when the Button is pressed, and whenever the cursor re-enters the Button while tracking. Returns self.
See also: |
| setState: |
| setState:(int)anInt |
| Sets the Button's state to anInt and redraws the Button. 0 is the normal or "off" state, and any nonzero number is the alternate or "on" state. Returns self.
See also: |
| setTitle: |
| setTitle:(const char *)aString |
| Sets the title displayed by the Button when in its normal state to aString. This title is always shown on Buttons that don't use their alternate contents when highighting or displaying their alternate state. Redraws the Button's inside and returns self.
See also: |
| setTitleNoCopy: |
| setTitleNoCopy:(const char *)aString |
| Similar to setTitle: but doesn't make a copy of aString. Returns self.
See also: |
| setTransparent: |
| setTransparent:(BOOL)flag |
| Sets whether the Button is transparent, and redraws the Button if flag is NO. Returns self.
A transparent Button tracks the mouse and sends its action, but doesn't draw. A transparent Button is useful for sensitizing an area on the screen so that an action gets sent to a target when the area receives a mouse click. See also: |
| setType: |
| setType:(int)aType |
| Sets the way the Button highlights while pressed, and how it shows its state. Redraws the Button and returns self. The types available are for the most common Button types, which are also accessible in Interface Builder; you can configure different behavior with ButtonCell's setHighlightsBy: and setShowsStateBy: methods. aType can be one of seven constants: |
| NX_MOMENTARYPUSH (the default): While the Button is held down it's shown as lit, and also "pushed in" to the screen if the Button is bordered. This type of Button is best for simply triggering actions, as it doesn't show its state; it always displays its normal icon or title. This option is called "Momentary Push" in Interface Builder's Button Inspector.
NX_MOMENTARYCHANGE: While the Button is pressed, the alternate icon or alternate title is displayed. This type always displays its normal title or icon (that is, it doesn't display its state). The miniaturize button in a window's title bar is a good example of this type of Button. This option is called "Momentary Change" in Interface Builder's Button Inspector. NX_PUSHONPUSHOFF: Holding the Button down causes it to be shown as lit, and also "pushed in" to the screen if the Button is bordered. The Button displays itself as lit while in its alternate state. This option is called "Push On/Push Off" in Interface Builder's Button Inspector. NX_ONOFF: Highlights while pressed by lighting, and stays lit in its alternate state. This option is called "On/Off" in Interface Builder's Button Inspector. NX_TOGGLE: Highlighting is performed by changing to the alternate title or icon "pushing in." The alternate state is shown by displaying the alternate title or icon. This option is called "Toggle" in Interface Builder's Button Inspector. NX_SWITCH: A variant of NX_TOGGLE that has no border, and that has a default icon called "switch" and an alternate icon called "switchH" (these are identical to the "NXswitch" and "NXswitchH" system bitmaps). This type of Button is available as a separate palette item in Interface Builder. NX_RADIOBUTTON: Like NX_SWITCH, but the default icon is "radio" and the alternate icon is "radioH" (identical to the "NXradio" and "NXradioH" system bitmaps). This type of Button is available as a separate palette item in Interface Builder. |
| There is no constant for Interface Builder's "Momentary Light" type; you can set this programmatically as follows: |
[[myButton cell] setHighlightsBy:NX_CHANGEGRAY | NX_CHANGEBACKGROUND];
[[myButton cell] setShowsStateBy:NX_NONE];
| See also: setType: (ButtonCell), setHighlightsBy: (ButtonCell), setShowsStateBy: (ButtonCell) |
| sound |
| sound |
| Returns the Sound played when the Button is pressed, and whenever the cursor re-enters the Button while tracking.
See also: |
| state |
| (int)state |
| Returns the Button's state, either 0 for normal or "off," or 1 for alternate or "on."
See also: |
| title |
| (const char *)title |
| Returns the title displayed on the Button when it's in its normal state, or always if the Button doesn't use its alternate contents for highlighting or displaying the alternate state. Returns NULL if there is no title.
See also: |