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 |
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:
If you set a segmented control to have a momentary style, a segment doesn’t show itself as selected (blue background) when the user touches it. The disclosure button is always momentary and doesn’t affect the actual selection.
In versions of iOS prior to 3.0, if a segmented control has only two segments, then it behaves like a switch—tapping the currently-selected segment causes the other segment to be selected. On iOS 3.0 and later, tapping the currently-selected segment does not cause the other segment to be selected.
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
-
– setImage:forSegmentAtIndex: -
– imageForSegmentAtIndex: -
– setTitle:forSegmentAtIndex: -
– titleForSegmentAtIndex:
Managing Segments
-
– insertSegmentWithImage:atIndex:animated: -
– insertSegmentWithTitle:atIndex:animated: -
numberOfSegmentsproperty -
– removeAllSegments -
– removeSegmentAtIndex:animated: -
selectedSegmentIndexproperty
Managing Segment Behavior and Appearance
-
momentaryproperty -
segmentedControlStyleproperty -
– setEnabled:forSegmentAtIndex: -
– isEnabledForSegmentAtIndex: -
– setContentOffset:forSegmentAtIndex: -
– contentOffsetForSegmentAtIndex: -
– setWidth:forSegmentAtIndex: -
– widthForSegmentAtIndex: -
apportionsSegmentWidthsByContentproperty
Customizing Appearance
-
tintColorproperty -
– backgroundImageForState:barMetrics: -
– setBackgroundImage:forState:barMetrics: -
– contentPositionAdjustmentForSegmentType:barMetrics: -
– setContentPositionAdjustment:forSegmentType:barMetrics: -
– dividerImageForLeftSegmentState:rightSegmentState:barMetrics: -
– setDividerImage:forLeftSegmentState:rightSegmentState:barMetrics: -
– titleTextAttributesForState: -
– setTitleTextAttributes:forState:
Properties
apportionsSegmentWidthsByContent
Indicates whether the control attempts to adjust segment widths based on their content widths.
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.hmomentary
A Boolean value that determines whether segments in the receiver show selected state.
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.
Declared In
UISegmentedControl.hnumberOfSegments
Returns the number of segments the receiver has. (read-only)
Availability
- Available in iOS 2.0 and later.
Declared In
UISegmentedControl.hsegmentedControlStyle
The style of the segmented control.
Discussion
The default style is UISegmentedControlStylePlain. See “UISegmentedControlStyle” for descriptions of valid constants.
Availability
- Available in iOS 2.0 and later.
Declared In
UISegmentedControl.hselectedSegmentIndex
The index number identifying the selected segment (that is, the last segment touched).
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.
See Also
Declared In
UISegmentedControl.htintColor
The tint color of the segmented control.
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.hInstance Methods
backgroundImageForState:barMetrics:
Returns the background image for a given state and bar metrics.
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.hcontentOffsetForSegmentAtIndex:
Returns the offset for drawing the content (image or text) of the specified 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.hcontentPositionAdjustmentForSegmentType:barMetrics:
Returns the positioning offset for a given segment and bar metrics.
Parameters
- leftCenterRightOrAlone
An identifier for a segment.
- barMetrics
Bar metrics.
Return Value
The content positioning offset for the segment identified by leftCenterRightOrAlone and barMetrics.
Discussion
For more details, see setContentPositionAdjustment:forSegmentType:barMetrics:.
Availability
- Available in iOS 5.0 and later.
Declared In
UISegmentedControl.hdividerImageForLeftSegmentState:rightSegmentState:barMetrics:
Returns the divider image used for a given combination of left and right segment states and bar metrics.
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.himageForSegmentAtIndex:
Returns the image for a specific 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.
See Also
Declared In
UISegmentedControl.hinitWithItems:
Initializes and returns a segmented control with segments having the given titles or images.
Parameters
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.hinsertSegmentWithImage:atIndex:animated:
Inserts a segment at a specified position in the receiver and gives it an image as content.
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
YESif the insertion of the new segment should be animated, otherwiseNO.
Availability
- Available in iOS 2.0 and later.
Declared In
UISegmentedControl.hinsertSegmentWithTitle:atIndex:animated:
Inserts a segment at a specific position in the receiver and gives it a title as content.
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
YESif the insertion of the new segment should be animated, otherwiseNO.
Availability
- Available in iOS 2.0 and later.
Declared In
UISegmentedControl.hisEnabledForSegmentAtIndex:
Returns whether the indicated segment is enabled.
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.
See Also
Declared In
UISegmentedControl.hremoveAllSegments
Removes all segments of the receiver
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
UISegmentedControl.hremoveSegmentAtIndex:animated:
Removes the specified segment from the receiver, optionally animating the transition.
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
YESif the removal of the new segment should be animated, otherwiseNO.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
UISegmentedControl.hsetBackgroundImage:forState:barMetrics:
Sets the background image for a given state and bar metrics.
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.
Declared In
UISegmentedControl.hsetContentOffset:forSegmentAtIndex:
Adjusts the offset for drawing the content (image or text) of the specified segment.
Parameters
- offset
The offset (specified as a
CGSizetype) 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.
See Also
Declared In
UISegmentedControl.hsetContentPositionAdjustment:forSegmentType:barMetrics:
Returns the content positioning offset for a given segment and bar metrics.
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.hsetDividerImage:forLeftSegmentState:rightSegmentState:barMetrics:
Sets the divider image used for a given combination of left and right segment states and bar metrics.
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.
Declared In
UISegmentedControl.hsetEnabled:forSegmentAtIndex:
Enables the specified segment.
Parameters
- enabled
YESto enable the specified segment orNOto 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.
See Also
Declared In
UISegmentedControl.hsetImage:forSegmentAtIndex:
Sets the content of a segment to a given image.
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.
See Also
Declared In
UISegmentedControl.hsetTitle:forSegmentAtIndex:
Sets the title of a 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.
See Also
Declared In
UISegmentedControl.hsetTitleTextAttributes:forState:
Sets the text attributes of the title for a given control 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.
Declared In
UISegmentedControl.hsetWidth:forSegmentAtIndex:
Sets the width of the specified segment of the receiver.
Parameters
- width
A float value specifying the width of the segment. The default value is {0.0}, which tells
UISegmentedControlto 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.
See Also
Declared In
UISegmentedControl.htitleForSegmentAtIndex:
Returns the title of the specified 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.
See Also
Declared In
UISegmentedControl.htitleTextAttributesForState:
Returns the text attributes of the title for a given control 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.hwidthForSegmentAtIndex:
Returns the width of the indicated segment of the receiver.
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.
See Also
Declared In
UISegmentedControl.hConstants
UISegmentedControlStyle
The styles of the segmented control.
typedef enum {
UISegmentedControlStylePlain,
UISegmentedControlStyleBordered,
UISegmentedControlStyleBar,
UISegmentedControlStyleBezeled,
} UISegmentedControlStyle;
Constants
UISegmentedControlStylePlainThe large plain style for segmented controls. This style is the default.
Available in iOS 2.0 and later.
Declared in
UISegmentedControl.h.UISegmentedControlStyleBorderedThe large bordered style for segmented controls.
Available in iOS 2.0 and later.
Declared in
UISegmentedControl.h.UISegmentedControlStyleBarThe 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.UISegmentedControlStyleBezeledThe 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
UISegmentedControlNoSegmentA segment index value indicating that there is no selected segment. See
selectedSegmentIndexfor 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
UISegmentedControlSegmentAnySpecifies any segment.
Available in iOS 5.0 and later.
Declared in
UISegmentedControl.h.UISegmentedControlSegmentLeftThe capped, leftmost segment.
Only applies when numSegments > 1.
Available in iOS 5.0 and later.
Declared in
UISegmentedControl.h.UISegmentedControlSegmentCenterAny segment between the left and rightmost segments.
Only applies when numSegments > 2.
Available in iOS 5.0 and later.
Declared in
UISegmentedControl.h.UISegmentedControlSegmentRightThe capped,rightmost segment. .
Only applies when numSegments > 1.
Available in iOS 5.0 and later.
Declared in
UISegmentedControl.h.UISegmentedControlSegmentAloneThe standalone segment, capped on both ends.
Only applies when numSegments = 1.
Available in iOS 5.0 and later.
Declared in
UISegmentedControl.h.
© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-12)