You are on page 1of 21

UISlider Class Reference

Contents

UISlider Class Reference 4
Overview 4 Customizing the Slider’s Appearance 4 Tasks 5 Accessing the Slider’s Value 5 Accessing the Slider’s Value Limits 5 Modifying the Slider’s Behavior 5 Changing the Slider’s Appearance 6 Overrides for Subclasses 7 Properties 7 continuous 7 currentMaximumTrackImage 7 currentMinimumTrackImage 8 currentThumbImage 9 maximumTrackTintColor 9 maximumValue 10 maximumValueImage 10 minimumTrackTintColor 10 minimumValue 11 minimumValueImage 11 thumbTintColor 12 value 12 Instance Methods 13 maximumTrackImageForState: 13 maximumValueImageRectForBounds: 13 minimumTrackImageForState: 14 minimumValueImageRectForBounds: 14 setMaximumTrackImage:forState: 15 setMinimumTrackImage:forState: 16 setThumbImage:forState: 16 setValue:animated: 17 thumbImageForState: 18 thumbRectForBounds:trackRect:value: 18 trackRectForBounds: 19

2011-10-12 | © 2011 Apple Inc. All Rights Reserved.

2

Contents Document Revision History 20 2011-10-12 | © 2011 Apple Inc. 3 . All Rights Reserved.

These images sit at either end of the slider control and indicate which value that end of the slider represents. Customizing the Slider’s Appearance The most common way to customize the slider’s appearance is to provide custom minimum and maximum value images. Different track images are used in order to provide context as to which end contains the minimum value.framework Available in iOS 2. 4 . the minimum track image typically contains a blue highlight while the maximum track image contains 2011-10-12 | © 2011 Apple Inc. For example. which are customizable. notes the current value of the slider and can be moved by the user to change the setting. For example. 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. 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. Slider controls draw the track using two distinct images. An indicator. or thumb.h Overview A UISlider object is a visual control used to select a single value from a continuous range of values.0 and later.UISlider Class Reference Inherits from Conforms to UIControl : UIView : UIResponder : NSObject NSCoding NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) NSObject (NSObject) Framework Availability Declared in /System/Library/Frameworks/UIKit. All Rights Reserved. Sliders are always displayed as horizontal bars. 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. The bar on which the thumb rides is referred to as the slider’s track. UISlider.

You can assign different tint colors for all of the standard parts provided by the slider. If you do not specify any custom images. – setValue:animated: (page 17) Sets the receiver’s current value. you can also customize the appearance of the thumb itself.UISlider Class Reference Tasks a white highlight. Note: The slider control provides a set of default images for both the track and thumb. and so on. allowing you to animate the change visually. Assigning different images to each state lets you customize the appearance of the slider when it is enabled. Accessing the Slider’s Value Limits minimumValue (page 11) property Contains the minimum value of the receiver. 2011-10-12 | © 2011 Apple Inc. highlighted. those images are used automatically. Like the track images. you can assign different thumb images to each control state of the slider. disabled. 5 . maximumValue (page 10) property Contains the maximum value of the receiver. Modifying the Slider’s Behavior continuous (page 7) property Contains a Boolean value indicating whether changes in the sliders value generate continuous update events. All Rights Reserved. Tasks Accessing the Slider’s Value value (page 12) property Contains the receiver’s current value. In addition to customizing the track images. or you customize the appearance further by assigning different pairs of track images to each of the control states of the slider.

