Programmatic access to the User Interface (UI) module is based on the abstract class UserInterface and the interface IPWindow.  This access is entirely independent of the type of user interface - whether it is a classic desktop, browser based, or any other type.  In fact it is often not possible to tell what type of user interface you are connected to.  This is because, when running in Viewer-Server mode, Controller modules in the server access a class derived from UserInterface called ProxyUserInterface  which transports calls to whatever viewer is running the session, and the type of UI in that viewer is not discoverable.

When a session starts, then the UI is initialised with a call to a method called InitialiseUserInterface.InitUserInterface.  This is called by the StartUp module if the application is being run in stand-alone mode, or by whatever viewer is running a session UI.  For now this is only the Persistate Viewer.  Persistate generates a default class and method for you, and you can develop it to show whatever windows, workspaces and layouts you want at application startup.  The generated InitialiseUserInterface class provides a good example of using the user interface API, so here is the one generated for the Library example application.

using System;
using System.Collections.Generic;
using System.Text;
using Persistate;
using Library.Model;
 
namespace Library.Desktop
{
   /// <summary>
   /// This class contains the InitUserInterface method which is called 
   /// from the Main method of the StartUp class, and also by the Persistate
   /// Viewer application when starting a session for the Library package.
   /// </summary>
   public static class InitialiseUserInterface
   {
      /// <summary>
      /// Shows start-up content in the user interface.
      /// </summary>
      /// <param name="ui">The user interface in which to show it.</param>
      /// <param name="title">The title to use for created window(s).</param>
      public static void InitUserInterface(UserInterface ui, string title)
      {
         // By default, login with currently logged in user - change as required
         ExecutionResult result = Operation.Login.Execute(null, null, 
            Credentials.CurrentUserCredentials());
         
         // if login fails, throw exception to terminate session
         if (result.ResultAction != ResultAction.Commit) 
            throw new Exception(result.SimpleMessage);
 
         // Create a single window using the default workspace
         IPWindow window = ui.CreateWindow(null, title);
 
         // Show the menu & toolbar in the top controls pane 
         window.Show(The.Library, The.Library.Class.Layouts[Layout.NameKey, 
            "LibraryControls"], "controls");
 
         // Show the Library tree in the left hand navigation pane.
         window.Show(The.Library, The.Library.Class.Layouts[Layout.NameKey, 
            "LibraryTree"], "navigation");
 
         // Show the status bar in the bottom status bar pane
         window.Show(Persistent.Empty, Layout.StatusStrip, "status bar");
 
         // Make window visible
         ui.ShowWindow(window);
 
         return;
      }
   }
}

Although this class is generated in the Library.Desktop namespace, note that it does not use any classes from the desktop user interface - only the abstract class UserInterface and the interface IPWindow.  The first thing this method does is to programmatically execute the Login operation.  This operation is supplied with a Credentials object which contains details of the current user logged in to the operating system.  These Credentials are marked as pre-authenticated, and if your application uses the standard implementation of Login, then no further authentication is performed, and a Principal object is created for the user if one does not already exist.

The next thing this method does is to create a window using the UserInterface.CreateWIndow method.  This takes a workspace name and window title as parameters.  By default, null is passed as the workspace name, which causes the window to use a default workspace.  This will be any workspace the user may have saved as a start-up workspace (see Customising the workspace ) or else any workspace defined in the package definition file, or if there are none, a default workspace from the Persistate package.  This method creates the window, but does not display it.

Next, the method makes three calls to IPWindow.Show.  There are a few overloads of this method - the one used here has all parameters supplied - namely the object to show, the Layout with which to show it, and the name of the Pane in which to show it.  You can miss out the Layout, and Persistate will use (by preference) one you have marked as default for type.  You can also miss out the Pane name, and Persistate will choose a pane for you based on certain criteria.  See the Splitting Panes section in Customising the workspace for details of these.

Finally, the method calls UserInterface.ShowWindow which displays the window to the user.  These three methods are core to the functioning of the abstract user interface system.  Below are some further often used methods, with examples.  For full details of all members of UserInterface and IPWindow, see the API documentation.

Major UserInterface methods

Here is a list of the facilities present in the UserInterface abstract class.  This is not a complete list - see the API documentation for full details.

Major IPWindow methods

Here is a list of the facilities present in the IPWindow interface.  This is not a complete list - see the API documentation for full details.