iOS Reference Library Apple Developer
Search

UIButton Class Reference

Inherits from
UIControl : UIView : UIResponder : NSObject
Conforms to
NSCoding
NSCoding (UIView)
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UIButton.h
Related sample code

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.

Tasks

Creating Buttons

Configuring Button Title

Configuring Button Images

Configuring Edge Insets

Getting the Current State

Getting Dimensions

Properties

For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.

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
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
Declared In
UIButton.h

buttonType

The button type. (read-only)

@property(nonatomic, readonly) UIButtonType buttonType

Discussion

See UIButtonType for the possible values.

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

contentEdgeInsets

The inset or outset margins for the edges of the button content drawing rectangle.

@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 edge—moving 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.

Availability
  • Available in iOS 2.0 and later.
See Also
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
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.
See Also
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. The value may be nil.

Availability
  • Available in iOS 2.0 and later.
See Also
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
Declared In
UIButton.h

currentTitleShadowColor

The color of the title’s 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
Declared In
UIButton.h

imageEdgeInsets

The inset or outset margins for the edges of the button image drawing rectangle.

@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 edge—moving 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.

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

imageView

The button’s 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 button’s view. For example:

UIButton *button                   = [UIButton buttonWithType: UIButtonTypeRoundedRect];
button.imageView.exclusiveTouch    = 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.

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
Declared In
UIButton.h

titleEdgeInsets

The inset or outset margins for the edges of the button title drawing rectangle.

@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 edge—moving 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.

Availability
  • Available in iOS 2.0 and later.
See Also
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 to configure the appearance of the button label. For example:

UIButton *button                  = [UIButton buttonWithType: UIButtonTypeRoundedRect];
button.titleLabel.font            = [UIFont systemFontOfSize: 12];
button.titleLabel.lineBreakMode   = UILineBreakModeTailTruncation;
button.titleLabel.shadowOffset    = CGSizeMake (1.0, 0.0);

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
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 for the possible values.

Return Value

A newly created button.

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

Instance Methods

backgroundImageForState:

Returns the background image used for a button state.

- (UIImage *)backgroundImageForState:(UIControlState)state

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
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 rectangle in which the receiver draws its background.

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

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
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.
See Also
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
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
Related Sample Code
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
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.

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 value for UIControlStateNormal 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
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 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
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 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
Declared In
UIButton.h

titleColorForState:

Returns the title color used for a state.

- (UIColor *)titleColorForState:(UIControlState)state

Parameters
state

The state that uses the title color. 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
Declared In
UIButton.h

titleForState:

Returns the title used for a state.

- (NSString *)titleForState:(UIControlState)state

Parameters
state

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

Return Value

The title for the specified state.

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

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
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. Possible values are described in UIControlState.

Return Value

The color of the title’s shadow for the specified state.

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

Constants

UIButtonType

Specifies the style of a button.

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

No button style.

Available in iOS 2.0 and later.

Declared in UIButton.h.

UIButtonTypeRoundedRect

A rounded-rectangle style button.

Available in iOS 2.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.

UIButtonTypeContactAdd

A contact add button.

Available in iOS 2.0 and later.

Declared in UIButton.h.

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


Last updated: 2009-09-09

Did this document help you? Yes It's good, but... Not helpful...