Action

public protocol Action

A single action that can be assigned to a Stream Deck key.

The action type is shown in the actions list and a new instance is initiated when the user adds an action to a key.

  • Settings returned by the Stream Deck application.

    If your action does not use settings, simply use NoSettings.

    Declaration

    Swift

    associatedtype Settings : Decodable, Encodable, Hashable

Action Properties

  • The name of the action. This string is visible to the user in the actions list.

    Declaration

    Swift

    static var name: String { get }

  • The unique identifier of the action.

    It must be a uniform type identifier (UTI) that contains only lowercase alphanumeric characters (a-z, 0-9), hyphen (-), and period (.).

    The string must be in reverse-DNS format.

    For example, if your domain is elgato.com and you create a plugin named Hello with the action My Action, you could assign the string com.elgato.hello.myaction as your action’s Unique Identifier.

    Declaration

    Swift

    static var uuid: String { get }

  • The relative path to a PNG image without the .png extension.

    This image is displayed in the actions list. The PNG image should be a 20pt x 20pt image. You should provide @1x and @2x versions of the image. The Stream Deck application take care of loaded the appropriate version of the image.

    Note

    This icon is not required for actions not visible in the actions list (VisibleInActionsList set to false).

    Declaration

    Swift

    static var icon: String { get }

  • Specifies an array of states.

    Each action can have one state or 2 states (on/off).

    For example the Hotkey action has a single state. However the Game Capture Record action has 2 states, active and inactive.

    The state of an action, supporting multiple states, is always automatically toggled whenever the action’s key is released (after being pressed).

    In addition, it is possible to force the action to switch its state by sending a setState event.

    Note

    If no states are specified the manifest will generate a single state using the Action‘s icon.

    Declaration

    Swift

    static var states: [PluginActionState]? { get }

  • Specifies an array of controllers.

    Valid values include “Keypad” and “Encoder”.

    Include “Keypad” to have an action shown for standard StreamDeck keys. Include “Encoder” to have an action down for the StreamDeck+ dials.

    Declaration

    Swift

    static var controllers: [ControllerType] { get }

  • An object containing encoder information.

    Declaration

    Swift

    static var encoder: RotaryEncoder? { get }
  • propertyInspectorPath Default implementation

    This can override PropertyInspectorPath member from the plugin if you wish to have different PropertyInspectorPath based on the action.

    The relative path to the Property Inspector html file if your plugin want to display some custom settings in the Property Inspector.

    Default Implementation

    Declaration

    Swift

    static var propertyInspectorPath: String? { get }
  • supportedInMultiActions Default implementation

    Boolean to prevent the action from being used in a Multi Action.

    True by default.

    Default Implementation

    Declaration

    Swift

    static var supportedInMultiActions: Bool? { get }
  • tooltip Default implementation

    The string displayed as tooltip when the user leaves the mouse over your action in the actions list.

    Default Implementation

    Declaration

    Swift

    static var tooltip: String? { get }
  • visibleInActionsList Default implementation

    Boolean to hide the action in the actions list.

    This can be used for plugin that only works with a specific profile. True by default.

    Default Implementation

    Declaration

    Swift

    static var visibleInActionsList: Bool? { get }
  • userTitleEnabled Default implementation

    Boolean to disable the title field for users in the property inspector. True by default.

    Default Implementation

    Declaration

    Swift

    static var userTitleEnabled: Bool? { get }

Instance Properties

  • The context value for the instance.

    Declaration

    Swift

    var context: String { get }

  • The coordinates of the instance.

    Declaration

    Swift

    var coordinates: Coordinates? { get }

  • Create a new instance with the specified context and coordinates.

    Declaration

    Swift

    init(context: String, coordinates: Coordinates?)

