The WindowManager

.NET Customisation User Guide

.NET Customisation : How to Write a CAF Addin : The WindowManager

An addin will typically expose its functionality to the user through the use of a graphical user interface. This can take the form of forms which are shown from ribbon menus or commandbar buttons or the addin writer may wish the addins graphical user interface to be hosted inside a dockable window or in an MDI child window. The facilities provided by the CAF WindowManager can be used to create these two types of window.

	// Create Addins Windows

// Get the WindowManager service

IWindowManagervwindowManagerDependencyResolver.GetImplementationOf<IWindowManager>();attributeListControl = new

AttributeListControl();

// Create a docked window to host an AttributeListControl

attributeListWindow = windowManager.CreateDockedWindow("Aveva.AttributeBrowser.AttributeList", "Attributes", attributeListControl, DockedPosition.Right);

attributeListWindow.Width = 200;

// Docked windows created at addin start should ensure their layout is saved between sessions.

attributeListWindow.SaveLayout = true;

Use the DependencyResolver.GetImplementationOf method to retrieve the IWindowManager service and the use of the CreateDockedWindow method to create a docked window to host the AttributeListControl. The first argument, Key, to the CreateDockedWindow method needs to be a unique window identifier. To help avoid clashes between docked windows created by addins running within the same application then it is recommended to adopt the <CompanyName>.<AddinName>.<WindowName> naming convention for this property.

An MDI window can be created via use of the WindowManager.CreateMdiWindow method.

As illustrated in this example, an important step when creating docked windows is the correct setting of the SaveLayout property. This property controls whether information about the layout and docking position is saved between application sessions. The code defines the default docking position as DockedPosition, but this can be interactively changed and the persistence of this user preference between sessions is desirable.

One aspect of the saving (serialisation) and restoring (de-serialisation) of this layout data is that this only works if only those docked windows for which there is layout information are present when the layout data is de-serialised. Therefore it is important that any docked window created during addin startup has this property set to true. If there is a mismatch between the number of docked windows in existence when the layout data is de-serialised then you will get one of the following warning message then the application starts up:

Warning: Loading Window Layout - Missing DockedWindow: Aveva.AttributeBrowserWarning: Failed to restore docked window layout

Warning: Loading Window Layout - Extra DockedWindow: Aveva.AttributeBrowserWarning: Failed to restore docked window layout

These warnings can only been seen when either adding or removing an addin from a module.

IWindow Interface

The DockedWindow and MdiWindow both implement the IWindow interface which has the following methods and properties:

void Hide() - Conceals the window from the user.

void Show() - Displays the window to the user.

void Float() - Displays the window as a floating window.

void Dock() - Docks the window within the main window.

void Close() - Destroys the window removing it from the windows collection.

System.Windows.Forms.Control Control - Gets the control displayed in the window.

bool Enabled - Gets or sets whether the window is enabled.

bool Floatable - Gets or sets whether the window is floatable.

int Height - Gets or sets the height of the window.

bool IsFloating - Gets the floating state of a window.

string Key - Gets the Key of the window in the WindowsCollection.

string Title - Gets or sets the title/caption of the window.

bool Visible - Gets or sets the visible state of the window.

int Width - Gets or sets the width of the window.

Size MaximumSize - Get or sets the maximum size of the window.

Size MinimumSize - Get or sets the minimum size of the window.

Window Events

The Docked and MDI Windows also support a number of events such as Closed, Activated, Deactivated, Resized.

WindowManager Events

The window manager also supports two events:

event System.EventHandler WindowLayoutLoaded - Occurs at startup just after the window layout has been loaded. This event can be used to update the state of commands which are being used to manage the visibility of a docked window. (see the ShowAttributeBrowserCommand.cs in the AttributeBrowserAddin sample)

event WindowEventHandler WindowAdded - Occurs when a new docked or MDI window is created.

The StatusBar

The CAF also provides the addin writer with an interface to the StatusBar located at be bottom of the main application window.

The StatusBar is accessed from the StatusBar property of the WindowManager.

StatusBar statusBar = windowManager.StatusBar;

It has the following properties which can be used to control the StatusBar and its contents:

bool Visible - Gets or sets the visibility of the StatusBar.

string Text - Gets or sets the text to display in the default StatusBar text pane.

int Progress - Gets or sets the progress bar value [0-100]. If this is set to 0 then the progress bar is hidden.

string ProgressText - Text to describe the action being tracked by the progress bar.

bool ShowDateTime - Gets or sets whether the Date and Time should be displayed on the StatusBar.

bool ShowCapsLock - Gets or sets whether the panel showing the CapsLock state is displayed on the StatusBar.

bool ShowNumLock - Gets or sets whether the panel showing the NumLock state is displayed on the StatusBar.

bool ShowScrollLock - Gets or sets whether the panel showing the ScrollLock state is displayed on the StatusBar.

bool ShowInsertMode - Gets or sets whether the panel showing the InsertMode is displayed on the statusbar.

StatusBarPanelsCollection Panels - Gets the collection of application defined StatusBar panels.

The StatusBar allows the user to create additional panels using the Panels collection property. The StatusBarPanelsCollection currently has methods to create StatusBarTextPanel objects and add them to the StatusBar.

// Add a new panel to contain the project name.

StatusBar statusBar = windowManager.StatusBar;

StatusBarTextPanel projectNamePanel =

statusBar.Panels.AddTextPanel ("Aveva.ProjectName" , "Project : " +

Project.CurrentProject.Name);

projectNamePanel.SizingMode = PanelSizingMode.Automatic;

// Get the panel image from the addins resource file.

projectNamePanel.Image = resourceManager.GetImage ("ID_PROJECT_ICON");

The StatusBarTextPanel object has a number of properties which control its content and behaviour. It also supports PanelClick and PanelDoubleClick events. For details of these please refer to the reference help file.