UISegmentedControl Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UISegmentedControl.h
Related sample code

Overview

A UISegmentedControl object is a horizontal control made of multiple segments, each segment functioning as a discrete button. A segmented control affords a compact means to group together a number of controls.

A segmented control can display a title (an NSString object) or an image (UIImage object). The UISegmentedControl object automatically resizes segments to fit proportionally within their superview unless they have a specific width set. When you add and remove segments, you can request that the action be animated with sliding and fading effects.

You register the target-action methods for a segmented control using the UIControlEventValueChanged constant as shown below.

[segmentedControl addTarget:self
                     action:@selector(action:)
           forControlEvents:UIControlEventValueChanged];

How you configure a segmented control can affect its display behavior:

Customizing Appearance

In iOS v5.0 and later, you can customize the appearance of segmented controls using the methods listed in “Customizing Appearance.” You can customize the appearance of all segmented controls using the appearance proxy (for example, [UISegmentedControl appearance]), or just of a single control.

When customizing appearance, in general, you should specify a value for the normal state of a property to be used by other states which don’t have a custom value set. Similarly, when a property is dependent on the bar metrics (on the iPhone in landscape orientation, bars have a different height from standard), you should make sure you specify a value for UIBarMetricsDefault.

In the case of the segmented control, appearance properties for UIBarMetricsLandscapePhone are only respected for segmented controls in the smaller navigation and toolbars that are used in landscape orientation on the iPhone.

To provide complete customization, you need to provide divider images for different state combinations, using setDividerImage:forLeftSegmentState:rightSegmentState:barMetrics::

// Image between two unselected segments.
[mySegmentedControl setDividerImage:image1 forLeftSegmentState:UIControlStateNormal
                  rightSegmentState:UIControlStateNormal barMetrics:barMetrics];
// Image between segment selected on the left and unselected on the right.
[mySegmentedControl setDividerImage:image1 forLeftSegmentState:UIControlStateSelected
                  rightSegmentState:UIControlStateNormal barMetrics:barMetrics];
// Image between segment selected on the right and unselected on the right.
[mySegmentedControl setDividerImage:image1 forLeftSegmentState:UIControlStateNormal
                  rightSegmentState:UIControlStateSelected barMetrics:barMetrics];

Tasks

Initializing a Segmented Control

Managing Segment Content

Managing Segments

Managing Segment Behavior and Appearance

Customizing Appearance

Properties

apportionsSegmentWidthsByContent

Indicates whether the control attempts to adjust segment widths based on their content widths.

@property(nonatomic) BOOL apportionsSegmentWidthsByContent
Discussion

If the value of this property is YES, for segments whose width value is 0, the control attempts to adjust segment widths based on their content widths.

The default is NO.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISegmentedControl.h

momentary

A Boolean value that determines whether segments in the receiver show selected state.

@property(nonatomic, getter=isMomentary) BOOL momentary
Discussion

The default value of this property is NO. If it is set to YES, segments in the control do not show selected state and do not update the value of selectedSegmentIndex after tracking ends.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UISegmentedControl.h

numberOfSegments

Returns the number of segments the receiver has. (read-only)

@property(nonatomic, readonly) NSUInteger numberOfSegments
Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

selectedSegmentIndex

The index number identifying the selected segment (that is, the last segment touched).

@property(nonatomic) NSInteger selectedSegmentIndex
Discussion

The default value is UISegmentedControlNoSegment (no segment selected) until the user touches a segment. Set this property to -1 to turn off the current selection. UISegmentedControl ignores this property when the control is in momentary mode. When the user touches a segment to change the selection, the control event UIControlEventValueChanged is generated; if the segmented control is set up to respond to this control event, it sends a action message to its target.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

tintColor

The tint color of the segmented control.

@property(nonatomic, retain) UIColor *tintColor
Discussion

The default value of this property is nil (no color). UISegmentedControl uses this property only if the style of the segmented control is UISegmentedControlStyleBar.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

Instance Methods

backgroundImageForState:barMetrics:

Returns the background image for a given state and bar metrics.