Events

  • didReceiveSettings(device:payload:) Default implementation

    Event received after calling the getSettings API to retrieve the persistent data stored for the action.

    Default Implementation

    Event received after calling the getSettings API to retrieve the persistent data stored for the action.

    Declaration

    Swift

    func didReceiveSettings(device: String, payload: SettingsEvent<Settings>.Payload)
  • willAppear(device:payload:) Default implementation

    When an instance of an action is displayed on the Stream Deck, for example when the hardware is first plugged in, or when a folder containing that action is entered, the plugin will receive a willAppear event.

    You will see such an event when:

    • the Stream Deck application is started
    • the user switches between profiles
    • the user sets a key to use your action

    Default Implementation

    When an instance of an action is displayed on the Stream Deck, for example when the hardware is first plugged in, or when a folder containing that action is entered, the plugin will receive a willAppear event.

    You will see such an event when:

    • the Stream Deck application is started
    • the user switches between profiles
    • the user sets a key to use your action

    Declaration

    Swift

    func willAppear(device: String, payload: AppearEvent<Settings>)

    Parameters

    device

    An opaque value identifying the device.
    payload

    The event payload sent by the server.
  • willDisappear(device:payload:) Default implementation

    When an instance of an action ceases to be displayed on Stream Deck, for example when switching profiles or folders, the plugin will receive a willDisappear event.

    You will see such an event when:

    • the user switches between profiles
    • the user deletes an action

    Default Implementation

    When an instance of an action ceases to be displayed on Stream Deck, for example when switching profiles or folders, the plugin will receive a willDisappear event.

    You will see such an event when:

    • the user switches between profiles
    • the user deletes an action

    Declaration

    Swift

    func willDisappear(device: String, payload: AppearEvent<Settings>)

    Parameters

    device

    An opaque value identifying the device.
    payload

    The event payload sent by the server.
  • keyDown(device:payload:) Default implementation

    When the user presses a key, the plugin will receive the keyDown event.

    Default Implementation

    When the user presses a key, the plugin will receive the keyDown event.

    Declaration

    Swift

    func keyDown(device: String, payload: KeyEvent<Settings>)

    Parameters

    device

    An opaque value identifying the device.
    payload

    The event payload sent by the server.
  • keyUp(device:payload:) Default implementation

    When the user releases a key, the plugin will receive the keyUp event.

    Default Implementation

    When the user releases a key, the plugin will receive the keyUp event.

    Declaration

    Swift

    func keyUp(device: String, payload: KeyEvent<Settings>)

    Parameters

    device

    An opaque value identifying the device.
    payload

    The event payload sent by the server.
  • dialRotate(device:payload:) Default implementation

    Default Implementation

    Declaration

    Swift

    func dialRotate(device: String, payload: EncoderEvent<Settings>)
  • dialPress(device:payload:) Default implementation

    Default Implementation

    Declaration

    Swift

    func dialPress(device: String, payload: EncoderPressEvent<Settings>)
  • touchTap(device:payload:) Default implementation

    Default Implementation

    Declaration

    Swift

    func touchTap(device: String, payload: TouchTapEvent<Settings>)

  • When the user changes the title or title parameters of the instance of an action, the plugin will receive a titleParametersDidChange event.

    Default Implementation

    When the user changes the title or title parameters of the instance of an action, the plugin will receive a titleParametersDidChange event.

    Declaration

    Swift

    func titleParametersDidChange(device: String, info: TitleInfo<Settings>)

    Parameters

    device

    An opaque value identifying the device.
    payload

    The event payload sent by the server.
  • propertyInspectorDidAppear(device:) Default implementation

    The plugin will receive a propertyInspectorDidAppear event when the Property Inspector appears.

    Default Implementation

    The plugin will receive a propertyInspectorDidAppear event when the Property Inspector appears.

    Declaration

    Swift

    func propertyInspectorDidAppear(device: String)

    Parameters

    device

    An opaque value identifying the device.

  • The plugin will receive a propertyInspectorDidDisappear event when the Property Inspector appears.

    Default Implementation

    The plugin will receive a propertyInspectorDidDisappear event when the Property Inspector appears.

    Declaration

    Swift

    func propertyInspectorDidDisappear(device: String)

    Parameters

    device

    An opaque value identifying the device.
  • sentToPlugin(payload:) Default implementation

    The plugin will receive a sendToPlugin event when the Property Inspector sends a sendToPlugin event.

    Default Implementation

    The plugin will receive a sendToPlugin event when the Property Inspector sends a sendToPlugin event.

    Declaration

    Swift

    func sentToPlugin(payload: [String : String])

    Parameters

    payload

    A json object that will be received by the plugin.

Sent

  • setSettings(to:) Extension method

    Save data persistently for the action’s instance.

    Declaration

    Swift

    @available(*, deprecated, message: "Use the Settings API.")
