UISlider Class Reference

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

Overview

A UISlider object is a visual control used to select a single value from a continuous range of values. Sliders are always displayed as horizontal bars. An indicator, or thumb, notes the current value of the slider and can be moved by the user to change the setting.

Customizing the Slider’s Appearance

The most common way to customize the slider’s appearance is to provide custom minimum and maximum value images. These images sit at either end of the slider control and indicate which value that end of the slider represents. For example, a slider used to control volume might display a small speaker with no sound waves emanating from it for the minimum value and display a large speaker with many sound waves emanating from it for the maximum value.

The bar on which the thumb rides is referred to as the slider’s track. Slider controls draw the track using two distinct images, which are customizable. The region between the thumb and the end of the track associated with the slider’s minimum value is drawn using the minimum track image. The region between the thumb and the end of the track associated with the slider’s maximum value is drawn using the maximum track image. Different track images are used in order to provide context as to which end contains the minimum value. For example, the minimum track image typically contains a blue highlight while the maximum track image contains a white highlight. You can assign different tint colors for all of the standard parts provided by the slider, or you customize the appearance further by assigning different pairs of track images to each of the control states of the slider. Assigning different images to each state lets you customize the appearance of the slider when it is enabled, disabled, highlighted, and so on.

In addition to customizing the track images, you can also customize the appearance of the thumb itself. Like the track images, you can assign different thumb images to each control state of the slider.

For more information about appearance and behavior configuration, see “Sliders”.

Tasks

Accessing the Slider’s Value

Accessing the Slider’s Value Limits

Modifying the Slider’s Behavior

Changing the Slider’s Appearance

Overrides for Subclasses

Properties

continuous

Contains a Boolean value indicating whether changes in the sliders value generate continuous update events.

@property(nonatomic, getter=isContinuous) BOOL continuous
Discussion

If YES, the slider sends update events continuously to the associated target’s action method. If NO, the slider only sends an action event when the user releases the slider’s thumb control to set the final value.

The default value of this property is YES.

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

currentMaximumTrackImage

Contains the maximum track image currently being used to render the receiver. (read-only)

@property(nonatomic, readonly) UIImage *currentMaximumTrackImage
Discussion

Sliders can have different track images for different control states. The image associated with this property reflects the maximum track image associated with the currently active control state. To get the maximum track image for a different control state, use the maximumTrackImageForState: method.

If no custom track images have been set using the setMaximumTrackImage:forState: method, this property contains the value nil. In that situation, the receiver uses the default maximum track image for drawing.

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

currentMinimumTrackImage

Contains the minimum track image currently being used to render the receiver. (read-only)

@property(nonatomic, readonly) UIImage *currentMinimumTrackImage
Discussion

Sliders can have different track images for different control states. The image associated with this property reflects the minimum track image associated with the currently active control state. To get the minimum track image for a different control state, use the minimumTrackImageForState: method.

If no custom track images have been set using the setMinimumTrackImage:forState: method, this property contains the value nil. In that situation, the receiver uses the default minimum track image for drawing.

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

currentThumbImage

Contains the thumb image currently being used to render the receiver. (read-only)

@property(nonatomic, readonly) UIImage *currentThumbImage
Discussion

Sliders can have different thumb images for different control states. The image associated with this property reflects the thumb image associated with the currently active control state. To get the thumb image for a different control state, use the thumbImageForState: method.

If no custom thumb images have been set using the setThumbImage:forState: method, this property contains the value nil. In that situation, the receiver uses the default thumb image for drawing.

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

maximumTrackTintColor

The color used to tint the standard maximum track images.

@property(nonatomic, retain) UIColor *maximumTrackTintColor
Discussion

Setting this property removes any custom maximum track images associated with the slider.

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

maximumValue

Contains the maximum value of the receiver.

@property(nonatomic) float maximumValue
Discussion

If you change the value of this property, and the current value of the receiver is above the new maximum, the current value is adjusted to match the new maximum value automatically.

The default value of this property is 1.0.

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

maximumValueImage

Contains the image that is drawn on the side of the slider representing the maximum value.

@property(nonatomic, retain) UIImage *maximumValueImage
Discussion

The image you specify should fit within the bounding rectangle returned by the maximumValueImageRectForBounds: method. If it does not, the image is scaled to fit. In addition, the receiver’s track is lengthened or shortened as needed to accommodate the image in its bounding rectangle.

This default value of this property is nil.

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

minimumTrackTintColor

The color used to tint the standard minimum track images.

@property(nonatomic, retain) UIColor *minimumTrackTintColor
Discussion

Setting this property removes any custom minimum track images associated with the slider.

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

minimumValue

Contains the minimum value of the receiver.

@property(nonatomic) float minimumValue
Discussion

If you change the value of this property, and the current value of the receiver is below the new minimum, the current value is adjusted to match the new minimum value automatically.

The default value of this property is 0.0.

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

minimumValueImage

Contains the image that is drawn on the side of the slider representing the minimum value.

@property(nonatomic, retain) UIImage *minimumValueImage
Discussion

The image you specify should fit within the bounding rectangle returned by the minimumValueImageRectForBounds: method. If it does not, the image is scaled to fit. In addition, the receiver’s track is lengthened or shortened as needed to accommodate the image in its bounding rectangle.

This default value of this property is nil.

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

thumbTintColor

The color used to tint the standard thumb images.

@property(nonatomic, retain) UIColor *thumbTintColor
Discussion

Setting this property removes any custom thumb images associated with the slider.

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

value

Contains the receiver’s current value.

@property(nonatomic) float value
Discussion

Setting this property causes the receiver to redraw itself using the new value. To render an animated transition from the current value to the new value, you should use the setValue:animated: method instead.

