UIButton Class Reference

Contents

UIButton Class Reference 4

Overview 4 Tasks 5 Creating Buttons 5 Configuring the Button Title 5 Configuring Button Presentation 5 Configuring Edge Insets 6 Getting the Current State 6 Getting Dimensions 7 Deprecated Properties 7 Properties 8 adjustsImageWhenDisabled 8 adjustsImageWhenHighlighted 8 buttonType 8 contentEdgeInsets 9 currentAttributedTitle 9 currentBackgroundImage 10 currentImage 10 currentTitle 11 currentTitleColor 11 currentTitleShadowColor 12 imageEdgeInsets 12 imageView 13 reversesTitleShadowWhenHighlighted 13 showsTouchWhenHighlighted 14 tintColor 14 titleEdgeInsets 15 titleLabel 15 Class Methods 16 buttonWithType: 16 Instance Methods 17 attributedTitleForState: 17 backgroundImageForState: 17 backgroundRectForBounds: 18

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

Contents

contentRectForBounds: 19 imageForState: 19 imageRectForContentRect: 20 setAttributedTitle:forState: 20 setBackgroundImage:forState: 21 setImage:forState: 22 setTitle:forState: 22 setTitleColor:forState: 23 setTitleShadowColor:forState: 24 titleColorForState: 24 titleForState: 25 titleRectForContentRect: 26 titleShadowColorForState: 26 Constants 27 UIButtonType 27

Deprecated UIButton Methods 29

Deprecated in iOS 3.0 29 font 29 lineBreakMode 29 titleShadowOffset 30

Document Revision History 31

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

UIButton Class Reference

Inherits from Conforms to

UIControl : UIView : UIResponder : NSObject NSCoding NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) UIDynamicItem (UIView) NSObject (NSObject)

Framework Availability Companion guide Declared in Related sample code

/System/Library/Frameworks/UIKit.framework Available in iOS 2.0 and later. Buttons UIButton.h

AddMusic avTouch Sampler Unit Presets (LoadPresetDemo) SimpleNetworkStreams UICatalog

Overview
An instance of the UIButton class implements a button on the touch screen. A button intercepts touch events and sends an action message to a target object when tapped. Methods for setting the target and action are inherited from UIControl. This class provides methods for setting the title, image, and other appearance properties of a button. By using these accessors, you can specify a different appearance for each button state. For information about basic view behaviors, see View Programming Guide for iOS . For more information about appearance and behavior configuration, see Buttons.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

UIButton Class Reference Tasks

Tasks
Creating Buttons
+ buttonWithType:

(page 16) Creates and returns a new button of the specified type.

Configuring the Button Title

titleLabel

(page 15) property A view that displays the value of the currentTitle property for a button. (read-only) (page 25) Returns the title associated with the specified state. (page 22) Sets the title to use for the specified state. (page 17) Returns the styled title associated with the specified state. (page 20) Sets the styled title to use for the specified state. (page 24) Returns the title color used for a state. (page 23) Sets the color of the title to use for the specified state. (page 26) Returns the shadow color of the title used for a state. (page 24) Sets the color of the title shadow to use for the specified state. (page 13) property A Boolean value that determines whether the title shadow changes when the button is highlighted.

titleForState:

setTitle:forState:

attributedTitleForState:

setAttributedTitle:forState:

titleColorForState:

setTitleColor:forState:

titleShadowColorForState:

setTitleShadowColor:forState:

reversesTitleShadowWhenHighlighted

Configuring Button Presentation

adjustsImageWhenHighlighted

(page 8) property A Boolean value that determines whether the image changes when the button is highlighted.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

UIButton Class Reference Tasks

adjustsImageWhenDisabled

(page 8) property A Boolean value that determines whether the image changes when the button is disabled. (page 14) property A Boolean value that determines whether tapping the button causes it to glow. (page 17) Returns the background image used for a button state. (page 19) Returns the image used for a button state. (page 21) Sets the background image to use for the specified button state. (page 22) Sets the image to use for the specified state. (page 14) property The tint color to apply to the button title and image.

showsTouchWhenHighlighted