- (UIImage *)backgroundImageForState:(UIControlState)state barMetrics:(UIBarMetrics)barMetrics
Parameters
state

A control state.

barMetrics

Bar metrics.

Return Value

The background image for state and barMetrics.

Discussion

For more details, see setBackgroundImage:forState:barMetrics:.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISegmentedControl.h

contentOffsetForSegmentAtIndex:

Returns the offset for drawing the content (image or text) of the specified segment.

- (CGSize)contentOffsetForSegmentAtIndex:(NSUInteger)segment
Parameters
segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

Return Value

The offset (specified as a CGSize structure) from the origin of the segment at which to draw the segment’s content.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

contentPositionAdjustmentForSegmentType:barMetrics:

Returns the positioning offset for a given segment and bar metrics.

- (UIOffset)contentPositionAdjustmentForSegmentType:(UISegmentedControlSegment)leftCenterRightOrAlone barMetrics:(UIBarMetrics)barMetrics
Parameters
leftCenterRightOrAlone

An identifier for a segment.

barMetrics

Bar metrics.

Return Value

The content positioning offset for the segment identified by leftCenterRightOrAlone and barMetrics.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISegmentedControl.h

dividerImageForLeftSegmentState:rightSegmentState:barMetrics:

Returns the divider image used for a given combination of left and right segment states and bar metrics.

- (UIImage *)dividerImageForLeftSegmentState:(UIControlState)leftState rightSegmentState:(UIControlState)rightState barMetrics:(UIBarMetrics)barMetrics
Parameters
leftState

The state of the left segment.

rightState

The state of the right segment.

barMetrics

Bar metrics.

Return Value

The divider image used for the given combination of left and right segment states and bar metrics

Availability
  • Available in iOS 5.0 and later.
Declared In
UISegmentedControl.h

imageForSegmentAtIndex:

Returns the image for a specific segment

- (UIImage *)imageForSegmentAtIndex:(NSUInteger)segment.
Parameters
segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

Return Value

Returns the image assigned to the receiver as content. If no image has been set, it returns nil.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UISegmentedControl.h

initWithItems:

Initializes and returns a segmented control with segments having the given titles or images.

- (id)initWithItems:(NSArray *)items
Parameters
items

An array of NSString objects (for segment titles) or UIImage objects (for segment images).

Return Value

A UISegmentedControl object or nil if there was a problem in initializing the object.

Discussion

The returned segmented control is automatically sized to fit its content within the width of its superview.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

insertSegmentWithImage:atIndex:animated:

Inserts a segment at a specified position in the receiver and gives it an image as content.

- (void)insertSegmentWithImage:(UIImage *)image atIndex:(NSUInteger)segment animated:(BOOL)animated
Parameters
image

An image object to use as the content of the segment.

segment

An index number identifying a segment in the control.

segment must be a number in the range 0 to the number of segments (numberOfSegments) inclusive; values exceeding this upper range are pinned to it.

The new segment is inserted just before the designated one.

animated

YES if the insertion of the new segment should be animated, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

insertSegmentWithTitle:atIndex:animated:

Inserts a segment at a specific position in the receiver and gives it a title as content.

- (void)insertSegmentWithTitle:(NSString *)title atIndex:(NSUInteger)segment animated:(BOOL)animated
Parameters
title

A string to use as the segment’s title.

segment

An index number identifying a segment in the control.

segment must be a number in the range 0 to the number of segments (numberOfSegments) inclusive; values exceeding this upper range are pinned to it.

The new segment is inserted just before the designated one.

animated

YES if the insertion of the new segment should be animated, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

isEnabledForSegmentAtIndex:

Returns whether the indicated segment is enabled.

- (BOOL)isEnabledForSegmentAtIndex:(NSUInteger)segment
Parameters
segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

Return Value

YES if the given segment is enabled and NO if the segment is disabled. By default, segments are enabled.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

removeAllSegments

Removes all segments of the receiver

- (void)removeAllSegments
Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

removeSegmentAtIndex:animated:

Removes the specified segment from the receiver, optionally animating the transition.

- (void)removeSegmentAtIndex:(NSUInteger)segment animated:(BOOL)animated
Parameters
segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

