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.

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)