| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/UIKit.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Declared in | UIButton.h |
| Related sample code |
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.
buttonType property
font property
lineBreakMode property
titleShadowOffset property
titleLabel property
reversesTitleShadowWhenHighlighted property
– setTitle:forState:
– setTitleColor:forState:
– setTitleShadowColor:forState:
– titleColorForState:
– titleForState:
– titleShadowColorForState:
adjustsImageWhenHighlighted property
adjustsImageWhenDisabled property
showsTouchWhenHighlighted property
– backgroundImageForState:
– imageForState:
– setBackgroundImage:forState:
– setImage:forState:
contentEdgeInsets property
titleEdgeInsets property
imageEdgeInsets property
currentTitle property
currentTitleColor property
currentTitleShadowColor property
currentImage property
currentBackgroundImage property
imageView property
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
A Boolean value that determines whether the image changes when the button is disabled.
@property(nonatomic) BOOL adjustsImageWhenDisabled
If YES, the image is drawn darker when the button is disabled. The default value is YES.
UIButton.hA Boolean value that determines whether the image changes when the button is highlighted.
@property(nonatomic) BOOL adjustsImageWhenHighlighted
If YES, the image is drawn lighter when the button is highlighted. The default value is YES.
UIButton.hThe button type. (read-only)
@property(nonatomic, readonly) UIButtonType buttonType
See UIButtonType for the possible values.
UIButton.hThe inset or outset margins for the edges of the button content drawing rectangle.
@property(nonatomic) UIEdgeInsets contentEdgeInsets
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.
UIButton.hThe current background image displayed on the button. (read-only)
@property(nonatomic, readonly, retain) UIImage *currentBackgroundImage
This value can be nil.
UIButton.hThe current image displayed on the button. (read-only)
@property(nonatomic, readonly, retain) UIImage *currentImage
This value can be nil.
UIButton.hThe current title that is displayed on the button. (read-only)
@property(nonatomic, readonly, retain) NSString *currentTitle
The value for this property is set automatically whenever the button state changes. The value may be nil.
– setTitle:forState: @property currentTitleColor @property currentTitleShadowColor @property titleLabelUIButton.hThe color used to display the title. (read-only)
@property(nonatomic, readonly, retain) UIColor *currentTitleColor
This value is guaranteed not to be nil. The default value is white.
UIButton.hThe color of the title’s shadow. (read-only)
@property(nonatomic, readonly, retain) UIColor *currentTitleShadowColor
The default value is white.
UIButton.hThe font used to display text on the button. (Deprecated. Use the font property of the titleLabel instead.)
@property(nonatomic, retain) UIFont *font
If nil, a system font is used. The default value is nil.
UIButton.hThe inset or outset margins for the edges of the button image drawing rectangle.
@property(nonatomic) UIEdgeInsets imageEdgeInsets
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.
UIButton.hThe button’s image view. (read-only)
@property(nonatomic,readonly,retain) UIImageView *imageView
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.
UIButton.hThe line break mode to use when drawing text. (Deprecated. Use the lineBreakMode property of the titleLabel instead.)
@property(nonatomic) UILineBreakMode lineBreakMode
This property is one of the constants described in the UILineBreakMode enumeration in NSString UIKit Additions Reference. The default value is UILineBreakModeMiddleTruncation.
UIButton.hA Boolean value that determines whether the title shadow changes when the button is highlighted.
@property(nonatomic) BOOL reversesTitleShadowWhenHighlighted
If YES, the shadow changes from engrave to emboss appearance when highlighted. The default value is NO.
UIButton.hA Boolean value that determines whether tapping the button causes it to glow.
@property(nonatomic) BOOL showsTouchWhenHighlighted
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.
UIButton.hThe inset or outset margins for the edges of the button title drawing rectangle.
@property(nonatomic) UIEdgeInsets titleEdgeInsets
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.
UIButton.hA view that displays the value of the currentTitle property for a button. (read-only)
@property(nonatomic,readonly,retain) UILabel *titleLabel
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.
UIButton.hThe offset of the shadow used to display the receiver’s title. (Deprecated. Use the shadowOffset property of the titleLabel instead.)
@property(nonatomic) CGSize titleShadowOffset
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.
UIButton.hCreates and returns a new button of the specified type.
+ (id)buttonWithType:(UIButtonType)buttonType
The button type. See UIButtonType for the possible values.
A newly created button.
UIButton.hReturns the background image used for a button state.
- (UIImage *)backgroundImageForState:(UIControlState)state
The state that uses the background image. Possible values are described in UIControlState.
The background image used for the specified state.
UIButton.hReturns the rectangle in which the receiver draws its background.
- (CGRect)backgroundRectForBounds:(CGRect)bounds
The bounding rectangle of the receiver.
The rectangle in which the receiver draws its background.
UIButton.hReturns the rectangle in which the receiver draws its entire content.
- (CGRect)contentRectForBounds:(CGRect)bounds
The bounding rectangle for the receiver.
The rectangle in which the receiver draws its entire content.
The content rectangle is the area needed to display the image and title including any padding and adjustments for alignment and other settings.
UIButton.hReturns the image used for a button state.
- (UIImage *)imageForState:(UIControlState)state
The state that uses the image. Possible values are described in UIControlState.
The image used for the specified state.
UIButton.hReturns the rectangle in which the receiver draws its image.
- (CGRect)imageRectForContentRect:(CGRect)contentRect
The content rectangle for the receiver.
The rectangle in which the receiver draws its image.
UIButton.hSets the background image to use for the specified button state.
- (void)setBackgroundImage:(UIImage *)image forState:(UIControlState)state
The background image to use for the specified state.
The state that uses the specified image. The values are described in UIControlState.
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.
UIButton.hSets the image to use for the specified state.
- (void)setImage:(UIImage *)image forState:(UIControlState)state
The image to use for the specified state.
The state that uses the specified title. The values are described in UIControlState.
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.
UIButton.hSets the title to use for the specified state.
- (void)setTitle:(NSString *)title forState:(UIControlState)state
The title to use for the specified state.
The state that uses the specified title. The values are described in UIControlState.
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.
UIButton.hSets the color of the title to use for the specified state.
- (void)setTitleColor:(UIColor *)color forState:(UIControlState)state
The color of the title to use for the specified state.
The state that uses the specified color. The values are described in UIControlState.
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.
UIButton.hSets the color of the title shadow to use for the specified state.
- (void)setTitleShadowColor:(UIColor *)color forState:(UIControlState)state
The color of the title shadow to use for the specified state.
The state that uses the specified color. The values are described in UIControlState.
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.
UIButton.hReturns the title color used for a state.
- (UIColor *)titleColorForState:(UIControlState)state
The state that uses the title color. Possible values are described in UIControlState.
The color of the title for the specified state.
UIButton.hReturns the title used for a state.
- (NSString *)titleForState:(UIControlState)state
The state that uses the title. Possible values are described in UIControlState.
The title for the specified state.
UIButton.hReturns the rectangle in which the receiver draws its title.
- (CGRect)titleRectForContentRect:(CGRect)contentRect
The content rectangle for the receiver.
The rectangle in which the receiver draws its title.
UIButton.hReturns the shadow color of the title used for a state.
- (UIColor *)titleShadowColorForState:(UIControlState)state
The state that uses the title shadow color. Possible values are described in UIControlState.
The color of the title’s shadow for the specified state.
UIButton.hSpecifies the style of a button.
typedef enum {
UIButtonTypeCustom = 0,
UIButtonTypeRoundedRect,
UIButtonTypeDetailDisclosure,
UIButtonTypeInfoLight,
UIButtonTypeInfoDark,
UIButtonTypeContactAdd,
} UIButtonType;
UIButtonTypeCustomNo button style.
Available in iPhone OS 2.0 and later.
Declared in UIButton.h.
UIButtonTypeRoundedRectA rounded-rectangle style button.
Available in iPhone OS 2.0 and later.
Declared in UIButton.h.
UIButtonTypeDetailDisclosureA detail disclosure button.
Available in iPhone OS 2.0 and later.
Declared in UIButton.h.
UIButtonTypeInfoLightAn information button that has a light background.
Available in iPhone OS 2.0 and later.
Declared in UIButton.h.
UIButtonTypeInfoDarkAn information button that has a dark background.
Available in iPhone OS 2.0 and later.
Declared in UIButton.h.
UIButtonTypeContactAddA contact add button.
Available in iPhone OS 2.0 and later.
Declared in UIButton.h.
UIButton.hLast updated: 2009-09-09
