Received Events

Plugins can receive events from the Stream Dock application.

Once the Stream Dock application has loaded a plugin and the user has set up some keys to use the plugin, the plugin will receive various events. Similarly, when the Property Inspector is displayed, it will receive some events.

Both plugins and Property Inspectors can receive the following events:

Event	Description
didReceiveSettings	Event received after settings change
didReceiveGlobalSettings	Event received after globalSettings change

Plugins may also receive the following additional events:

Event	Description
keyDown	Event received when a user presses a key
keyUp	Event received when a user releases a key
dialDown	Event received when a user presses a dial
dialUp	Event received when a user releases a pressed dial
dialRotate	Event received when a user rotates a dial
willAppear	Event received when an action instance appears on the Stream Dock (e.g., when hardware is first inserted or when entering a folder containing the action)
willDisappear	Event received when an action instance no longer appears on the Stream Dock (e.g., when switching profiles or folders)
titleParametersDidChange	Event received when the user changes the title or title parameters
deviceDidConnect	Event received when a device is inserted into the computer
deviceDidDisconnect	Event received when a device is removed from the computer
applicationDidLaunch	Event received when a monitored application is launched
applicationDidTerminate	Event received when a monitored application terminates
systemDidWakeUp	Event received when the computer wakes up
propertyInspectorDidAppear	Event received when the Property Inspector appears in the Stream Dock UI (e.g., when selecting a new instance)
propertyInspectorDidDisappear	Event received when the Property Inspector is destroyed in the Stream Dock UI (e.g., when selecting a new instance and the old instance triggers this event)
sendToPlugin	Event received when the Property Inspector uses this event

Property Inspectors may also receive the following event:

Event	Description
sendToPropertyInspector	Event received when the plugin uses this event

didReceiveSettings

Event received after settings change

{
  "action": "com.mirabox.demo.action1", 
  "event": "didReceiveSettings", 
  "context": "uniqueValue", 
  "device": "uniqueValue", 
  "payload": {
   "settings": {<json data>},
    "coordinates": {
      "column": 3, 
      "row": 1
    }, 
    "isInMultiAction": false
  }
}

Member	Description
action	Unique identifier for the action
event	didReceiveSettings
context	Value that identifies the instance action
device	Value used to identify the device
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains the persistent storage data
coordinates	Coordinates of the triggered action
state	Set only if the action defines multiple states in its manifest.json. The value, starting from 0, contains the current state of the action
isInMultiAction	Boolean indicating whether the action is within a Multi-Action

didReceiveGlobalSettings

Event received after globalSettings change

{
  "event": "didReceiveGlobalSettings", 
  "payload": {
   "settings": {<json data>}
  }
}

Member	Description
event	didReceiveGlobalSettings
payload	A JSON object

The payload object contains the following member:

Payload	Description
settings	This JSON object contains the persistent storage data

dialDown

When the user presses the knob, the plugin will receive the event

{
  "action": "com.mirabox.demo.action2",
  "event": "dialDown",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "controller": "Encoder",
    "settings": {<json data>},
    "coordinates": {
      "column": 0,
      "row": 0
    },
  }
}

Member	Description
action	Unique identifier for the action. If your plugin supports multiple actions, use this value to determine which action was triggered
event	dialDown
context	Value that identifies the instance action
device	Value used to identify the device
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains the persistent storage data
coordinates	Coordinates of the triggered action
controller	Encoder

dialUp

When the user releases the pressed knob, the plugin will receive the event

{
  "action": "com.mirabox.demo.action2",
  "event": "dialUp",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "controller": "Encoder",
    "settings": {<json data>},
    "coordinates": {
      "column": 0,
      "row": 0
    },
  }
}

Member	Description
action	Unique identifier for the action. If your plugin supports multiple actions, use this value to determine which action was triggered
event	dialUp
context	Value that identifies the instance action
device	Value used to identify the device
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains the persistent storage data
coordinates	Coordinates of the triggered action
controller	Encoder

dialRotate

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

{
  "action": "com.mirabox.demo.action2",
  "event": "dialRotate",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "controller": "Encoder",
    "settings": {<json data>},
    "coordinates": {
      "column": 0,
      "row": 0
    },
    "ticks": -5,
    "pressed": false
  }
}

