Review 12.2 .NET Addin User Guide

AVEVA Review 12.2 .
NET Addin User Guide
AVEVA Solutions Limited
Disclaimer
1.1 AVEVA does not warrant that the use of the AVEVA software will be uninterrupted, error-free or free from viruses. 1.2 AVEVA shall not be liable for: loss of profits; loss of business; depletion of goodwill and/or similar losses; loss of anticipated savings; loss of goods; loss of contract; loss of use; loss or corruption of data or information; any special, indirect, consequential or pure economic loss, costs, damages, charges or expenses which may be suffered by the user, including any loss suffered by the user resulting from the inaccuracy or invalidity of any data created by the AVEVA software, irrespective of whether such losses are suffered directly or indirectly, or arise in contract, tort (including negligence) or otherwise. 1.3 AVEVA's total liability in contract, tort (including negligence), or otherwise, arising in connection with the performance of the AVEVA software shall be limited to 100% of the licence fees paid in the year in which the user's claim is brought. 1.4 Clauses 1.1 to 1.3 shall apply to the fullest extent permissible at law. 1.5 In the event of any conflict between the above clauses and the analogous clauses in the software licence under which the AVEVA software was purchased, the clauses in the software licence shall take precedence.
Copyright
Copyright and all other intellectual property rights in this manual and the associated software, and every part of it (including source code, object code, any data contained in it, the manual and any other documentation supplied with it) belongs to, or is validly licensed by, AVEVA Solutions Limited or its subsidiaries. All rights are reserved to AVEVA Solutions Limited and its subsidiaries. The information contained in this document is commercially sensitive, and shall not be copied, reproduced, stored in a retrieval system, or transmitted without the prior written permission of AVEVA Solutions Limited. Where such permission is granted, it expressly requires that this copyright notice, and the above disclaimer, is prominently displayed at the beginning of every copy that is made. The manual and associated documentation may not be adapted, reproduced, or copied, in any material or electronic form, without the prior written permission of AVEVA Solutions Limited. The user may not reverse engineer, decompile, copy, or adapt the software. Neither the whole, nor part of the software described in this publication may be incorporated into any third-party software, product, machine, or system without the prior written permission of AVEVA Solutions Limited, save as permitted by law. Any such unauthorised action is strictly prohibited, and may give rise to civil liabilities and criminal prosecution. The AVEVA software described in this guide is to be installed and operated strictly in accordance with the terms and conditions of the respective software licences, and in accordance with the relevant User Documentation. Unauthorised or unlicensed use of the software is strictly prohibited. Copyright 1992 to current year. AVEVA Solutions Limited and its subsidiaries. All rights reserved. AVEVA shall not be liable for any breach or infringement of a third party's intellectual property rights where such breach results from a user's modification of the AVEVA software or associated documentation. AVEVA Solutions Limited, High Cross, Madingley Road, Cambridge, CB3 0HB, United Kingdom.
Trademark
AVEVA and Tribon are registered trademarks of AVEVA Solutions Limited or its subsidiaries. Unauthorised use of the AVEVA or Tribon trademarks is strictly forbidden. AVEVA product/software names are trademarks or registered trademarks of AVEVA Solutions Limited or its subsidiaries, registered in the UK, Europe and other countries (worldwide). The copyright, trademark rights, or other intellectual property rights in any other product or software, its name or logo belongs to its respective owner.
AVEVA Review .NET Addin User Guide
Revision Sheet
Date
Version
Comments / Remarks Issued Up Issue
September 2011 12.1.1 February 2013 12.2
Contents
Page
.NET Addin
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1
.NET Customisation Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1
Customising Review with .NET Add-ins . . . . . . . . . . . . . . . . . . . . . . 2:1

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1 Create an Add-in Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1
Add a Reference to the Review API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:4 Developing the User Control as an Add-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:10 Responding to Review Selection Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:12 Creating a Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:14 Applying the Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:15 Navigating to the Selected Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:15 Class and User Control Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:16
Using the Add-in in Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:20 Configure which Add-ins are Loaded by Review . . . . . . . . . . . . . . . . . . . . . . . 2:22
Common Application Framework Interfaces . . . . . . . . . . . . . . . . . . 3:1

Create a Project To Host The CAF Addin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2 Add a Reference to the Review and CAF API . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4 The IAddin Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5 Reference the Review Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:8 The WindowManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:8 Addin Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:9
Copyright 1992 to current year. AVEVA Solutions Limited and its subsidiaries. All rights reserved.
12.2
Writing a Command Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:9
Menu and Command Bar Customisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:12 Configuring a Module to Load an Addin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:13 Add a button to open the addin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:14
Share Information between CAF addins . . . . . . . . . . . . . . . . . . . . . . 4:1

Share from Owning Addin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:1 Consume Shared Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:2
Get Data From Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:3
The Review Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:1

IReview
Members
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:1
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:1
IAddin
Members
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5
ICamera
Members Members Members
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:6
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:8
CameraEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:7 ICameraManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:8 IElement

Members Members Members
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:8
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:10
ElementEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:9 IElementManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:10 IMaterial

Members Members Members Members
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:12
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:14 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:14 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:15
MaterialEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:14 IMaterialManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:14 IAnimationManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:15 Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:16
1 1:ii
12.2
Members Members Members Members Members Members Members
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:17 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:18 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:20
IGroupManager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:16 ITrajectoryManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:18 ILightManager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:18 UserMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:19 IUserEventManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:20 UserEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:20 Other ReviewAPI Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:20
MaterialInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:20 ReviewActiveSelection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:21
1 1:iii
12.2
1 1:iv
12.2

Introduction
Introduction
AVEVA Review .NET Addin User Guide is intended to give a software engineer with experience using Microsoft Visual Studio guidance developing .NET applications for use with the AVEVA Review products.
1.1
.NET Customisation Architecture

The introduction of a customisation capability using Microsoft .NET technology has opened up many new possibilities and is particularly relevant for the integration of AVEVA products with other customer systems. The AVEVA Review .NET API's provide access to various aspects of the product including Graphical User Interface and Geometry.
1:1
12.2

Introduction
1:2
12.2

Customising Review with .NET Add-ins

A user can write custom applications that can be added in to the AVEVA Review user interface. These Add-ins are applications written in a Microsoft .NET programming language that integrate closely with Review through an exposed object model (refer to The Review Object Model). Add-ins enable the user to create features that are not catered for within the Review application, but are specific to the end user. Note: Add-in technology does not replace the command line method of customising Review (described in the Review User Guide).
2.1
Intended Audience
This section describes the user specification for creating add-ins for AVEVA Review. Creating an add-in requires a basic understanding of developing .NET applications using Microsoft Visual Studio .NET version 2005 or later. Implementing interfaces in classes will also be covered in this section.
2.2
Create an Add-in Project

In an example described in this section a user control will be written in C#. It is also possible to write a user control using any of the .NET programming languages. This section will describe how to create a simple Review add-in. The add-in will feature two buttons. One button will allow the user to change the colour of a selected element to green. Another button will allow the user to focus on a selected element in the Review Observer window. A detailed description of the final addin is covered in Using the Add-in in Review. Click Start > All Programs > Microsoft Visual Studio 2008 > Miscrosoft Visual Studio 2008 to launch the Microsoft Visual Studio start page.
2:1
12.2

Click File > New > Project from the main menu bar to open the New Project dialog. In the left pane select Visual C# from the list of Project Types. In the right pane select Windows Forms Control Library from the list of Templates. Enter a Name for the project, for this example enter EngineerAddin. Specify a Location to store the new project files and then click on OK (leaving the remaining fields with their default values).
2:2
12.2

As a result of selecting the Windows Forms Control Library a Microsoft Visual Studio window will open pre populated with a standard Windows Form User Control (UserControl1).
Right click on the user control (UserControl1) to expand a context menu.
Click Properties to display a docked Properties window.
2:3
12.2

Under the (Name) attribute in the Properties window, change the default name of UserControl1 to BaseUserControl.
2.2.1
Add a Reference to the Review API