backgroundImageForState:

imageForState:

setBackgroundImage:forState:

setImage:forState:

tintColor

Configuring Edge Insets

contentEdgeInsets

(page 9) property The inset or outset margins for the rectangle surrounding all of the buttons content. (page 15) property The inset or outset margins for the rectangle around the buttons title text. (page 12) property The inset or outset margins for the rectangle around the buttons image.

titleEdgeInsets

imageEdgeInsets

Getting the Current State

buttonType

(page 8) property The button type. (read-only) (page 11) property The current title that is displayed on the button. (read-only) (page 9) property The current styled title that is displayed on the button. (read-only)

currentTitle

currentAttributedTitle

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

UIButton Class Reference Tasks

currentTitleColor

(page 11) property The color used to display the title. (read-only) (page 12) property The color of the titles shadow. (read-only) (page 10) property The current image displayed on the button. (read-only) (page 10) property The current background image displayed on the button. (read-only) (page 13) property The buttons image view. (read-only)

currentTitleShadowColor

currentImage

currentBackgroundImage

imageView

Getting Dimensions
backgroundRectForBounds:

(page 18) Returns the rectangle in which the receiver draws its background. (page 19) Returns the rectangle in which the receiver draws its entire content. (page 26) Returns the rectangle in which the receiver draws its title. (page 20) Returns the rectangle in which the receiver draws its image.

contentRectForBounds:

titleRectForContentRect:

imageRectForContentRect:

Deprecated Properties
font

(page 29) property Deprecated in iOS 3.0 The font used to display text on the button. (Deprecated. Use the font property of the titleLabel (page 15) instead.) (page 29) property Deprecated in iOS 3.0 The line break mode to use when drawing text. (Deprecated. Use the lineBreakMode property of the titleLabel (page 15) instead.) (page 30) property Deprecated in iOS 3.0 The offset of the shadow used to display the receivers title. (Deprecated. Use the shadowOffset property of the titleLabel (page 15) instead.)

lineBreakMode

titleShadowOffset

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

UIButton Class Reference Properties

Properties
adjustsImageWhenDisabled
A Boolean value that determines whether the image changes when the button is disabled.
@property(nonatomic) BOOL adjustsImageWhenDisabled

Discussion If YES, the image is drawn darker when the button is disabled. The default value is YES. Availability Available in iOS 2.0 and later. See Also
@property adjustsImageWhenHighlighted

(page 8)

Declared in
UIButton.h

adjustsImageWhenHighlighted
A Boolean value that determines whether the image changes when the button is highlighted.
@property(nonatomic) BOOL adjustsImageWhenHighlighted

Discussion If YES, the image is drawn lighter when the button is highlighted. The default value is YES. Availability Available in iOS 2.0 and later. See Also
@property adjustsImageWhenDisabled

(page 8)

Declared in
UIButton.h

buttonType
The button type. (read-only)

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

UIButton Class Reference Properties

@property(nonatomic, readonly) UIButtonType buttonType

Discussion See UIButtonType (page 27) for the possible values. Availability Available in iOS 2.0 and later. Declared in
UIButton.h

contentEdgeInsets
The inset or outset margins for the rectangle surrounding all of the buttons content.
@property(nonatomic) UIEdgeInsets contentEdgeInsets

Discussion Use this property to resize and reposition the effective drawing rectangle for the button content. The content comprises the button image and button title. You can specify a different value for each of the four insets (top, left, bottom, right). A positive value shrinks, or insets, that edgemoving it closer to the center of the button. A negative value expands, or outsets, that edge. Use the UIEdgeInsetsMake function to construct a value for this property. The default value is UIEdgeInsetsZero. The button uses this property to determine intrinsicContentSize and sizeThatFits:. Availability Available in iOS 2.0 and later. See Also (page 12) @property titleEdgeInsets (page 15)
@property imageEdgeInsets

Declared in
UIButton.h

currentAttributedTitle
The current styled title that is displayed on the button. (read-only)

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

UIButton Class Reference Properties

@property(nonatomic, readonly, retain) NSAttributedString *currentAttributedTitle