Member	Description
action	Unique identifier for the action. If your plugin supports multiple actions, use this value to determine which action was triggered
event	dialRotate
context	Value that identifies the instance action
device	Value used to identify the device
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains the persistent storage data
coordinates	Coordinates of the triggered action
controller	Encoder
ticks	An integer representing the number of "ticks" during knob rotation. Positive values indicate clockwise rotation, negative values indicate counterclockwise rotation, and zero indicates no rotation
pressed	Boolean value indicating whether the knob was in a pressed state during rotation

keyDown

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

{
  "action": "com.mirabox.demo.action2",
  "event": "keyDown",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "settings": {<json data>},
    "coordinates": {
      "column": 0,
      "row": 0
    },
    "state": 0,
    "isInMultiAction": false
  }
}

Member	Description
action	Unique identifier for the action. If your plugin supports multiple actions, use this value to determine which action was triggered
event	keyDown
context	Value that identifies the instance action
device	Value used to identify the device
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains the persistent storage data
coordinates	Coordinates of the triggered action
state	Set only if the action has multiple states defined in its manifest.json. The value starting from 0 represents the current state of the action
isInMultiAction	Boolean value indicating whether the action is within a Multi-Action

keyUp

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

{
  "action": "com.mirabox.demo.action2",
  "event": "keyUp",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "settings": {<json data>},
    "coordinates": {
      "column": 0,
      "row": 0
    },
    "state": 0,
    "isInMultiAction": false
  }
}

Member	Description
action	Unique identifier for the action. If your plugin supports multiple actions, use this value to determine which action was triggered
event	keyUp
context	Value that identifies the instance action
device	Value used to identify the device
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains the persistent storage data
coordinates	Coordinates of the triggered action
state	Set only if the action has multiple states defined in its manifest.json. The value starting from 0 represents the current state of the action
isInMultiAction	Boolean value indicating whether the action is within a Multi-Action

willAppear

When an instance of an action appears on the Stream Dock, such as when hardware is first inserted or when entering a folder that contains the action, the plugin will receive an event. You will see this event in the following scenarios:

• The Stream Dock application starts

• The user switches between profiles

• The user sets a key to use your action

{
    "action": "com.mirabox.demo.action1",
    "event": "willAppear",
    "context": uniqueValue,
    "device": uniqueValue,
    "payload": {
        "settings": {<json data>},
        "coordinates": {
            "column": 3, 
            "row": 1
        },
        "controller": "Keypad",
        "state": 0,
        "isInMultiAction": false
    }
}

Member	Description
action	Unique identifier for the action. If your plugin supports multiple actions, use this value to determine which action was triggered
event	willAppear
context	Value that identifies the instance action
device	Value used to identify the device
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains the persistent storage data
coordinates	Coordinates of the triggered action
controller	Keypad (normal buttons), Information (view-only, no touch or button events), SecondaryScreen (small screen display), Knob (rotary control)
state	Set only if the action has multiple states defined in its manifest.json. The value starting from 0 represents the current state of the action
isInMultiAction	Boolean value indicating whether the action is within a Multi-Action

willDisappear

When an instance of an action stops being displayed on the Stream Dock, such as when switching profiles or folders, the plugin will receive an event. You will see this event in the following scenarios:

• The user switches between profiles

• The user deletes the action

{
    "action": "com.mirabox.demo.action1",
    "event": "willDisappear",
    "context": uniqueValue,
    "device": uniqueValue,
    "payload": {
        "settings": {<json data>},
        "coordinates": {
            "column": 3, 
            "row": 1
        },
        "controller": "Keypad",
        "state": 0,
        "isInMultiAction": false
    }
}

Member	Description
action	Unique identifier for the action. If your plugin supports multiple actions, use this value to determine which action was triggered
event	willDisappear
context	Value that identifies the instance action
device	Value used to identify the device
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains the persistent storage data
coordinates	Coordinates of the triggered action
controller	Keypad (normal buttons), Information (view-only, no touch or button events), SecondaryScreen (small screen display), Knob (rotary control)
state	Set only if the action has multiple states defined in its manifest.json. The value starting from 0 represents the current state of the action
isInMultiAction	Boolean value indicating whether the action is within a Multi-Action

titleParametersDidChange

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

{
  "action": "com.mirabox.demo.action1", 
  "event": "titleParametersDidChange", 
  "context": "uniqueValue", 
  "device": "uniqueValue", 
  "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"
    }
  }
}

Member	Description
action	Unique identifier for the action. If your plugin supports multiple actions, use this value to determine which action was triggered
event	titleParametersDidChange
context	Value that identifies the instance action
device	Value used to identify the device
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains the persistent storage data
coordinates	Coordinates of the triggered action
title	New title
state	Set only if the action has multiple states defined in its manifest.json. The value starting from 0 represents the current state of the action
titleParameters	JSON object describing the new title parameters