If you try to set a value that is below the minimum or above the maximum value, the minimum or maximum value is set instead. The default value of this property is 0.0.

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

Instance Methods

maximumTrackImageForState:

Returns the maximum track image associated with the specified control state.

- (UIImage *)maximumTrackImageForState:(UIControlState)state
Parameters
state

The control state whose maximum track image you want. You should specify only one control state value for this parameter.

Return Value

The maximum track image associated with the specified state, or nil if an appropriate image could not be retrieved. This method might return nil if you specify multiple control states in the state parameter. For a description of track images, see “Customizing the Slider’s Appearance.”

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

maximumValueImageRectForBounds:

Returns the drawing rectangle for the maximum value image.

- (CGRect)maximumValueImageRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The computed drawing rectangle for the image.

Discussion

You should not call this method directly. If you want to customize the rectangle in which the maximum value image is drawn, you can override this method and return a different rectangle.

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

minimumTrackImageForState:

Returns the minimum track image associated with the specified control state.

- (UIImage *)minimumTrackImageForState:(UIControlState)state
Parameters
state

The control state whose minimum track image you want. You should specify only one control state value for this parameter.

Return Value

The minimum track image associated with the specified state, or nil if no image has been set. This method might also return nil if you specify multiple control states in the state parameter. For a description of track images, see “Customizing the Slider’s Appearance.”

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

minimumValueImageRectForBounds:

Returns the drawing rectangle for the minimum value image.

- (CGRect)minimumValueImageRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The computed drawing rectangle for the image.

Discussion

You should not call this method directly. If you want to customize the rectangle in which the minimum value image is drawn, you can override this method and return a different rectangle.

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

setMaximumTrackImage:forState:

Assigns a maximum track image to the specified control states.

- (void)setMaximumTrackImage:(UIImage *)image forState:(UIControlState)state
Parameters
image

The maximum track image to associate with the specified states.

state

The control state with which to associate the image.

Discussion

The orientation of the track image must match the orientation of the slider control. To facilitate the stretching of the image to fill the space between the thumb and end point, track images are usually defined in three regions. A stretchable region sits between two end cap regions. The end caps define the portions of the image that remain as is and are not stretched. The stretchable region is a 1-point wide area between the end caps that can be replicated to make the image appear longer.

To define the end cap sizes for a slider, assign an appropriate value to the image’s leftCapWidth property. For more information about how this value defines the regions of the slider, see the UIImage class.

Setting a new track image for any state clears any custom tint color you may have provided for maximum track images.

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

setMinimumTrackImage:forState:

Assigns a minimum track image to the specified control states.

- (void)setMinimumTrackImage:(UIImage *)image forState:(UIControlState)state
Parameters
image

The minimum track image to associate with the specified states.

state

The control state with which to associate the image.

Discussion

The orientation of the track image must match the orientation of the slider control. To facilitate the stretching of the image to fill the space between the thumb and end point, track images are usually defined in three regions. A stretchable region sits between two end cap regions. The end caps define the portions of the image that remain as is and are not stretched. The stretchable region is a 1-point wide area between the end caps that can be replicated to make the image appear longer.

To define the end cap sizes for a slider, assign an appropriate value to the image’s leftCapWidth property. For more information about how this value defines the regions of the slider, see the UIImage class.

Setting a new track image for any state clears any custom tint color you may have provided for minimum track images.

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

setThumbImage:forState:

Assigns a thumb image to the specified control states.

- (void)setThumbImage:(UIImage *)image forState:(UIControlState)state
Parameters
image

The thumb image to associate with the specified states.

state

The control state with which to associate the image.

Discussion

Setting a new thumb image for any state clears any custom tint color you may have provided for thumb images.

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

setValue:animated:

Sets the receiver’s current value, allowing you to animate the change visually.

- (void)setValue:(float)value animated:(BOOL)animated
Parameters
value

The new value to assign to the value property

animated

Specify YES to animate the change in value when the receiver is redrawn; otherwise, specify NO to draw the receiver with the new value only. Animations are performed asynchronously and do not block the calling thread.

Discussion

If you try to set a value that is below the minimum or above the maximum value, the minimum or maximum value is set instead. The default value of this property is 0.0.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UISlider.h

thumbImageForState:

Returns the thumb image associated with the specified control state.

- (UIImage *)thumbImageForState:(UIControlState)state
Parameters
state

The control state whose thumb image you want. You should specify only one control state value for this parameter.

Return Value

The thumb image associated with the specified state, or nil if an appropriate image could not be retrieved. This method might return nil if you specify multiple control states in the state parameter. For a description of track and thumb images, see “Customizing the Slider’s Appearance.”

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

thumbRectForBounds:trackRect:value:

Returns the drawing rectangle for the slider’s thumb image.

- (CGRect)thumbRectForBounds:(CGRect)bounds trackRect:(CGRect)rect value:(float)value
Parameters
bounds

The bounding rectangle of the receiver.

rect

The drawing rectangle for the receiver’s track, as returned by the trackRectForBounds: method.

value

The current value of the slider.

Return Value

The computed drawing rectangle for the thumb image.

Discussion

You should not call this method directly. If you want to customize the thumb image’s drawing rectangle, you can override this method and return a different rectangle. The rectangle you return should reflect the size of your thumb image and its current position on the slider’s track.

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

trackRectForBounds:

Returns the drawing rectangle for the slider’s track.

- (CGRect)trackRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The computed drawing rectangle for the track. This rectangle corresponds to the entire length of the track between the minimum and maximum value images.

Discussion

You should not call this method directly. If you want to customize the track rectangle, you can override this method and return a different rectangle. The returned rectangle is used to scale the track and thumb images during drawing.

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