Discussion The value for this property reflects the title associated with the controls current state. For states that do not have a custom title string associated with them, this method returns the attributed title that is currently displayed, which is typically the one associated with the UIControlStateNormal state. Availability Available in iOS 6.0 and later. Declared in
UIButton.h

currentBackgroundImage
The current background image displayed on the button. (read-only)
@property(nonatomic, readonly, retain) UIImage *currentBackgroundImage

Discussion This value can be nil. Availability Available in iOS 2.0 and later. See Also
@property currentImage

(page 10)

Declared in
UIButton.h

currentImage
The current image displayed on the button. (read-only)
@property(nonatomic, readonly, retain) UIImage *currentImage

Discussion This value can be nil. Availability Available in iOS 2.0 and later.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

10

UIButton Class Reference Properties

See Also
@property currentBackgroundImage

(page 10)

Declared in
UIButton.h

currentTitle
The current title that is displayed on the button. (read-only)
@property(nonatomic, readonly, retain) NSString *currentTitle

Discussion The value for this property is set automatically whenever the button state changes. For states that do not have a custom title string associated with them, this method returns the title that is currently displayed, which is typically the one associated with the UIControlStateNormal state. The value may be nil. Availability Available in iOS 2.0 and later. See Also
setTitle:forState:

(page 22)

(page 11) @property currentTitleShadowColor (page 12) @property titleLabel (page 15)
@property currentTitleColor

Declared in
UIButton.h

currentTitleColor
The color used to display the title. (read-only)
@property(nonatomic, readonly, retain) UIColor *currentTitleColor

Discussion This value is guaranteed not to be nil. The default value is white. Availability Available in iOS 2.0 and later. See Also
@property currentTitle

(page 11)

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

11

UIButton Class Reference Properties

@property currentTitleShadowColor

(page 12)

Related Sample Code

GKTapper

Declared in
UIButton.h

currentTitleShadowColor
The color of the titles shadow. (read-only)
@property(nonatomic, readonly, retain) UIColor *currentTitleShadowColor

Discussion The default value is white. Availability Available in iOS 2.0 and later. See Also (page 11) @property currentTitleColor (page 11)
@property currentTitle

Declared in
UIButton.h

imageEdgeInsets
The inset or outset margins for the rectangle around the buttons image.
@property(nonatomic) UIEdgeInsets imageEdgeInsets

Discussion Use this property to resize and reposition the effective drawing rectangle for the button image. You can specify a different value for each of the four insets (top, left, bottom, right). A positive value shrinks, or insets, that edgemoving it closer to the center of the button. A negative value expands, or outsets, that edge. Use the UIEdgeInsetsMake function to construct a value for this property. The default value is UIEdgeInsetsZero. This property is used only for positioning the image during layout. The button does not use this property to determine intrinsicContentSize and sizeThatFits:.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

12

UIButton Class Reference Properties

Availability Available in iOS 2.0 and later. See Also (page 9) @property titleEdgeInsets (page 15)
@property contentEdgeInsets

Declared in
UIButton.h

imageView
The buttons image view. (read-only)
@property(nonatomic, readonly, retain) UIImageView *imageView

Discussion Although this property is read-only, its own properties are read/write. Use these properties to configure the appearance and behavior of the buttons view. For example:
UIButton *button button.imageView.exclusiveTouch = [UIButton buttonWithType: UIButtonTypeSystem]; = YES;

The imageView property returns a value even if the button has not been displayed yet. The value of the property is nil for system buttons. Availability Available in iOS 3.0 and later. Declared in
UIButton.h

reversesTitleShadowWhenHighlighted
A Boolean value that determines whether the title shadow changes when the button is highlighted.
@property(nonatomic) BOOL reversesTitleShadowWhenHighlighted

Discussion If YES, the shadow changes from engrave to emboss appearance when highlighted. The default value is NO.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

13

UIButton Class Reference Properties

Availability Available in iOS 2.0 and later. Declared in

UIButton.h

showsTouchWhenHighlighted
A Boolean value that determines whether tapping the button causes it to glow.
@property(nonatomic) BOOL showsTouchWhenHighlighted

