Events

The UI Extension Application has different kinds of event handlers:

1. Module or Dashboard Startup handlers. These functions are called once when the module or dashboard starts and are considered entry points to your application.
2. Interface events which are are specific to the UI Extension API Interfaces. For example: you can react to an event which is fired whenever the user selects an object in a listing.
3. Custom Command events. These are raised when a custom command - such as a context-menu item - is clicked by the user.
4. Built-in commands, which you can listen by registering to listen to MFiles.Event.BuiltinCommand for the IShellFrame.

Module Startup

Global function OnNewShellUI is the first function called inside the module. This function gets the new IShellUI as parameter

main.js

function OnNewShellUI( shellUI )
{
    // Called during the initialization
}

For many Extension the most important object you can get from the IShellUI is the IShellFrame instance. For that you have to listen for two events:

1. MFiles.Event.NewShellFrame event is fired by the IShellUI instance when the IShellFrame instance is available.
2. MFiles.Event.Started event is fired by the IShellFrame instance when that instance is ready to be used.

Sample code to illustrate the event sequence in the module to get both IShellFrame and IShellUI instances.

main.js

// This function which handles UI Extension initialization phase.
function OnNewShellUI( shellUI )
{
    // Wait for the ShellFrame to be created and started
    shellUI.Events.Register(
        MFiles.Event.NewShellFrame,
        shellFrame => {
            shellFrame.Events.Register(
                MFiles.Event.Started,
                () => {
                    Start( shellUI, shellFrame )
                });
    });
}

// Main application
async function Start( shellUI, shellFrame ) {
    // TODO: write the UI Extension code here.
}

Dashboard Startup

The startup events are fired only once per module. The function handlers must be named functions binded to the global window object inside the dashboard.

OnNewDashboard gets instance of IDashboard as a parameter. The most common Interfaces like IShellFrame and IShellUI are accessible through that interface.

// Dashboard bootstrap function
function OnNewDashboard( newDashboard ) {

}

tip

The argument of the OnNewDashboard function is instance of UIDashboard which has the ShellFrame property, which is one of the most important interfaces for the UI Extensions: IShellFrame.

ShellFrame has ShellUI property which links to the IShellUI, which is another very important interface, because it contains the Vault property, which allows you to access the Vault API

Interface Events

Each interface object has Event property which is instance of IEvents. This interface has two methods:

• Register which is used to register a new event handler for a given Event. This function returns a handle, which can be used to unregister the event handler.
• Unregister which takes the handler returned by the Register function as parameter.

Example of registering an event handler which listens to the IShellListing Selection Changed event.

// shellListing is of type IShellListing
const eventHandle = await shellListing.Events.Register(
  MFiles.Event.SelectionChanged, 
  items => {
    // When the event fires you get the IShellItems object 
  }
);

info

Notice that the Register methods return value is a Promise. You have to either await that in the async function or resolve the promise using .then( eventHandle => { ]})

To see which Interface events are available for each UI Extension Interface see the API Reference Guide for events

Unregistering an Event Handler

To unregister an event handler simply pass the handle returned by the Register method to the Unregister method.

shellListing.Events.Unregister(eventHandle);

Cancelling built-in events

Built-in events can be cancelled by returning false from the attached handler. This can be useful if the handler itself overrides the default behavior:

shellFrame.Commands.Events.Register(
    MFiles.Event.BuiltinCommand,
    (cmdId: number, objectType: number) => {
        // If the user has clicked to create a document then override the behavior.
        if (cmdId === MFiles.BuiltinCommand.NewObject && objectType === 0) {
            shellFrame.ShowMessage("BuiltinCommand as Cancelled by Event handler");
            return false;
        }
    }
)