PluginDelegate

public protocol PluginDelegate

The PluginDelegate represents the entry point to to your plugin and is used to generate the manifest.

Your plugin’s @main type should conform to PluginDelegate in order for the framework to handle plugin lifecycle and command line events.

Settings
Settings returned by the Stream Deck application.

If your plugin does not use global settings, simply use NoSettings.
Declaration
Swift

associatedtype Settings : Decodable, Encodable, Hashable

Manifest

name
The name of the plugin.

This string is displayed to the user in the Stream Deck store.
Declaration
Swift

static var name: String { get }
description
Provides a general description of what the plugin does.

This string is displayed to the user in the Stream Deck store.
Declaration
Swift

static var description: String { get }
category
The name of the custom category in which the actions should be listed.

This string is visible to the user in the actions list. If you don’t provide a category, the actions will appear inside a “Custom” category.
Declaration
Swift

static var category: String? { get }
categoryIcon
The relative path to a PNG image without the .png extension.

This image is used in the actions list. The PNG image should be a 28pt x 28pt image. You should provide @1x and @2x versions of the image. The Stream Deck application takes care of loading the appropriate version of the image.
Declaration
Swift

static var categoryIcon: String? { get }
author
The author of the plugin.

This string is displayed to the user in the Stream Deck store.
Declaration
Swift

static var author: String { get }
icon
The relative path to a PNG image without the .png extension.

This image is displayed in the Plugin Store window. The PNG image should be a 72pt x 72pt image. You should provide @1x and @2x versions of the image. The Stream Deck application takes care of loading the appropriate version of the image.
Declaration
Swift

static var icon: String { get }
url
A URL displayed to the user if he wants to get more info about the plugin.
Declaration
Swift

static var url: URL? { get }
version
The version of the plugin which can only contain digits and periods.

This is used for the software update mechanism.
Declaration
Swift

static var version: String { get }
os
The list of operating systems supported by the plugin as well as the minimum supported version of the operating system.
Declaration
Swift

static var os: [PluginOS] { get }
applicationsToMonitor Default implementation
List of application identifiers to monitor (applications launched or terminated).

See the applicationDidLaunch and applicationDidTerminate events.

Default Implementation
Declaration
Swift

static var applicationsToMonitor: ApplicationsToMonitor? { get }
software Default implementation
Indicates which version of the Stream Deck application is required to install the plugin.

Default Implementation
Declaration
Swift

static var software: PluginSoftware { get }
sdkVersion Default implementation
This value should be set to 2.

Default Implementation
Declaration
Swift

static var sdkVersion: Int { get }
codePath Default implementation
The relative path to the HTML/binary file containing the code of the plugin.

Default Implementation
Declaration
Swift

static var codePath: String { get }
codePathMac Default implementation
Override CodePath for macOS.

Default Implementation
Declaration
Swift

static var codePathMac: String? { get }
codePathWin Default implementation
Override CodePath for Windows.

Default Implementation
Declaration
Swift

static var codePathWin: String? { get }
actions
The actions defined by your plugin.
Declaration
Swift

static var actions: [any Action.Type] { get }
init()
Declaration
Swift

init()

Events Received

didReceiveSettings(action:context:device:payload:) Default implementation
Event received after calling the getSettings API to retrieve the persistent data stored for the action.

Default Implementation
Declaration
Swift

@available(*, deprecated, message: "Action events are no longer sent to the plugin") func didReceiveSettings(action: String, context: String, device: String, payload: SettingsEvent<NoSettings>.Payload)
didReceiveGlobalSettings(_:) Default implementation
Event received after calling the getGlobalSettings API to retrieve the global persistent data.

Default Implementation
Declaration
Swift

func didReceiveGlobalSettings(_ settings: [String : String])
didReceiveGlobalSettings(_:)
Event received after calling the getGlobalSettings API to retrieve the global persistent data.
Declaration
Swift

