NSSegmentedControl Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.3 and later.
Companion guide
Declared in
NSSegmentedControl.h
Related sample code

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:

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.
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.
See Also
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.

Figure 1  NSSegmentStyle examples
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,
};
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.

Declared in NSSegmentedControl.h.

NSSegmentStyleRounded

The control is displayed using the rounded style. See Figure 1 for examples.

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

Declared in NSSegmentedControl.h.