animated

YES if the removal of the new segment should be animated, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

setBackgroundImage:forState:barMetrics:

Sets the background image for a given state and bar metrics.

- (void)setBackgroundImage:(UIImage *)backgroundImage forState:(UIControlState)state barMetrics:(UIBarMetrics)barMetrics
Parameters
backgroundImage

The background image to use for state and barMetrics.

state

A control state.

barMetrics

Bar metrics.

Discussion

If backgroundImage is an image returned from resizableImageWithCapInsets:, the cap widths are calculated from that information.

If backgroundImage is not an image returned from resizableImageWithCapInsets:, the cap width is calculated by subtracting one from the image's width then dividing by 2. The cap widths are used as the margins for text placement. To adjust the margin, use the margin adjustment methods.

Discussion

For more details, see backgroundImageForState:barMetrics:.

Availability
  • Available in iOS 5.0 and later.
Related Sample Code
Declared In
UISegmentedControl.h

setContentOffset:forSegmentAtIndex:

Adjusts the offset for drawing the content (image or text) of the specified segment.

- (void)setContentOffset:(CGSize)offset forSegmentAtIndex:(NSUInteger)segment
Parameters
offset

The offset (specified as a CGSize type) from the origin of the segment at which to draw the segment’s content. The default offset is (0,0).

segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

setContentPositionAdjustment:forSegmentType:barMetrics:

Returns the content positioning offset for a given segment and bar metrics.

- (void)setContentPositionAdjustment:(UIOffset)adjustment forSegmentType:(UISegmentedControlSegment)leftCenterRightOrAlone barMetrics:(UIBarMetrics)barMetrics
Parameters
adjustment

The positioning offset for the segment identified by leftCenterRightOrAlone and barMetrics.

leftCenterRightOrAlone

An identifier for a segment type.

barMetrics

Bar metrics.

Discussion

You use this method to adjust the position of a title or image within the given segment of a segmented control.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISegmentedControl.h

setDividerImage:forLeftSegmentState:rightSegmentState:barMetrics:

Sets the divider image used for a given combination of left and right segment states and bar metrics.

- (void)setDividerImage:(UIImage *)dividerImage forLeftSegmentState:(UIControlState)leftState rightSegmentState:(UIControlState)rightState barMetrics:(UIBarMetrics)barMetrics
Parameters
dividerImage

The divider image to use.

leftState

The state of the left segment.

rightState

The state of the right segment.

barMetrics

Bar metrics.

Availability
  • Available in iOS 5.0 and later.
Related Sample Code
Declared In
UISegmentedControl.h

setEnabled:forSegmentAtIndex:

Enables the specified segment.

- (void)setEnabled:(BOOL)enabled forSegmentAtIndex:(NSUInteger)segment
Parameters
enabled

YES to enable the specified segment or NO to disable the segment. By default, segments are enabled.

segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

setImage:forSegmentAtIndex:

Sets the content of a segment to a given image.

- (void)setImage:(UIImage *)image forSegmentAtIndex:(NSUInteger)segment
Parameters
image

An image object to display in the segment. .

segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

Discussion

A segment can only have an image or a title; it can’t have both. There is no default image.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

setTitle:forSegmentAtIndex:

Sets the title of a segment.

- (void)setTitle:(NSString *)title forSegmentAtIndex:(NSUInteger)segment
Parameters
title

A string to display in the segment as its title.

segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

Discussion

A segment can only have an image or a title; it can’t have both. There is no default title.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

setTitleTextAttributes:forState:

Sets the text attributes of the title for a given control state.

- (void)setTitleTextAttributes:(NSDictionary *)attributes forState:(UIControlState)state
Parameters
attributes

The text attributes of the title for state.

state

A control state.

Discussion

The attributes dictionary can specify the font, text color, text shadow color, and text shadow offset for the title in the text attributes dictionary, using the keys in NSString UIKit Additions Reference.

Availability
  • Available in iOS 5.0 and later.
Related Sample Code
Declared In
UISegmentedControl.h

setWidth:forSegmentAtIndex:

Sets the width of the specified segment of the receiver.

- (void)setWidth:(CGFloat)width forSegmentAtIndex:(NSUInteger)segment
Parameters
width

A float value specifying the width of the segment. The default value is {0.0}, which tells UISegmentedControl to automatically size the segment.

segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

titleForSegmentAtIndex:

Returns the title of the specified segment.

- (NSString *)titleForSegmentAtIndex:(NSUInteger)segment
Parameters
segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

Return Value

Returns the string (title) assigned to the receiver as content. If no title has been set, it returns nil.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

titleTextAttributesForState:

Returns the text attributes of the title for a given control state.

- (NSDictionary *)titleTextAttributesForState:(UIControlState)state
Parameters
state

A control state.

Return Value

The text attributes of the title for state.

Discussion

For more details, see setTitleTextAttributes:forState:

Availability
  • Available in iOS 5.0 and later.
Declared In
UISegmentedControl.h

widthForSegmentAtIndex:

Returns the width of the indicated segment of the receiver.

- (CGFloat)widthForSegmentAtIndex:(NSUInteger)segment
Parameters
segment

An index number identifying a segment in the control. It must be a number between 0 and the number of segments (numberOfSegments) minus 1; values exceeding this upper range are pinned to it.

Return Value

A float value specifying the width of the segment. If the value is {0.0}, UISegmentedControl automatically sizes the segment.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISegmentedControl.h

Constants

UISegmentedControlStyle

The styles of the segmented control.

typedef enum {
   UISegmentedControlStylePlain,
   UISegmentedControlStyleBordered,
   UISegmentedControlStyleBar,
   UISegmentedControlStyleBezeled,
} UISegmentedControlStyle;
Constants
UISegmentedControlStylePlain

The large plain style for segmented controls. This style is the default.

Available in iOS 2.0 and later.

Declared in UISegmentedControl.h.

UISegmentedControlStyleBordered

The large bordered style for segmented controls.

Available in iOS 2.0 and later.

Declared in UISegmentedControl.h.

UISegmentedControlStyleBar

The small toolbar style for segmented controls. Segmented controls in this style can have a tint color (see tintColor).

Available in iOS 2.0 and later.

Declared in UISegmentedControl.h.

UISegmentedControlStyleBezeled

The large bezeled style for segmented controls. Segmented controls in this style can have a tint color (see tintColor).

Available in iOS 4.0 and later.

Declared in UISegmentedControl.h.

Discussion

You use these constants as values for the segmentedControlStyle property.

Segment Selection

A constant for indicating that no segment is selected.

enum {
   UISegmentedControlNoSegment = -1
};
Constants
UISegmentedControlNoSegment

A segment index value indicating that there is no selected segment. See selectedSegmentIndex for further information.

Available in iOS 2.0 and later.

Declared in UISegmentedControl.h.

UISegmentedControlSegment

Constants for specifying a segment in a control

typedef enum {
   UISegmentedControlSegmentAny = 0,
   UISegmentedControlSegmentLeft = 1,
   UISegmentedControlSegmentCenter = 2,
   UISegmentedControlSegmentRight = 3,
   UISegmentedControlSegmentAlone = 4,
} UISegmentedControlSegment;
Constants
UISegmentedControlSegmentAny

Specifies any segment.

Available in iOS 5.0 and later.

Declared in UISegmentedControl.h.

UISegmentedControlSegmentLeft

The capped, leftmost segment.

Only applies when numSegments > 1.

Available in iOS 5.0 and later.

Declared in UISegmentedControl.h.

UISegmentedControlSegmentCenter

Any segment between the left and rightmost segments.

Only applies when numSegments > 2.

Available in iOS 5.0 and later.

Declared in UISegmentedControl.h.

UISegmentedControlSegmentRight

The capped,rightmost segment. .

Only applies when numSegments > 1.

Available in iOS 5.0 and later.

Declared in UISegmentedControl.h.

UISegmentedControlSegmentAlone

The standalone segment, capped on both ends.

Only applies when numSegments = 1.

Available in iOS 5.0 and later.

Declared in UISegmentedControl.h.