Skip to main content

Working with the Shell Listing

The Shell Listing represents the list of files, objects, views, groupings, or other content shown within the current object listing. Changes in the listing view affect various parts of the client. For example: when objects are selected or deselected the Preview and Metadata tabs display information about the selected object(s).

The ActiveListing is a property of IShellFrame and there are two main events, which are fired when it changes:

  • MFiles.Event.NewShellListing is fired when a new listing is created, for example when user navigates to another view.
  • MFiles.Event.SelectionChanged is fired when user makes a new selection in the active view, for example by clicking the object with mouse.

All properties and methods of the listing are described in IShellListing and properties and methods of the selected items are described in IShellItems.

The ActiveListing has two properties which enumerate the items inside the Listing

  • items which is instance of IShellItems holds all items in the listing
  • CurrentSelection which is instance of IShellItems holds the user selected items

Observing the changes to Current Selection​

Current selection represents the user selected items from the Listing View.

To observe the selection changes of the active selection you can listen to MFiles.Event.SelectionChanged event.


// hold the current values 
const state = {
    listing: null,
    selectedItems: null,
    selectionChangedEventId: 0
}

// Observe changes to the active view
shellListing.Events.Register( 
    MFiles.Event.NewShellListing,
    async (listing) => {

        // Before registering a new handler, unregister the previous event handler
        if( state.selectionChangedEventId ) {
            state.listing.Events.Unregister( currentSelection.selectionChangedEventId );
            state.selectionChangedEventId = 0;
        }

        // Save the old listing item so that we can unregister the event handler.
        state.listing = listing;

        // save the event handler id so that we can unregister if if the view changes.
        state.selectionChangedEventId = await listing.Events.Register(
            MFiles.Event.SelectionChanged,
            (items) => {
                // items is IShellItems instance holding the current selection

                 // log number of selected items
                console.log( items.Count );

                // get the object verions and log the titles of the files
                const list = items.ObjectVersions || [];
                list.forEach( item => {
                    console.log( item.object_version?.title );
                })
            }
        )

    }
);

Add New File to Multi Document Object​

Here is a React example of how to add new file into a multi document object. The Example assumes selectedItems has instance of IShellItems.

Replacing a File​

Here is a React example of how to replace a file into a normal document object. The Example assumes selectedItems has instance of IShellItems.

Selecting Next Object​

listing.SelectNextObject();

Selecting Previous Object​

listing.SelectPrevObject();