Handling IMatch Messages

IMatch Messages

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 IdentifierDescription
File Window
fileWindow.selectionChangedThe selection or the focused file in the active file window has changed.
fileWindow.clearedThe 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.selectionClearedThe selection in the active file window was cleared. No file is selected anymore.
fileWindow.focusChangedThe 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.focusClearedThe focus was cleared. No file is focused anymore.
fileWindow.scopeChangedThe 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.setFocusThe 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.killFocusThe 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.
ParameterDescription
data.fileNameThe fully-qualified name of the database file.
database.openedA new database was opened and attached. This message is sent when IMatch is starting or when the user switches to another database.
ParameterDescription
data.fileNameThe fully-qualified name of the database file.
Application
app.activeViewChangedThe 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).
ParameterDescription
data.viewThe name of the (new) active view.
You can use the function getActiveView to determine the current view.
app.activeFileWindowChangedThe active file window has changed. This message is sent when the user switches to another view or closes a result window.
app.selectedFoldersChangedThe selected folder in the Media & Folders View has changed. You can access the selected folders via the @imatch.selectedFolders idlist.
app.selectedCategoriesChangedThe selected category in the Category View has changed. You can access the selected categories via the @imatch.selectedCategories idlist.
app.selectedCollectionsChangedThe selected collection in the Collection View has changed. You can access the selected collections via the @imatch.selectedCollections idlist.
app.selectedTimelineNodesChangedThe selected node in the Timeline View has changed. You can access the selected nodes via the @imatch.selectedTimelineNodes idlist.
app.appfilter.createdThe app filter for the app specified in the data part of the message was created.
app.appfilter.updatedThe app filter for the app specified in the data part of the message was updated.
app.appfilter.removedThe app filter for the app specified in the data part of the message was removed.
app.fileOp.batchBeginIMatch 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.globalOptionsChangedGlobal options have changed (usually triggered by the user when he makes changes in Edit > Preferences).
app.contextChangedThe 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.batchEndA batch operation has completed.
app.workspace.loadedA 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.closingIMatch is closing. Apps should stop all running processes when this message is received.
App Panel
app.panelActivateAn 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.panelDeactivateAn 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.
ParameterDescription
data.visibleThis parameter is true when the panel is still visible.
If the panel is part of a group and the user activates another panel in that group, the panel will be both deactivated and invisible.
This message can be used to cancel resource-intensive operations (e.g., animations or web service calls) when a panel is no longer visible.
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.panelHideAn 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.startAn import & export module is running, e.g. the Batch Processor. The name and GUID of the module are provided in data.
app.import-export.finishAn import & export module has finished. The GUID of the module is provided in data.
app.import-export.progressAn 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.newAppA new app was found. This message is sent when the file system monitor in Match detects a new app.
appmanager.updatedAppAn existing app was updated.
appmanager.removedAppAn app was removed from the file system.
appmanager.app.startedAn 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.closedAn app closed (modal closed, panel closed, ...). The parameter is an object and contains the id of the app in the appId member.
appmanager.appResult.setAn 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.