func didReceiveGlobalSettings(_ settings: Settings)


                    
                    
                    willAppear(action:context: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

Declaration

Swift

@available(*, deprecated, message: "Action events are no longer sent to the plugin")
func willAppear(action: String, context: String, device: String, payload: AppearEvent<NoSettings>)

Parameters

`action`	The action’s unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
`context`	An opaque value identifying the instance’s action or Property Inspector.
`device`	An opaque value identifying the device.
`payload`	The event payload sent by the server.


                    
                    
                    willDisappear(action:context: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

Declaration

Swift

@available(*, deprecated, message: "Action events are no longer sent to the plugin")
func willDisappear(action: String, context: String, device: String, payload: AppearEvent<NoSettings>)

Parameters

`action`	The action’s unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
`context`	An opaque value identifying the instance’s action or Property Inspector.
`device`	An opaque value identifying the device.
`payload`	The event payload sent by the server.


                    
                    
                    keyDown(action:context:device:payload:)

Default implementation

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

Default Implementation

Declaration

Swift

@available(*, deprecated, message: "Action events are no longer sent to the plugin")
func keyDown(action: String, context: String, device: String, payload: KeyEvent<NoSettings>)

Parameters

`action`	The action’s unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
`context`	An opaque value identifying the instance’s action or Property Inspector.
`device`	An opaque value identifying the device.
`payload`	The event payload sent by the server.


                    
                    
                    keyUp(action:context:device:payload:)

Default implementation

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

Default Implementation

Declaration

Swift

@available(*, deprecated, message: "Action events are no longer sent to the plugin")
func keyUp(action: String, context: String, device: String, payload: KeyEvent<NoSettings>)

Parameters

`action`	The action’s unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
`context`	An opaque value identifying the instance’s action or Property Inspector.
`device`	An opaque value identifying the device.
`payload`	The event payload sent by the server.


                    
                    
                    titleParametersDidChange(action:context:device:info:)

Default implementation

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

Default Implementation

Declaration

Swift

@available(*, deprecated, message: "Action events are no longer sent to the plugin")
func titleParametersDidChange(action: String, context: String, device: String, info: TitleInfo<NoSettings>)

Parameters

`action`	The action’s unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
`context`	An opaque value identifying the instance’s action or Property Inspector.
`device`	An opaque value identifying the device.
`payload`	The event payload sent by the server.


                    
                    
                    deviceDidConnect(_:deviceInfo:)

Default implementation

When a device is plugged to the computer, the plugin will receive a deviceDidConnect event.

Default Implementation

Declaration

Swift

func deviceDidConnect(_ device: String, deviceInfo: DeviceInfo)

Parameters

`action`	The action’s unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
`context`	An opaque value identifying the instance’s action or Property Inspector.
`device`	An opaque value identifying the device.
`payload`	The event payload sent by the server.


                    
                    
                    deviceDidDisconnect(_:)

Default implementation

When a device is unplugged from the computer, the plugin will receive a deviceDidDisconnect event.

Default Implementation

Declaration

Swift

func deviceDidDisconnect(_ device: String)

Parameters


                                device

An opaque value identifying the device.


                    
                    
                    applicationDidLaunch(_:)

Default implementation

A plugin can request in its manifest.json to be notified when some applications are launched or terminated.

In order to do so, the manifest.json should contain an ApplicationsToMonitor object specifying the list of application identifiers to monitor. On macOS the application bundle identifier is used while the exe filename is used on Windows.

Default Implementation

Declaration

Swift

func applicationDidLaunch(_ application: String)

Parameters


                                application

The identifier of the application that has been launched.


                    
                    
                    applicationDidTerminate(_:)

Default implementation

A plugin can request in its manifest.json to be notified when some applications are launched or terminated.

Default Implementation

Declaration

Swift

func applicationDidTerminate(_ application: String)

Parameters


                                application

The identifier of the application that has been launched.

systemDidWakeUp() Default implementation
When the computer is wake up, the plugin will receive the systemDidWakeUp event.

Default Implementation
Declaration
Swift

func systemDidWakeUp()


                    
                    
                    propertyInspectorDidAppear(action:context:device:)

Default implementation

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

Default Implementation

Declaration

Swift

func propertyInspectorDidAppear(action: String, context: String, device: String)

Parameters

`action`	The action unique identifier.
`context`	An opaque value identifying the instance’s action.
`device`	An opaque value identifying the device.


                    
                    
                    propertyInspectorDidDisappear(action:context:device:)

Default implementation

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

Default Implementation

Declaration

Swift

func propertyInspectorDidDisappear(action: String, context: String, device: String)

Parameters

`action`	The action unique identifier.
`context`	An opaque value identifying the instance’s action.
`device`	An opaque value identifying the device.


                    
                    
                    sentToPlugin(context:action:payload:)

Default implementation

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

Default Implementation

Declaration

Swift

@available(*, deprecated, message: "Action events are no longer sent to the plugin")
func sentToPlugin(context: String, action: String, payload: [String : String])

Parameters

`context`	An opaque value identifying the instance’s action or Property Inspector.
`action`	The action unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered.
`payload`	A json object that will be received by the plugin.

pluginWasCreated() Default implementation
Called immediately after main().

Default Implementation

The default implementation of static PluginDelegate.pluginWasCreated()
Declaration
Swift

static func pluginWasCreated()

Sent


                    
                    
                    setSettings(in:to:)

Extension method

Save data persistently for the action’s instance.

Declaration

Swift

@available(*, deprecated, message: "Use the Settings API.")
func setSettings(in context: String, 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(in:to:)

Extension method

Save data persistently for the action’s instance.

Declaration

Swift

func setSettings<P>(in context: String, to settings: P) where P : Encodable

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(in:) 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(in context: String)


                    
                    
                    setGlobalSettings(_:)

Extension method

Save data securely and globally for the plugin.

Declaration

Swift

func setGlobalSettings(_ settings: [String : Any])

Parameters

`context`	An opaque value identifying the instance’s action or Property Inspector.
`settings`	A json object which is persistently saved globally.


                    
                    
                    getGlobalSettings()

Extension method

Request the global persistent data.

Declaration

Swift

func getGlobalSettings()

Parameters


                                context

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


                    
                    
                    openURL(_:)

Extension method

Open an URL in the default browser.

Declaration

Swift

func openURL(_ url: URL)

Parameters

url

The URL to open


                    
                    
                    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(in:to:target:state:)

Extension method

Dynamically change the title of an instance of an action.

Declaration

Swift

func setTitle(in context: String, 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(in: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(in context: String, 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.


                    
                    
                    setImage(in:toImage:withExtension:subdirectory: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(in context: String, 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.


                    
                    
                    setImage(in:toSVG: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(in context: String, 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(in:)

Extension method

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

Declaration

Swift

func showAlert(in context: String)

Parameters


                                context

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


                    
                    
                    showOk(in:)

Extension method

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

Declaration

Swift

func showOk(in context: String)

Parameters


                                context

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


                    
                    
                    setState(in:to:)

Extension method

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

Declaration

Swift

func setState(in context: String, 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.


                    
                    
                    switchToProfile(named:)

Extension method

Switch to one of the preconfigured read-only profiles.

Declaration

Swift

func switchToProfile(named name: String)

Parameters


                                name

The name of the profile to switch to. The name should be identical to the name provided in the manifest.json file.


                    
                    
                    sendToPropertyInspector(in:action:payload:)

Extension method

Send a payload to the Property Inspector.

Declaration

Swift

func sendToPropertyInspector(in context: String, action: String, 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.

main() Extension method
The default main function.

This method configures the plugin, calls pluginWasCreated(), and then registers the plugin.
Declaration
Swift

static func main()
executableName Extension method
Determine the CodePath for the plugin based on the bundles executable’s name.
Declaration
Swift

static var executableName: String { get }