FUIButton

open class FUIButton : UIButton, FUIButtonClosureHandling, FUIStateSelectable, FUIBackgroundSchemeSupporting, PrepareForReuse

Subclass of UIButton, which provides for rounded edge and rounded fill styles. It also provides for per-state tint colors, persistent selection, and a closure-styled tap handler.

The FUIButton implements the Fiori Design Language in default configuration.

Usage

Initialization

Init button with expected style (for default, use .tertiary).

To use FUIButton style variants in Interface Builder, the convenience subclasses FUIRoundedButton (.tertiary) and FUIRoundedFillButton (.primary) are also available.

// init with expected style.

let normalButton = FUIButton() // equivalent to FUIButton(style: .tertiary)
let roundedOutlineButton = FUIButton(style: .secondary)       // equivalent to `FUIRoundedButton()`
let roundedFilledButton = FUIButton(style: .primary)  // equivalent to `FUIRoundedFillButton()`

Setting button style and semantic attribute

There are three button styles supported: primary, secondary, and tertiary. You can also configure the semantic attribute (normal, tint, negative) for the button.

button.style = .primary
button.semantic = .negative

Setting title(s)

UIButton provides two techniques for setting its title:

  1. setTitle(_:, for:)
  2. titleLabel.text

The behavior of the (2) is inconsistent, and discouraged by Apple. As a result, titleLabel.text should be avoided in favor of technique setTitle(_:_:). The FUIButton will correct the behavior of titleLabel.text, if setTitle(_:_:) is not used. However, if the developer at any point invokes setTitle(_:, for:) directly, FUIButton will cease to correct for titleLabel.text, and will defer to the developer to use the API correctly.

button.setTitle("Follow", for: .normal)
button.setTitle("Unfollow", for: .selected)

Specify Selection Behavior

The default behavior of UIButton is to toggle between .normal and .highlighted UIControlState, on user touches started and touches ended. The .selected state is never used.

FUIButton supports toggling between .normal and .selected UIControlState, by setting the isPersistentSelection flag to true. This is particularly useful, if using the button to toggle a property. The developer may use the isSelected: Bool API to toggle cause this transition.

button.isPersistentSelection = true    // causes button to toggle between `.normal` and `.selected` states on user touch

When isPersistentSelection == true, the button may transition briefly through the .highlighted state, between .selected and .normal on user touches. Configure settings for [.selected, .highlighted], if implementing custom behavior here.

Color Configuration

In any style, you may choose to override the background color for state, which is useful for applying an inverted style.

button.setBackgroundColor(UIColor.preferredFioriColor(forStyle: .tintColorLight), for: .highlighted)

In any style, you may choose to override the title color for state, which is useful for applying an inverted style.

button.setTitleColor(UIColor.preferredFioriColor(forStyle: .header), for: .normal)

You can set whether the border color is applied based onUIControlState

button.setIsApplyingBorderColor(true, for: .normal)

The FUIButton also implements the FUIBackgroundSchemeSupporting protocol, which enables developers to inform the control whether it is being presented against a ‘light’ background, or ‘dark’ background. The default style of the button will adapt to the background color scheme; defaults to .light.

Size Calculation

The FUIButton calculates an intrinsicContentSize from its imageView and titleLabel, its various insets, and its directionalLayoutMargins.

To manage the width of the text in the titleLabel, use the regular UILabel API to configure the wrapping behavior.

button.titleLabel?.preferredMaxLayoutWidth = 200
button.titleLabel?.lineBreakMode = .byWordWrapping

As an additional configuration option, the FUIButton provides a flag isPreservingPreferredMaxLayoutWidth, which uses the preferredMaxLayoutWidth as a minimum width for the titleLabel when calculating intrinsicContentSize. This is useful, when implementing a fixed-width button with variable texts, or toggling variable-width texts on state.

Note

This will not affect the titleLabel text wrapping behavior.

button.isPreservingPreferredMaxLayoutWidth = true

Selection handler:

Optional closure-based substitute for addTarget(_:_:_:) method for handling user taps. Passes self as input parameter. Is compatible with addTarget(_:_:_:) selector registration.

If used in combination with the target-action selector registration, handlers will be invoked in the following order:

  1. didSelectHandler
  2. target-action selector

Theming

Support Button class paths:

Button {} fdlFUIButton {}

Supported Button attributes:

tint-color { -selected | -highlighted | -selected-highlighted | -selected-disabled | -disabled } (Color) background-color { -normal | -selected | -highlighted | -selected-highlighted | -selected-disabled | -disabled } { -primary| -secondary| -tertiary } (Color) background-image { -selected | -highlighted | -selected-highlighted | -selected-disabled | -disabled } (Image) content-insets (Box) image-insets (Box) title-insets (Box) shadow-color (Color) shadow-offset (Offset) shadow-opacity (Number) shadow-radius (Number)

Supported Text attributes:

font-color { -selected | -highlighted | -selected-highlighted | -selected-disabled | -disabled } (Color) font-name (FontName) font-style (UIFontTextStyle) font-size (Number) text-align (TextAlign) text-alpha (Number) text-auto-fit (Boolean) text-line-clamp (Integer) text-shadow-color { -selected | -highlighted | -selected-highlighted | -selected-disabled | -disabled } (Color) text-shadow-offset (Offset)

Supported ImageView attributes:

image { -highlighted | -selected | -selected-highlightecd | -selected-disabled | -disabled } (Image)

Remark

The tint-color { -* } attribute will override the font-color { -* } attribute on a state-by-state basis. E.g. tint-color-highlighted will override font-color-highlighted, but will not affect font-color.
  • Specialized init method, implementing the common ‘rounded’ button style. Applies default contentEdgeInsets = UIEdgeInsets(top: 7, left: 16, bottom: 7, right: 16)

    Declaration

    Swift

    convenience public init(style: FUIButtonStyle)

    Parameters

    style

    { .primary, .secondary, .tertiary }

  • Workaround for the compile issue where empty initializer is not accessible in xcframework.

    Declaration

    Swift

    required public init()
  • Sets background color for UIControlState for most button configurations.

    Declaration

    Swift

    public func setBackgroundColor(_ color: UIColor, for state: UIControlState)

    Parameters

    color

    background color

    state

    control state (as determined by UIButton superclass)

  • Sets tint color for UIControlState provided. When style == { .none | .fuiRounded} , invokes setTitleColor(_:_:) for state, and if style is not .none, applies tint color to imageView. When style == .fuiRoundedFilled, invokes the setBackgroundColor(_:_:) for state.

    Declaration

    Swift

    @available(*, deprecated, message: "No longer supported. Set textColor and tintColor programmatically.")
    open func setTintColor(_ color: UIColor, for state: UIControlState)

    Parameters

    color

    tint color

    state

    control state (as determined by UIButton superclass)

  • Sets button style. It is tertiary by default.

    Declaration

    Swift

    public var style: FUIButtonStyle { get set }
  • Sets button background color scheme. It is device by default.

    Declaration

    Swift

    public var backgroundColorScheme: FUIBackgroundColorScheme { get set }
  • Sets button semantic attribute. It is normal by default.

    Declaration

    Swift

    public var semantic: FUIButtonSemantic { get set }
  • Applies blur effect for disabled or secondary style.

    The default is true.

    Declaration

    Swift

    public var appliesBlurEffect: Bool { get set }
  • Enable shadow for the button. It is false by default.

    Declaration

    Swift

    public var isShadowEnabled: Bool { get set }
  • Sets whether the border color is appled based onUIControlState

    • value: Bool
    • state: control state (as determined by UIButton superclass)

    Declaration

    Swift

    public func setIsApplyingBorderColor(_ value: Bool, for state: UIControlState)
  • Optional closure handler, for responding to UIControlEvent.primaryActionTriggered.

    Declaration

    Swift

    open var didSelectHandler: ((FUIButton) -> Void)?
  • Enables UIControlState.selected to be persisted after user tap. Requires that user re-tap button to de-select, or that developer invoke isSelected = false setter. Defaults to false.

    Note

    If set to true, button will skip UIControlState.highlighted on tap, and return UIControlState.selected, while isSelected == true.

    Declaration

    Swift

    public var isPersistentSelection: Bool { get set }
  • Set spacing between the image and the title when both the image and the title are on the button. The default value is LayoutParams.titleImageSpacing

    Declaration

    Swift

    public var imageTitleSpacing: CGFloat { get set }
  • Undocumented

    Declaration

    Swift

    public var imagePosition: NSDirectionalRectEdge { get set }
  • Instructs the intrinsicContentSize calculation to use the button’s titleLabel?.preferredMaxLayoutWidth as the constant width of the titleLabel subview.

    Declaration

    Swift

    public var isPreservingPreferredMaxLayoutWidth: Bool
  • A Boolean that indicates whether the button automatically updates title font when the device’s content size category changes. It is true by default

    Declaration

    Swift

    open var adjustsContentSizeForAccessibilityContentSizeCategory: Bool { get set }
  • Undocumented

    Declaration

    Swift

    open override func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?)