---

NSSegmentedCell Class Reference

Overview

The NSSegmentedCell class implements the appearance and behavior of a horizontal button divided into multiple segments. This class is used in conjunction with the NSSegmentedControl class to implement a segmented control.

You can customize the attributes of a segmented control using the methods of NSSegmentedCell. To customize the appearance of individual segments, you can also subclass and override the drawSegment:inFrame:withView: method.

Tasks

Specifying the Number of Segments

• – setSegmentCount:
• – segmentCount

Specifying the Selected Segment

• – setSelectedSegment:
• – setSelected:forSegment:
• – selectSegmentWithTag:
• – makeNextSegmentKey
• – makePreviousSegmentKey
• – selectedSegment
• – isSelectedForSegment:

Specifying the Tracking Mode

• – setTrackingMode:
• – trackingMode

Configuring Individual Segments

• – setLabel:forSegment:
• – labelForSegment:
• – setImage:forSegment:
• – imageForSegment:
• – setImageScaling:forSegment:
• – imageScalingForSegment:
• – setWidth:forSegment:
• – widthForSegment:
• – setEnabled:forSegment:
• – isEnabledForSegment:
• – setMenu:forSegment:
• – menuForSegment:
• – setToolTip:forSegment:
• – toolTipForSegment:
• – setTag:forSegment:
• – tagForSegment:

Drawing Custom Content

• – drawSegment:inFrame:withView:

Specifying Segment Visual Styles

• – interiorBackgroundStyleForSegment:
• – segmentStyle
• – setSegmentStyle:

Instance Methods

drawSegment:inFrame:withView:

Draws the segment in the specified view.

- (void)drawSegment:(NSInteger)segment inFrame:(NSRect)frame withView:(NSView *)controlView

Parameters

segment

The index of the segment to draw. This method raises an NSRangeException if the index is out of bounds.

frame

The rectangle in which to draw the segment. This rectangle is specified in user space coordinates of the specified view.

controlView

The view in which to draw the segment.

Discussion

You can override this method to provide a custom appearance for segmented controls. You should not call this method directly. It is called for you automatically by the control when it needs to be redrawn.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – drawWithFrame:inView: (NSCell)

Declared In

NSSegmentedCell.h

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.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setImage:forSegment:

Declared In

NSSegmentedCell.h

imageScalingForSegment:

Returns the image scaling mode associated with the specified segment.

- (NSImageScaling)imageScalingForSegment:(NSInteger)segment

Parameters

segment

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

Return Value

The scaling mode in use for the specified segment. For the possible values see Segmented Control Visual Styles. If no value has been explicitly set NSImageScaleProportionallyDown is returned.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setImageScaling:forSegment:

Declared In

NSSegmentedCell.h

interiorBackgroundStyleForSegment:

Returns the interior background style for the specified segment.

- (NSBackgroundStyle)interiorBackgroundStyleForSegment:(NSInteger)segment

Parameters

segment

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

Return Value

The background style to use for specified segment See Background Styles in NSCell for possible values.

Discussion

The interior background style describes the surface drawn onto in drawInteriorWithFrame:inView:.

This is both an override point and a useful method to call. In a custom segment cell with a custom bezel you can override this method to describe the surface on a per-segment basis.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – setEnabled:forSegment:

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – setSelected:forSegment:

Declared In

NSSegmentedCell.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.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setLabel:forSegment:

Declared In

NSSegmentedCell.h

makeNextSegmentKey

Selects the next segment.

- (void)makeNextSegmentKey

Discussion

The next segment is the one to the right of the currently selected segment. For the last segment, the selection wraps back to the beginning of the control.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – makePreviousSegmentKey

Declared In

NSSegmentedCell.h

makePreviousSegmentKey

Selects the previous segment.

- (void)makePreviousSegmentKey

Discussion

The previous segment is the one to the left of the currently selected segment. For the first segment, the selection wraps around to the last segment of the control.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – makeNextSegmentKey

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – setMenu:forSegment:

Declared In

NSSegmentedCell.h

segmentCount

Returns the number of segments in the receiver.

- (NSInteger)segmentCount

Return Value

The number of segments in the receiver.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setSegmentCount:

Declared In

NSSegmentedCell.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 “Segmented Control Visual Styles” in NSSegmentedControl Class Reference.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – setSelectedSegment:

Declared In

NSSegmentedCell.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.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setTag:forSegment:

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – isEnabledForSegment:

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – imageForSegment:

Declared In

NSSegmentedCell.h

setImageScaling:forSegment:

Sets the image scaling mode for the specified segment.

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

Parameters

scaling

The scaling mode to assign to the specified segment. For the possible values see Segmented Control Visual Styles.

segment

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

Discussion

The image scaling mode for a segment affects how the image inside the corresponding cell is positioned and resized when the cell itself grows or shrinks. The image scaling mode does not itself cause the cell to change size in any way. If a cell does not contain an image, the scaling mode has no effect.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – imageScalingForSegment:

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – labelForSegment:

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – menuForSegment:

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – segmentCount

Declared In

NSSegmentedCell.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 possible values see “Segmented Control Visual Styles” in NSSegmentedControl Class Reference in NSSegmentedControl Class Reference.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – isSelectedForSegment:

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – selectedSegment

Declared In

NSSegmentedCell.h

setTag:forSegment:

Sets the tag for the specified segment.

- (void)setTag:(NSInteger)tag forSegment:(NSInteger)segment

Parameters

tag

The tag of the segment.

segment

The index of the segment whose tool tag you want to set. This method raises an NSRangeException if the index is out of bounds.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – tagForSegment:

Declared In

NSSegmentedCell.h

setToolTip:forSegment:

Sets the tool tip for the specified segment.

- (void)setToolTip:(NSString *)toolTip forSegment:(NSInteger)segment

Parameters

toolTip

The text of the tool tip you want to display for the segment.

segment

The index of the segment whose tool tip you want to set. This method raises an NSRangeException if the index is out of bounds.

Discussion

Tool tips are currently not displayed.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – toolTipForSegment:

Declared In

NSSegmentedCell.h

setTrackingMode:

Sets the tracking mode for the receiver.

- (void)setTrackingMode:(NSSegmentSwitchTracking)trackingMode

Parameters

trackingMode

The tracking mode to use for the segments. Possible values for trackingMode are described in NSSegmentSwitchTracking.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – trackingMode

Declared In

NSSegmentedCell.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 Mac OS X v10.3 and later.

See Also

• – widthForSegment:

Declared In

NSSegmentedCell.h

tagForSegment:

Returns the tag of the specified segment.

- (NSInteger)tagForSegment:(NSInteger)segment

Parameters

segment

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

Return Value

The tag of the segment.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setTag:forSegment:

Declared In

NSSegmentedCell.h

toolTipForSegment:

Returns the tool tip of the specified segment.

- (NSString *)toolTipForSegment:(NSInteger)segment

Parameters

segment

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

Return Value

The text of the tool tip.

Discussion

Tool tips are currently not displayed.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setToolTip:forSegment:

Declared In

NSSegmentedCell.h

trackingMode

Returns the tracking mode of the receiver.

- (NSSegmentSwitchTracking)trackingMode

Return Value

The tracking mode used for the segments Possible values for trackingMode are described in NSSegmentSwitchTracking.The default value is NSSegmentSwitchTrackingSelectOne.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setTrackingMode:

Declared In

NSSegmentedCell.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.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setWidth:forSegment:

Declared In

NSSegmentedCell.h

Constants

NSSegmentSwitchTracking

An NSSegmentedCell object uses the following constants, which describe the various tracking modes for a cell. You access these values using setTrackingMode: and trackingMode methods of the class.

typedef enum {
   NSSegmentSwitchTrackingSelectOne = 0,
   NSSegmentSwitchTrackingSelectAny = 1,
   NSSegmentSwitchTrackingMomentary = 2
} NSSegmentSwitchTracking;

Constants

NSSegmentSwitchTrackingSelectOne

Only one segment may be selected.

Available in Mac OS X v10.3 and later.

Declared in NSSegmentedCell.h.

NSSegmentSwitchTrackingSelectAny

Any segment can be selected.

Available in Mac OS X v10.3 and later.

Declared in NSSegmentedCell.h.

NSSegmentSwitchTrackingMomentary

A segment is selected only when tracking.

Available in Mac OS X v10.3 and later.

Declared in NSSegmentedCell.h.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSSegmentedCell.h

---