Discussion If YES, the button glows when tapped; otherwise, it does not. The image and button behavior is not changed by the glow. The default value is NO. Availability Available in iOS 2.0 and later. See Also
@property adjustsImageWhenHighlighted

(page 8)

Declared in
UIButton.h

tintColor
The tint color to apply to the button title and image.
@property(nonatomic, retain) UIColor *tintColor

Discussion In iOS v7.0, all subclasses of UIView derive their behavior for tintColor from the base class. See the discussion of tintColor at the UIView level for more information. This property has no default effect for buttons with type UIButtonTypeCustom (page 27). For custom buttons, you must implement any behavior related to tintColor (page 14) yourself. Availability Available in iOS 5.0 and later. Declared in
UIButton.h

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

14

UIButton Class Reference Properties

titleEdgeInsets
The inset or outset margins for the rectangle around the buttons title text.
@property(nonatomic) UIEdgeInsets titleEdgeInsets

Discussion Use this property to resize and reposition the effective drawing rectangle for the button title. You can specify a different value for each of the four insets (top, left, bottom, right). A positive value shrinks, or insets, that edgemoving it closer to the center of the button. A negative value expands, or outsets, that edge. Use the UIEdgeInsetsMake function to construct a value for this property. The default value is UIEdgeInsetsZero. The insets you specify are applied to the title rectangle after that rectangle has been sized to fit the buttons text. Thus, positive inset values may actually clip the title text. This property is used only for positioning the title during layout. The button does not use this property to determine intrinsicContentSize and sizeThatFits:. Availability Available in iOS 2.0 and later. See Also (page 9) @property imageEdgeInsets (page 12)
@property contentEdgeInsets

Declared in
UIButton.h

titleLabel
A view that displays the value of the currentTitle property for a button. (read-only)
@property(nonatomic, readonly, retain) UILabel *titleLabel

Discussion Although this property is read-only, its own properties are read/write. Use these properties primarily to configure the text of the button. For example:
UIButton *button button.titleLabel.font button.titleLabel.lineBreakMode = [UIButton buttonWithType: UIButtonTypeSystem]; = [UIFont systemFontOfSize: 12]; = UILineBreakModeTailTruncation;

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

15

UIButton Class Reference Class Methods

Do not use the label object to set the text color or the shadow color. Instead, use the setTitleColor:forState: (page 23) and setTitleShadowColor:forState: (page 24) methods of this class to make those changes. The titleLabel property returns a value even if the button has not been displayed yet. The value of the property is nil for system buttons. Availability Available in iOS 3.0 and later. See Also
@property currentTitle

(page 11)

Related Sample Code

GKTapper

Declared in
UIButton.h

Class Methods
buttonWithType:
Creates and returns a new button of the specified type.
+ (id)buttonWithType:(UIButtonType)buttonType

Parameters
buttonType

The button type. See UIButtonType (page 27) for the possible values. Return Value A newly created button. Discussion This method is a convenience constructor for creating button objects with specific configurations. If you subclass UIButton, this method does not return an instance of your subclass. If you want to create an instance of a specific subclass, you must alloc/init the button directly. When creating a custom buttonthat is a button with the type UIButtonTypeCustom (page 27)the frame of the button is set to (0, 0, 0, 0) initially. Before adding the button to your interface, you should update the frame to a more appropriate value.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

16

UIButton Class Reference Instance Methods

Availability Available in iOS 2.0 and later.

Related Sample Code

Accessory iPhoneMixerEQGraphTest iPhoneMultichannelMixerTest UICatalog XMLPerformance Declared in

UIButton.h

Instance Methods
attributedTitleForState:
Returns the styled title associated with the specified state.
- (NSAttributedString *)attributedTitleForState:(UIControlState)state

Parameters
state

The state that uses the styled title. The possible values are described in UIControlState. Return Value The title for the specified state. If no attributed title has been set for the specific state, this method returns the attributed title associated with the UIControlStateNormal state. If no attributed title has been set for UIControlStateNormal, returns nil. Availability Available in iOS 6.0 and later. Declared in
UIButton.h

