Class: UIButton

Inherits:
UIControl show all

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.

Instance Attribute Summary (collapse)

Attributes inherited from UIControl

#contentHorizontalAlignment, #contentVerticalAlignment, #enabled, #highlighted, #selected, #state, #touchInside, #tracking

Attributes inherited from UIView

#alpha, #autoresizesSubviews, #autoresizingMask, #backgroundColor, #bounds, #center, #clearsContextBeforeDrawing, #clipsToBounds, #contentMode, #contentScaleFactor, #exclusiveTouch, #frame, #gestureRecognizers, #hidden, #layer, #multipleTouchEnabled, #opaque, #restorationIdentifier, #subviews, #superview, #tag, #transform, #userInteractionEnabled, #window

Attributes inherited from UIResponder

#inputAccessoryView, #inputView, #undoManager

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from UIControl

#actionsForTarget:forControlEvent:, #addTarget:action:forControlEvents:, #allControlEvents, #allTargets, #beginTrackingWithTouch:withEvent:, #cancelTrackingWithEvent:, #continueTrackingWithTouch:withEvent:, #endTrackingWithTouch:withEvent:, #removeTarget:action:forControlEvents:, #sendAction:to:forEvent:, #sendActionsForControlEvents:

Methods inherited from UIView

#addConstraint:, #addConstraints:, #addGestureRecognizer:, #addSubview:, #alignmentRectForFrame:, #alignmentRectInsets, animateWithDuration:animations:, animateWithDuration:animations:completion:, animateWithDuration:delay:options:animations:completion:, areAnimationsEnabled, beginAnimations:context:, #bringSubviewToFront:, commitAnimations, #constraints, #constraintsAffectingLayoutForAxis:, #contentCompressionResistancePriorityForAxis:, #contentHuggingPriorityForAxis:, #convertPoint:fromView:, #convertPoint:toView:, #convertRect:fromView:, #convertRect:toView:, #decodeRestorableStateWithCoder:, #didAddSubview:, #didMoveToSuperview, #didMoveToWindow, #drawRect:, #drawRect:forViewPrintFormatter:, #encodeRestorableStateWithCoder:, #endEditing:, #exchangeSubviewAtIndex:withSubviewAtIndex:, #exerciseAmbiguityInLayout, #frameForAlignmentRect:, #gestureRecognizerShouldBegin:, #hasAmbiguousLayout, #hitTest:withEvent:, #initWithFrame:, #insertSubview:aboveSubview:, #insertSubview:atIndex:, #insertSubview:belowSubview:, #intrinsicContentSize, #invalidateIntrinsicContentSize, #isDescendantOfView:, layerClass, #layoutIfNeeded, #layoutSubviews, #needsUpdateConstraints, #pointInside:withEvent:, #removeConstraint:, #removeConstraints:, #removeFromSuperview, #removeGestureRecognizer:, requiresConstraintBasedLayout, #sendSubviewToBack:, setAnimationBeginsFromCurrentState:, setAnimationCurve:, setAnimationDelay:, setAnimationDelegate:, setAnimationDidStopSelector:, setAnimationDuration:, setAnimationRepeatAutoreverses:, setAnimationRepeatCount:, setAnimationStartDate:, setAnimationTransition:forView:cache:, setAnimationWillStartSelector:, setAnimationsEnabled:, #setContentCompressionResistancePriority:forAxis:, #setContentHuggingPriority:forAxis:, #setNeedsDisplay, #setNeedsDisplayInRect:, #setNeedsLayout, #setNeedsUpdateConstraints, #setTranslatesAutoresizingMaskIntoConstraints:, #sizeThatFits:, #sizeToFit, #systemLayoutSizeFittingSize:, transitionFromView:toView:duration:options:completion:, transitionWithView:duration:options:animations:completion:, #translatesAutoresizingMaskIntoConstraints, #updateConstraints, #updateConstraintsIfNeeded, #viewForBaselineLayout, #viewPrintFormatter, #viewWithTag:, #willMoveToSuperview:, #willMoveToWindow:, #willRemoveSubview:

Methods inherited from UIResponder

#becomeFirstResponder, #canBecomeFirstResponder, #canPerformAction:withSender:, #canResignFirstResponder, #isFirstResponder, #motionBegan:withEvent:, #motionCancelled:withEvent:, #motionEnded:withEvent:, #nextResponder, #reloadInputViews, #remoteControlReceivedWithEvent:, #resignFirstResponder, #touchesBegan:withEvent:, #touchesCancelled:withEvent:, #touchesEnded:withEvent:, #touchesMoved:withEvent:

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Instance Attribute Details

- (Boolean) adjustsImageWhenDisabled

A Boolean value that determines whether the image changes when the button is disabled. If YES, the image is drawn darker when the button is disabled. The default value is YES.

Returns:

  • (Boolean)

- (Boolean) adjustsImageWhenHighlighted

A Boolean value that determines whether the image changes when the button is highlighted. If YES, the image is drawn lighter when the button is highlighted. The default value is YES.

Returns:

  • (Boolean)

- (UIButtonType) buttonType (readonly)

The button type. (read-only) See UIButtonType for the possible values.

Returns:

- (UIEdgeInsets) contentEdgeInsets

The inset or outset margins for the rectangle surrounding all of the button’s content. 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.

Returns:

- (NSAttributedString) currentAttributedTitle (readonly)

The current styled title that is displayed on the button. (read-only) The value for this property reflects the title associated with the control’s 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.

Returns:

- (UIImage) currentBackgroundImage (readonly)

