Events
IDashboardEvents
The IDashboard interface has Events property, which provides access to the IDashboardEvents interface. This interface provides two methods:
- Register( event, callback ): Registers an event handler for the specified event and returns the event handler ID.
- Unregister( eventId ): Unregisters the event handler with the specified ID.
One of the use cases for events in IDashboard is to listen for custom data changes provided by UpdateCustomData method.
Here is a JavaScript example of how to use the IDashboardEvents interface to listen for custom data changes using globally defined events.
// Register event handler for the custom data changes.
const eventId = await dashboard.Events.Register(
MFiles.Event.CustomDataChanged,
(data) => {
console.log("Custom data changed: ", data);
},
);
| Event | Description | Arguments |
|---|---|---|
| Refresh | Triggered when the dashboard data is refreshed. | |
| Started | Sent when the dashboard turns to started state. | |
| Stop | Sent before the dashboard is stopped. | |
| CustomDataChanged | This event is triggered, when custom data on dashboard has changed. The event can be used to update the dashboard based on the new data. This event will fire at least once when the dashboard is started and initialized. | data New custom data for the dashboard |
ISearchPaneEvents
Interface for the Search pane events. The interface provides two methods:
- Register( event, callback ): Registers an event handler for the specified event.
- Unregister( eventId ): Unregisters the event handler with the specified ID.
| Event | Description | Arguments |
|---|---|---|
| Stop | Sent before the Searchpane is closed. | |
| Started | Registers event handler for the Search pane started event, which means that the Search pane is ready to be used. |
IShellFrameEvents
IShellFrameEvents interface provides means to manage shell frame events. The interface provides two methods:
- Register( event, callback ): Registers an event handler for the specified event.
- Unregister( eventId ): Unregisters the event handler with the specified ID.
| Event | Description | Arguments |
|---|---|---|
| Stop | Sent before the IShellFrame is stopped. | |
| Started | Registers event handler for the IShellFrame started event, which means that the IShellFrame is ready to be used. This event will trigger at least once for each registered callback if the IShellFrame is already started and not yet stopped. | |
| ViewLocationChanged | Registers event handler for the IShellFrame ViewLocationChanged event, which means that the view location has changed. | |
| ViewLocationChangedAsync | Registers event handler for the IShellFrame ViewLocationChangedAsync event, which means that the view location has changed. | |
| NewCommands | Registers event handler for the IShellFrame NewCommands event, which means that a new ICommands interface has been created and is ready to be used. | |
| NewRightPane | Registers event handler for the IShellFrame NewRightPane event, which means that a shell pane container is created for right shell pane. | |
| NewShellListing | Registers event handler for the IShellFrame NewShellListing event, which means that a new shell listing object is created. | newShellisting The new IShellListing object. |
IShellListingEvents
IShellListingEvents interface provides means to manage shell listing events. The interface provides two methods:
- Register( event, callback ): Registers an event handler for the specified event.
- Unregister( eventId ): Unregisters the event handler with the specified ID.
| Event | Description | Arguments |
|---|---|---|
| Started | Registers event handler for the IShellListingEvents started event. | |
| Stop | Registers event handler for the IShellListingEvents stopped event. | |
| SelectionChanged | Registers event handler for the IShellListingEvents SelectionChanged event. This event is triggered when the selection in the listing view is set, changed or removed. | shellItems Contains the selected items. |
| SelectNextObject | Registers event handler for the IShellListingEvents SelectNextObject event. This event is triggered when the next object in the listing is selected. | |
| SelectPreviousObject | Registers event handler for the IShellListingEvents SelectPreviousObject event. This event is triggered when the previous object in the listing is selected. | |
| SelectNextFolder | Registers event handler for the IShellListingEvents SelectNextFolder event. This event is triggered when the next folder in the listing is selected. | folderType type of the folder, which have been selected. |
| SelectPreviousFolder | Registers event handler for the IShellListingEvents SelectPreviousFolder event. This event is triggered when the previous folder in the listing is selected. | folderType type of the folder, which have been selected. |
| ListingDeactivated | Registers event handler for the IShellListingEvents ListingDeactivated event. This event is triggered when the listing object becomes inactive and loses the input focus. | shellListing The next active shell listing object. Can be null. |
| ListingActivated | Registers event handler for the IShellListingEvents ListingActivated event. This event is triggered when the listing object becomes active and receives the input focus. | shellListing The previous active shell listing object. Can be null. |
| ContentChanged | Registers event handler for the IShellListingEvents ContentChanged event. This event is triggered when the current listing content is changed, or listed items are modified. | shellItems Contains all items in the listing. |
| ListItemAdded | Registers event handler for the IShellListingEvents ListItemAdded event. This event is triggered when one or more items are added to the listing. | objectVersion Object |
| ListItemRemoved | Registers event handler for the IShellListingEvents ListItemRemoved event. This event is triggered when one or more items are removed from the listing. | listItem Either an array of ObjectVersionEx if non-folder objects are removed or a single ObjectVersionEx, in case folder is removed. removedExternalFolder In case folder was removed, include information about the old external folder item being removed in case of |
| ListItemModified | Registers event handler for the IShellListingEvents ListItemModified event. This event is triggered when one or more of the items that are currently selected are modified. | oldServerObjVer Array of old object versions. newObjVer Array of new objects. |
| SelectedItemsChanged | Registers event handler for the IShellListingEvents SelectedItemsChanged event. This event is triggered when one or more of the items that are currently selected are modified. | shellItems Contains the selected items. |
IShellPaneContainerEvents
Interface for the Shell pane container events. The interface provides two methods:
- Register( event, callback ): Registers an event handler for the specified event.
- Unregister( eventId ): Unregisters the event handler with the specified ID.
| Event | Description | Arguments |
|---|---|---|
| Stop | Sent when the object turns to stopped state. | |
| Started | Sent when the object turns to started state. |
IShellPaneTabEvents
Interface for the Shell pane tab events. The interface provides two methods:
- Register( event, callback ): Registers an event handler for the specified event.
- Unregister( eventId ): Unregisters the event handler with the specified ID.
| Event | Description | Arguments |
|---|---|---|
| Started | Sent when the object turns to started state. | |
| Stop | Sent before the object is stopped. |
IWindowEvents
Interface for the Window events. The interface provides two methods:
- Register( event, callback ): Registers an event handler for the specified event.
- Unregister( eventId ): Unregisters the event handler with the specified ID.
| Event | Description | Arguments |
|---|---|---|
| CloseWindow | Sent when the window is requested to closed. |
IShellUIEvents
Interface for the Shell UI events. The interface provides two methods:
- Register( event, callback ): Registers an event handler for the specified event.
- Unregister( eventId ): Unregisters the event handler with the specified ID.
| Event | Description | Arguments |
|---|---|---|
| Started | Sent when the object turns to started state. | |
| Stop | Sent when the application is stopping. | |
| NewShellFrame | Triggered when any shell frame object is created, including normal shell frames, common dialogs, and embedded or special shell frames. | shellFrame - The new shell frame object. |
| NewNormalShellFrame | Triggered when a normal shell frame object is created. Note that this event is not triggered for common dialogs, or embedded or special shell frames. | shellFrame - The new shell frame object. |
| CrossApplicationNotification | Broadcasted message to multiple applications. | appGUID - GUID of the target application, or null if broadcasted to all applications. msgId - ID of the message which is sent to the other applications. data - Custom data to be sent. |
| CheckInObjects | Triggered when the check in of one or more vault objects is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objVers - The object versions being checked in. properties - The properties to add/replace during check-in. options - Flags that control the operation. |
| ObjectsCheckedIn | Triggered after the request to check in one or more vault objects succeeded on M-Files Server. | checkedInObjects - The extended object info for checked-in objects. |
| CheckOutObjects | Triggered when the checking out of one or more vault objects is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objIds - The objects being checked out. |
| ObjectsCheckedOut | Triggered after the request to check out one or more vault objects succeeded on M-Files Server. | checkedOutVersions - The new checked-out object versions with properties and ACL. previousVersions - The previous versions before checkout. |
| UndoObjectCheckouts | Triggered when the undoing checkout of one or more vault objects is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objVers - The checked-out object versions being reverted. force - If true, undo checkout is performed even if not checked out to the caller. |
| ObjectCheckoutsUndone | Triggered after the request to undo checkout of one or more vault objects succeeded on M-Files Server. | restoredObjects - The extended object info for restored objects. |
| DestroyObjects | Triggered when the destruction of one or more vault objects is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objIds - The objects being permanently destroyed. |
| ObjectsDestroyed | Triggered after the request to destroy one or more vault objects succeeded on M-Files Server. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | updatedObjects - Information about objects that were also updated during the operation. |
| DestroyObjectVersions | Triggered when the destruction of one or more object versions is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | objVers - The object versions being permanently destroyed. |
| ObjectVersionsDestroyed | Triggered after the request to destroy one or more object versions succeeded on M-Files Server. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | updatedObjects - Information about objects that were also updated during the operation. |
| RemoveObjects | Triggered when the deletion of one or more vault objects is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objIds - The objects being deleted. |
| ObjectsRemoved | Triggered after the request to delete one or more vault objects succeeded on M-Files Server. | deletedObjects - The extended object info for deleted objects. |
| UndeleteObjects | Triggered when the undeletion of one or more vault objects is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | objIds - The objects being restored from deletion. |
| ObjectsUndeleted | Triggered after the request to undelete one or more vault objects succeeded on M-Files Server. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | extObjectInfos - The extended object info for undeleted objects. |
| RemoveObjectFile | Triggered when the removal of a file from an object version is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objVer - The object version from which the file is being removed. fileVer - The file being removed. |
| ObjectFileRemoved | Triggered after a request to remove an object file from an object version succeeds on M-Files Server. | objectVersion - Information about the latest version of the document after the operation. |
| RollBackObjectVersion | Triggered when the roll back of a previous vault object version is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | objId - The object to roll back. rollbackVersion - The version to roll back to. A new version is created using this as source. |
| ObjectVersionRolledBack | Triggered after a request to roll back a previous vault object version succeeds on M-Files Server. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | extObjectInfo - Information about the object after the operation. |
| CreateObject | Triggered when the creation of a new object is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objectTypeId - The object type ID for the new object. properties - The properties for the new object. acl - The access control list for the new object. options - Flags that control the operation. checkIn - If true, the object is checked in immediately after creation. objFileSources - The file sources for the new object. |
| ObjectCreated | Triggered after the request to create a new object succeeded on M-Files Server. | isVisibleToUser - True if the created object is visible to the user. createdObject - The created object with properties and ACL. |
| AddObjectFile | Triggered when the addition of a new file to a document is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objVer - The object version to which the file is being added. title - The title of the new file. extension - The file extension (without the leading dot). createdAtUtc - The UTC timestamp when the file was originally created. accessedAtUtc - The UTC timestamp when the file was last accessed. writtenAtUtc - The UTC timestamp when the file was last written to. changedAtUtc - The UTC timestamp when the file was last changed (content or attributes). |
| ObjectFileAdded | Triggered after a request to add a file to a document succeeds on M-Files Server. | fileVer - The version information of the added file. objectVersion - The object version after the file was added. |
| RenameObjectFile | Triggered when the renaming of a file in a document is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objVer - The object version containing the file. fileVer - The file being renamed. title - The new title for the file. extension - The new extension for the file (without the leading dot). |
| ObjectFileRenamed | Triggered after a request to rename a file in a document succeeds on M-Files Server. | objectVersion - The object version after the file was renamed. |
| SetPropertiesOfObjectVersions | Triggered when setting properties for one or more object versions is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | setPropertiesParams - Array of parameters for setting properties on multiple objects. |
| PropertiesOfObjectVersionsSet | Triggered after a request to set properties of one or more object versions succeeds on M-Files Server. | extObjectInfos - Extended object info for each object after the properties were set. |
| SetObjectVersionPermissions | Triggered when changing the permissions of an object version is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objVer - The object version whose permissions are being changed. acl - The new access control list. options - Flags that control the operation. |
| ObjectVersionPermissionsSet | Triggered after a request to change the permissions of an object version succeeds on M-Files Server. | isSpecifiedVersionStillVisible - True if the specified version is still visible after the operation. specifiedVersion - Information about the specified version after the operation. extObjectInfo - Extended object info after the operation. |
| SetObjectLevelProperty | Triggered when setting an object-level property is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. | objId - The object whose property is being set. property - The property value to set. options - Flags that control the operation. |
| ObjectLevelPropertySet | Triggered after a request to set an object-level property succeeds on M-Files Server. | extObjectInfo - Extended object info after the operation. |
| ModifyObjectVersionLabels | Triggered when modifying the labels of an object version is requested. This event occurs before the request is passed to M-Files Server. Return a promise that resolves true to proceed, or Error object/false to cancel the operation. When resolving with an Error object, its message will be shown to the user, enabling you to provide a custom explanation for why the operation was stopped. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | objVer - The object version whose labels are being modified. clearFromOtherVersions - If true, the specified labels are cleared from other versions. append - If true, the labels are appended to existing labels; if false, existing labels are replaced. labelIDs - The IDs of the labels to set. |
| ObjectVersionLabelsModified | Triggered after a request to modify the labels of an object version succeeds on M-Files Server. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | objVer - The object version whose labels were modified. clearFromOtherVersions - If true, the specified labels were cleared from other versions. append - If true, the labels were appended to existing labels. labelIDs - The IDs of the labels that were set. |
| ChangeVaultLanguage | Triggered when changing the vault language is requested. This event occurs before the request is passed to M-Files Server. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | languageId - The ID of the new vault language. |
| VaultLanguageChanged | Triggered after the vault language has been changed. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. | languageId - The ID of the new vault language. |
| LogOut | Triggered when logging out of the vault is requested. This event occurs before the logout is processed. NOTE: Stability is experimental. Non-backward compatible changes or removal may occur in any future release. Use of this feature is not recommended for production environments. |
ICommandsEvents
Ths ICommandEvents interface provides methods to register and unregister event handlers for custom commands:
- Register( event, callback ): Registers an event handler for the specified event and returns the event handler ID.
- Unregister( eventId ): Unregisters the event handler with the specified ID.
The ICommands interface has Events property, which provides access to the ICommandsEvents interface.
Here is a JavaScript example of how to use the ICommandsEvents interface to listen for custom command events and their data:
const commandsEvents = shellFrame.Commands.Events;
// Register event handler for the custom command
const eventId = await commandsEvents.Register(
Event.CustomCommand,
(commandID, data) => {
console.log("Custom command invoked: ", commandID);
console.log("Data: ", data);
},
);
| Event | Description | Arguments |
|---|---|---|
| CustomCommand | Triggered when a custom command is invoked. | commandID The ID of the custom command to be used. data The data passed to the custom command. |
| BuiltinCommand | Callback handler for Builtin commands. Allows UI Extensibility applications to intercept and optionally cancel built-in command execution. | argument of type ( commandId : BuiltinCommand, param : any ) => Promise< boolean > |