backgroundImageForState:
Returns the background image used for a button state.
- (UIImage *)backgroundImageForState:(UIControlState)state

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

17

UIButton Class Reference Instance Methods

Parameters
state

The state that uses the background image. Possible values are described in UIControlState. Return Value The background image used for the specified state. Availability Available in iOS 2.0 and later. See Also
setBackgroundImage:forState:

(page 21)

Declared in
UIButton.h

backgroundRectForBounds:
Returns the rectangle in which the receiver draws its background.
- (CGRect)backgroundRectForBounds:(CGRect)bounds

Parameters
bounds

The bounding rectangle of the receiver. Return Value The bounds rectangle in which to draw any standard button content. Discussion The default implementation of this method returns the value in the bounds parameter. This rectangle represents the area in which the button draws its standard background content. Subclasses that provide custom background adornments can override this method and return a modified bounds rectangle to prevent the button from drawing over any custom content. Availability Available in iOS 2.0 and later. See Also
contentRectForBounds:

(page 19)

Declared in
UIButton.h

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

18

UIButton Class Reference Instance Methods

contentRectForBounds:
Returns the rectangle in which the receiver draws its entire content.
- (CGRect)contentRectForBounds:(CGRect)bounds

Parameters
bounds

The bounding rectangle for the receiver. Return Value The rectangle in which the receiver draws its entire content. Discussion The content rectangle is the area needed to display the image and title including any padding and adjustments for alignment and other settings. Availability Available in iOS 2.0 and later. See Also (page 9) backgroundRectForBounds: (page 18)
@property contentEdgeInsets

Declared in
UIButton.h

imageForState:
Returns the image used for a button state.
- (UIImage *)imageForState:(UIControlState)state

Parameters
state

The state that uses the image. Possible values are described in UIControlState. Return Value The image used for the specified state. Availability Available in iOS 2.0 and later.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

19

UIButton Class Reference Instance Methods

See Also
setImage:forState:

(page 22)

Declared in
UIButton.h

imageRectForContentRect:
Returns the rectangle in which the receiver draws its image.
- (CGRect)imageRectForContentRect:(CGRect)contentRect

Parameters
contentRect

The content rectangle for the receiver. Return Value The rectangle in which the receiver draws its image. Availability Available in iOS 2.0 and later. See Also (page 19) titleRectForContentRect: (page 26)
contentRectForBounds:

Declared in
UIButton.h

setAttributedTitle:forState:
Sets the styled title to use for the specified state.
- (void)setAttributedTitle:(NSAttributedString *)title forState:(UIControlState)state

Parameters
title

The styled text string so use for the title.

state

The state that uses the specified title. The possible values are described in UIControlState.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

20

UIButton Class Reference Instance Methods

Discussion Use this method to set the title of the button, including any relevant formatting information. If you set both a title and an attributed title for the button, the button prefers the use of the attributed title. At a minimum, you should set the value for the normal state. If a title is not specified for a state, the default behavior is to use the title associated with the UIControlStateNormal state. If the value for UIControlStateNormal is not set, then the property defaults to a system value. Availability Available in iOS 6.0 and later. Declared in
UIButton.h

setBackgroundImage:forState:
Sets the background image to use for the specified button state.
- (void)setBackgroundImage:(UIImage *)image forState:(UIControlState)state

Parameters
image

The background image to use for the specified state.

state

The state that uses the specified image. The values are described in UIControlState. Discussion In general, if a property is not specified for a state, the default is to use the UIControlStateNormal value. If the UIControlStateNormal value is not set, then the property defaults to a system value. Therefore, at a minimum, you should set the value for the normal state. Availability Available in iOS 2.0 and later. See Also
backgroundImageForState:

(page 17)

Related Sample Code

Accessory AddMusic UICatalog

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

21

UIButton Class Reference Instance Methods

Declared in
UIButton.h

setImage:forState:
Sets the image to use for the specified state.
- (void)setImage:(UIImage *)image forState:(UIControlState)state

Parameters
image

The image to use for the specified state.

state

