NSSegmentedControl Class Reference

Inherits from	NSControl : NSView : NSResponder : NSObject
Conforms to	NSAnimatablePropertyContainer (NSView) NSUserInterfaceItemIdentification (NSView) NSDraggingDestination (NSView) NSCoding (NSResponder) NSObject (NSObject)
Framework	/System/Library/Frameworks/AppKit.framework
Availability	Available in OS X v10.3 and later.
Companion guide	Segmented Control Programming Guide
Declared in	NSSegmentedControl.h
Related sample code	ButtonMadness ClipboardViewer ImageMap ImageMapExample PDF Annotation Editor

Overview

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

Tasks

Specifying Number of Segments

Specifying Selected Segment

Working with Individual Segments

Specifying Segment Display

Instance Methods

imageForSegment:

Returns the image associated with the specified segment.

- (NSImage *)imageForSegment:(NSInteger)segment

Parameters

segment: The index of the segment whose image you want to get. This method raises an NSRangeException if the index is out of bounds.

Return Value

The image associated with the segment; otherwise, nil.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

imageScalingForSegment:

Returns the scaling mode used to display the specified segment’s image.

- (NSImageScaling)imageScalingForSegment:(NSInteger)segment

Parameters

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.

Return Value

One of the image scaling constants. For a list of possible values, see NSImageScaling. The default value is NSImageScaleProportionallyDown.

Availability

Available in OS X v10.5 and later.

Declared In

NSSegmentedControl.h

isEnabledForSegment:

Returns a Boolean value indicating whether the specified segment is enabled.

- (BOOL)isEnabledForSegment:(NSInteger)segment

Parameters

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.

Return Value

YES if the segment is enabled; otherwise, NO.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

isSelectedForSegment:

Returns a Boolean value indicating whether the specified segment is selected.

- (BOOL)isSelectedForSegment:(NSInteger)segment

Parameters

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.

Return Value

YES if the segment is selected; otherwise, NO.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

labelForSegment:

Returns the label of the specified segment

- (NSString *)labelForSegment:(NSInteger)segment

Parameters

segment: The index of the segment whose label you want to get. This method raises an NSRangeException if the index is out of bounds.

Return Value

The label of the segment. The returned string contains the entire text of the label, even if that text is normally truncated during drawing.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

menuForSegment:

Returns the menu for the specified segment

- (NSMenu *)menuForSegment:(NSInteger)segment

Parameters

segment: The index of the segment whose menu you want to get. This method raises an NSRangeException if the index is out of bounds.

Return Value

The menu associated with the segment; otherwise, nil.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

segmentCount

Returns the number of segments in the receiver.

- (NSInteger)segmentCount

Return Value

The number of segments.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

segmentStyle

Returns the visual style used to display the receiver.

- (NSSegmentStyle)segmentStyle

Return Value

An NSSegmentStyle value that specifies the visual display used by the receiver. For possible values see “NSSegmentStyle.”

Availability

Available in OS X v10.5 and later.

Declared In

NSSegmentedControl.h

selectedSegment

Returns the index of the selected segment of the receiver.

- (NSInteger)selectedSegment

Return Value

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.

Availability

Available in OS X v10.3 and later.

Related Sample Code

Declared In

NSSegmentedControl.h

selectSegmentWithTag:

Selects the segment with the specified tag.

- (BOOL)selectSegmentWithTag:(NSInteger)tag

Parameters

tag: The tag associated with the desired segment.

Return Value

YES if the segment was selected successfully; otherwise, NO.

Discussion

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.

Availability

Available in OS X v10.4 and later.

Declared In

NSSegmentedControl.h

setEnabled:forSegment:

Sets the enabled state of the specified segment

- (void)setEnabled:(BOOL)flag forSegment:(NSInteger)segment

Parameters

flag: YES to enable the segment; otherwise, NO to disable it.
segment: The index of the segment you want to enable or disable. This method raises an NSRangeException if the index is out of bounds.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

setImage:forSegment:

Sets the image for the specified segment.

- (void)setImage:(NSImage *)image forSegment:(NSInteger)segment

Parameters

image: 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.
segment: The index of the segment whose image you want to set. This method raises an NSRangeException if the index is out of bounds.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

setImageScaling:forSegment:

Sets the scaling mode used to display the specified segment’s image.

- (void)setImageScaling:(NSImageScaling)scaling forSegment:(NSInteger)segment

Parameters

scaling: One of the image scaling constants. For a list of possible values, see NSImageScaling.
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.

Availability

Available in OS X v10.5 and later.

Declared In

NSSegmentedControl.h

setLabel:forSegment:

Sets the label for the specified segment.

- (void)setLabel:(NSString *)label forSegment:(NSInteger)segment

Parameters

label: 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.
segment: The index of the segment whose label you want to set. This method raises an NSRangeException if the index is out of bounds.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

setMenu:forSegment:

Sets the menu for the specified segment.

- (void)setMenu:(NSMenu *)menu forSegment:(NSInteger)segment

Parameters

menu: 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.
segment: The index of the segment whose menu you want to set. This method raises an NSRangeException if the index is out of bounds.

Discussion

Adding a menu to a segment allows that segment to be used as a pop-up button.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

setSegmentCount:

Sets the number of segments in the receiver.

- (void)setSegmentCount:(NSInteger)count

Parameters

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.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

setSegmentStyle:

Sets the visual style used to display the receiver.

- (void)setSegmentStyle:(NSSegmentStyle)segmentStyle

Parameters

segmentStyle: An NSSegmentStyle value that specifies the visual display used by the receiver. For the possible values see “NSSegmentStyle.”

Discussion

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.

Availability

Available in OS X v10.5 and later.

Declared In

NSSegmentedControl.h

setSelected:forSegment:

Sets the selection state of the specified segment.

- (void)setSelected:(BOOL)flag forSegment:(NSInteger)segment

Parameters

flag: YES if you want to select the segment; otherwise, NO.
segment: The index of the segment whose selection state you want to set. This method raises an NSRangeException if the index is out of bounds.

Discussion

If the receiver allows only a single selection, this method deselects any other selected segments.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

setSelectedSegment:

Sets the selected segment of the receiver.

- (void)setSelectedSegment:(NSInteger)selectedSegment

Parameters

selectedSegment: The zero-based index of the desired segment. This method raises an NSRangeException if the index is out of bounds.

Discussion

If the receiver allows multiple selections, this method selects the specified segment using setSelected:forSegment:.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

setWidth:forSegment:

Sets the width of the specified segment.

- (void)setWidth:(CGFloat)width forSegment:(NSInteger)segment

Parameters

width: 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.
segment: The index of the segment whose width you want to set. This method raises an NSRangeException if the index is out of bounds.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

widthForSegment:

Returns the width of the specified segment.

- (CGFloat)widthForSegment:(NSInteger)segment

Parameters

segment: The index of the segment whose width you want to get. This method raises an NSRangeException if the index is out of bounds.

Return Value

The width of the segment, measured in points, or 0 if the segment is sized to fit the available space automatically.

Availability

Available in OS X v10.3 and later.

Declared In

NSSegmentedControl.h

Constants

NSSegmentStyle

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,
   NSSegmentStyleSlider = 7,
};
typedef NSInteger NSSegmentStyle;

Constants

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 OS X v10.5 and later.