BoundUserAction

public struct BoundUserAction<ResultType>

A wrapper for a type-erased user action that has been bound to a particular action runner.

This provides a way for the owner of the action runner (which may not be a view controller) to provide actions to the view controller that can be performed on their own, without needing access to the action runner. Because they are type-erased, it’s possible to create a heterogenous collection of bound user actions (for showing a menu, for instance) or have a property expose an action whose underlying type is different depending on the state of the app.

Bound user actions can also be easily converted into various UIKit action types as necessary for different types of UI, like context menus and action sheets.

To bind a user action to an action runner, creating a BoundUserAction, use UserAction.bind(to:title:options:). It’s also possible to create a BoundUserAction directly from closures in cases where a user action isn’t appropriate for the task.

Creating Bound Actions

  • Create a bound action for an arbitrary code block.

    Only use this for really specific cases where you want to expose an action that really only affects local state, and therefore doesn’t make sense to be a UserAction. A good example is toggling the editing state of the view.

    Declaration

    Swift

    public init(
    title: String,
    shortTitle: String? = nil,
    options: Options = [],
    canPerform: @escaping CanPerformHandler = { true },
    perform: @escaping PerformHandler
)

    Parameters

    title

    A localized string that will be displayed in UI elements generated from the action.
    shortTitle

    A localized string that will be used instead of title for space-constrained UI elements like table row swipe actions. Optional, title will be used if not provided.
    options

    Options to affect how UI elements are generated for the action.
    canPerform

    A block that reports whether the action is currently able to be performed. Affects whether UI elements for the action are enabled. If not provided, the action is always able to be performed.
    perform

    A block that performs the action.

Types

  • An alias for BoundUserActionOptions.

    Declaration

    Swift

    public typealias Options = BoundUserActionOptions

  • A function that determines if the action can be performed.

    Declaration

    Swift

    public typealias CanPerformHandler = () -> Bool

  • A function that performs work before the action is performed.

    Declaration

    Swift

    public typealias WillPerformHandler = () -> Void

  • A function that performs the work of the action.

    Declaration

    Swift

    public typealias PerformHandler = (_ source: UserActions.Source?, _ willPerform: @escaping () -> Void) -> AnyPublisher<ResultType, Error>

    Parameters

    source

    A UI element to present view controllers from if needed.
    willPerform

    A block that should be run before the action’s work is performed.

    Return Value

    A publisher that will send a single result value when the action completes.

Customizing Actions

  • Whether the action should be marked as destructive in UI.

    In context menus and action sheets, this causes the text for the action to be shown in red.

    This can be enabled as creation time with the .destructive option.

    Declaration

    Swift

    public var isDestructive: Bool { get set }

  • Attach additional work to happen before the action is performed.

    The creator of the bound action can use this to schedule work to occur if the user chooses to perform the action.

    Declaration

    Swift

    public func onWillPerform(_ block: @escaping () -> Void) -> Self

    Parameters

    block

    The work to perform before the action.

    Return Value

    A copy of the action with the additional work attached.

Performing Actions

  • Perform the action immediately.

    Declaration

    Swift

    @discardableResult
public func perform(source: UserActions.Source? = nil, willPerform: @escaping () -> Void = {})
    -> AnyPublisher<ResultType, Error>

    Parameters

    source

    A UI element which view controllers that this action presents will use as their source.
    willPerform

    An optional block that will run before the action’s work is performed.

    Return Value

    A publisher that will send a single result value when the action completes.

  • Whether the action can currently be performed.

    Declaration

    Swift

    public var canPerform: Bool { get }

Creating UIKit Actions

  • Create a alert action that can be added to a UIAlertController action sheet.

    The alert action will have the destructive style if isDestructive is true.

    Declaration

    Swift

    func alertAction(
    willPerform: @escaping () -> Void = {},
    completion: @escaping (ResultType) -> Void = { _ in }
) -> UIAlertAction

    Parameters

    willPerform

    An optional closure to perform before the action runs.
    completion

    An optional closure to perform when the action completes.

    Return Value

    An alert action that will perform this action when the user selects that option in the alert controller.

  • Create a menu action that can be added to contextual menu.

    The menu action will have the disabled attribute if it can’t be performed when this method is called. It will have the destructive attribute if isDestructive is true. It can also include an image or have its state set so it appears checked.

    Declaration

    Swift

    func menuAction(
    image: UIImage? = nil,
    state: UIMenuElement.State = .off,
    source: UserActions.Source? = nil,
    willPerform: @escaping () -> Void = {},
    completion: @escaping (ResultType) -> Void = { _ in }
) -> UIAction

    Parameters

    image

    An optional image to include on the menu action.
    state

    An optional state to set on the menu action. Defaults to off, so the menu action will not dispaly with a checkmark.
    source

    A UI element which view controllers that this action presents will use as their source.
    willPerform

    An optional closure to perform before the action runs.
    completion

    An optional closure to perform when the action completes.

    Return Value

    A menu action that will perform this action when the user selects that option from the menu.

  • Create a contextual action that can be added to table row swipe actions.

    The contextual action will have the destructive style if isDestructive is true. Unlike other UI elements created from bound user actions, contextual actions will use the short display name of a user action since swipe actions are very space-constrained.

    Declaration

    Swift

    func contextualAction(
    willPerform: @escaping () -> Void = {},
    completion: @escaping (ResultType) -> Void = { _ in }
) -> UIContextualAction

    Parameters

    willPerform

    An optional closure to perform before the action runs.
    completion

    An optional closure to perform when the action completes.

    Return Value

    A contextual action that will perform this action when the user taps the button in the swipe actions.