The state that uses the specified title. The values are described in UIControlState. Discussion In general, if a property is not specified for a state, the default is to use the UIControlStateNormal value. If the UIControlStateNormal value is not set, then the property defaults to a system value. Therefore, at a minimum, you should set the value for the normal state. Availability Available in iOS 2.0 and later. See Also
imageForState:

(page 19)

Related Sample Code

Regions WiTap

Declared in
UIButton.h

setTitle:forState:
Sets the title to use for the specified state.
- (void)setTitle:(NSString *)title forState:(UIControlState)state

Parameters
title

The title to use for the specified state.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

22

UIButton Class Reference Instance Methods

state

The state that uses the specified title. The possible values are described in UIControlState. Discussion Use this method to set the title for the button. The title you specify derives its formatting from the buttons associated label object. If you set both a title and an attributed title for the button, the button prefers the use of the attributed title over this one. At a minimum, you should set the value for the normal state. If a title is not specified for a state, the default behavior is to use the title associated with the UIControlStateNormal state. If the value for UIControlStateNormal is not set, then the property defaults to a system value. Availability Available in iOS 2.0 and later. See Also
titleForState:

(page 25)

Related Sample Code

UICatalog XMLPerformance Declared in

UIButton.h

setTitleColor:forState:
Sets the color of the title to use for the specified state.
- (void)setTitleColor:(UIColor *)color forState:(UIControlState)state

Parameters
color

The color of the title to use for the specified state.

state

The state that uses the specified color. The possible values are described in UIControlState. Discussion In general, if a property is not specified for a state, the default is to use the UIControlStateNormal value. If the UIControlStateNormal value is not set, then the property defaults to a system value. Therefore, at a minimum, you should set the value for the normal state.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

23

UIButton Class Reference Instance Methods

Availability Available in iOS 2.0 and later. See Also

titleColorForState:

(page 24)

Related Sample Code

UICatalog

Declared in
UIButton.h

setTitleShadowColor:forState:
Sets the color of the title shadow to use for the specified state.
- (void)setTitleShadowColor:(UIColor *)color forState:(UIControlState)state

Parameters
color

The color of the title shadow to use for the specified state.
state

The state that uses the specified color. The possible values are described in UIControlState. Discussion In general, if a property is not specified for a state, the default is to use the UIControlStateNormal value. If the UIControlStateNormal value is not set, then the property defaults to a system value. Therefore, at a minimum, you should set the value for the normal state. Availability Available in iOS 2.0 and later. See Also
titleShadowColorForState:

(page 26)

Declared in
UIButton.h

titleColorForState:
Returns the title color used for a state.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

24

UIButton Class Reference Instance Methods

- (UIColor *)titleColorForState:(UIControlState)state

Parameters
state

The state that uses the title color. The possible values are described in UIControlState. Return Value The color of the title for the specified state. Availability Available in iOS 2.0 and later. See Also
setTitleColor:forState:

(page 23)

Declared in
UIButton.h

titleForState:
Returns the title associated with the specified state.
- (NSString *)titleForState:(UIControlState)state

Parameters
state

The state that uses the title. The possible values are described in UIControlState. Return Value The title for the specified state. If no title has been set for the specific state, this method returns the title associated with the UIControlStateNormal state. Availability Available in iOS 2.0 and later. See Also
setTitle:forState:

(page 22)

Declared in
UIButton.h

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

25

UIButton Class Reference Instance Methods

titleRectForContentRect:
Returns the rectangle in which the receiver draws its title.
- (CGRect)titleRectForContentRect:(CGRect)contentRect

Parameters
contentRect

The content rectangle for the receiver. Return Value The rectangle in which the receiver draws its title. Availability Available in iOS 2.0 and later. See Also (page 19) imageRectForContentRect: (page 20)
contentRectForBounds:

Declared in
UIButton.h

titleShadowColorForState:
Returns the shadow color of the title used for a state.
- (UIColor *)titleShadowColorForState:(UIControlState)state

Parameters
state

The state that uses the title shadow color. The possible values are described in UIControlState. Return Value The color of the titles shadow for the specified state. Availability Available in iOS 2.0 and later. See Also
setTitleShadowColor:forState:

(page 24)

