UserAction

public protocol UserAction

A type that describes a particular action that the user can perform and how to perform it.

There are several subprotocols of UserAction that each provide a different way for types to define how they perform a user action:

To implement a user action, a type should conform to exactly one of the above protocols and implement the appropriate method to define how to do its work.

  • The type of value this action returns when it completes successfully.

    If an action type doesn’t specify this, it defaults to Void, meaning the action doesn’t return a meaningful value.

    Declaration

    Swift

    associatedtype ResultType = Void

Action Presentation
  • canPerform Default implementation

    Whether the action is currently valid to perform.

    This will be used to automatically disable menu actions.

    Default Implementation

    By default, user actions can always be performed.

    Declaration

    Swift

    var canPerform: Bool { get }

  • The name to describe this action in undo alerts.

    If nil, no action name will be set. This is strongly discouraged in general, but there are some actions that don’t make sense to undo because they either have no persistent effect or they affect external systems in a way that is hard or impossible to undo.

    Declaration

    Swift

    var undoActionName: String? { get }
  • displayName Default implementation

    The name used by default when this action is shown in the user interface.

    This can be overridden if desired when binding the action to the runner, but it makes bound actions less reusable.

    Default Implementation

    By default, user actions use the undoActionName as their display name.

    Declaration

    Swift

    var displayName: String? { get }
  • shortDisplayName Default implementation

    The name used by default when this action is shown in space-constrained parts of the user interface, like table row swipe actions.

    If not implemented, it defaults to the display name.

    Default Implementation

    By default, user actions use the displayName itself as the short version of their display name.

    Declaration

    Swift

    var shortDisplayName: String? { get }

Passing Actions Around
  • bind(to:title:options:) Extension method

    Binds an action to a specific runner, allowing it to be performed independently.

    Binding an action allows you to pass an action (or group of actions) to other parts of your app as a value. The bound action does not remember the type of the user action, only the type of its result. The bound action can be performed without having access to the runner.

    A bound action also has conveniences for creating UI elements for the action.

    Declaration

    Swift

    func bind(
    to runner: UserActions.Runner,
    title: String? = nil,
    options: BoundUserActionOptions = []
) -> BoundUserAction<ResultType>

    Parameters

    runner

    The action runner that the bound action will use to perform.
    title

    An optional title to use for UI generated from the bound action. If not provided, which is preferred, displayName or shortDisplayName will be used as appropriate.
    options

    Options to configure how the action will be displayed in UI.

    Return Value

    A type-erased version of the action that is bound to the action runner.