The titleParameters object contains the following members:

TitleParameters	Description
fontFamily	Title font
fontSize	Font size of the title
fontStyle	Font style of the title
fontUnderline	Boolean value for the title underline
showTitle	Boolean value indicating whether the title is visible
titleAlignment	Position of the title
titleColor	Title color

deviceDidConnect

When a device is inserted into the computer, the plugin will receive this event

{
 "event": "deviceDidConnect",
    "device": uniqueValue,
     "deviceInfo": {
        "name": "Device Name",
        "type": 0,
         "size": {
            "columns": 5,
            "rows": 3
        }
    },
}

Member	Description
event	deviceDidConnect
device	Value used to identify the device
deviceInfo	A JSON object

The deviceInfo object contains the following members:

Device	Description
type	Type of the device
size	Number of rows and columns of keys the device has
name	Name of the device

deviceDidDisconnect

When a device is disconnected from the computer, the plugin will receive this event

{
 "event": "deviceDidDisconnect",
    "device": uniqueValue
}

Member	Description
event	deviceDidDisconnect
device	Value used to identify the device

applicationDidLaunch

Plugins can request to be notified when certain applications are launched or terminated in their manifest.json. The manifest.json should include an object specifying a list of application identifiers to monitor. On macOS, use the application bundle identifier, and on Windows, use the exe file name. For example, the Apple Mail sample plugin uses the following:

"ApplicationsToMonitor": {
 "mac": [
  "com.apple.mail"
 ]
}

When a monitored application is launched, the plugin will receive this event

{
    "event": "applicationDidLaunch",
    "payload" : {
        "application": "com.apple.mail"
    }
}

applicationDidLaunch

When a monitored application is launched, the plugin will receive this event.

Member	Description
event	applicationDidLaunch
payload	A JSON object

The payload object contains the following members:

Payload	Description
application	The identifier of the launched application

applicationDidTerminate

The plugin can request notifications when certain applications are launched or terminated in its manifest.json. The manifest.json should include an object specifying the list of application identifiers to monitor. On macOS, use the application bundle identifier, and on Windows, use the exe file name. For example, the Apple Mail sample plugin uses the following:

"ApplicationsToMonitor": {
 "mac": [
  "com.apple.mail"
 ]
}

When a monitored application terminates, the plugin will receive this event

{
    "event": "applicationDidTerminate",
    "payload" : {
        "application": "com.apple.mail"
    }
}

Member	Description
event	applicationDidLaunch
payload	A JSON object

The payload object contains the following members:

payload	Description
application	The identifier of the terminated application

systemDidWakeUp

When the computer wakes up, the plugin will receive this event.

{
 "event": "systemDidWakeUp"
}

Member	Description
event	systemDidWakeUp

Important points to note：

• The plugin may receive multiple systemDidWakeUp events when the computer wakes up.

• The availability of the device cannot be guaranteed when the plugin receives the systemDidWakeUp event.

propertyInspectorDidAppear

When the property inspector appears, the plugin will receive this event.

{
  "action": "com.mirabox.demo.action1", 
  "event": "propertyInspectorDidAppear", 
  "context": uniqueValue, 
  "device": uniqueValue
}

Member	Description
action	The unique identifier for the action. Use this value to determine which action triggered the event if your plugin supports multiple actions.
event	propertyInspectorDidAppear
context	Identifier for the instance action
device	Identifier for the device

propertyInspectorDidDisappear

When the property inspector disappears, the plugin will receive this event.

{
    "action": "com.mirabox.demo.action1", 
    "event": "propertyInspectorDidDisappear", 
    "context": uniqueValue, 
    "device": uniqueValue
}

Member	Description
action	The unique identifier for the action. Use this value to determine which action triggered the event if your plugin supports multiple actions.
event	propertyInspectorDidDisappear
context	Identifier for the instance action
device	Identifier for the device

sendToPlugin

When the property inspector sends a sendToPlugin event, the plugin will receive this event.

{
    "action": "com.mirabox.demo.action1", 
    "event": "sendToPlugin", 
    "context": uniqueValue, 
    "payload": {<json data>}
}

sendToPropertyInspector

When the plugin sends a sendToPropertyInspector event, the property inspector will receive this event.

{
    "action": "com.mirabox.demo.action1", 
    "event": "sendToPropertyInspector", 
    "context": uniqueValue, 
    "payload": {<json data>}
}