This document describes all messages sent by IMatch via the web socket.
IMatch occasionally sends messages to interested receivers. Messages are valid JSON.
Each message uses a string as the message identifier in the msg
element, and additional parameters depending on the message.
Message Identifier | Description | ||||
---|---|---|---|---|---|
File Window | |||||
fileWindow.selectionChanged | The selection or the focused file in the active file window has changed. | ||||
fileWindow.cleared | The file window was cleared (empties), e.g. in preparation of a folder change. This message is sent very often, and sometimes even multiple times in a row, even if the selection has not really changed. If your app performs expensive operations when it receives this message, you may cache the last selection and compare it with the current selection when this message is received. | ||||
fileWindow.selectionCleared | The selection in the active file window was cleared. No file is selected anymore. | ||||
fileWindow.focusChanged | The focused file in the active file window has changed. The data element contains the id of the focused file, or 0 when no file is focused. | ||||
fileWindow.focusCleared | The focus was cleared. No file is focused anymore. | ||||
fileWindow.scopeChanged | The scope (which files are shown) in the file window changes. This message is sent every time the file window updates its scope, e.g., when a new folder or category is selected, something changes in the filter panel, the user is working with the search bar etc. | ||||
fileWindow.setFocus | The file window has received the input focus and is now the active window. The name of the file window is included in the message data. | ||||
fileWindow.killFocus | The file window is no longer the active window. The name of the file window is included in the message data. | ||||
Database | |||||
database.closing |
The current database is closing. This message is sent when IMatch is closing or if the user switches to another database.
|
||||
database.opened | A new database was opened and attached. This message is sent when IMatch is starting or when the user switches to another database.
|
||||
Application | |||||
app.activeViewChanged | The active view has changed. This event is sent when the user switches to another view (e.g., from the Media & and Folders View to the Category View).
|
||||
app.activeFileWindowChanged | The active file window has changed. This message is sent when the user switches to another view or closes a result window. | ||||
app.selectedFoldersChanged | The selected folder in the Media & Folders View has changed. You can access the selected folders via the @imatch.selectedFolders idlist. | ||||
app.selectedCategoriesChanged | The selected category in the Category View has changed. You can access the selected categories via the @imatch.selectedCategories idlist. | ||||
app.selectedCollectionsChanged | The selected collection in the Collection View has changed. You can access the selected collections via the @imatch.selectedCollections idlist. | ||||
app.selectedTimelineNodesChanged | The selected node in the Timeline View has changed. You can access the selected nodes via the @imatch.selectedTimelineNodes idlist. | ||||
app.appfilter.created | The app filter for the app specified in the data part of the message was created. | ||||
app.appfilter.updated | The app filter for the app specified in the data part of the message was updated. | ||||
app.appfilter.removed | The app filter for the app specified in the data part of the message was removed. | ||||
app.fileOp.batchBegin | IMatch begins with a long-running batch operation (e.g., copying files, moving folders, renaming, ...). An app may consider pausing web socket message processing during a batch operation because usually hundreds or thousands of messages are sent. To improve IMatch performance, an app may call closeWebSocket in the app.fileOp.batchBegin and openWebSocket in the app.fileOp.batchEnd message handler.
| ||||
app.globalOptionsChanged | Global options have changed (usually triggered by the user when he makes changes in Edit > Preferences). | ||||
app.contextChanged | The application context has changed (other view, dialog open, ...).
id is the context id and name is the name of the context if available. See also the getAppContext | ||||
app.fileOp.batchEnd | A batch operation has completed. | ||||
app.workspace.loaded | A workspace was loaded. You can query the name of the workspace via the imatch/workspace/info endpoint or the getWorkspaceInfo method of the IMatch class. | ||||
app.closing | IMatch is closing. Apps should stop all running processes when this message is received. | ||||
App Panel | |||||
app.panelActivate | An app panel has been activated (the user clicked on the panel group tab or the panel itself). This message is sent only to the app running in that panel. | ||||
app.panelDeactivate | An app panel has been deactivated. The user clicked into another panel or window. This message is sent only to the app running in that panel.
| ||||
app.panelShow | When an app starts, it is considered to be visible. Later, the user may hide apps running in an app panel by switching to another panel in the same group. This event is sent when an app panel has been made visible (e.g., the user switched to the app panel from another panel, un-hiding the app panel in that process). This message is sent only to the app running in that panel. If an app panel is hidden, you may want to perform some optimizations, like not calculating things all the time or updating stuff when monitoring events. Apps should be designed to use low CPU when hidden. | ||||
app.panelHide | An app panel has been hidden (e.g., the user switched from the app panel from another panel, hiding the app panel in that process). This message is sent only to the app running in that panel. | ||||
Import & Export | |||||
app.import-export.start | An import & export module is running, e.g. the Batch Processor. The name and GUID of the module are provided in data. | ||||
app.import-export.finish | An import & export module has finished. The GUID of the module is provided in data. | ||||
app.import-export.progress | An import & export module is running and providing a progress percentage (0-100). The GUID of the module and the percentage are provided in data. | ||||
App Manager | |||||
appmanager.newApp | A new app was found. This message is sent when the file system monitor in Match detects a new app. | ||||
appmanager.updatedApp | An existing app was updated. | ||||
appmanager.removedApp | An app was removed from the file system. | ||||
appmanager.app.started | An app was started (modal, panel or otherwise). The parameter is an object and contains the id of the app in the appId member. | ||||
appmanager.app.closed | An app closed (modal closed, panel closed, ...). The parameter is an object and contains the id of the app in the appId member. | ||||
appmanager.appResult.set | An app has used the imatch/apps/result endpoint to set a result. The message contains a JSON object with the appId and result data set. |
Handling Messages
To receive messages from IMatch, you create a web socket with IMatch.openWebSocket method and then listen to incoming messages via onmessage
.
IMatch.openWebSocket();
IMatch.webSocket().onmessage = function(e) {
// Parse the message from string format into JSON.
var msg = JSON.parse(e.data);
if (msg.msg == 'fileWindow.selectionChanged') {
// The user selected different files in the file window.
}
...
};
Example
For a working example, see the App Spy or File Window sample app.