func setSettings(to settings: [String : Any])

    Parameters

    context

    An opaque value identifying the instance’s action or Property Inspector.
    settings

    A json object which is persistently saved for the action’s instance.
  • setSettings(to:) Extension method

    Save data persistently for the action’s instance.

    Declaration

    Swift

    func setSettings(to settings: Settings)

    Parameters

    context

    An opaque value identifying the instance’s action or Property Inspector.
    settings

    A json object which is persistently saved for the action’s instance.
  • getSettings() Extension method

    Request the persistent data for the action’s instance.

    • context: An opaque value identifying the instance’s action or Property Inspector.

    Declaration

    Swift

    func getSettings()
  • logMessage(_:) Extension method

    Write a debug log to the logs file.

    Declaration

    Swift

    func logMessage(_ message: String)

    Parameters

    message

    A string to write to the logs file.
  • logMessage(_:separator:) Extension method

    Write a debug log to the logs file.

    Declaration

    Swift

    func logMessage(_ items: Any..., separator: String = " ")

    Parameters

    items

    Zero or more items to print.
    separator

    A string to print between each item. The default is a single space (“ ”).
  • setTitle(to:target:state:) Extension method

    Dynamically change the title of an instance of an action.

    Declaration

    Swift

    func setTitle(to title: String?, target: Target? = nil, state: Int? = nil)

    Parameters

    context

    An opaque value identifying the instance’s action or Property Inspector.
    title

    The title to display. If there is no title parameter, the title is reset to the title set by the user.
    target

    Specify if you want to display the title on hardware, software, or both.
    state

    A 0-based integer value representing the state of an action with multiple states. This is an optional parameter. If not specified, the title is set to all states.
  • setImage(to:target:state:) Extension method

    Dynamically change the image displayed by an instance of an action.

    The image is automatically encoded to a prefixed base64 string.

    Declaration

    Swift

    func setImage(to image: NSImage?, target: Target? = nil, state: Int? = nil)

    Parameters

    context

    An opaque value identifying the instance’s action or Property Inspector.
    image

    An image to display.
    target

    Specify if you want to display the title on hardware, software, or both.
    state

    A 0-based integer value representing the state of an action with multiple states. This is an optional parameter. If not specified, the title is set to all states.

  • Dynamically change the image displayed by an instance of an action.

    The image is automatically encoded to a prefixed base64 string.

    Declaration

    Swift

    func setImage(toImage image: String?, withExtension ext: String, subdirectory subpath: String?, target: Target? = nil, state: Int? = nil)

    Parameters

    context

    An opaque value identifying the instance’s action or Property Inspector.
    image

    The name of an image to display.
    ext

    The filename extension of the file to locate.
    subpath

    The subdirectory in the plugin bundle in which to search for images.
    target

    Specify if you want to display the title on hardware, software, or both.
    state

    A 0-based integer value representing the state of an action with multiple states. This is an optional parameter. If not specified, the title is set to all states.

  • Dynamically change the image displayed by an instance of an action.

    The image is automatically encoded to a prefixed base64 string.

    Declaration

    Swift

    func setImage(toSVG svg: String?, target: Target? = nil, state: Int? = nil)

    Parameters

    context

    An opaque value identifying the instance’s action or Property Inspector.
    image

    The SVG to display.
    target

    Specify if you want to display the title on hardware, software, or both.
    state

    A 0-based integer value representing the state of an action with multiple states. This is an optional parameter. If not specified, the title is set to all states.
  • showAlert() Extension method

    Temporarily show an alert icon on the image displayed by an instance of an action.

    Declaration

    Swift

    func showAlert()

    Parameters

    context

    An opaque value identifying the instance’s action or Property Inspector.
  • showOk() Extension method

    Temporarily show an OK checkmark icon on the image displayed by an instance of an action.

    Declaration

    Swift

    func showOk()

    Parameters

    context

    An opaque value identifying the instance’s action or Property Inspector.
  • setState(to:) Extension method

    Change the state of the action’s instance supporting multiple states.

    Declaration

    Swift

    func setState(to state: Int)

    Parameters

    context

    An opaque value identifying the instance’s action or Property Inspector.
    state

    A 0-based integer value representing the state of an action with multiple states. This is an optional parameter. If not specified, the title is set to all states.

  • Send a payload to the Property Inspector.

    Declaration

    Swift

    func sendToPropertyInspector(payload: [String : Any])

    Parameters

    context

    An opaque value identifying the instance’s action or Property Inspector.
    action

    The action unique identifier.
    payload

    A json object that will be received by the Property Inspector.
  • setFeedback(_:) Extension method

    The plugin can send a setFeedback event to the Stream Deck application to dynamically change properties of items on the Stream Deck + touch display layout.

    Declaration

    Swift

    func setFeedback(_ payload: [String : Any])
  • setFeedbackLayout(_:) Extension method

    The plugin can send a setFeedbackLayout event to the Stream Deck application to dynamically change the current Stream Deck + touch display layout.

    setFeedbackLayout can use the id of a built-in layout or a relative path to a custom layout JSON file.

    Declaration

    Swift

    func setFeedbackLayout(_ layout: LayoutName)

    Parameters

    layout

    The layout to set.

Defaults

  • uuid Extension method

    The Action’s UUID.

    Declaration

    Swift

    public var uuid: String { get }