Declared in
UIButton.h

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

26

UIButton Class Reference Constants

Constants
UIButtonType
Specifies the style of a button.

typedef enum { UIButtonTypeCustom = 0, UIButtonTypeSystem, UIButtonTypeDetailDisclosure, UIButtonTypeInfoLight, UIButtonTypeInfoDark, UIButtonTypeContactAdd, UIButtonTypeRoundedRect, } UIButtonType;

Constants
UIButtonTypeCustom

No button style. Available in iOS 2.0 and later. Declared in UIButton.h.

UIButtonTypeSystem

A system style button, such as those shown in navigation bars and toolbars. Available in iOS 7.0 and later. Declared in UIButton.h.
UIButtonTypeDetailDisclosure

A detail disclosure button. Available in iOS 2.0 and later. Declared in UIButton.h.
UIButtonTypeInfoLight

An information button that has a light background. Available in iOS 2.0 and later. Declared in UIButton.h.
UIButtonTypeInfoDark

An information button that has a dark background. Available in iOS 2.0 and later. Declared in UIButton.h.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

27

UIButton Class Reference Constants

UIButtonTypeContactAdd

A contact add button. Available in iOS 2.0 and later. Declared in UIButton.h.
UIButtonTypeRoundedRect

A rounded-rectangle style button. (Deprecated. Use UIButtonTypeSystem (page 27) instead.) Deprecated in iOS 7.0. Declared in UIButton.h. Availability Available in iOS 2.0 and later. Declared in
UIButton.h

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

28

Deprecated UIButton Methods

A method identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in iOS 3.0

font
The font used to display text on the button. (Deprecated in iOS 3.0. Use the font property of the titleLabel (page 15) instead.)
@property(nonatomic, retain) UIFont *font

Discussion If nil, a system font is used. The default value is nil. Availability Available in iOS 2.0 and later. Deprecated in iOS 3.0. See Also
@property titleLabel

(page 15)

Declared in
UIButton.h

lineBreakMode
The line break mode to use when drawing text. (Deprecated in iOS 3.0. Use the lineBreakMode property of the titleLabel (page 15) instead.)
@property(nonatomic) NSLineBreakMode lineBreakMode

Discussion This property is one of the constants described in the UILineBreakMode enumeration in NSString UIKit Additions Reference . The default value is UILineBreakModeMiddleTruncation.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

29

Deprecated UIButton Methods Deprecated in iOS 3.0

Availability Available in iOS 2.0 and later. Deprecated in iOS 3.0. See Also
@property titleLabel

(page 15)

Declared in
UIButton.h

titleShadowOffset
The offset of the shadow used to display the receivers title. (Deprecated in iOS 3.0. Use the shadowOffset property of the titleLabel (page 15) instead.)
@property(nonatomic) CGSize titleShadowOffset

Discussion The horizontal and vertical offset values, specified using the width and height fields of the CGSize data type. Positive values always extend up and to the right from the user's perspective. The default value is CGSizeZero. Availability Available in iOS 2.0 and later. Deprecated in iOS 3.0. See Also
@property titleLabel

(page 15)

Declared in
UIButton.h

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

30

Document Revision History

This table describes the changes to UIButton Class Reference .

Date 2013-09-18

Notes Added description for the UIButtonTypeSystem property, new in iOS 7; clarified the return value description for the attributedTitleForState: method. Clarified the return value description in attributedTitleForState: (page 17). Changed the code snippets in the descriptions of the imageView (page 13) and titleLabel (page 15) properties to employ the UIButtonTypeSystem (page 27) constant, new in iOS 7.

2012-09-19 2011-10-12 2009-09-09

Added a new interfaces related to styled-text support in iOS 6. Updated for iOS 5.0. Clarified descriptions of the contentEdgeInsets (page 9), titleEdgeInsets (page 15), and imageEdgeInsets (page 12) properties. Other minor improvements.

2009-04-23

Updated for iOS 3.0. Added descriptions for the titleLabel (page 15) and imageView (page 13) properties. Minor corrections.

2008-05-23

New document that describes the class used to implement buttons on the touch screen.

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

31

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