Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/AppKit.framework |
Availability | Available in Mac OS X v10.3 and later. |
Companion guide | |
Declared in | NSSegmentedControl.h |
Related sample code |
An NSSegmentedControl
object implements a horizontal button made of multiple segments.
The NSSegmentedControl
class uses an NSSegmentedCell
class to implement much of the control's functionality. Most methods in NSSegmentedControl
are simply "cover methods” that call the corresponding method in NSSegmentedCell
. The methods of NSSegmentedCell
that do not have covers relate to accessing and setting values for tags and tool tips; programatically setting the key segment; and establishing the mode of the control.
The features of a segmented control include:
Each segment can have an image, text (label), menu, tooltip, and tag
Either the whole control or individual segments can be enabled or disabled
There are three tracking modes for segments: select one mode (also known as radio button mode and illustrated by Finder’s view mode selection control), momentary mode (as illustrated by Safari’s toolbar buttons), or select any mode (where any combination of buttons may be on or off)
Each segment can be either a fixed width or autosized to fit the contents
If a segment has text and is marked as autosizing, then the text may be truncated so that the control completely fits
If an image is too large to fit in a segment, it is clipped
Full keyboard control of the user interface
– setWidth:forSegment:
– widthForSegment:
– setImage:forSegment:
– imageForSegment:
– setLabel:forSegment:
– labelForSegment:
– setMenu:forSegment:
– menuForSegment:
– setSelected:forSegment:
– isSelectedForSegment:
– setEnabled:forSegment:
– isEnabledForSegment:
Returns the image associated with the specified segment.
- (NSImage *)imageForSegment:(NSInteger)segment
The index of the segment whose image you want to get. This method raises an NSRangeException
if the index is out of bounds.
The image associated with the segment; otherwise, nil
.
NSSegmentedControl.h
Returns the scaling mode used to display the specified segment’s image.
- (NSImageScaling)imageScalingForSegment:(NSInteger)segment
The index of the segment whose enabled state you want to get. This method raises an NSRangeException
if the index is out of bounds.
One of the image scaling constants. For a list of possible values, see NSImageScaling
. The default value is NSImageScaleProportionallyDown
.
NSSegmentedControl.h
Returns a Boolean value indicating whether the specified segment is enabled.
- (BOOL)isEnabledForSegment:(NSInteger)segment
The index of the segment whose enabled state you want to get. This method raises an NSRangeException
if the index is out of bounds.
YES
if the segment is enabled; otherwise, NO
.
NSSegmentedControl.h
Returns a Boolean value indicating whether the specified segment is selected.
- (BOOL)isSelectedForSegment:(NSInteger)segment
The index of the segment whose selection state you want to get. This method raises an NSRangeException
if the index is out of bounds.
YES
if the segment is selected; otherwise, NO
.
NSSegmentedControl.h
Returns the label of the specified segment
- (NSString *)labelForSegment:(NSInteger)segment
The index of the segment whose label you want to get. This method raises an NSRangeException
if the index is out of bounds.
The label of the segment. The returned string contains the entire text of the label, even if that text is normally truncated during drawing.
NSSegmentedControl.h
Returns the menu for the specified segment
- (NSMenu *)menuForSegment:(NSInteger)segment
The index of the segment whose menu you want to get. This method raises an NSRangeException
if the index is out of bounds.
The menu associated with the segment; otherwise, nil
.
NSSegmentedControl.h
Returns the number of segments in the receiver.
- (NSInteger)segmentCount
The number of segments.
NSSegmentedControl.h
Returns the visual style used to display the receiver.
- (NSSegmentStyle)segmentStyle
An NSSegmentStyle
value that specifies the visual display used by the receiver. For possible values see “Segmented Control Visual Styles.”
NSSegmentedControl.h
Returns the index of the selected segment of the receiver.
- (NSInteger)selectedSegment
The index of the currently selected segment or -1 if no segment is selected. If the receiver allows multiple selections, this method returns the most recently selected segment.
NSSegmentedControl.h
Selects the segment with the specified tag.
- (BOOL)selectSegmentWithTag:(NSInteger)tag
The tag associated with the desired segment.
YES
if the segment was selected successfully; otherwise, NO
.
Typically, you use Interface Builder to specify the tag for each segment. You may also set this value programmatically using the setTag:forSegment:
method of NSSegmentedCell
.
– setTag:forSegment:
(NSSegmentedCell)NSSegmentedControl.h
Sets the enabled state of the specified segment
- (void)setEnabled:(BOOL)flag forSegment:(NSInteger)segment
YES
to enable the segment; otherwise, NO
to disable it.
The index of the segment you want to enable or disable. This method raises an NSRangeException
if the index is out of bounds.
NSSegmentedControl.h
Sets the image for the specified segment.
- (void)setImage:(NSImage *)image forSegment:(NSInteger)segment
The image to apply to the segment or nil
if you want to clear the existing image. Images are not scaled to fit inside a segment. If the image is larger than the available space, it is clipped.
The index of the segment whose image you want to set. This method raises an NSRangeException
if the index is out of bounds.
NSSegmentedControl.h
Sets the scaling mode used to display the specified segment’s image.
- (void)setImageScaling:(NSImageScaling)scaling forSegment:(NSInteger)segment
One of the image scaling constants. For a list of possible values, see NSImageScaling
.
The index of the segment whose enabled state you want to get. This method raises an NSRangeException
if the index is out of bounds.
NSSegmentedControl.h
Sets the label for the specified segment.
- (void)setLabel:(NSString *)label forSegment:(NSInteger)segment
The label you want to display in the segment. If the width of the string is greater than the width of the segment, the string's text is truncated during drawing.
The index of the segment whose label you want to set. This method raises an NSRangeException
if the index is out of bounds.
NSSegmentedControl.h
Sets the menu for the specified segment.
- (void)setMenu:(NSMenu *)menu forSegment:(NSInteger)segment
The menu you want to add to the segment or nil
to clear the current menu. This menu is displayed when the user clicks and holds the mouse button while the mouse is over the segment.
The index of the segment whose menu you want to set. This method raises an NSRangeException
if the index is out of bounds.
Adding a menu to a segment allows that segment to be used as a pop-up button.
NSSegmentedControl.h
Sets the number of segments in the receiver.
- (void)setSegmentCount:(NSInteger)count
The number of segments the receiver should have. If this value is less than the number of segments currently in the receiver, segments are removed from the right of the control. Similarly, if the number is greater than the current number of segments, the new segments are added on the right. This value must be between 0
and 2049
.
NSSegmentedControl.h
Sets the visual style used to display the receiver.
- (void)setSegmentStyle:(NSSegmentStyle)segmentStyle
An NSSegmentStyle
value that specifies the visual display used by the receiver. For the possible values see “Segmented Control Visual Styles.”
Figure 1 shows the visual styles and their corresponding NSSegmentStyle
constant. The NSSegmentStyleAutomatic
constant will automatically determined based on the type of window in which the control is displayed and the position within the window., and is not shown in the figure.
NSSegmentedControl.h
Sets the selection state of the specified segment.
- (void)setSelected:(BOOL)flag forSegment:(NSInteger)segment
YES
if you want to select the segment; otherwise, NO
.
The index of the segment whose selection state you want to set. This method raises an NSRangeException
if the index is out of bounds.
If the receiver allows only a single selection, this method deselects any other selected segments.
NSSegmentedControl.h
Sets the selected segment of the receiver.
- (void)setSelectedSegment:(NSInteger)selectedSegment
The zero-based index of the desired segment. This method raises an NSRangeException
if the index is out of bounds.
If the receiver allows multiple selections, this method selects the specified segment using setSelected:forSegment:
.
NSSegmentedControl.h
Sets the width of the specified segment.
- (void)setWidth:(CGFloat)width forSegment:(NSInteger)segment
The width of the segment, measured in points. Specify the value 0
if you want the segment to be sized to fit the available space automatically.
The index of the segment whose width you want to set. This method raises an NSRangeException
if the index is out of bounds.
NSSegmentedControl.h
Returns the width of the specified segment.
- (CGFloat)widthForSegment:(NSInteger)segment
The index of the segment whose width you want to get. This method raises an NSRangeException
if the index is out of bounds.
The width of the segment, measured in points, or 0 if the segment is sized to fit the available space automatically.
NSSegmentedControl.h
The following constants specify the visual style used to display the segmented control. They are used by setSegmentStyle:
.
enum { NSSegmentStyleAutomatic = 0, NSSegmentStyleRounded = 1, NSSegmentStyleTexturedRounded = 2, NSSegmentStyleRoundRect = 3, NSSegmentStyleTexturedSquare = 4, NSSegmentStyleCapsule = 5, NSSegmentStyleSmallSquare = 6 }; typedef NSInteger NSSegmentStyle;
NSSegmentStyleAutomatic
The appearance of the segmented control is automatically determined based on the type of window in which the control is displayed and the position within the window.
Available in Mac OS X v10.5 and later.
Declared in NSSegmentedControl.h
.
NSSegmentStyleRounded
The control is displayed using the rounded style. See Figure 1 for examples.
Available in Mac OS X v10.5 and later.
Declared in NSSegmentedControl.h
.
NSSegmentStyleTexturedRounded
The control is displayed using the textured rounded style. See Figure 1 for examples.
Available in Mac OS X v10.5 and later.
Declared in NSSegmentedControl.h
.
NSSegmentStyleRoundRect
The control is displayed using the round rect style. See Figure 1 for examples.
Available in Mac OS X v10.5 and later.
Declared in NSSegmentedControl.h
.
NSSegmentStyleTexturedSquare
The control is displayed using the textured square style. See Figure 1 for examples.
Available in Mac OS X v10.5 and later.
Declared in NSSegmentedControl.h
.
NSSegmentStyleCapsule
The control is displayed using the capsule style. See Figure 1 for examples.
Available in Mac OS X v10.5 and later.
Declared in NSSegmentedControl.h
.
NSSegmentStyleSmallSquare
The control is displayed using the small square style. See Figure 1 for examples.
Available in Mac OS X v10.5 and later.
Declared in NSSegmentedControl.h
.
© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-05-06)