Events Received
Once a plugin is loaded by the Stream Deck application and the user sets some keys to use the plugin, the plugin will receive some events. Similarly when a Property Inspector is displayed, it will receive some events.
Both the plugin and the Property Inspector can receive these events:
| Event | Description |
|---|---|
| didReceiveSettings | Event received after calling the getSettings API to retrieve the persistent data stored for the action. |
| didReceiveGlobalSettings | Event received after calling the getGlobalSettings API to retrieve the global persistent data. |
The plugin may receive these additional events:
| Event | Description |
|---|---|
| keyDown | When the user presses a key, the plugin will receive the keyDown event. |
| keyUp | When the user releases a key, the plugin will receive the keyUp event. |
| willAppear | 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. |
| willDisappear | 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. |
| titleParametersDidChange | When the user changes the title or title parameters, the plugin will receive a titleParametersDidChange event. |
| deviceDidConnect | When a device is plugged to the computer, the plugin will receive a deviceDidConnect event. |
| deviceDidDisconnect | When a device is unplugged from the computer, the plugin will receive a deviceDidDisconnect event. |
| applicationDidLaunch | When a monitored application is launched, the plugin will be notified and will receive the applicationDidLaunch event. |
| applicationDidTerminate | When a monitored application is terminated, the plugin will be notified and will receive the applicationDidTerminate event. |
| systemDidWakeUp | When the computer is wake up, the plugin will be notified and will receive the systemDidWakeUp event. |
| propertyInspectorDidAppear | Event received when the Property Inspector appears in the Stream Deck software user interface, for example when selecting a new instance. |
| propertyInspectorDidDisappear | Event received when the Property Inspector for an instance is removed from the Stream Deck software user interface, for example when selecting a different instance. |
| sendToPlugin | Event received by the plugin when the Property Inspector uses the sendToPlugin event. |
The Property Inspector may also receive these events:
| Event | Description |
|---|---|
| sendToPropertyInspector | Event received by the Property Inspector when the plugin uses the sendToPropertyInspector event. |
didReceiveSettings
The didReceiveSettings event is received after calling the getSettings API to retrieve the persistent data stored for the action.
The json structure looks like:
var json = {
"action": "com.elgato.example.action1",
"event": "didReceiveSettings",
"context": opaqueValue,
"device": opaqueValue,
"payload": {
"settings": {<json data>},
"coordinates": {
"column": 3,
"row": 1
},
"isInMultiAction": false
}
};
| Members | Description |
|---|---|
| action | The action unique identifier. |
| event | didReceiveSettings |
| context | An opaque value identifying the instance's action. |
| device | An opaque value identifying the device. |
| payload | A json object |
The payload object contains the following members:
| Payload | Description |
|---|---|
| settings | This json object contains persistently stored data. |
| coordinates | The coordinates of the action triggered. |
| state | This is a parameter that is only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action. |
| isInMultiAction | Boolean indicating if the action is inside a Multi Action. |
This API has been introduced in Stream Deck 4.1.
didReceiveGlobalSettings
The didReceiveGlobalSettings event is received after calling the getGlobalSettings API to retrieve the global persistent data stored for the plugin.
The json structure looks like:
var json = {
"event": "didReceiveGlobalSettings",
"payload": {
"settings": {<json data>}
}
}
};
| Members | Description |
|---|---|
| event | didReceiveGlobalSettings |
| payload | A json object |
The payload object contains the following members:
| Payload | Description |
|---|---|
| settings | This json object contains persistently stored data. |
This API has been introduced in Stream Deck 4.1.
keyDown
When the user presses a key, the plugin will receive the keyDown event as a json structure like:
var json = {
"action": "com.elgato.example.action1",
"event": "keyDown",
"context": opaqueValue,
"device": opaqueValue,
"payload": {
"settings": {<json data>},
"coordinates": {
"column": 3,
"row": 1
},
"state": 0,
"userDesiredState": 1,
"isInMultiAction": false
}
};
| Members | Description |
|---|---|
| action | The action's unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered. |
| event | keyDown |
| context | An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API. |
| device | An opaque value identifying the device. |
| payload | A json object |
The payload object contains the following members:
| Payload | Description |
|---|---|
| settings | This json object contains data that you can set and are stored persistently. |
| coordinates | The coordinates of the action triggered. |
| state | This is a parameter that is only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action. |
| userDesiredState | This is a parameter that is only set when the action is triggered with a specific value from a Multi Action. For example if the user sets the Game Capture Record action to be disabled in a Multi Action, you would see the value 1. Only the value 0 and 1 are valid. |
| isInMultiAction | Boolean indicating if the action is inside a Multi Action. |
keyUp
When the user releases a key, the plugin will receive the keyUp event as a json structure like:
var json = {
"action": "com.elgato.example.action1",
"event": "keyUp",
"context": opaqueValue,
"device": opaqueValue,
"payload": {
"settings": {<json data>},
"coordinates": {
"column": 3,
"row": 1
},
"state": 0,
"userDesiredState": 1,
"isInMultiAction": false
}
};
| Members | Description |
|---|---|
| action | The action unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered. |
| event | keyUp |
| context | An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API. |
| device | An opaque value identifying the device. |
| payload | A json object |
The payload object contains the following members:
| Payload | Description |
|---|---|
| settings | This json object contains data that you can set and is stored persistently. |
| coordinates | The coordinates of the action triggered. |
| state | This is a parameter that is only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action. |
| userDesiredState | This is a parameter that is only set when the action is triggered with a specific value from a Multi Action. For example if the user sets the Game Capture Record action to be disabled in a Multi Action, you would see the value 1. Only the value 0 and 1 are valid. |
| isInMultiAction | Boolean indicating if the action is inside a Multi Action. |
willAppear
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
The json structure looks like:
var json = {
"action": "com.elgato.example.action1",
"event": "willAppear",
"context": opaqueValue,
"device": opaqueValue,
"payload": {
"settings": {<json data>},
"coordinates": {
"column": 3,
"row": 1
},
"state": 0,
"isInMultiAction": false
}
};
| Members | Description |
|---|---|
| action | The action unique identifier. If you plugin supports multiple actions, you should use this value to know which action was triggered. |
| event | willAppear |
| context | An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API. |
| device | An opaque value identifying the device. |
| payload | A json object |
The payload object contains the following members:
| Payload | Description |
|---|---|
| settings | This json object contains data that you can set and are stored persistently. |
| coordinates | The coordinates of the action triggered. |
| state | This is a parameter that is only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action. |
| isInMultiAction | Boolean indicating if the action is inside a Multi Action. |
willDisappear
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
The json structure looks like:
var json = {
"action": "com.elgato.example.action1",
"event": "willDisappear",
"context": opaqueValue,
"device": opaqueValue,
"payload": {
"settings": {<json data>},
"coordinates": {
"column": 3,
"row": 1
},
"state": 0,
"isInMultiAction": false
}
};
| Members | Description |
|---|---|
| action | The action unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered. |
| event | willAppear |
| context | An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API. |
| device | An opaque value identifying the device. |
| payload | A json object |
The payload object contains the following members:
| Payload | Description |
|---|---|
| settings | This json object contains data that you can set and is stored persistently. |
| coordinates | The coordinates of the action triggered. |
| state | This is a parameter that is only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action. |
| isInMultiAction | Boolean indicating if the action is inside a Multi Action. |
titleParametersDidChange
When the user changes the title or title parameters of the instance of an action, the plugin will receive a titleParametersDidChange event.
The json structure looks like:
var json = {
"action": "com.elgato.example.action1",
"event": "titleParametersDidChange",
"context": "opaqueValue",
"device": "opaqueValue",
"payload": {
"coordinates": {
"column": 3,
"row": 1
},
"settings": {<json data>},
"state": 0,
"title": "",
"titleParameters": {
"fontFamily": "",
"fontSize": 12,
"fontStyle": "",
"fontUnderline": false,
"showTitle": true,
"titleAlignment": "bottom",
"titleColor": "#ffffff"
}
}
}
| Members | Description |
|---|---|
| action | The action unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered. |
| event | titleParametersDidChange |
| context | An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API. |
| device | An opaque value identifying the device. |
| payload | A json object |
The payload object contains the following members:
| Payload | Description |
|---|---|
| settings | This json object contains data that you can set and is stored persistently. |
| coordinates | The coordinates of the action triggered. |
| state | This value indicates for which state of the action the title or title parameters have been changed. |
| title | The new title. |
| titleParameters | A json object describing the new title parameters. |
The titleParameters object contains the following members:
| TitleParameters | Description |
|---|---|
| fontFamily | The font family for the title. |
| fontSize | The font size for the title. |
| fontStyle | The font style for the title. |
| fontUnderline | Boolean indicating an underline under the title. |
| showTitle | Boolean indicating if the title is visible. |
| titleAlignment | Vertical alignment of the title. Possible values are "top", "bottom" and "middle". |
| titleColor | Title color. |
deviceDidConnect
When a device is plugged to the computer, the plugin will receive a deviceDidConnect event.
The json structure looks like:
var json = {
"event": "deviceDidConnect",
"device": opaqueValue,
"deviceInfo": {
"name": "Device Name",
"type": 0,
"size": {
"columns": 5,
"rows": 3
}
},
};
| Members | Description |
|---|---|
| event | deviceDidConnect |
| device | An opaque value identifying the device. |
| deviceInfo | A json object containing information about the device. |
The deviceInfo object contains the following members:
| device | Description |
|---|---|
| type | Type of device. Possible values are kESDSDKDeviceType_StreamDeck (0), kESDSDKDeviceType_StreamDeckMini (1), kESDSDKDeviceType_StreamDeckXL (2), kESDSDKDeviceType_StreamDeckMobile (3) and kESDSDKDeviceType_CorsairGKeys (4). |
| size | The number of columns and rows of keys that the device owns. |
| name | The name of the device set by the user. |
deviceDidDisconnect
When a device is unplugged from the computer, the plugin will receive a deviceDidDisconnect event.
The json structure looks like:
var json = {
"event": "deviceDidDisconnect",
"device": opaqueValue
};
| Members | Description |
|---|---|
| event | deviceDidDisconnect |
| device | An opaque value identifying the device. |
applicationDidLaunch
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. For example the Apple Mail sample plugin uses the following:
"ApplicationsToMonitor": {
"mac": [
"com.apple.mail"
]
]
When a monitored application is launched, the plugin will be notified and will receive the applicationDidLaunch event.
The json structure looks like:
var json = {
"event": "applicationDidLaunch",
"payload" : {
"application": "com.apple.mail"
}
};
| Members | Description |
|---|---|
| event | applicationDidLaunch |
| payload | A json object |
The payload object contains the following members:
| Payload | Description |
|---|---|
| application | The identifier of the application that has been launched. |
applicationDidTerminate
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. For example the Apple Mail sample plugin uses the following:
"ApplicationsToMonitor": {
"mac": [
"com.apple.mail"
]
]
When a monitored application is terminated, the plugin will be notified and will receive the applicationDidTerminate event.
The json structure looks like:
var json = {
"event": "applicationDidTerminate",
"payload" : {
"application": "com.apple.mail"
}
};
| Members | Description |
|---|---|
| event | applicationDidTerminate |
| payload | A json object |
The payload object contains the following members:
| Payload | Description |
|---|---|
| application | The identifier of the application that has been launched. |
systemDidWakeUp
When the computer is wake up, the plugin will receive the systemDidWakeUp event.
The json structure looks like:
var json = {
"event": "systemDidWakeUp"
};
| Members | Description |
|---|---|
| event | systemDidWakeUp |
Several important points to note:
- A plugin could get multiple
systemDidWakeUpevents when waking up the computer - When the plugin receives the
systemDidWakeUpevent, there is no garantee that the devices are available
This API has been introduced in Stream Deck 4.3.
propertyInspectorDidAppear
The plugin will receive a propertyInspectorDidAppear event when the Property Inspector appears:
var json = {
"action": "com.elgato.example.action1",
"event": "propertyInspectorDidAppear",
"context": opaqueValue,
"device": opaqueValue
};
| Members | Description |
|---|---|
| action | The action unique identifier. |
| event | propertyInspectorDidAppear |
| context | An opaque value identifying the instance's action. |
| device | An opaque value identifying the device. |
This API has been introduced in Stream Deck 4.1.
propertyInspectorDidDisappear
The plugin will receive a propertyInspectorDidDisappear event when the Property Inspector disappears:
var json = {
"action": "com.elgato.example.action1",
"event": "propertyInspectorDidDisappear",
"context": opaqueValue,
"device": opaqueValue
};
| Members | Description |
|---|---|
| action | The action unique identifier. |
| event | propertyInspectorDidDisappear |
| context | An opaque value identifying the instance's action. |
| device | An opaque value identifying the device. |
This API has been introduced in Stream Deck 4.1.
sendToPlugin
The plugin will receive a sendToPlugin event when the Property Inspector sends a sendToPlugin event:
var json = {
"action": "com.elgato.example.action1",
"event": "sendToPlugin",
"context": opaqueValue,
"payload": {<json data>}
};
sendToPropertyInspector
The Property Inspector will receive a sendToPropertyInspector event when the plugin sends a sendToPropertyInspector event:
var json = {
"action": "com.elgato.example.action1",
"event": "sendToPropertyInspector",
"context": opaqueValue,
"payload": {<json data>}
};