The current background image displayed on the button. (read-only) This value can be nil.

Returns:

- (UIImage) currentImage (readonly)

The current image displayed on the button. (read-only) This value can be nil.

Returns:

- (String) currentTitle (readonly)

The current title that is displayed on the button. (read-only) 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.

Returns:

- (UIColor) currentTitleColor (readonly)

The color used to display the title. (read-only) This value is guaranteed not to be nil. The default value is white.

Returns:

- (UIColor) currentTitleShadowColor (readonly)

The color of the title’s shadow. (read-only) The default value is white.

Returns:

- (UIEdgeInsets) imageEdgeInsets

The inset or outset margins for the rectangle around the button’s image. 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.

Returns:

- (UIImageView) imageView (readonly)

The button’s image view. (read-only) 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: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.

Returns:

- (Boolean) reversesTitleShadowWhenHighlighted

A Boolean value that determines whether the title shadow changes when the button is highlighted. If YES, the shadow changes from engrave to emboss appearance when highlighted. The default value is NO.

Returns:

  • (Boolean)

- (Boolean) showsTouchWhenHighlighted

A Boolean value that determines whether tapping the button causes it to glow. 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.

Returns:

  • (Boolean)

- (UIColor) tintColor

The tint color for the button. The default value is nil.This property is not valid for all button types.

Returns:

- (UIEdgeInsets) titleEdgeInsets

The inset or outset margins for the rectangle around the button’s title text. 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.The insets you specify are applied to the title rectangle after that rectangle has been sized to fit the button’s text. Thus, positive inset values may actually clip the title text.

Returns:

- (UILabel) titleLabel (readonly)

A view that displays the value of the currentTitle property for a button. (read-only) 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:Do not use the label object to set the text color or the shadow color. Instead, use the setTitleColor:forState: and setTitleShadowColor:forState: 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.

Returns:

Class Method Details

+ (Object) buttonWithType(buttonType)

Creates and returns a new button of the specified type. This method is a convenience constructor for creating button objects with specific configurations. It 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 button—that is a button with the type UIButtonTypeCustom—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.

Parameters:

Returns:

  • (Object)

    A newly created button.

Instance Method Details

- (NSAttributedString) attributedTitleForState(state)

Returns the styled title associated with the specified state.

Parameters:

  • state (UIControlState)

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

Returns:

  • (NSAttributedString)

    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.

- (UIImage) backgroundImageForState(state)

Returns the background image used for a button state.

Parameters:

  • state (UIControlState)

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

Returns:

  • (UIImage)

    The background image used for the specified state.

- (CGRect) backgroundRectForBounds(bounds)

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

Parameters:

  • bounds (CGRect)

    The bounding rectangle of the receiver.

Returns:

  • (CGRect)

    The bounds rectangle in which to draw any standard button content.

- (CGRect) contentRectForBounds(bounds)

Returns 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.

Parameters:

  • bounds (CGRect)

    The bounding rectangle for the receiver.

Returns:

  • (CGRect)

    The rectangle in which the receiver draws its entire content.

- (UIImage) imageForState(state)

Returns the image used for a button state.

Parameters:

  • state (UIControlState)

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

Returns:

  • (UIImage)

    The image used for the specified state.

- (CGRect) imageRectForContentRect(contentRect)

Returns the rectangle in which the receiver draws its image.

Parameters:

  • contentRect (CGRect)

    The content rectangle for the receiver.

Returns:

  • (CGRect)

    The rectangle in which the receiver draws its image.

- (Object) setAttributedTitle(title, forState:state)

Sets the styled title to use for the specified state. 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.

Parameters:

  • title (NSAttributedString)

    The styled text string so use for the title.

  • state (UIControlState)

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

Returns:

- (Object) setBackgroundImage(image, forState:state)

Sets the background image to use for the specified button state. 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.

Parameters:

  • image (UIImage)

    The background image to use for the specified state.

  • state (UIControlState)

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

Returns:

- (Object) setImage(image, forState:state)

Sets the image to use for the specified state. 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.

Parameters:

  • image (UIImage)

    The image to use for the specified state.

  • state (UIControlState)

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

Returns:

- (Object) setTitle(title, forState:state)

Sets the title to use for the specified state. Use this method to set the title for the button. The title you specify derives its formatting from the button’s 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.

Parameters:

  • title (String)

    The title to use for the specified state.

  • state (UIControlState)

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

Returns:

- (Object) setTitleColor(color, forState:state)

Sets the color of the title to use for the specified state. 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.

Parameters:

  • color (UIColor)

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

  • state (UIControlState)

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

Returns:

- (Object) setTitleShadowColor(color, forState:state)

Sets the color of the title shadow to use for the specified state. 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.

Parameters:

  • color (UIColor)

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

  • state (UIControlState)

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

Returns:

- (UIColor) titleColorForState(state)

Returns the title color used for a state.

Parameters:

  • state (UIControlState)

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

Returns:

  • (UIColor)

    The color of the title for the specified state.

- (String) titleForState(state)

Returns the title associated with the specified state.

Parameters:

  • state (UIControlState)

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

Returns:

  • (String)

    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.

- (CGRect) titleRectForContentRect(contentRect)

Returns the rectangle in which the receiver draws its title.

Parameters:

  • contentRect (CGRect)

    The content rectangle for the receiver.

Returns:

  • (CGRect)

    The rectangle in which the receiver draws its title.

- (UIColor) titleShadowColorForState(state)

Returns the shadow color of the title used for a state.

Parameters:

  • state (UIControlState)

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

Returns:

  • (UIColor)

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