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
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(
(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


Selecting Previous Object