property – setMinimumTrackImage:forState: maximumTrackTintColor (page 9) The color used to tint the standard maximum track images. property – setMaximumTrackImage:forState: thumbTintColor (page 12) The color used to tint the standard thumb images. (read-only) – thumbImageForState: (page 18) Returns the thumb image associated with the specified control state. (page 16) Assigns a thumb image to the specified control states.UISlider Class Reference Tasks Changing the Slider’s Appearance minimumValueImage (page 11) property Contains the image that is drawn on the side of the slider representing the minimum value. (page 15) Assigns a maximum track image to the specified control states. (read-only) – maximumTrackImageForState: (page 13) Returns the maximum track image associated with the specified control state. currentThumbImage (page 9) property Contains the thumb image currently being used to render the receiver. All Rights Reserved. currentMinimumTrackImage (page 8) property Contains the minimum track image currently being used to render the receiver. 6 . (read-only) – minimumTrackImageForState: (page 14) Returns the minimum track image associated with the specified control state. (page 16) Assigns a minimum track image to the specified control states. minimumTrackTintColor (page 10) property The color used to tint the standard minimum track images. currentMaximumTrackImage (page 7) property Contains the maximum track image currently being used to render the receiver. maximumValueImage (page 10) property Contains the image that is drawn on the side of the slider representing the maximum value. – setThumbImage:forState: 2011-10-12 | © 2011 Apple Inc.

