PlatformUI API - access the Notes Client workbench

Abstract

ShowTable of Contents

HideTable of Contents

1 Access the API

1.1 Message boxes
1.2 File and directory dialogs
1.3 Workbench access

2 Download link

The PlatformUI API gives you access to the Eclipse part of the Notes Client user interface: You can find out what the user is currently looking at, open new display areas for content (so called view parts) or bring existing ones to the front.

The API also contains helper classes to display message boxes and file/directory selection dialogs.

Access the API

To use the PlatformUI API, call the method com.x2e.PlatformUIAPI.getUI(conn) with a valid XPages2Eclipse connection object.

The resulting object of type IRemotePlatformUI contains a useful helper method to write text to the Notes Client's status bar:

var conn=X2E.createConnection();
var pUI=com.x2e.PlatformUIAPI.getUI(conn);
pUI.logToStatusBar("This text is displayed in the status bar of the Notes Client");

Message boxes

The MessageBoxTools class that you get by calling pUI.getMessageBoxTools() makes it easy to display a variety of message box types from server-side JavaScript of an XPage, and also from JavaScript code launched at client startup and JavaScript background jobs. The class offers all kinds of standard message boxes that SWT, the graphical library of Eclipse, offers

var conn=X2E.createConnection();
var pUI=com.x2e.PlatformUIAPI.getUI(conn);
var msgBoxTools=pUI.getMessageBoxTools();
//the first parameter is a bit combination of an ICON_ constant and the button types (e.g. OK, CANCEL)
msgBoxTools.showMessageBox(2 /* ICON_INFORMATION */ | 32 /* OK */,"Title", "Information message");

For a complete reference of available message box icons and buttons, please refer to the Javadocs for the IRemoteMessageBoxTools class in the API Javadocs.
The sample application for this wiki article demonstrates all valid icon/button combinations (see the download section at the end of this article):

File and directory dialogs

Standard web technologies only offer simple upload controls to select and upload a single file from the browser.
By using the class IRemoteFileDialogTools of the PlatformUI API for local XPages applications instead, you get support for multiple file selection, filetype filters and a directory selection dialog.

For example, here is the code to open a file selection dialog for image file types with multi selection support:

var conn=X2E.createConnection();
var platformUI=com.x2e.PlatformUIAPI.getUI(conn);
var fdTools=platformUI.getFileDialogTools();
var filterNames=["All images", "All files"];
var filterExt=["*.jpg;*.jpeg;*.png;*.gif", "*.*"];
var filterIndex=0; ///index of selected filter
var filterPath=null; //do not specify a default directory
var fileName=null; //do not specify a default filename
var overwrite=false; //use true to let the dialog
  //ask "Do you really want to overwrite file xyz?" if file exists
var dlgText=null; //use default text
var selPathArr=fdTools.showFileDialog(4096 /* OPEN */ | 2 /* MULTI */, filterNames,
  filterExt, filterIndex, filterPath, fileName, overwrite, dlgText);
if (selPathArr && selPathArr.length>0) {
   //do something with image paths in the array selPathArr
}

The wiki article Clipboard API - write text, files and images to the clipboard contains a sample application which uses the file dialog tools class to let the user select a file that will then be copied to the system clipboard.

A directory selection dialog can be displayed by calling the method showDirectoryDialog() of the file dialog tools class:

var startPath="c:\\temp";
var selDirectoryPath=fdTools.showDirectoryDialog(String startPath, "Please select a directory to import");
if (selDirectoryPath) {
   //do something with selected directory path
}

The directory selection function is used in the sample of the wiki article JavaScript Jobs - Background operations developed in JavaScript: we let the user select one or more directories that will then be scanned recursively in a background job written in JavaScript. The purpose is to calculate MD5 checksums for each file found in order to find duplicates.

Workbench access

The Workbench (IRemoteWorkbench in the XPages2Eclipse API) is the top element in the UI of an Eclipse-based application.
It contains one or more Workbench Windows (IRemoteWorkbenchWindow). A Workbench Page (IRemoteWorkbenchPage) is assigned to each Workbench Window and provides additional functionality. In Eclipse, there is a 1:1 relationship between the Workbench Window and the Workbench Page, athough the API looks like there may be multiple pages per window (there are historical reasons for this design decision).

A Workbench Page has one Eclipse Perspective (IRemotePerspectiveDescriptor) that is currently displayed: a visual composition of one or more Workbench Parts (IRemoteWorkbenchPart) which in most cases are View Parts (IRemoteViewPart), a subclass of Workbench Part with some additional properties and methods.

In the Eclipse IDE and Domino Designer, the term "Perspective" can be found in the Window top level menu: You can switch between predefined Perspectives (e.g. "Domino Designer", "Java", "Debug") and you can even define your own Perspective if you prefer to have specific views (View Parts) on the same screen.

In the Lotus Notes Standard Client, Perspectives are not that present. Each tab on the main tab bar at the top of the Client window represents one Eclipse Perspective. In most cases, the Perspectives in the Notes Client only contain one View Part without a visible border or title bar.

However, in Composite Applications and via the XPages2Eclipse API methods, Perspectives can look and behave more Eclipse-like: you can arrange multiple View Parts manually or programmatically, e.g. for a side-by-side comparison of contents. View Parts can display data independent from others. One View Part could for example display Notes data, while another one uses a web browser control to display web content.

The following code snippet reads a few properties of the View Parts visible on the current tab:

var wb=pUI.getWorkbench();
var activeWindow=wb.getActiveWindow();
var activePage=activeWindow.getActivePage();
//read the internal ID and label of the currently active main tab (Eclipse Perspective)
var perspective=activePage.getPerspective();
pUI.logToStatusBar("Current perspective: id="+perspective.getId()+", label="+perspective.getLabel());
//now let's find out what kind of view parts are visible on the tab
var viewRefs=activePage.getViewReferences();
for (var i=0; i<viewRefs.length; i++) {
   var currViewRef=viewRefs[i];
   //the primary ID is a generic type id for this kind of view
   //(e.g. "com.ibm.workplace.noteswc.views.NotesViewData" for View Parts displaying NSF data)
   var currPrimaryId=currViewRef.getId();
   //the secondary ID uniquely identifies a specific view part instance
   var currViewPartId=currViewRef.getSecondaryId();
   //read the view part's title:
   var currTitle=currViewRef.getTitle();   
}

You can find a complete reference for the available PlatformUI API classes and methods in the Javadoc for the XPages2Eclipse Base Product.

Most of the sample applications in this product wiki read and modify the workbench content by calling PlatformUI API methods.
Two of them are particularly interesting:
Focus Tracking - Track viewpart and perspective activation with JavaScript listeners
Component API - Create component viewparts programmatically