Adding a reference to the ReviewAPI.dll file will expose the AVEVA Review object library. This will give the developer direct access to controls and functions within the AVEVA Review application. Click Project from the main menu bar and then click Add Reference.
2:4
12.2

Select the Browse tab, and then navigate to the default AVEVA Review install directory, for example:
C:\AVEVA\Review12.2
From the default install directory select the file ReviewAPI.dll. Then click OK. Important: Do not attempt to use an older version of the ReviewAPI.dll file than the version of AVEVA Review that the add-in is intended to run in. If an old version of the ReviewAPI.dll file is used the following error will be displayed.
The ReviewApi will now be listed under References, in the Solution Explorer.
2:5
12.2

A new class must be created containing code that will be used to access the properties and members of the IAddin Interface. Right click the project name (EngineerAddin) in the Solution Explorer and select Add > Class to open the Add New Item window.
In the left pane select Visual C# Items from the list of Categories. In the right pane select Class from the list of Templates. In the Name field enter AccessAddin and then click Add. A new tab will be opened in the user interface showing the C# source code contained in the newly created class.
2:6
12.2

Note: The user can switch between user controls in the project by clicking on the required tabs. Add the ReviewAPI to the list of using statements by including the syntax:
using Aveva.Review.API;
Append the AccessAddin class name with a colon and then add the statement IAddin, as shown below.
namespace EngineerAddin { class AccessAddin: IAddin { } }