Declared in UISlider.UISlider Class Reference Properties Overrides for Subclasses – maximumValueImageRectForBounds: (page 13) Returns the drawing rectangle for the maximum value image. the slider only sends an action event when the user releases the slider’s thumb control to set the final value. (page 14) Returns the drawing rectangle for the minimum value image. (page 18) Returns the drawing rectangle for the slider’s thumb image. If NO. getter=isContinuous) BOOL continuous Discussion If YES.0 and later.h currentMaximumTrackImage Contains the maximum track image currently being used to render the receiver. All Rights Reserved. (page 19) Returns the drawing rectangle for the slider’s track. 7 . the slider sends update events continuously to the associated target’s action method. Availability Available in iOS 2. – minimumValueImageRectForBounds: – trackRectForBounds: – thumbRectForBounds:trackRect:value: Properties continuous Contains a Boolean value indicating whether changes in the sliders value generate continuous update events. The default value of this property is YES. (read-only) 2011-10-12 | © 2011 Apple Inc. @property(nonatomic.

0 and later. Availability Available in iOS 2. To get the maximum track image for a different control state. If no custom track images have been set using the setMaximumTrackImage:forState: method. See Also (page 14) – setMinimumTrackImage:forState: (page 16) – minimumTrackImageForState: 2011-10-12 | © 2011 Apple Inc. In that situation. this property contains the value nil. readonly) UIImage *currentMaximumTrackImage Discussion Sliders can have different track images for different control states. See Also (page 13) – setMaximumTrackImage:forState: (page 15) – maximumTrackImageForState: Declared in UISlider. the receiver uses the default maximum track image for drawing. The image associated with this property reflects the maximum track image associated with the currently active control state.h currentMinimumTrackImage Contains the minimum track image currently being used to render the receiver. In that situation. The image associated with this property reflects the minimum track image associated with the currently active control state. use the minimumTrackImageForState: method.0 and later. If no custom track images have been set using the setMinimumTrackImage:forState: method. 8 .UISlider Class Reference Properties @property(nonatomic. Availability Available in iOS 2. this property contains the value nil. All Rights Reserved. the receiver uses the default minimum track image for drawing. readonly) UIImage *currentMinimumTrackImage Discussion Sliders can have different track images for different control states. To get the minimum track image for a different control state. (read-only) @property(nonatomic. use the maximumTrackImageForState: method.

See Also – thumbImageForState: – setThumbImage:forState: (page 18) (page 16) Declared in UISlider. readonly) UIImage *currentThumbImage Discussion Sliders can have different thumb images for different control states.h maximumTrackTintColor The color used to tint the standard maximum track images. Availability Available in iOS 2.h currentThumbImage Contains the thumb image currently being used to render the receiver. All Rights Reserved.0 and later. 9 . Availability Available in iOS 5. To get the thumb image for a different control state. (read-only) @property(nonatomic. If no custom thumb images have been set using the setThumbImage:forState: method.h 2011-10-12 | © 2011 Apple Inc. use the thumbImageForState: method.UISlider Class Reference Properties Declared in UISlider. @property(nonatomic. this property contains the value nil. the receiver uses the default thumb image for drawing. retain) UIColor *maximumTrackTintColor Discussion Setting this property removes any custom maximum track images associated with the slider.0 and later. In that situation. Declared in UISlider. The image associated with this property reflects the thumb image associated with the currently active control state.

retain) UIImage *maximumValueImage Discussion The image you specify should fit within the bounding rectangle returned by the maximumValueImageRectForBounds: method. the current value is adjusted to match the new maximum value automatically. 2011-10-12 | © 2011 Apple Inc.0 and later. Declared in UISlider.UISlider Class Reference Properties maximumValue Contains the maximum value of the receiver.h maximumValueImage Contains the image that is drawn on the side of the slider representing the maximum value. @property(nonatomic. 10 . Availability Available in iOS 2. The default value of this property is 1. In addition. the image is scaled to fit. and the current value of the receiver is above the new maximum.0. Declared in UISlider.0 and later. the receiver’s track is lengthened or shortened as needed to accommodate the image in its bounding rectangle. Availability Available in iOS 2. All Rights Reserved. @property(nonatomic) float maximumValue Discussion If you change the value of this property. This default value of this property is nil.h minimumTrackTintColor The color used to tint the standard minimum track images. If it does not.

the receiver’s track is lengthened or shortened as needed to accommodate the image in its bounding rectangle. Availability Available in iOS 2. 11 .UISlider Class Reference Properties @property(nonatomic. In addition. Declared in UISlider.0 and later. @property(nonatomic. retain) UIColor *minimumTrackTintColor Discussion Setting this property removes any custom minimum track images associated with the slider. Declared in UISlider. the current value is adjusted to match the new minimum value automatically.0. The default value of this property is 0. If it does not.h minimumValue Contains the minimum value of the receiver.0 and later. retain) UIImage *minimumValueImage Discussion The image you specify should fit within the bounding rectangle returned by the minimumValueImageRectForBounds: method. All Rights Reserved. Availability Available in iOS 5. the image is scaled to fit. and the current value of the receiver is below the new minimum.0 and later. Availability Available in iOS 2. This default value of this property is nil. @property(nonatomic) float minimumValue Discussion If you change the value of this property. 2011-10-12 | © 2011 Apple Inc.h minimumValueImage Contains the image that is drawn on the side of the slider representing the minimum value.

@property(nonatomic) float value Discussion Setting this property causes the receiver to redraw itself using the new value.h value Contains the receiver’s current value. @property(nonatomic.0 and later. the minimum or maximum value is set instead.UISlider Class Reference Properties Declared in UISlider. To render an animated transition from the current value to the new value.0.h 2011-10-12 | © 2011 Apple Inc. Availability Available in iOS 5. See Also – setValue:animated: (page 17) Declared in UISlider. retain) UIColor *thumbTintColor Discussion Setting this property removes any custom thumb images associated with the slider.h thumbTintColor The color used to tint the standard thumb images. All Rights Reserved. Declared in UISlider. If you try to set a value that is below the minimum or above the maximum value. The default value of this property is 0. Availability Available in iOS 2.0 and later. 12 . you should use the setValue:animated: method instead.

you can override this method and return a different rectangle. see “Customizing the Slider’s Appearance” (page 4). You should specify only one control state value for this parameter. .UISlider Class Reference Instance Methods Instance Methods maximumTrackImageForState: Returns the maximum track image associated with the specified control state. If you want to customize the rectangle in which the maximum value image is drawn. See Also – setMaximumTrackImage:forState: (page 15) Declared in UISlider. Return Value The maximum track image associated with the specified state. Return Value The computed drawing rectangle for the image. This method might return nil if you specify multiple control states in the state parameter.(CGRect)maximumValueImageRectForBounds:(CGRect)bounds Parameters bounds The bounding rectangle of the receiver.h maximumValueImageRectForBounds: Returns the drawing rectangle for the maximum value image.(UIImage *)maximumTrackImageForState:(UIControlState)state Parameters state The control state whose maximum track image you want. For a description of track images.0 and later. or nil if an appropriate image could not be retrieved. . 2011-10-12 | © 2011 Apple Inc. Discussion You should not call this method directly. 13 . All Rights Reserved. Availability Available in iOS 2.

14 . 2011-10-12 | © 2011 Apple Inc. .0 and later.h minimumTrackImageForState: Returns the minimum track image associated with the specified control state. For a description of track images. see “Customizing the Slider’s Appearance” (page 4). Return Value The minimum track image associated with the specified state. This method might also return nil if you specify multiple control states in the state parameter. Declared in UISlider.(CGRect)minimumValueImageRectForBounds:(CGRect)bounds Parameters bounds The bounding rectangle of the receiver. or nil if no image has been set. All Rights Reserved.0 and later.h minimumValueImageRectForBounds: Returns the drawing rectangle for the minimum value image.UISlider Class Reference Instance Methods Availability Available in iOS 2. See Also – setMinimumTrackImage:forState: (page 16) Declared in UISlider. You should specify only one control state value for this parameter. Availability Available in iOS 2. .(UIImage *)minimumTrackImageForState:(UIControlState)state Parameters state The control state whose minimum track image you want.

To define the end cap sizes for a slider. Declared in UISlider. 15 . state The control state with which to associate the image. assign an appropriate value to the image’s leftCapWidth property. track images are usually defined in three regions. A stretchable region sits between two end cap regions. The stretchable region is a 1-point wide area between the end caps that can be replicated to make the image appear longer. Discussion The orientation of the track image must match the orientation of the slider control. . All Rights Reserved. To facilitate the stretching of the image to fill the space between the thumb and end point. 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. The end caps define the portions of the image that remain as is and are not stretched. Discussion You should not call this method directly.(void)setMaximumTrackImage:(UIImage *)image forState:(UIControlState)state Parameters image The maximum track image to associate with the specified states. see the UIImage class.h setMaximumTrackImage:forState: Assigns a maximum track image to the specified control states.UISlider Class Reference Instance Methods Return Value The computed drawing rectangle for the image. Availability Available in iOS 2. See Also – maximumTrackImageForState: (page 13) 2011-10-12 | © 2011 Apple Inc. Availability Available in iOS 2.0 and later. For more information about how this value defines the regions of the slider. Setting a new track image for any state clears any custom tint color you may have provided for maximum track images.0 and later.

assign an appropriate value to the image’s leftCapWidth property.(void)setThumbImage:(UIImage *)image forState:(UIControlState)state 2011-10-12 | © 2011 Apple Inc.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. track images are usually defined in three regions. To define the end cap sizes for a slider. For more information about how this value defines the regions of the slider. Declared in UISlider. The stretchable region is a 1-point wide area between the end caps that can be replicated to make the image appear longer. see the UIImage class.0 and later. A stretchable region sits between two end cap regions. 16 . 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. 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. All Rights Reserved. The end caps define the portions of the image that remain as is and are not stretched. state The control state with which to associate the image.UISlider Class Reference Instance Methods Declared in UISlider. .h setThumbImage:forState: Assigns a thumb image to the specified control states. .

Discussion Setting a new thumb image for any state clears any custom tint color you may have provided for thumb images.0 and later. allowing you to animate the change visually. state The control state with which to associate the image. All Rights Reserved. otherwise. See Also – thumbImageForState: (page 18) Declared in UISlider. Availability Available in iOS 2. Discussion If you try to set a value that is below the minimum or above the maximum value. The default value of this property is 0. Availability Available in iOS 2.h setValue:animated: Sets the receiver’s current value. the minimum or maximum value is set instead. Animations are performed asynchronously and do not block the calling thread.(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.0 and later. See Also @property value (page 12) 2011-10-12 | © 2011 Apple Inc. .0. specify NO to draw the receiver with the new value only.UISlider Class Reference Instance Methods Parameters image The thumb image to associate with the specified states. 17 .

See Also – setThumbImage:forState: (page 16) Declared in UISlider. This method might return nil if you specify multiple control states in the state parameter. value The current value of the slider. Availability Available in iOS 2.(CGRect)thumbRectForBounds:(CGRect)bounds trackRect:(CGRect)rect value:(float)value Parameters bounds The bounding rectangle of the receiver. All Rights Reserved. see “Customizing the Slider’s Appearance” (page 4). Return Value The thumb image associated with the specified state. 18 .h thumbRectForBounds:trackRect:value: Returns the drawing rectangle for the slider’s thumb image. rect The drawing rectangle for the receiver’s track.h thumbImageForState: Returns the thumb image associated with the specified control state. or nil if an appropriate image could not be retrieved. For a description of track and thumb images. . You should specify only one control state value for this parameter. as returned by the trackRectForBounds: (page 19) method.(UIImage *)thumbImageForState:(UIControlState)state Parameters state The control state whose thumb image you want. 2011-10-12 | © 2011 Apple Inc.UISlider Class Reference Instance Methods Declared in UISlider. .0 and later.

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.h trackRectForBounds: Returns the drawing rectangle for the slider’s track.h 2011-10-12 | © 2011 Apple Inc. 19 .UISlider Class Reference Instance Methods Return Value The computed drawing rectangle for the thumb image. you can override this method and return a different rectangle. .0 and later. you can override this method and return a different rectangle. This rectangle corresponds to the entire length of the track between the minimum and maximum value images. Return Value The computed drawing rectangle for the track. Discussion You should not call this method directly. The returned rectangle is used to scale the track and thumb images during drawing. Discussion You should not call this method directly.0 and later. If you want to customize the track rectangle. Declared in UISlider. Availability Available in iOS 2. All Rights Reserved. Declared in UISlider.(CGRect)trackRectForBounds:(CGRect)bounds Parameters bounds The bounding rectangle of the receiver. If you want to customize the thumb image’s drawing rectangle.

New document that describes the class implementing sliders--visual controls used to select a single value from a continuous range of values. 20 . 2011-10-12 | © 2011 Apple Inc.Document Revision History This table describes the changes to UISlider Class Reference . All Rights Reserved. Date 2011-10-12 2008-06-16 Notes Updated for iOS 5.

WITH RESPECT TO THIS DOCUMENT. express or implied. This warranty gives you specific legal rights. . ITS QUALITY. in any form or by any means.. This document is intended to assist application developers to develop applications only for Apple-labeled computers. ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. APPLE MAKES NO WARRANTY OR REPRESENTATION. mechanical. even if advised of the possibility of such damages. recording. ACCURACY. registered in the U. stored in a retrieval system. or transmitted. agent. and other countries. OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages. or employee is authorized to make any modification. iOS is a trademark or registered trademark of Cisco in the U. INDIRECT. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT. No part of this publication may be reproduced. Apple Inc. OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT. No licenses. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS. electronic. or addition to this warranty. EXPRESS OR IMPLIED. so the above limitation or exclusion may not apply to you. INCIDENTAL. No Apple dealer.Apple Inc.S. Even though Apple has reviewed this document. and you may also have other rights which vary from state to state. are granted with respect to any of the technology described in this document. SPECIAL. photocopying.S. and other countries and is used under license. or otherwise. extension.” AND YOU. MERCHANTABILITY. All rights reserved. EITHER EXPRESS OR IMPLIED. © 2011 Apple Inc. CA 95014 408-996-1010 Apple and the Apple logo are trademarks of Apple Inc. 1 Infinite Loop Cupertino. AS A RESULT. THIS DOCUMENT IS PROVIDED “AS IS. THE READER. Apple retains all intellectual property rights associated with the technology described in this document. without prior written permission of Apple Inc. with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice.. ORAL OR WRITTEN.