Swiftpack.co - Package - elegantchaos/Actions


An abstraction for action-handling, for Swift applications.


Note that the API is in flux currently.

Although I'm using semantic version numbers, I will abuse them until things settle down - so new maintenance releases are likely to contain breaking changes for a while. This is simply to avoid prematurely ending up at version 10.x!


Actions are discrete pieces of work that do something. This may be modifying the model, or performing a user interface action, it doesn't really matter.

Actions are registered with the ActionManager, using an identifier. They are then invoked via the ActionManager, using the same identifier.

Actions are decoupled from each other, and from everything that they don't need to perform their specific task.

When an action is performed, it is passed a context. This contains all the information that it needs to perform its action, and is the main mechanism for ensuring that coupling is loose and dynamic.

The context supplied to the action is filled in by items in the responder chain. In this way, it is literally dependent on the user interface context - which window is at the front, which item is selected, and so on. The same action can be invoked in many different situations, as long as something in the responder chain supplies the correct context. Swift's type safety helps here, making it easy to extract the relevant parameters from the context ensuring that they are of the right type.

UI Integration

The Actions module has no dependencies on AppKit/UIKit. It could be used to implement actions for a command line application, or on a non-Apple platform.

The ActionsKit module, on the other hand, builds on top of Actions and integrates it into the responder chain for AppKit or UIKit.

This allows you to bind UI buttons, menus etc to send performAction selector to the responder chain, and have the action manager pick them up, infer the action to execute, and perform is. It also implements some validation support.

Undo support is not there yet, but will be added.



Make an ActionManager, attach it to something global (eg your app delegate), and register some actions with it.

If you're going to bind UI items to it, use one of the ActionManagerMac or ActionManagerMobile subclasses, and hook it into the responder chain by calling installResponder.

class Application: NSObject, NSApplicationDelegate {
let actionManager = ActionManagerMac()

func applicationWillFinishLaunching(_ notification: Notification) {
        MyAction(identifier: "MyAction"),
        AnotherAction(identifier: "AnotherAction")


Set the action of user interface objects to performAction(_ sender: Any), and the target to the first responder. Set the identifier of the UI item to the identifier of the action you want to invoke.

Alternatively, invoke an action directly with actionManager.perform("MyAction").


Actions are classes.

To define an action, inherit from Action, and implement perform:

class MyAction: PersonAction {
    override func perform(context: ActionContext) {
        // do stuff here


The context passed to perform contains the original sender.

It also contains a dictionary of other information. Items in the responder chain can add items to this dictionary whenever actions are performed, by implementing the ActionContextProvider protocol.

This lets a view controller or window controller pass essential information to actions whilst keeping them fully decoupled.

The context also contains a parameters array. Parameters are parsed out of the identifier that was used to invoke the action.

The algorithm for parsing the identifier is:

  • split it into a list of strings separated by '.'
  • pop items from the left of the list until we find one that matches a registered action
  • everything unused to the right of the list becomes the context parameters

This allows you to bind multiple user interface items to the same action, in a parameterised way.

For example you can set a button's identifier to button.MyAction and a menu item's to menu.MyAction. Both will have unique identifiers - which Xcode insists on - but both will be resolved to the MyAction action.

In another example, you could set two button identifiers to MyAction.red and MyAction.blue. Both will invoke MyAction, but the context.parameters array will contain ["red"] for the first one, and ["blue"] for the second. The action can read this parameter and behave differently in either case.


Actions are often only valid in certain situations - for example when some text is selected - or they want to change their name or visibility depending on the context.

To perform validation, override the validate(context: ActionContext) -> Validation and examine the context that's passed in.

When using the Mac or iOS action managers, validation is invoked automatically for certain user interface actions. In other situations you can invoke it manually as appropriate. The automatic validation is almost always appropriate, but if there's a situation where you want to skip it, you can do so by arranging for the context to contain a true value for the skipValidation.

Action Observers

If your user interface wants to know when certain actions have been performed, this pattern may be useful.

Define a protocol for observers of your action(s). This can contain anything you need.

Implement your protocol in the user interface controllers that want to observe. Also implement the ActionContextProvider protocol, and append the controller to a key that the action(s) will read:

protocol MyActionObserver {
  func myMethod(myArgument: String)

extension MyViewController: ActionContextProvider, MyActionObserver {

func provide(context: ActionContext) {
    context.append(key: "MyActionObserver", value: self)

In the action, as well as perfoming the actual work, enumerate the observer key. For each observer, call a method from your protocol, passing any arguments or context that is relevant:

class MyAction: PersonAction {
    override func perform(context: ActionContext) {
        // do some stuff here
        // notify observers
        context.forEach(key: "MyActionObserver") { (observer: MyActionObserver) in
            observer.myMethod(myArgument: "myValue")


Stars: 0
Help us keep the lights on



v1.2.4 - Mar 13, 2019

Added rudimentary serialization support.

v1.2.3 - Mar 11, 2019

Allow global notification handlers to be registered with the action manager, so that they can be called for every action performed.

Add a packed method to the action context which can turn an action invocation into a dictionary, for storage or later replay.

v1.2.2 - Jan 23, 2019

Added ability to disable validation via the context.

v1.2.1 - Dec 18, 2018

Improved logging. Fix for bug where only one observer could be registered for a context.

v1.2.0 - Dec 10, 2018

Added validation mechanism that can disable/hide/rename commands.