Right click over IAddin and click Implement Interface > Implement Interface.
The class source code will be populated with default properties and methods of the IAddin interface:
class AccessAddin: IAddin {
#region IAddin Members
public string AddinName
2:7
12.2

{ get { throw new Not ImplementedException(); } }
public System.Windows.Forms.UserControl Control { get { throw new Not ImplementedException(); } }
public string Description { get { throw new Not ImplementedException(); } }
public int Priority { get { throw new Not ImplementedException(); } }
public void Start(IReview review) { throw new Not ImplementedException(); }
public void Stop() { throw new Not ImplementedException(); }
#endregion } }
All of the Not ImplementedException()statements must be replaced with the users own custom C# code. If AVEVA Review encounters an exception while it runs an addin this can cause unexpected results.
2:8
12.2

To access the default user control (BaseUserControl) from the AccessAddin class create an instance of the class using the new keyword within the AccessAddin class body. Name the instance of the class as MaterialControl. Do this by adding the following syntax below the class declaration in the AccessAddin class source.
class AccessAddin: IAddin { private BaseUserControl BaseUserControl (); MaterialControl = new
In the following steps each of the Not ImplementedException() statements will be replaced so that a new value will be returned to the IAddin interface methods. The Public String AddinName method is a read-only property as it only gets and returns the string type passed to it.
public string AddinName { get { return "Material colour change"; } }

The Control Property returns a reference to the UserControl that will be displayed in Review. In this case simply return the MaterialControl member created earlier.
public System.Windows.Forms.UserControl Control { get { return MaterialControl; } }

The Description property will return a string type, "Material Addin". This is the name that appears in the Addin Menu in Review, as well as the name of the title in the Addin window.
public string Description { get { return "Material Addin"; } }

The priority property must be an integer value. The priority method is not longer supported by Review but must be specified to maintain compatability.
public int Priority { get { return 0; } }

Make sure that the exception statement is deleted from the Stop function and no code is added. The stop method is called by Review on quiting the application. The user could
2:9
12.2

include code here that must be run before Review quits, for example saving any settings used by the addin. However for this example the stop method will not be used.
public void Stop() { // no code }

The Start function is described later in the following section of this guide.
2.2.2
Developing the User Control as an Add-in

When the add-in runs it will be passed an IReview Interface. This is the main interface to Review API and will be used for such things as material creation and navigation. In the Microsoft Visual Studio user interface click the tab UserControl1.
Right click on the form control and select View Code to open a window showing the c# source of the form control.
2:10
12.2

Add a reference to the ReviewAPI in the using statements:
using Aveva.Review.API;
Create a member of type IReview to store the reference to the interface as shown below.
namespace EngineerAddin { public partial class BaseUserControl : UserControl { private IReview ReviewInterface;
public BaseUserControl() { InitializeComponent(); } } }

Create a new function called AttachReview with an argument review of type IReview.
public void AttachReview(IReview review) {
2:11
12.2

Assign the created private IReview Interface to the AttachReview argument review; both of type IReview.
public void AttachReview(IReview review) { ReviewInterface = review; }

When Review loads the add-ins it will call the Start method and access the AttachReview function and its argument review, in the AccessAddin class, through the instance of the user control, MaterialControl. Tab back to AccessAddin and insert the following code in the Start function:
public void Start(IReview review) { MaterialControl.AttachReview(review); }
2.2.3
Responding to Review Selection Changes

Review add-ins can subscribe to an event that will be triggered whenever the active selection changes in Review. The active selection is the selection in the currently active Review window. Review windows that trigger active selection change events are: Explorer, camera windows, search results and drawlist. To subscribe to active selection change events first create a member to handle the event. Click on the UserControl1.cs tab to view the source for UserControl1.
The event handler must have the same signature as the one shown below.
public void ActiveSelectionChanged(object sender) {
}
Visual Studio's intellisense is a very useful function that provides options depending on the statement of code written. The intellisense is in black text, and yellow background. Scrolling to the preferred choice and pressing tab or enter, inputs the choice. Next subscribe to the selection change event using this function to handle the event. This can be done through the static SubscribeForSelectionChangedEvent method on the
2:12
12.2

ReviewActiveSelection class. The ReviewActiveSelection class provides access to the active selection through static methods.
public void AttachReview(IReview review) { ReviewInterface = review; ReviewActiveSelection.SubscribeForSelectionChangedEvent(n ew ReviewActiveSelection.SelectionChangedEvent(ActiveSelecti onChanged));
}
Create a label in the user control by dragging a label from the Visual Studio toolbox. Give the new label the name ElementNameLabel.
In the ActiveSelectionChanged function the user can add code to handle the selection change. In the following example the name of the first element of the selection will be copied into the text value of the label created in the previous steps.
public void ActiveSelectionChanged(object sender) { if (ReviewActiveSelection.Selection.Count > 0) { ElementNameLabel.Text (string)ReviewActiveSelection.Selection[0]; } }

The Selection property, a member of ReviewActiveSelection, is an ArrayList containing the names of the selected elements.
2:13
12.2

2.2.4
Creating a Material
To create or query material information through the Review API use the MaterialInfo class defined in the ReviewAPI.dll. First add a MaterialInfo member to the UserControl and name it greenMaterial.
public partial class BaseUserControl : UserControl { private IReview ReviewInterface; private MaterialInfo greenMaterial; private string greenMaterialName = "Green Material";
public BaseUserControl() { InitializeComponent(); }
Next, in the AttachReview function create a new material using the following code:
public void AttachReview(IReview review) { ReviewInterface = review; ReviewActiveSelection.SubscribeForSelectionChangedEvent(n ew ReviewActiveSelection.SelectionChangedEvent(ActiveSelecti onChanged)); greenMaterial = new MaterialInfo(0, 100, 0, 0, 0, 0, 0, 0); }
In this example the material is set up with green colour and values for ambient, metalness, specular, smoothness and transparency set to 0. Add the following code to AttachReview function to check if a material with the name 'Green Material' already exists. If the green material does not exist then the code will create it then set it with the material information created above.
ArrayList materialNames = ReviewInterface.GetAllMaterials(); if (!materialNames.Contains(greenMaterialName)) { ReviewInterface.CreateMaterial(greenMaterialName); }
2:14
12.2

ReviewInterface.SetMaterialInfo(greenMaterialName, greenMaterial);
Note: Before creating an ArrayList make sure that the using System.Collections; statement is added to the list of using statements.
2.2.5
Applying the Material

To apply the material to the selected element, create a button by selecting a Button Control from the Visual Studio toolbox controls. Name the new button SetMaterialButton from the properties window. Add an event handler for the click event on the button by double clicking the SetMaterialButton button. This automatically populates the user control code with the SetMaterialButton event handler. Use the SetElementMaterial function to apply the green material to the element name in the label.
private void EventArgs e) {
SetMaterialButton_Click(object
sender,
ReviewInterface.SetElementMaterial(ElementNameLabel.Text, greenMaterialName); }
2.2.6
Navigating to the Selected Element

To navigate to the selected element, create a button by selecting a Button Control from the Visual Studio toolbox controls. Name the new button LookToElementButton from the properties window. Add an event handler for the click event by double clicking the LookToElementButton button. In this event handler use the LookAtElement function to look at the element. This will look to the selected element in the observer window with snap move with the element highlighted.
2:15
12.2

private void EventArgs e) {
LookToElementButton_Click(object
sender,
ReviewInterface.LookAtElement(CameraType.Observer, ElementNameLabel.Text, LookType.DynamicMove, true); }
This will look to the selected element in the observer window with snap move and highlighting.
2.2.7
Class and User Control Code

This concludes the steps required to create an addin. The screen shot that follows shows the final User Control appearance.
The final C# code used in the AccessAddin class and UserControl class follows. AccessAddin class
using System;
2:16
12.2

using System.Collections.Generic; using System.Linq; using System.Text; using Aveva.Review.API;
namespace EngineerAddin { class AccessAddin: IAddin { private BaseUserControl MaterialControl = new BaseUserControl();
#region IAddin Members
public string AddinName { get { return "Material colour change"; } }
public System.Windows.Forms.UserControl Control { get { return MaterialControl; } }
public string Description { get { return "Material Addin"; } }
public int Priority { get { return 0; } }
2:17
12.2

public void Start(IReview review) { MaterialControl.AttachReview(review); }
#endregion } }
UserControl class
using System; using System.Collections.Generic; using System.ComponentModel; using System.Drawing; using System.Data; using System.Linq; using System.Text; using System.Windows.Forms; using Aveva.Review.API; using System.Collections;
namespace EngineerAddin { public partial class BaseUserControl : UserControl { private IReview ReviewInterface; private MaterialInfo greenMaterial; private Material"; string greenMaterialName = "Green
2:18
12.2

public BaseUserControl() { InitializeComponent(); }
public void AttachReview(IReview review) { ReviewInterface = review; ReviewActiveSelection.SubscribeForSelectionChangedEvent(n ew ReviewActiveSelection.SelectionChangedEvent(ActiveSelecti onChanged)); greenMaterial = new MaterialInfo(0, 100, 0, 0, 0, 0, 0, 0);
ArrayList ReviewInterface.GetAllMaterials();
materialNames
materialNames = review.GetAllMaterials(); if (!materialNames.Contains(greenMaterialName)) { ReviewInterface.CreateMaterial(greenMaterialName); } ReviewInterface.SetMaterialInfo(greenMaterialName, greenMaterial); }
public void ActiveSelectionChanged(object sender) { if (ReviewActiveSelection.Selection.Count > 0) { ElementNameLabel.Text (string)ReviewActiveSelection.Selection[0]; } =
2:19
12.2

private void SetMaterialButton_Click(object sender, EventArgs e) { ReviewInterface.SetElementMaterial(ElementNameLabel.Text, greenMaterialName); }
private void LookToElementButton_Click(object sender, EventArgs e) { ReviewInterface.LookAtElement(CameraType.Observer, ElementNameLabel.Text, LookType.DynamicMove, true); }
} }
2.3
Using the Add-in in Review

When this project is built it will create a DLL named EngineerAddin.dll. Copy this DLL into the Addins folder in the Review install directory. When Review launches it will pick up this add-in and the name will appear under the main menu Addins menu. Clicking on this menu item displays the add-in.
When elements are selected in Review, their names will appear in the label ElementNameLabel. Clicking on the button SetMaterialButton paints the element green.
2:20
12.2

Clicking on the button LookToElementButton navigates the observer to look at the element.
2:21
12.2

Should any changes need to be made or if the addin does not appear in Review; the AVEVA folder in the application data directory, will need to be deleted. Hidden files will need to be enabled from the tool options. Go to the command window and type: del "%userprofile%\Local Settings\Application Data\AVEVA" to delete the AVEVA folder. This would delete all previous settings associated with the last build. Once the new build is created when the code is run, a new AVEVA folder with current settings will be created. Lack of deleting the AVEVA folder will result in the previous settings remaining, even if the code has changed.
2.4
Configure which Add-ins are Loaded by Review

It is possible to specify which add-ins are loaded into Review when it runs. This is done by using a configuration file called Addins.xml. In this file list the add-in DLLs that will be loaded into Review when it runs. Add the paths to the add-in DLLs relative to the Review install directory, then place the Addins.xml file in the same directory as Review.exe. When Review runs it will look for the file Addins.xml if it finds this file it will only load those DLLs specified in this file. If it does not find and Addins.xml file it will load all addins that are in the Addins directory. Below is an example of the contents of an Addins.xml file which specifies two add-ins to load: DataViewer.dll and MyAddin.dll.
<?xml version="1.0" encoding="utf-8" ?> <ArrayOfString xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <string>Addins\DataViewer.dll</string> <string>Addins\MyAddin.dll</string> </ArrayOfString>
2:22
12.2

Common Application Framework Interfaces

A limitation of a standard Review Addin as described in the previous section is that the user can only stage an addin inside a single window. Developing a CAF addin allows the user to open multiple windows and controls, each of which can comunicate with each other. The Common Application Framework (CAF) is an extensible framework which provides the .NET programmer with access to various services which support both application development and customisation. The foundations of the CAF are provided by the two interface assemblies: Aveva.ApplicationFramework.dll Aveva.ApplicationFramework.Presentation.dll
These interfaces provide the following major services: Namespace: Aveva.ApplicationFramework AddinManager: This class provides properties and methods for the management of ApplicationFramework Addins. ServiceManager: This class defines an interface which provides a means by which the various components of the ApplicationFramework can publish their services. The ServiceManager also acts as a service provider responding to requests for services. It can also be used by applications and application addins to publish additional services. SettingsManager: This class provides properties and methods for the management of application settings which are stored in settings groups which are persisted between sessions.
Namespace: Aveva.ApplicationFramework.Presentation CommandBarManager: This provides access to the menus and commandbars of a CAF based application. It also has methods to load the definition of menus and commandbars from User Interface customisation (UIC) files. CommandManager: This class defines an interface to provide the presentation framework client with a mechanism for the management of command objects which can be associated with Tools or other User interface objects. The action of invoking a tool (e.g clicking a ButtonTool) will cause the execution of the associated command object. It is possible to associated the same command object with a number of different user interface objects (e.g. ButtonTool on a Menu and a LinkLabel) thereby allowing for the centralisation of these user interface objects action within a command. Various state-like properties of a command (e.g. enabled/checked) would also be reflected in all user interface objects associated with a command. For example, disabling a command would cause all associated user interface objects to be disabled. User interface objects are associated with a command through a CommandExecutor derived class. ResourceManager: This class defines an interface to provide Addins with a simplified mechanism to access localizable resources.The ResourceManager provides a number of methods which allows an addin to then access the various types of resources (string, image, cursor, icon etc.) which resource files may contain.
3:1
12.2

WindowManager: This provides access to the main application window, the StatusBar and a collection of MDI and docked windows. It also provides the addin writer with methods to create MDI and docked windows to host user controls.
3.1
Create a Project To Host The CAF Addin

There are many similarities in creating a CAF addin to a standard Review addin described in the previous section of this guide. Starting a new project in Visual Studio follows the same process. Click Start > All Programs > Microsoft Visual Studio 2008 > Miscrosoft Visual Studio 2008.
Click File > New > Project from the main menu bar to open the New Project dialog. In the left pane select Visual C# from the list of Project Types. In the right pane select Windows Forms Control Library from the list of Templates. Enter a Name for the project, for this example enter EngineerAddinCAF. Specify a Location to store the new project files and then click on OK (leaving the remaining fields with their default values).
3:2
12.2

As a result of selecting the Windows Forms Control Library a Microsoft Visual Studio window will open pre populated with a standard Windows Form User Control (UserControl1). A benefit of developing a CAF based addin is that the user can re-use code that has been used in a standard Addin project. To demonstrate this concept the user control from the previous section will be copied into this project and then the necessary CAF code will be added. Refering to the standard addin project copy the source files that were created for the Usercontrol1. The files that need to be copied are: UserControl1.cs UserControl1.Designer.cs UserControl1 One method of locating the source files for a control is to open the project in Visual Studio and then right click on the control and select Open Containing Folder:
3:3
12.2

After overwriting the UserControl1 source files the new EngineerAddingCAF project should have a Windows form control as follows:
At this point the user can add new classes that will expose the CAF and ReviewAPI, these are described in the following sections of this guide.
3.2
Add a Reference to the Review and CAF API

Adding a reference to the ReviewAPI.dll file will expose the AVEVA Review object library. This will give the developer direct access to controls and functions within the AVEVA Review application. Adding a reference to the Aveva.ApplicationFramework.Presentation.dll and Aveva.ApplicationFramework.dll files will expose the Microsoft CAF object library. This will give the developer direct access to the presentation controls and functions provided by the CAF. The developer will also be able to communicate with other applications that are also using CAF. Click Project from the main menu bar and then click Add Reference. Select the Browse tab, and then navigate to the default AVEVA Review install directory, for example:
C:\AVEVA\Review12.2
From the default install directory select the following files: (Hold down the control key (CTRL) to select multiple files) Aveva.ApplicationFramework.Presentation.dll Aveva.ApplicationFramework.dll ReviewAPI.dll After clicking OK the selected files will be visible under References in the Solution Explorer.
3:4
12.2

3.3
The IAddin Interface

A new class must be created containing code that will be used to access the properties and members of the IAddin Interface. Right click the project name (EngineerAddinCAF) in the Solution Explorer and select Add > Class to open the Add New Item window In the left pane select Visual C# Items from the list of Categories. In the right pane select Class from the list of Templates.
In the Name field enter EngineerAddinCAFAddin and then click Add. A new tab will be opened in the user interface showing the C# source code contained in the newly created class. What distinguishes an addin from any other .NET assembly is that an addin must contain a class which implements the IAddin interface. When the CAF loads and starts an addin it interrogates the assembly for the class which implements this interface, creates an instance of this class and calls the IAddin.Start method.
3:5
12.2

This creates a class window.

using System; using System.Collections.Generic; using System.Text;
namespace EngineerAddinCAF { class EngineerAddinCAFAddin { } }
Add using statements that reference the ApplicationFramework namespace.

using Aveva.ApplicationFramework; using Aveva.ApplicationFramework.Presentation;
Implement the IAddin interface on the EngineerAddinCAFAddin class by following the class name with a colon and the name of the addin.
using System; using System.Collections.Generic; using System.Text; using Aveva.ApplicationFramework; using Aveva.ApplicationFramework.Presentation;
namespace EngineerAddinCAF { class EngineerAddinCAFAddin: IAddin { } }
Right click over the IAddin and click Implement Interface > Implement Interface.
The class source code will be populated with default properties and methods of the IAddin interface:
using System; using System.Collections.Generic; using System.Text; using Aveva.ApplicationFramework; using Aveva.ApplicationFramework.Presentation;
namespace EngineerAddinCAF {
3:6
12.2

class EngineerAddinCAFAddin: IAddin { #region IAddin Members
public string Description { get { throw new NotImplementedException(); } }
public string Name { get { throw new NotImplementedException(); } }
public void Start(ServiceManager serviceManager) { throw new NotImplementedException(); }
public void Stop() { throw new NotImplementedException(); }
#endregion } }
All of the Not ImplementedException()statements must be replaced with the users own custom C# code. If AVEVA Review encounters an exception while it runs an addin this can cause unexpected results. In the following steps each of the Not ImplementedException() statements will be replaced so that a new value will be returned to the IAddin interface methods. In the Description return a string.
public string Description { get { return "Engineer Addin to focus on elements and change colour"; } }
The Public String AddinName method is a read-only property as it only gets and returns the string type passed to it.
public string Name

{ get { return "Engineer Addin"; } }
3:7
12.2

Make sure that the exception statement is deleted from the Stop function and no code added.
The Start method performs the initialization of the Addin. Remove the exception statement and leave blank ready for syntax that will be added in the following sections of this guide.
public void Start(ServiceManager serviceManager) {
3.4
Reference the Review Service

To expose the Review API funtionality the user must call the IReview service using the serviceManager.GetService method. Add the following syntax to the Start function:
// connect to Review API Aveva.Review.API.IReview reviewApi = (Aveva.Review.API.IReview)serviceManager.GetService(typeof(Aveva.Revie w.API.IReview));
3.5
The WindowManager
An addin will typically expose its functionality to the user through the use of a graphical user interface. This could be through forms which are shown from menu or commandbar buttons or the addin writer may wish the addins graphical user interface to be hosted inside a dockable window. The facilities provided by the CAF WindowManager can be used to create these two types of window. The code below shows the use of the serviceManager.GetService method to retrieve the WindowManager service and the use of the CreateDockedWindow method to create a docked window to host the BaseUserControl form (that was copied from the standard addin project). Add the following code to the body of the Start function:
WindowManager windowManager = (WindowManager)serviceManager.GetService(typeof(WindowManager));
Create two new variables of type DockedWindow and BaseUserControl at the start of the class. Name the two variables as EngineerAddinCAFWindow and EngineerAddinCAFControl, repectively.
class EngineerAddinCAF: IAddin { private DockedWindow EngineerAddinCAFWindow; private BaseUserControl EngineerAddinCAFControl;
3:8
12.2

Add the following code:

EngineerAddinCAFControl = new BaseUserControl(); EngineerAddinCAFWindow = windowManager.CreateDockedWindow("Aveva.EngineerAddinCAF.EngineerAddin CAFControl", "Engineer Addin", EngineerAddinCAFControl, DockedPosition.Right); EngineerAddinCAFWindow.Width = 265; EngineerAddinCAFWindow.SaveLayout = true;
The first argument, Key, to the CreateDockedWindow method must 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, i.e., Aveva.EngineerAddinCAF.EngineerAddinCAFControl. "Engineer Addin" in the creation of the docked window, is the text that will appear as the title of the window in the Review application. 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 user can interactively change the default docking position and the persistence of this user preference between sessions is desirable. When the EngineerAddinCAFWindow object has been created it can then be attached to the ReviewAPI by adding the following syntax within the Start function.
// Attach the Review API to the EngineerAddinCAFControl EngineerAddinCAFControl.AttachReview(reviewApi);
3.6
Addin Commands
User access to an addin's functionality is typically accessed through main menus, context menus and tools on a commandbar. The CAF provides interfaces through the CommandBarManager for the creation of menus, commandbars and the various types of tool that they can contain. One of the advantages of a command based model is that it forces the decoupling of the user interface or presentation layer from the application logic. The application logic has no direct reference to the presentation layer entities. If application state needs to be reflected in the user interface then the application modifies the state of the command. The command knows which user interface entities are associated with it and takes the necessary steps to make sure that its internal state is reflected in the user interface. This is easily achieved for state such as "enabled", "visible" or "checked", but becomes complex when dynamic application state needs to be reflected in user interface entities such as a combo-box.
3.6.1
Writing a Command Class

To manage the visibility state of a docked window, in this case the EngineerAddinCAFWindow docked window, a simple command class is used. The CAF provides an abstract base class from which every Command class must inherit. The constructor for a Command class should set the base class Key property which is used to reference the command from within a UIC file.
3:9
12.2

The Command base class has the following methods and properties which can be overridden by a derived Command class. void Execute() : This method must be overridden to provide the command execution functionality. CommandState GetState() : This method is called by the CAF to update the state of the contents of a context menu. The returned value is a CommandState enumeration for various states of a command. This enumeration can be treated as a bit field; that is, a set of flags. Bit fields can be combined using a bitwise OR operation. The command state is then reflected by the user interface. String Description : A description for the command. void Refresh(string context) : This method will be called whenever the CommandManager.ApplicationContext property is changed. This gives the command the opportunity to update its Enabled or Visible state in response to this context change. This command state change would then be reflected in the user interface. The Command base class also has a number of properties which are use to update the command state following user interface changes or vice-versa. bool Checked: If associated with a user interface entity such as a StateButtonTool then this property and the corresponding state of the user interface entity are kept synchronised. bool Enabled: Changes to this property are reflected in all associated user interface entities. ArrayList List: This property allows a command to communicate a list of string values to the user interface. This can be used when a command is associated with for example a ComboBoxTool. int SelectedIndex: This property is updated to indicate which item from a list has been selected by the user. object Value: This property holds the currently value of an associated user interface entity. bool ValueChanged: Before calling the execute method the CAF sets this property if the value of the user interface entity has changed. The flag is cleared when execution has finished. bool Visible: Changes to this property are reflected in all associated user interface entities. Registering a command with the CAF is done by adding an instance of a command class to the CommandManagers.Commands collection. Create a new class, ShowEngineerAddinCommand, and populate the class as detailed below.
using System; using System.Collections.Generic; using System.Text; using Aveva.ApplicationFramework.Presentation;
namespace EngineerAddinCAF { //Class to manage the visibility state of the EngineerAddin docked window // This command should be associated with a StateButtonTool.
3:10
12.2

public class ShowEngineerAddinCommand : Command { private DockedWindow _window; //Constructor for ShowEngineerAddinCommand //The docked window whose visibilty state will be managed. public ShowEngineerAddinCommand(DockedWindow window) { // Set the command key this.Key = "Aveva.EngineerAddinCAF"; // Save the docked window _window = window; // Create an event handler for the window closed event _window.Closed += new EventHandler(_window_Closed); // Create an event handler for the WindowLayoutLoaded event WindowManager.Instance.WindowLayoutLoaded += new EventHandler(Instance_WindowLayoutLoaded); }
void Instance_WindowLayoutLoaded(object sender, EventArgs e) { // Update the command state to match initial window visibility this.Checked = _window.Visible; }
void _window_Closed(object sender, EventArgs e) { // Update the command state when the window is closed this.Checked = false; } // Override the base class Execute method to show and hide the window public override void Execute() { if (this.Checked) { _window.Show(); } else { _window.Hide(); } } }
3:11
12.2

Now add the following syntax to the Start function of the EngineerAddinCAFAddin class. This will call the above code at run time.
CommandManager commandManager = (CommandManager)serviceManager.GetService(typeof(CommandM anager)); ShowEngineerAddinCommand showCommand = new ShowEngineerAddinCommand(EngineerAddinCAFWindow); commandManager.Commands.Add(showCommand);
3.7
Menu and Command Bar Customisation

User access to functionality provided through an addin is normally provided through the use of menus and/or tools on a commandbar. The recommended method of adding a button to the AVEVA Review user interface is to expose the advanced CAF customisation form and then add a new button which will call a custom class (such as that described in Writing a Command Class). By default the advanced customisation form is not available from the AVEVA Review user interface. When the user right clicks in the toolbar and selects Customise the following window will be displayed, note that there is no way for a user to add a custom button.
When an addin is first loaded the Start function will always be executed first. The user can add the following code to the Start function to the expose the advanced CAF customisation form.
3:12
12.2

CommandBarManager commandBarManager = (CommandBarManager)serviceManager.GetService(typeof(Comma ndBarManager)); commandBarManager.CustomizationType = CustomizationType.Custom;

When the user right clicks in the toolbar and selects Customise the following window will now be opened.
Before describing how to add a custom button the user must edit the ReviewAddins.xml file to add the EngineerAddinCAF addin to the list of loaded addins. The user must then run Review for the newly added code to expost the advanced CAF customisation window. Editing the ReviewAddins.xml file is descibed in the following section
3.8
Configuring a Module to Load an Addin

Having written an addin the next step is to get the addin to be loaded when AVEVA Review is launched. Each CAF based application has an XML addin configuration file which contains a list of the addins that the application should load at startup. The default location for this file is in the same directory as the application executable. The Review application has a file called ReviewAddins.xml. For the above example; add the name of the project of the addin, EngineerAddinCAF, as shown in bold below.
<?xml version="1.0" encoding="utf-8"?> <ArrayOfString xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <string>CAFAddins\ReviewAddinsn</string> <string>CAFAddins\PdmsConnection</string> <string>CAFAddins\ReviewShareAddin</string> <string>CAFAddins\DataViewer</string> <string>CAFAddins\PdmsExplorer</string> <string>CAFAddins\PdmsAttributeViewer</string>
3:13
12.2

<string>CAFAddins\EngineerAddinCAF</string> </ArrayOfString>
3.9
Add a button to open the addin

After editing the ReviewAddins.xml to include the new addin the user can launch Review. When Review is launched it will run the code that was described in Menu and Command Bar Customisation that exposes the advanced CAF customisation functionality. The user can now right click in the toolbar and select Customise to display the advanced customise window. Right click on a blank area of the middle pane, which has the Command options. Select New and then StateButton.
Change the Caption of the StateButton to Engineer Addin. This is the label that will appear on the button. The name of the StateButton on the middle pane also changes to Engineer Addin. To assign the created Addin project to the newly created button, select the Command option. This presents the Command window below. Select the Core Command option button from the Command Type group box. From the Core Commands list, expand the Aveva option, and select the application that was earlier created in Visual Studio, EngineerAddinCAF. Click the OK button. (If the Addin does not appear, the code written in Visual Studio would need debugging to establish the cause of the problem)
3:14
12.2

The above step should result in the Key specified in the class created in Writing a Command Class being input in the command option; and through which the controls in the Addin will be accessed.
Right clicking on the Command Bar as shown below, and selecting New CommandBar.
3:15
12.2

To add the newly created state button to the Command Bars or the Menu Bar, drag the state button to the specific menu. In this case, drag the status button Engineer Addin to the new command bar. Click the Apply and OK buttons to accept the changes. Important: DO NOT attempt to use Review imediately after adding the new button. To make sure that the changes are implemented and recognized within the application, Review must be reloaded. Select the File menu and Exit the application. Restart the Review application again, and the new statebutton, should be visible on the command bar and View menu; both shown below.
3:16
12.2

Share Information between CAF addins

A benefit of writing CAF addins over standard Review addins is that the user can share information between addins. The following sections describes how the user can expose information from one addin that can be collected from another. In this section the user will create a project that will own information that can then be collected by another addin. The project created in the previous sections of this guide will be adapted so that it will own information that can be collected.
4.1
Share from Owning Addin

In the project that will own the information start by adding the following code below the list of using statements in the EngineerAddinCAFaddin class.
public interface IMySharedData { string SampleMethod(); }

Scroll down the source and located the following function
public void Start(ServiceManager serviceManager)

Then add the following code:
// Register this instance to CAF to allow other addins to interact with this one. serviceManager.AddService(typeof(IMySharedData), EngineerAddinCAFControl);
Open the UserControl1 class and locate the following declaration:
public partial class BaseUserControl : UserControl

After UserControl add a comma followed by IMySharedData as follows:
public partial class BaseUserControl : UserControl, IMySharedData

Before the end of the BaseUserControl class add the following
#region IMySharedData Members
public string SampleMethod()
4:1
12.2

{ return ElementNameLabel.Text; }
#endregion
These steps have created a new CAF service which will expose the value of a label on the addin form. Compile a dll and place it in the review CAFAddins folder.
4.2
Consume Shared Data

After sharing data from an owning addin the user can consume that data using the CAF service manager. Collecting data from the service manager can be achieved with the use of short commands (see Get Data From Service) however this section describes that process in context by creating a separate addin. This section will describe how to consume data but will make the assumption that the user is now familiar with creating a separate addin using c#. This section will make reference to aspects of creating addins that have been described in the previous sections of this guide. In this section the user will create a simple CAF addin that will retrieve the value of a label on the form of the owning CAF addin created in the previous sections of this guide and then use that value to populate a label on its own form.
Begin by creating a new C# project with a Windows form control using the Windows Forms Control Library. Name the project ConsumeAddin. Refering to section Add a Reference to the Review and CAF API the user must add references to the following: AVEVA.ApplicationFramework AVEVA.ApplicationFramework.Presentation ReviewAPI.dll Add an additional reference to the dll of the owning project (the owning project must be compiled). This must be done so that the user can reference the IMySharedData interface (as described in the previous section).
4:2
12.2

Right click the project name (ConsumeAddin) in the Solution Explorer and select Add > Class to open the Add New Item window. In the left pane select Visual C# Items from the list of Categories. In the right pane select Class from the list of Templates. In the Name field enter ConsumeAddin.cs and then click Add. In the ConsumeAddin.cs file implement the IAddin interface (refer to section The IAddin Interface and then register the form control with CAF as described in the The WindowManager. Create another class with the name showConsumeaddincafcommands.cs to control the visibility of the addin within Review (the same code created in section Writing a Command Class can be re-used to achieve this). In the new class showConsumeaddincafcommands.cs make sure that the key value is different to that created for the previous project:
this.Key = " Aveva.ConsumeAddinCAF";
A basic project has now been created, at this point the user can make use of the service manager to collect data from another CAF addin.
4.2.1
Get Data From Service

Click on the UserControl1 form and select View Code to display the source code for the form then add the following code
private ServiceManager _serviceManager; public void SetServiceManager(ServiceManager serviceManager) { _serviceManager = serviceManager; }

Create a new button. Create a new label with the name OwningElementLabel. Double click on the button and add the following code:
IMySharedData data = (IMySharedData)_serviceManager.GetService(typeof(IMyShare dData)); OwningElementLabel.Text = data.SampleMethod();
4:3
12.2

4:4
12.2

The Review Object Model
A
A.1

IReview
IReview is the main access point to the Review API (Application Programming Interface). Some of the common Review functionality is available through functions on IReview. Using IReview it is also possible to get access to various manager classes that provide greater functionality.
A.1.1
Members
Member
Description Creates a material with the supplied name in Review. Type String Description The name of the material to create.
CreateMaterial
Argument
material
Member
Description Freezes the current state of material association to elements in the model. This creates a snapshot of the current element-material association that can be rolled-back to with a call to ResetMaterials()
FreezeMaterials
Member
Description Resets the element-material association to the state at the last call of FreezeMaterials(). If FreezeMaterials() has not been called then this will roll all elements back to the materials defined in the model file.
ResetMaterials
Member
Description Returns an ArrayList of String objects containing the names of all materials currently defined in Review.
GetAllMaterials
A:1
12.2

Member
Description add-in user controls. This helps add-in controls fit in with the visual style of Review.
GetBackgroundColour Returns a Colour object that defines the background colour to use for
Member
Description Returns a bool that defines if a material with the supplied name already exists in Review. Type String Description The name of the material to query.
GetMaterialExist s
Argument
material
Member
Description Gets information about a given material. Type String MaterialInfo Description The name of the material to query. A MaterialInfo object that will receive the material information
GetMaterialInfo
Argument
material Info
Member
Description Returns a VisibilityType that defines the visibility of the material Type String Description The name of the material to query.
GetMaterialVisibility
Argument
material
Member
Description Sets a camera to look at an element in the model. Type Aveva.VPD.ReviewApi.CameraType Description The camera to use, can be the Observer window or one of the other 7 cameras The name of the element to look at The type of move method. Can be snap, dynamic or no move. Defines if the element should be highlighted after the move.
LookAtElement
Argument
camera
element lookMethod highlight
String Aveva.VPD.ReviewApi.LookType bool
A:2
12.2

Member
Description Refreshes the Review displays.
RefreshAll
Member
Description Sets the visible state of all elements in the model Type Aveva.VPD.ReviewApi.VisibilityType Description The visibility type to set on all elements in the model.
SetAllElementVisibility
Argument
visibility
Member Argument
Description Type ArrayList String Description An ArrayList of String objects containing the names of element to apply the material to The name of the material to apply to the elements.
SetElementMaterial Sets material type for a list of elements element material
Member
Description Sets material type for a single element Type String String Description The name of element to apply the material to The name of the material to apply to the element.
SetElementMateri al
Argument
element material
Member
Description Sets visibility type for a list of elements Type ArrayList Description An ArrayList of String objects containing the names of element to apply the material to The visibility type to apply to the elements.
SetElementVisibility
Argument
element
visibility
Aveva.VPD.ReviewApi.VisibilityType
A:3
12.2

Member
Description Sets visibility type for a single element Type String Aveva.VPD.ReviewApi.VisibilityType Description The name of element apply the material to to
SetElementVisibility
Argument
element visibility
The visibility type to apply to the element.
Member
Description Sets information for a given material. Type String MaterialInfo Description The name of the material to query. A MaterialInfo containing the information on the material to be set.
SetMaterialInfo
Argument
material Info
Member
Description Sets the visibility type for a given material. Type String Aveva.VPD.ReviewApi.VisibilityType Description The name of the material to query. The visibility type to apply to the material.
SetMaterialVisibility
Argument
material visibility
Member
Description Gets the camera manager interface
CameraManager
Member
Description Gets the element manager interface
ElementManager
Member
Description Gets the material manager interface
MaterialManager
Member
Description Gets Review interface instance
Instance
A:4
12.2

Member
Description Gets the user event manager
UserEventManager
Member
Description Gets the Review Instance Id
Id
A.2
IAddin
IAddin needs to be implemented by any class in the add-in assembly. At runtime Review will load the add-in assemblies and communicate with them through the IAddin interface. Review will pass an IReview interface to the add-in when it starts. Review will also get the main user control that will be displayed in the Review main Window.
A.2.1
Members
Member
Description This function will be called by Review to indicate to the add-in that it can start processing calls to Review. Review will also pass the add-in an IReview interface to make calls to. Type Aveva.VPD.ReviewApi.IReview Description The interface to Review to make calls to.
Start
Argument
review
Member
Description This function will be called by Review to indicate that it must stop making calls to the Review Interface.
Stop
Member
Description The name of the add-in that will be used to identify it in the Review GUI. This name will be added to the Addin menu list so the add-in can be displayed and hidden. This name will also appear in the title bar of the window containing the add-in control.
AddinName [get]
Member
Description Returns the User Control that will be displayed in the add-in window. This User Control will provide the main GUI for the add-in
Control [get]
A:5
12.2

Member
Description
Description [get] A description of the add-in
Member
Description Unused in this version of Review
Priority [get]
A.3
ICamera
Provides interface for a particular camera or view of the model. This should be used for camera specific actions such as setting the position and orientation or getting the currently picked elements for the view.
A.3.1
Members
Member
Description Gets the CameraType for the camera.
CameraType
Member
Description Gets or sets an array of floats representing the position of the camera in the model
Position
Member
Description Gets or sets an array of floats representing the optical centre of the camera in the model
Centre
Member
Description Gets or sets a float representing the bearing of the camera
Bearing
Member
Description Gets or sets a float representing the elevation of the camera
Elevation
Member
Description Gets or sets a float representing the roll of the camera
Roll
A:6
12.2

Member
Description Gets or sets a float representing the field of view of the camera
FOV
Member
Description Sets the position, optical centre and roll of the camera using the specified values Type float[] float[] float Description An array indicating the position of the camera An array indicating the optical centre of this camera A value indicating the roll of the camera
SetPositionAndCentre
Argument
position centre roll
Member
Description Gets or sets an array of elements picked on the camera
PickedElements
Member
Description Gets or sets an array of strings which represent the names of the elements picked on the camera
PickedElementNames
A.4
CameraEvents
Provides a concrete class that exposes camera events from within Review. A client may subscribe to these events by creating a new instance of the class and attaching to the provided event members.
A.4.1
Members
Member
Description Creates a CameraEvents object Type Aveva.VPD.ReviewApi.ICameraManager Description The Camera Manager object
CameraEvents
Argument
Member
Description Occurs when a camera changes
CameraChangedEvent
A:7
12.2

A.5
ICameraManager
Provides an interface for the management of cameras within Review. This should typically be used for obtaining the interface to a specific camera.
A.5.1
Members
Member
Description Retrieves an ICamera object for the specified camera Type Aveva.VPD.ReviewApi.CameraType Description The camera to be retrieved
GetCamera
Argument
Camera
A.6
IElement
Provides interface for a particular element. This should be used for element specific actions such as setting its visibility state or material assignment.
A.6.1
Members
Member
Description Gets the name of the element
Name
Member
Description Gets or sets a VisibilityType enum representing the visibility type of the element
VisibilityType
Member
Description Gets or sets an IMaterial object representing the material of the element.
Material
Member
Description Gets a Boolean value indicating whether the element is in the Active Selection.
Selected
Member
Description Adds the element to the Active Selection. Type object Description The sender of the request.
AddToSelection
Argument
sender
A:8
12.2

Member
Description Removes the element from the Active Selection. Type object Description The sender of the request.
RemoveFromSelection
Argument
sender
Member
Description Gets an array of the child elements
Children
Member
Description Looks at the element on the specified camera Type Aveva.VPD.ReviewApi.ICamera Aveva.VPD.ReviewApi.LookType bool Description The camera to be moved. The method by which the camera should be moved. A value indicating whether the element should be highlighted after the move.
LookAt
Argument
camera lookMethod highlight
A.7
ElementEvents
Provides a concrete class that exposes element events from within Review. A client may subscribe to these events by creating a new instance of the class and attaching to the provided event members.
A.7.1
Members
Member
Description
ElementMaterialChangedEvent Occurs when the material of an element changes.
Member
Description Occurs when the visibility type of an element changes.
ElementVisibilityTypeChangedEvent
Member
Description Occurs when the active selection changes
ElementSelectionChangedEvent
A:9
12.2

Member
Description Creates an ElementEvents object Type Aveva.VPD.ReviewApi.IElementManager Description The Element Manager object.
ElementEvents
Argument
A.8
IElementManager
Provides an interface for the management of elements within Review. This should be used to get the interface to a specific element or actions pertaining to all elements in the model.
A.8.1
Members
Member
Description Retrieves an IElement object for the specified element after checking the element exists. Throws an ArgumentException if the element doesn't exist. Type string Description The name of the element to be retrieved.
GetElement
Argument
name
Member
Description Retrieves an IElement object for the specified element. If checkExists is set and the element does not exists then an ArgumentException is thrown. Type string bool Description The name of the element to be retrieved. Check if the element exists.
GetElement
Argument
name checkExists
Member
Description Gets the root element for the current model
RootElement
Member
Description Gets an array of the elements in the Active Selection
SelectedElements
A:10
12.2

Member
Description Sets an array of elements to the Active Selection. Type object IElement [] Description The request sender. The elements to be set.
SetSelectedElements
Argument
sender elements
Member Argument
Description Type object string[] Description The request sender. The element names to be set.
SetSelectedElementNamess Sets an array of element names to the Active Selection. sender elements
Member
Description Retrieves a Boolean value indicating whether the specified element exists Type string Description The name of the element to be evaluated.
ElementExists
Argument
name
Member
Description Sets the visibility type for all elements in the current model Type Aveva.VPD.ReviewApi. VisibilityType Description The visibility type to be applied.
SetAllElementsVisibilityType
Argument
visibilityType
Member
Description Sets the material for all elements in the current model Type Aveva.VPD.ReviewApi.IMaterial Description The material to be applied
SetAllElementsMaterial
Argument
material
A:11
12.2

Member Argument
Description Type Aveva.VPD.ReviewApi.IElement[] Aveva.VPD.ReviewApi.VisibilityType Description The elements to be changed The visibility type to be applied
SetElementsVisibilityType Sets the visibility type for the specified elements elements visibilityType
Member Argument
Description Type Aveva.VPD.ReviewApi.IElement[] Aveva.VPD.ReviewApi.IMaterial Description The elements to be changed. The material to be applied.
SetElementsMaterial Sets the material for the specified elements elements material
Member
Description Freeze the current associations state between elements and materials. This provides the state to which ResetMaterials method will revert.
FreezeMaterials
Member
Description Reset the material name associated with each element to those at the last frozen. Initially the frozen state is that contained within a Review status file.
ResetMaterials
A.9
IMaterial
Provides interface for a particular material. This should be used for material specific actions such as setting its colour and lighting properties.
A.9.1
Members
Member
Description Gets the name of the material
Name
Member
Description Retrieves a MaterialInfo object for the material
GetMaterialInfo
A:12
12.2

Member
Description Sets the MaterialInfo object for the material Type Aveva.VPD.ReviewApi.MaterialInfo Description The required MaterialInfo object.
SetMaterialInfo
Argument
materialInfo
Member
Description Gets or sets the colour of the material
Colour
Member
Description Gets or sets the ambient value of the material [0 .. 100]
Ambient
Member
Description Gets or sets the specular value of the material [0 .. 100]
Specular
Member
Description Gets or sets the metalness value of the material [0 .. 100]
Metalness
Member
Description Gets or sets the smoothness value of the material [0 .. 100]
Smoothness
Member
Description Gets or sets the transparency value of the material [0 .. 100]
Transparency
Member
Description Gets or sets the visibility type of the material
VisibilityType
Member
Description Deletes the material
Delete
A:13
12.2

A.10 MaterialEvents
Provides a concrete class that exposes material events from within Review. A client may subscribe to these events by creating a new instance of the class and attaching to the provided event members.
A.10.1
Members
Member
Description
MaterialChangedEvent Occurs when a material changes
Member
Description Occurs when a material is created
MaterialCreatedEvent
Member
Description Occurs when a material is deleted
MaterialDeletedEvent
Member
Description Creates a MaterialEvents object Type Aveva.VPD.ReviewApi.IMaterialManager Description The Material Manager object.
MaterialEvents
Argument
A.11
IMaterialManager
Provides an interface for the management of materials within Review. This should typically be used for creating, deleting and enumerating materials.
A.11.1
Members
Member
Description Creates a material Type string MaterialInfo Description The name of the material to be created. A MaterialInfo object for the material.
CreateMaterial
Argument
Name materialInfo
A:14
12.2

Member
Description Deletes the specified material Type Aveva.VPD.ReviewApi.IMaterial Description The material to be deleted.
DeleteMaterial
Argument
material
Member
Description Deletes the specified material Type string Description The name of the material to be deleted.
DeleteMaterial
Argument
name
Member
Description Retrieves the material of the specified name Type string Description Retrieves the material of the specified name.
GetMaterial
Argument
name
Member
Description Gets an array of all the materials in the current model
AllMaterials
Member
Description Retrieves a Boolean value indicating whether the specified material exists. Type string Description The name of the material to be evaluated.
MaterialExists
Argument
name
A.12 IAnimationManager
Interface for managing animations.
A.12.1
Members
Member
Description Get copy of the animation that is currently set in Review. Return Value is an Animation instance that contains a copy of the current animation data.
GetCurrentAnim ation
A:15
12.2

Member
Description Sets the current animation Type Animation Description An Animation instance that contains the animation data to set into Review.
SetCurrentAnim ation
Argument
animation
Member
Description Returns the max animation time of the current animation.
GetCurrentAnim ationMaxTime
Member
Description Sets the time of the currently set animation in Review. Any cameras or groups specified in the animation will be moved to the position along the animation paths specified by the time. Type Single Description The animation time. Must be less than the animation max time retrieved from GetCurrentAnimationMaxTime (see above) Set to true if clash detection should be enabled in the view for the frame.
SetCurrentAnim ationFrame
Argument
time
enableClash
Boolean
A.13 Animation
Specifies an entire animation. Defines the actors such as observer, lights and groups and their respective trajectories.
A.13.1
Members
Member
Description Calculate hashcode for the Animation.
GetHashCode
Member
Description Compare two Animation.
Equals
A.14 IGroupManager
Interface to the Group Manager.
A:16
12.2

A.14.1
Members
Member
Description Creates a Group. Returns an IGroup object for the specified Group Type String GroupInfo Description The name of the Group to be created A GroupInfo object for the Group
CreateGroup
Argument
name GroupInfo
Member
Description Creates a Group. Returns an IGroup object for the specified Group Type GroupInfo Description A GroupInfo object for the Group
CreateGroup
Argument
GroupInfo
Member
Description Deletes the specified Group. Type IGroup Description The Group to be deleted
DeleteGroup
Argument
Group
Member
Description Deletes the specified Group. Type String Description The name of the Group to be deleted
DeleteGroup
Argument
name
Member
Description Retrieves the Group of the specified name. Returns an IGroup object for the specified Group. Type String Description The name of the Group to be retrieved.
GetGroup
Argument
name
Member
Description Retrieves a value indicating whether the specified Group exists. Returns a value indicating that the specified Group exists or not. Type String Description The name of the Group to be evaluated.
GroupExists
Argument
name
A:17
12.2

A.15 ITrajectoryManager
Interface for managing trajectories/animations paths.
A.15.1
Members
Member
Description Get copy of named trajectory data. Return Value is an instance that contains the trajectory data. Type String Description The name of the trajectory whose data should be returned.
GetTrajectory
Argument
name
Member
Description Create an empty trajectory. Return Value is an instance that contains the newly-created trajectory data. Type String Description The name of the new trajectory to create.
CreateTrajectory
Argument
name
Member
Description Delete a named trajectory. Type String Description The name of the new trajectory to delete.
DeleteTrajectory
Argument
name
Member
Description Set trajectory. Type Trajectory Description An instance that should be set in Review.
SaveTrajectory
Argument
trajectory
A.16 ILightManager
Provides interface to light manager.
A:18
12.2

A.16.1
Members
Member
Description Get light definition. Return Value is an instance containing data for the specified light. Type Int32 Description The number of the light to return data for. Should be in the range 1 to 7.
GetLight
Argument
lightNumber
Member
Description Get ambient light definition. Return Value is an instance containing data on the ambient light.
GetAmbientLight
Member
Description Set light definition. Type Light Description An instance containing data on the light to set.
SetLight
Argument
light
Member
Description Set ambient light definition. Type AmbientLight Description An instance containing data on the ambient light to set.
SetAmbientLight
Argument
light
A.17 UserMessage
Provides a class that enables passing of user defined objects to other subscribers of user events.
A.17.1
Members
Member
Description Create new user message to raise through the API Type Object Description User defined object or class to pass through the API
UserMessage
Argument
Message
A:19
12.2

Member
Description Retrieve user-defined message payload Type Description
Message
Argument
None
A.18 IUserEventManager
Provides an interface to events raised within Review containing user defined objects.
A.18.1
Members
Member
Description Raises a new user event with a user defined payload Type Aveva.VPD.ReviewApi.UserMessage Description The message to raise
RaiseUserEvent
Argument
message
A.19 UserEvents
Provides a concrete class that exposes user events from within Review. A client may subscribe to these events by creating a new instance of the class and attaching to the provided event members.
A.19.1
Members
Member
Description Creates a UserEvents object Type Aveva.VPD.ReviewApi.IUserEventMan ager Description The UserEventManager object.
UserEvents
Argument
Member
Description Occurs a user event is raised.
UserEvent
A.20 Other ReviewAPI Classes

A.20.1 MaterialInfo
The MaterialInfo class is used to define the visual properties of Review materials. The MaterialInfo class contains the following members:
A:20
12.2

Member
Type System.Int32 System.Int32 System.Int32 System.Int32 System.Int32 System.Int32
Description The red value of the colour of the material in the range 0-100 The green value of the colour of the material in the range 0-100 The blue value of the colour of the material in the range 0-100 The ambient reflectivity of the material in the range 0-100 The specular reflectivity of the material in the range 0-100 Defines the amount of plastic-metal in the material. This is defined in the range 0-100 with 0 being plastic and 100 being metal. Defines how smooth the material is. This is defined in the range 0-100 with 0 being rough and 100 being smooth. Defines how transparent the material is. This is defined in the range 0-100 with 0 being opaque and 100 being transparent.
Red Green Blue Ambient Specular Metalness
Smoothness
System.Int32
Transparen cy
System.Int32
A.20.2
ReviewActiveSelection
The ReviewActiveSelection class provides access to the list of selected elements in Review. Using this class an add-in can query or set the list of selected elements and subscribe to an event that is fired when the selection changes. The ReviewActiveSelection class contains the following members:
Member
Description Sets the selection and fires an event to all subscribers that the selection has changed. Type System.Object System.Collections.ArrayList Description The object selection. that is setting the
SelectionChang ed
Argument
sender selection
An ArrayList of String objects containing the names of the selected elements.
Member
Description Subscribes to the event that is fired when the active selection changes. In Review 6.4 or later the selection changed event is triggered by selection changes in the Explorer, Observer View, Camera views and the Search Results window.
SubscribeForSe lectionChanged Event
A:21
12.2

Argument
Type ReviewActiveSelection.SelectionCh angedEvent
Description The function to act as an event handler for the selection changed event.
A:22
12.2

Review 12.2 .NET Addin User Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Review 12.2 .NET Addin User Guide

Uploaded by

Copyright:

Available Formats

AVEVA Review 12.2 .

NET Addin User Guide

AVEVA Solutions Limited

AVEVA Review .NET Addin User Guide

Comments / Remarks Issued Up Issue

September 2011 12.1.1 February 2013 12.2

AVEVA Review .NET Addin User Guide

AVEVA Review .NET Addin User Guide

AVEVA Review .NET Addin User Guide

Customising Review with .NET Add-ins . . . . . . . . . . . . . . . . . . . . . . 2:1

Common Application Framework Interfaces . . . . . . . . . . . . . . . . . . 3:1

AVEVA Review .NET Addin User Guide

Writing a Command Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:9

Share Information between CAF addins . . . . . . . . . . . . . . . . . . . . . . 4:1

The Review Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:1

CameraEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:7 ICameraManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:8 IElement

ElementEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:9 IElementManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:10 IMaterial

AVEVA Review .NET Addin User Guide

Members Members Members Members Members Members Members

AVEVA Review .NET Addin User Guide

AVEVA Review .NET Addin User Guide

.NET Customisation Architecture

AVEVA Review .NET Addin User Guide

AVEVA Review .NET Addin User Guide

Customising Review with .NET Add-ins

Create an Add-in Project

AVEVA Review .NET Addin User Guide

AVEVA Review .NET Addin User Guide

Right click on the user control (UserControl1) to expand a context menu.

Click Properties to display a docked Properties window.

AVEVA Review .NET Addin User Guide

Add a Reference to the Review API

AVEVA Review .NET Addin User Guide

AVEVA Review .NET Addin User Guide

AVEVA Review .NET Addin User Guide

namespace EngineerAddin { class AccessAddin: IAddin { } }

class AccessAddin: IAddin {

#region IAddin Members

public string AddinName

AVEVA Review .NET Addin User Guide

{ get { throw new Not ImplementedException(); } }

public System.Windows.Forms.UserControl Control { get { throw new Not ImplementedException(); } }

public string Description { get { throw new Not ImplementedException(); } }

public int Priority { get { throw new Not ImplementedException(); } }

public void Start(IReview review) { throw new Not ImplementedException(); }

public void Stop() { throw new Not ImplementedException(); }

AVEVA Review .NET Addin User Guide

class AccessAddin: IAddin { private BaseUserControl BaseUserControl (); MaterialControl = new

public string AddinName { get { return "Material colour change"; } }

public System.Windows.Forms.UserControl Control { get { return MaterialControl; } }

public string Description { get { return "Material Addin"; } }

public int Priority { get { return 0; } }

AVEVA Review .NET Addin User Guide

public void Stop() { // no code }

Developing the User Control as an Add-in

AVEVA Review .NET Addin User Guide

Add a reference to the ReviewAPI in the using statements:

public BaseUserControl() { InitializeComponent(); } } }

public void AttachReview(IReview review) {

AVEVA Review .NET Addin User Guide

public void AttachReview(IReview review) { ReviewInterface = review; }

public void Start(IReview review) { MaterialControl.AttachReview(review); }

Responding to Review Selection Changes

public void ActiveSelectionChanged(object sender) {