Review 12.2 .NET Addin User Guide

AVEVA Review 12.2 .NET Addin User Guide

AVEVA Sol u t i on s L im i t ed

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 AVEV AVEVA A 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 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 cla uses and the analogous clauses in the software licence under which the AVEVA 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, AVEV AVEVA A Solutions Limited or i ts subsidiaries. All rights are reserved to AVEV AVEVA A Solutions Limited and its subsidiaries. The information contained in this document 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 liabiliti es 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. AVEV AVEVA A Solutions Limited and its subsidiaries. All rights reserved. AVEV VEVA A 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 AVEVA software or associated documentation. AVEV AVEVA A Solutions Limited, High Cross, Madingley Road, Road, Cambridge, CB3 0HB, United United Kingdom.

Trademark AVEV AVEVA A and Tribon are registered trademarks of AVEV AVEVA A Solutions Limited or its subsidiaries. Unauthorised use of the AVEVA AVEVA or Tribon trademarks is strictly forbidden. AVEV AVEVA A product/software names are trademarks or registered trademarks of AVEV VEVA A 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 Sol u t i on s L im i t ed

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 AVEV AVEVA A 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 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 cla uses and the analogous clauses in the software licence under which the AVEVA 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, AVEV AVEVA A Solutions Limited or i ts subsidiaries. All rights are reserved to AVEV AVEVA A Solutions Limited and its subsidiaries. The information contained in this document 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 liabiliti es 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. AVEV AVEVA A Solutions Limited and its subsidiaries. All rights reserved. AVEV VEVA A 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 AVEVA software or associated documentation. AVEV AVEVA A Solutions Limited, High Cross, Madingley Road, Road, Cambridge, CB3 0HB, United United Kingdom.

Trademark AVEV AVEVA A and Tribon are registered trademarks of AVEV AVEVA A Solutions Limited or its subsidiaries. Unauthorised use of the AVEVA AVEVA or Tribon trademarks is strictly forbidden. AVEV AVEVA A product/software names are trademarks or registered trademarks of AVEV VEVA A 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 Revi ew .NET Ad A d di n User Us er Gui d e

Revision Revision Sheet Sheet

Dat e

Ver s i o n

Co m m en ts / Rem ar k s

September 2011 12.1.1

Issued

February 2013

Up Issue

12.2

AVEVA Revi ew .NET Addi n User Gui de

AVEVA Rev iew .NET Addin User Gui de

AVEVA Review .NET Addin User Guide

Contents

Page

.NET Addin Intr oduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1 .NET Customisati on A rchitecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1

Customi sin g Review wi th .NET Add-ins . . . . . . . . . . . . . . . . . . . . . . 2:1 Int ended Audi ence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1 Create an Add-in Proj ect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 t he Add-in in Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:20 Configure whic h Ad d-ins are Loaded b y Review . . . . . . . . . . . . . . . . . . . . . . . 2:22

Common A ppli cation Framework Interfaces . . . . . . . . . . . . . . . . . . 3:1 Create a Pro ject To Host The CAF Addi n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2 Ad d a Referenc e to th e Review an d CA F API . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4 The IAd din Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5 Reference the Revi ew Servic e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:8 The Win dowManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:8 Ad di n Co mm and s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:9

© Copyright 1992 to current year. AVEVA Solu tio ns L imi ted an d it s su bsi diar ies. All rig hts reser ved.

i

12.2


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

Menu and Com mand B ar Cust omisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:12 Configuring a Module to Load an A ddi n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:13 Ad d a b ut ton to op en t he ad di n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3: 14

Share Infor matio n between CAF addi ns . . . . . . . . . . . . . . . . . . . . . . 4:1 Share fr om Owni ng Addin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:1 Consume Shar ed Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:2 Get Data From Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:3

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

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A :1

Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:1

IAddin

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5

Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5

ICamera

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A :6

Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:6

CameraEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 7 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:7

ICameraManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 8 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:8

IElement

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A :8

Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:8

ElementEvent s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A :9 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:9

IElemen tManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 10 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:10

IMateri al

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:12

Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:12

Materi alEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 14 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:14

IMateri alManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 14 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:14

IAnim ationManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 15 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:15

An imat io n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 16

© Copyright 1992 to current year. AVEVA Sol uti ons Li mi ted and its sub sid iari es. All rig hts reser ved.

1 1:ii

12.2


Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:16

IGroupManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 16 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:17

ITrajector yManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 18 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:18

ILi ghtManager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 18 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:19

UserMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 19 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:19

IUserEventManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 20 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:20

UserEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 20 Members

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:20

Other Revi ewAPI Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 20 MaterialInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:20 ReviewActiveSelection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:21

© Copyright 1992 to current year. AVEVA Solu ti ons Li mi ted an d it s su bsi diar ies. All rig hts reser ved.

1 1:iii

12.2



1 1:iv

12.2

AVEVA Rev iew .NET Addin User Gui de Introduction

1

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

AVEVA Rev iew .NET Addin User Gui de Introduction


1:2

12.2

AVEVA Rev iew .NET Addin User Gui de Customising Review with .NET Add-ins

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 Ad d-i ns 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 > Proj ect 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 Propert ies 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 dire ct access to controls and functions within the AVEVA Review application. Click Project from the main menu bar and then click Ad d Ref eren ce .


2:4

12.2


Select the Browse tab, and then navigate to the default AVEVA Review install directory, for example:

C: \ AVEVA\ Revi ew12. 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 pr operties and members of the IAddin Interface. Right click the project name (EngineerAddin ) in the Solution Explorer and select Ad d > Class to open the Ad d 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 Ac ces sA dd in and then click Ad d . 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:

usi ng Aveva.Review.API; Append the Ac ces sA dd in class name with a colon and then add the statement IAddin , as shown below.

names pace Engi neer Addi n { c l as s Access Addi n: I Addi n { } } 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:

c l as s AccessAddi n: I Addi n { #r egi on I Addi n Member s publ i c s t r i ng Addi nName


2:7

12.2


{ get { t hr ow new Not I mpl ement edExcept i on( ) ; } } publ i c Syst em. Wi ndows. For ms. User Cont r ol Cont r ol { get { t hr ow new Not I mpl ement edExcept i on( ) ; } } publ i c s t r i ng Descri pt i on { get { t hr ow new Not I mpl ement edExcept i on( ) ; } } publ i c i nt Pr i or i t y { get { t hr ow new Not I mpl ement edExcept i on( ) ; } } publ i c voi d S t a r t ( I Revi ew r evi ew) { t hr ow new Not I mpl ement edExcept i on( ) ; } publ i c voi d St op( ) { t hr ow new Not I mpl ement edExcept i on( ) ; } #endr egi on } } All of the Not I mpl ement edExcept i on( ) 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 Ac ces sA dd in class create an instance of the class using the new keyword within the Ac ces sA dd in class body. Name the instance of the class as MaterialControl . Do this by adding the following syntax below the class declaration in the Ac ces sA dd in class source.

c l as s AccessAddi n: I Addi n { pr i vat e BaseUser Cont r ol BaseUser Cont r ol ( ) ;

Mat er i al Cont r ol

=

new

In the following steps each of the Not I mpl ement edExcept i on( ) 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.

publ i c s t r i ng Addi nName { get { r e t u r n " Mat er i al col our change" ; } } The Control Property returns a reference to the UserControl t hat will be displayed in Review. In this case simply return the MaterialControl member created earlier.

publ i c Syst em. Wi ndows. For ms. User Cont r ol Cont r ol { get { r e t u r n Mat er i al Cont r ol ; } } 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.

publ i c s t r i ng Descri pt i on { get { r e t u r n " Mat er i al Addi n" ; } } The priority property must be an integer value. The priority method is not longer supported by Review but must be specified to maintain compatability.

publ i c i nt Pr i or i t y { get { r e t u r n 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.

publ i c voi d St op( ) { / / 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:

usi ng Aveva. Revi ew. API ; Create a member of type IReview to store the reference to the interface as shown below.

names pace Engi neer Addi n { publ i c par t i al cl as s BaseUser Cont r ol : User Cont r ol { pr i vat e I Revi ew Revi ewI nt er f ace; publ i c BaseUser Cont r ol ( ) {

I ni t i al i zeComponent ( ) ; } }

} Create a new function called At tac hReview with an argument review of type IReview .

publ i c voi d At t achRevi ew( I Revi ew r evi ew) { }


2:11

12.2


Assign the created private IReview Interface to the At tac hRev iew argument review ; both of type IReview .

publ i c voi d At t achRevi ew( I Revi ew r evi ew) { Revi ewI nt er f ace = r evi ew; } When Review loads the add-ins it will call the Start method and access the At tac hRev iew function and its argument review, in the Ac ces sA dd in class, through the instance of the user control, MaterialControl . Tab back to AccessAddin and insert the following code in the Start function:

publ i c voi d S t a r t ( I Revi ew r evi ew) {

Mat er i al Cont r ol . At t achRevi ew( r evi ew) ;

}

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.

publ i c voi d Act i veSel ect i onChanged( obj ect s ender ) { } 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 ent er, 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.

publ i c voi d At t achRevi ew( I Revi ew r evi ew) { Revi ewI nt er f ace = r evi ew; Revi ewAct i veSel ect i on. Subscr i beFor Sel ect i onChangedEvent ( n ew Revi ewAct i veSel ect i on. Sel ect i onChangedEvent ( Act i veSel ecti 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 Ac ti veSel ect io nCh ang ed 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.

publ i c voi d Act i veSel ect i onChanged( obj ect s ender ) { i f ( Revi ewAct i veSel ect i on. Sel ect i on. Count > 0) { El ement NameLabel . Text ( st r i ng) Revi ewAct i veSel ect i on. Sel ec t i on[ 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

Cr eat ing a Mat er ial 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 .

publ i c par t i al cl as s BaseUser Cont r ol : User Cont r ol { pr i vat e I Revi ew Revi ewI nt er f ace; pr i vat e Mat er i al I nf o gr eenMat er i al ; pr i vat e st r i ng gr eenMat er i al Name = " Gr een Mat er i al " ; publ i c BaseUser Cont r ol ( ) {

I ni t i al i zeComponent ( ) ; }

Next, in the At tac hRev iew function create a new material using the following code:

publ i c voi d At t achRevi ew( I Revi ew r evi ew) { Revi ewI nt er f ace = r evi ew; Revi ewAct i veSel ect i on. Subscr i beFor Sel ect i onChangedEvent ( n ew Revi ewAct i veSel ect i on. Sel ect i onChangedEvent ( Act i veSel ecti onChanged) ) ; gr eenMat er i al = new Mat er i al I nf o( 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 At tachRev iew 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.

Ar r ayLi st mat er i al Names = Revi ewI nt er f ace. Get Al l Mat er i al s( ) ; i f ( ! mat er i al Names. Cont ai ns( gr eenMat er i al Name) ) {

Revi ewI nt er f ace. Cr eat eMat er i al ( gr eenMat er i al Name) ;

}


2:14

12.2


Revi ewI nt er f ace. Set Mat er i al I nf o( gr eenMat er i al Name, gr eenMat er i al ) ; Note: Before creating an Ar ray Li st make sure that the using System.Collections; statement is added to the list of using statements.

2.2.5

A pp ly in g t he Mat er ial 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.

pr i vat e voi d Event Ar gs e)

Set Mat er i al But t on_Cl i ck( obj ect

s ender ,

{ Revi ewI nt er f ace. Set El ement Mat er i al ( El ement NameLabel . Text , gr eenMat er i al Name) ; }

2.2.6

Navigating to the Selected Element To navigate to the selected element, create a button by selecting aButton 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


pr i vat e voi d Event Ar gs e)

LookToEl ement But t on_Cl i ck( obj ect

s ender ,

{ Revi ewI nt er f ace. LookAt El ement ( Camer aType. Obser ver , El ement NameLabel . Text , LookType. Dynami cMove, t r u e) ; }

This will look to the selected element in the observer window with snap move and highlighting.

2.2.7

Cl as s an d Us er Co nt ro l Co de 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 f ollows. Ac ces sA dd in cl ass

usi ng Syst em;


2:16

12.2


usi ng Syst em. Col l ect i ons. Gener i c; usi ng Syst em. Li nq; usi ng Syst em. Text ; usi ng Aveva. Revi ew. API ; names pace Engi neer Addi n { c l as s Access Addi n: I Addi n { pr i vat e BaseUser Cont r ol Mat er i al Cont r ol BaseUser Cont r ol ( ) ;

= new

#r egi on I Addi n Member s publ i c s t r i ng Addi nName { get { r e t u r n " Mat er i al col our change" ; } } publ i c Syst em. Wi ndows. For ms. User Cont r ol Cont r ol { get { r e t u r n Mat er i al Cont r ol ; } } publ i c s t r i ng Descri pt i on { get { r e t u r n "Mat er i al Addi n" ; } } publ i c i nt Pr i or i t y { get { r e t u r n 0; } }


2:17

12.2


publ i c voi d S t a r t ( I Revi ew r evi ew) {

Mat er i al Cont r ol . At t achRevi ew( r evi ew) ; } publ i c voi d St op( ) { / / no code } #endr egi on }

} UserControl class

usi ng Syst em; usi ng Syst em. Col l ect i ons. Gener i c; usi ng Syst em. Component Model ; usi ng Syst em. Dr awi ng; usi ng Syst em. Dat a; usi ng Syst em. Li nq; usi ng Syst em. Text ; usi ng Syst em. Wi ndows. For ms; usi ng Aveva. Revi ew. API ; usi ng Syst em. Col l ect i ons; names pace Engi neer Addi n { publ i c par t i al cl as s BaseUser Cont r ol : User Cont r ol { pr i vat e I Revi ew Revi ewI nt er f ace; pr i vat e Mat er i al I nf o gr eenMat er i al ; pr i vat e

s t r i ng gr eenMat er i al Name

= " Gr een

Mat er i al " ;


2:18

12.2


publ i c BaseUser Cont r ol ( ) {

I ni t i al i zeComponent ( ) ; } publ i c voi d At t achRevi ew( I Revi ew r evi ew) { Revi ewI nt er f ace = r evi ew;

Revi ewAct i veSel ect i on. Subscr i beFor Sel ect i onChangedEvent ( n ew Revi ewAct i veSel ect i on. Sel ect i onChangedEvent ( Act i veSel ecti onChanged) ) ; gr eenMat er i al = new Mat er i al I nf o( 0, 100, 0, 0, 0, 0, 0, 0) ; Ar r ayLi st Revi ewI nt er f ace. Get Al l Mat er i al s( ) ;

mat er i al Names

=

mat er i al Names = r evi ew. Get Al l Mat er i al s( ) ; i f ( ! mat er i al Names. Cont ai ns( gr eenMat er i al Name) ) { Revi ewI nt er f ace. Cr eat eMat er i al ( gr eenMat er i al Name) ; } Revi ewI nt er f ace. Set Mat er i al I nf o( gr eenMat er i al Name, gr eenMat er i al ) ; } publ i c voi d Act i veSel ect i onChanged( obj ect s ender ) { i f ( Revi ewAct i veSel ect i on. Sel ect i on. Count > 0) { El ement NameLabel . Text ( st r i ng) Revi ewAct i veSel ect i on. Sel ec t i on[ 0] ;

=

}


2:19

12.2


} pr i vat e voi d Set Mat er i al But t on_Cl i ck( obj ect sender , Event Ar gs e) { Revi ewI nt er f ace. Set El ement Mat er i al ( El ement NameLabel . Text , gr eenMat er i al Name) ; } pr i vat e voi d LookToEl ement But t on_Cl i ck( obj ect sender , Event Ar gs e) { Revi ewI nt er f ace. LookAt El ement ( Camer aType. Obser ver , El ement NameLabel . Text , LookType. Dynami cMove, t r u e) ; }

} }

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 Ad di ns 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 Ad di ns 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 Addi ns. 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 Addi ns. xml file in the same directory as Revi ew. exe. When Review runs it will look for the file Addi ns. xml if it finds this file it will only load those DLLs specified in this file. If it does not find and Addi ns. xml file it will load all addins that are in the Addins directory. Below is an example of the contents of an Addi ns. xml file which specifies two add-ins to load: Dat aVi ewer . dl l and MyAddi n. dl l .

Addins\DataViewer.dll Addins\MyAddin.dll


2:22

12.2

AVEVA Rev iew .NET Addin User Gui de Common Application Framework Interfaces

3

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 oth er. 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.Appli cationFramework

•

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.Appli cationFramework.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 pro vides 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

AVEVA A VEVA Rev iew .NET Ad A d d in User Gui d e Common Application Framework Interfaces

•

3.1

StatusBar 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.

Crea reate a Proje roject To Host Host The CAF Addin 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 > Proj Proj ect 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 Containin Containin g 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 tha t will expose the CAF and ReviewAPI, these are described in the following sections of this guide.

3.2

Add a Refere ference nce to the the Review view and and CAF CAF API API Adding a reference to the ReviewAPI.dll file will expose the AVEVA Review object library. This will give the developer dire ct access to controls and functions within the AVEVA AVEVA Review application. Adding a reference to the Aveva.A Av eva.A pp li cat io nFr amew or k.Pr esen tat io n.d ll and Aveva.A Av eva.A pp li cat io nFr amew or k.d ll 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 Ad d Ref eren ce . Select the Browse tab, and then navigate to the defa ult AVEVA AVEVA Review install directory, directory, for example:

C: \ AVEVA EVA\ Revi ew12. 12. 2 From the default install directory select the following files: (Hold down the control key (CTRL ) to select multiple files) Aveva.A Av eva.A pp li cat io nFr amew or k.Pr esen tatio tat io n.d ll Aveva.A Av eva.A pp li cat io nFr amew or k.d ll 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 pr operties and members of the IAddin Interface. Right click the project name (EngineerAddinCAF ) in the Solution Explorer and select Ad d > Cl ass to open the Ad d 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 Ad d . 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. usi ng Sys t em; usi ng Syst em. Col l ect i ons. Gener i c; usi ng Syst em. Text ; names pace Engi neer Addi nCAF { c l as s Engi neer Addi nCAFAddi n { } }

Add using statements that reference the ApplicationFramework namespace. usi ng Aveva. Appl i cat i onFr amewor k; usi ng Aveva. Appl i cat i onFr amework. Present ati on;

Implement the IAddin interface on the EngineerAddinCAFAddin class by following the class name with a colon and the name of the addin. usi ng Sys t em; usi ng Syst em. Col l ect i ons. Gener i c; usi ng Syst em. Text ; usi ng Aveva. Appl i cat i onFr amewor k; usi ng Aveva. Appl i cat i onFr amework. Present ati on; names pace Engi neer Addi nCAF { c l as s Engi neer Addi nCAFAddi n: I Addi n { } }

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: usi ng Sys t em; usi ng Syst em. Col l ect i ons. Gener i c; usi ng Syst em. Text ; usi ng Aveva. Appl i cat i onFr amewor k; usi ng Aveva. Appl i cat i onFr amework. Present ati on; names pace Engi neer Addi nCAF {


3:6

12.2


c l as s Engi neer Addi nCAFAddi n: I Addi n { #r egi on I Addi n Member s publ i c s t r i ng Descri pt i on { get { t hr ow new Not I mpl ement edExcept i on( ) ; } } publ i c s t r i ng Name { get { t hr ow new Not I mpl ement edExcept i on( ) ; } } publ i c voi d S t a r t ( Ser vi ceManager ser vi ceManager ) { t hr ow new Not I mpl ement edExcept i on( ) ; } publ i c voi d St op( ) { t hr ow new Not I mpl ement edExcept i on( ) ; } #endr egi on } }

All of the Not I mpl ement edExcept i on( ) 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 I mpl ement edExcept i on( ) statements will be replaced so that a new value will be returned to the IAddin interface methods. In the Description return a string. publ i c s t r i ng Descri pt i on { get { r e t u r n " Engi neer Addi n t o f ocus on el ement s and change col our " ; } }

The Public String AddinName method is a read-only property as it only gets and returns the string type passed to it.

publ i c st r i ng Name { get { r e t u r n " Engi neer Addi n"; } }


3:7

12.2


Make sure that the exception statement is deleted from the Stop function and no code added. publ i c voi d St op( ) { / / no code }

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. publ i c voi d S t a r t ( Ser vi ceManager ser vi ceManager ) { }

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 t o Revi ew API Aveva. Revi ew. API . I Revi ew r evi ewApi = ( Aveva. Revi ew. API . I Revi ew) servi ceManager . GetSer vi ce( t ypeof ( Aveva. Revi e w. API . I Revi ew) ) ;

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: Wi ndowManager wi ndowManager = ( Wi ndowManager ) servi ceManager. GetSer vi ce( t ypeof ( Wi ndowManager ) ) ;

Create two new variables of type DockedWindow and BaseUserControl at the start of the class. Name the two variables as and EngineerAddinCAFWindow EngineerAddinCAFControl , repectively.

c l as s Engi neer Addi nCAF: I Addi n { pr i vat e DockedWi ndow Engi neer Addi nCAFWi ndow; pr i vat e BaseUser Cont r ol Engi neer Addi nCAFCont r ol ;


3:8

12.2


Add the following code: Engi neer Addi nCAFCont r ol = new BaseUser Cont r ol ( ) ; Engi neer Addi nCAFWi ndow = wi ndowManager . Cr eat eDockedWi ndow( " Aveva. Engi neerAddi nCAF. Engi neer Addi n CAFCont r ol " , " Engi neer Addi n", Engi neer Addi nCAFCont r ol , DockedPosi t i on. Ri ght ) ; Engi neer Addi nCAFWi ndow. Wi dt h = 265; Engi neer Addi nCAFWi ndow. SaveLayout = t r u e;

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 .. 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 do cking 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.

/ / At t ach t he Revi ew API t o t he Engi neer Addi nCAFCont r ol Engi neer Addi nCAFCont r ol . At t achRevi ew( r evi ewApi ) ;

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 r eflected 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

Wr it in g a Com man d Cl ass 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 functionality.

command execution

Command State 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.

method will be called whenever the CommandManager . Appl i cat i onCont ext 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. void

Refresh(string

context) :

This

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. Ar ray Li st Li st : 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 CommandManager s. Commands collection. Create a new class, ShowEngineerAddinCommand, and populate the class as detailed below. usi ng Sys t em; usi ng Syst em. Col l ect i ons. Gener i c; usi ng Syst em. Text ; usi ng Aveva. Appl i cat i onFr amework. Present ati on; names pace Engi neer Addi nCAF { / / Cl ass t o manage the vi si bi l i t y st at e of t he Engi neer Addi n docked wi ndow / / Thi s command shoul d be associ at ed wi t h a St at eBut t onTool .


3:10

12.2


publ i c c l as s ShowEngi neer Addi nCommand : Command { pr i vat e DockedWi ndow _ wi ndow; / / Const r uct or f or ShowEngi neer Addi nCommand / / The docked wi ndow whose vi si bi l t y st at e wi l l be managed. publ i c ShowEngi neer Addi nCommand( DockedWi ndow wi ndow) { / / Set t he command key t hi s. Key = " Aveva. Engi neer Addi nCAF" ; / / Save t he docked wi ndow _ wi ndow = wi ndow; / / Cr eat e an event handl er f or t he wi ndow cl osed event _ wi ndow. Cl osed += new Event Handl er ( _wi ndow_Cl osed) ; / / Cr eat e an event handl er f or t he Wi ndowLayout Loaded event Wi ndowManager . I nst ance. Wi ndowLayout Loaded += new Event Handl er ( I nst ance_Wi ndowLayout Loaded) ; } voi d I nst ance_ Wi ndowLayout Loaded( obj ect sender , Event Ar gs e) { / / Updat e t he command st at e t o mat ch i ni t i al wi ndow vi si bi l i t y t hi s. Checked = _wi ndow. Vi si bl e; } voi d _wi ndow_ Cl osed( obj ect sender , Event Ar gs e) { / / Updat e t he command st at e when t he wi ndow i s c l osed t hi s. Checked = f al se; } / / Over r i de t he base cl ass Execut e met hod t o show and hi de t he wi ndow publ i c over r i de voi d Execut e( ) { i f ( t hi s. Checked) {

_wi ndow. Show( ) ; } el s e { _wi ndow. Hi de( ) ; } } }


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 ) ser vi ceManager . Get Ser vi ce( t ypeof ( CommandM anager ) ) ; ShowEngi neer Addi nCommand showCommand = new ShowEngi neer Addi nCommand( Engi neer Addi nCAFWi ndow) ; 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


CommandBar Manager commandBar Manager = ( CommandBar Manager ) ser vi ceManager . Get Ser vi ce( t ypeof ( Comma ndBar Manager ) ) ; commandBar Manager . Cust omi zat i onType = Cust omi zat i onType. Cust om; 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.

CAFAddi ns\ Revi ewAddi nsn CAFAddi ns\ PdmsConnect i on CAFAddi ns\ Revi ewShar eAddi n CAFAddi ns\ Dat aVi ewer CAFAddi ns\ PdmsExpl or er CAFAddi ns\ PdmsAt t r i but eVi ewer


3:13

12.2


CAFAddi ns\ Engi neer Addi nCAF

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 Ap pl y 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

AVEVA Rev iew .NET Addin User Gui de Share Information between CAF addins

4

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.

publ i c i nt er f ac e I MyShar edDat a { st r i ng Sampl eMet hod( ) ; } Scroll down the source and located the following function

publ i c voi d St ar t ( Ser vi ceManager ser vi ceManager ) Then add the following code:

/ / Regi st er t hi s i nst ance t o CAF t o al l ow ot her addi ns t o i nt er act wi t h t hi s one. ser vi ceManager . AddSer vi ce( t ypeof ( I MyShar edDat a) , Engi neer Addi nCAFCont r ol ) ; Open the UserControl1 class and locate the following declaration:

publ i c par t i al cl as s BaseUser Cont r ol : User Cont r ol After UserControl add a comma followed by IMySharedData as follows:

publ i c par t i al cl ass BaseUser Cont r ol : User Cont r ol , I MyShar edDat a Before the end of the BaseUserControl class add the following

#r egi on I MyShar edDat a Member s publ i c s t r i ng Sampl eMet hod( )


4:1

12.2


{ r e t u r n El ement NameLabel . Text ; } #endr egi on 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.Ap pl ic ati on Fram ewo rk AVEVA.Ap pl ic ati on Fram ewo rk .Presen tatio n 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 Ad d > Class to open the Ad d 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 Ad d . 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:

t hi s. Key = " Aveva. ConsumeAddi nCAF" ;

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 Fr om Ser vi ce Click on the UserControl1 form and select View Code to display the source code for the form then add the following code

pr i vat e Ser vi ceManager _s er vi ceManager ; publ i c voi d Set Ser vi ceManager ( Ser vi ceManager ser vi ceManager ) { _ser vi ceManager = ser vi ceManager ; } Create a new button. Create a new label with the name OwningElementLabel. Double click on the button and add the following code:

I MyShar edDat a dat a = ( I MyShar edDat a) _ser vi ceManager . Get Ser vi ce( t ypeof ( I MyShar e dDat a) ) ; Owni ngEl ement Label . Text = dat a. Sampl eMet hod( ) ;


4:3

12.2



4:4

12.2

AVEVA Rev iew .NET Addin User Gui de The Review Object Model

A

The Review Object Model

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

Memb ers

Member

Description

Cr eat eMat er i al

Creates a material with the supplied name in Review.

Ar gu men t

Type

Desc ri pt io n

mat er i al

String

The name of the material to create.

Member

Description

Fr eezeMat er i al s

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

Member

Description

Reset Mat er i al s

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 def ined in the model file.

Member

Description

Get Al l Mat er i al s

Returns an ArrayList of String objects containing the names of all materials currently defined in Review.


A: 1

12.2


Member

Description

Get Backgr oundCol our

Returns a Colour object that defines the background colour to use for add-in user controls. This helps add-in controls fit in with the visual style of Review.

Member

Description

Get Mat er i al Exi st s

Returns a bool that defines if a material with the supplied name already exists in Review.

Ar gu men t

Type

Desc ri pt io n

mat er i al

String

The name of the material to query.

Member

Description

Get Mat er i al I nf o

Gets information about a given material.

Ar gu men t

Type

Desc ri pt io n

mat er i al I nf o

String


MaterialInfo

A MaterialInfo object that will receive the material information

Member

Description

Get Mat er i al Vi s i bi l i t y

Returns a VisibilityType that defines the visibility of the material

Ar gu men t

Type

Desc ri pt io n

mat er i al

String


Member

Description

LookAt El ement

Sets a camera to look at an element in the model.

Ar gu men t

Type

Desc ri pt io n

camer a

Aveva.VPD.ReviewApi.CameraType

The camera to use, can be the Observer window or one of the other 7 cameras

el ement l ookMet hod

String

The name of the element to look at

Aveva.VPD.ReviewApi.LookType

The type of move method. Can be snap, dynamic or no move.

hi ghl i ght

bool

Defines if the element should be highlighted after the move.


A: 2

12.2


Member

Description

Ref r eshAl l

Refreshes the Review displays.

Member

Description

Set Al l El ement Vi s i bi l i t y

Sets the visible state of all elements in the model

Ar gu men t

Type

vi si bi l i t y

Desc ri pt io n

Aveva.VPD.ReviewApi.VisibilityType

Member

Description

Set El ement Mat er i al

Sets material type for a list of elements

Ar gu men t

Typ e

The visibility type to set on all elements in the model.

Desc ri pt io n

el ement

ArrayList

An ArrayList of String objects containing the names of element to apply the material to

mat er i al

String

The name of the material to apply to the elements.

Member

Description

Set El ement Mat er i al

Sets material type for a single element

Ar gu men t

Type

Descri pt io n

el ement mat er i al

String

The name of element to apply the material to

String

The name of the material to apply to the element.

Member

Description

Set El ement Vi s i bi l i t y

Sets visibility type for a list of elements

Ar gu men t

Type

Desc ri pt io n

el ement

ArrayList

An ArrayList of String objects containing the names of element to apply the material to

vi si bi l i t y


The visibility type to apply to the elements.


A: 3

12.2


Member

Description

Set El ement Vi s i bi l i t y

Sets visibility type for a single element

Ar gu men t

Type

Desc ri pt io n

el ement

String

The name of element apply the material to

vi si bi l i t y


The visibility type to apply to the element.

to

Member

Description

Set Mat er i al I nf o

Sets information for a given material.

Ar gu men t

Type

Desc ri pt io n

mat er i al I nf o

String


MaterialInfo

A MaterialInfo containing the information on the material to be set.

Member

Description

Set Mat er i al Vi s i bi l i t y

Sets the visibility type for a given material.

Ar gu men t

Type

Desc ri pt io n

mat er i al

String


vi si bi l i t y


The visibility type to apply to the material.

Member

Description

Camer aManager

Gets the camera manager interface

Member

Description

El ement Manager

Gets the element manager interface

Member

Description

Mat er i al Manager

Gets the material manager interface

Member

Description

I nst ance

Gets Review interface instance


A: 4

12.2


Member

Description

User Event Manager

Gets the user event manager

Member

Description

Id

Gets the Review Instance 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

Memb ers

Member

Description

Start

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.

Ar gu men t

Type

r evi ew

Desc ri pt io n

Aveva.VPD.ReviewApi.IReview

The interface to Review to make calls to.

Member

Description

St op

This function will be called by Review to indicate that it must stop making calls to the Review Interface.

Member

Description

Addi nName [ get ]

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.

Member

Description

Cont r ol [ get ]

Returns the User Control that will be disp layed in the add-in window. This User Control will provide the main GUI for the add-in


A: 5

12.2


Member

Description

Descr i pt i on [ get ] A description of the add-in

Member

Description

Pr i or i t y [ get ]

Unused in this version of Review

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

Memb ers

Member

Description

Camer aType

Gets the CameraType for the camera.

Member

Description

Pos i t i on

Gets or sets an array of floats repres enting the position of the camera in the model

Member

Description

Cent r e

Gets or sets an array of floats representing the optical centre of the camera in the model

Member

Description

Bear i ng

Gets or sets a float representing the bearing of the camera

Member

Description

El evat i on

Gets or sets a float representing the elevation of the camera

Member

Description

Rol l

Gets or sets a float representing the roll of the camera


A: 6

12.2


Member

Description

FOV

Gets or sets a float representing the field of view of the camera

Member

Description

Set Posi t i onAndCent r e

Sets the position, optical centre and roll of the camera using the specified values

Ar gu men t

Type

Desc ri pt io n

pos i t i on cent r e r ol l

float[]

An array indicating the position of the camera

float[]

An array indicating the optical centre of this camera

float

A value indicating the roll of the camera

Member

Description

Pi ckedEl ement s

Gets or sets an array of elements picked on the camera

Member

Description

Pi ckedEl ement Names

Gets or sets an array of strings which represent the names of the elements picked on the camera

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

Memb ers

Member

Description

Camer aEvent s

Creates a CameraEvents object

Ar gu men t

Type

M

Descri pt io n

Aveva.VPD.ReviewApi.ICameraManager

Member

Description

Camer aChangedEvent

Occurs when a camera changes


A: 7

The Camera Manager object

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

Memb ers

Member

Description

Get Camer a

Retrieves an ICamera object for the specified camera

Ar gu men t

Type

Camer a

A.6

Desc ri pt io n

Aveva.VPD.ReviewApi.CameraType

The camera to be retrieved

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

Memb ers

Member

Description

Name

Gets the name of the element

Member

Description

Vi s i bi l i t yType

Gets or sets a VisibilityType enum representing the visibility type of the element

Member

Description

Mat er i al

Gets or sets an IMaterial object representing the material of the element.

Member

Description

Sel ect ed

Gets a Boolean value indicating whether the element is in the Active Selection.

Member

Description

AddToSel ect i on

Adds the element to the Active Selection.

Ar gu men t

Type

Desc ri pt io n

sender

object

The sender of the request.


A: 8

12.2


Member

Description

RemoveFr omSel ect i on

Removes the element from the Active Selection.

Ar gu men t

Typ e

Desc ri pt io n

sender

object

The sender of the request.

Member

Description

Chi l dr en

Gets an array of the child elements

Member

Description

LookAt

Looks at the element on the specified camera

Ar gu men t

Type

Desc ri pt io n

camer a l ookMet hod

Aveva.VPD.ReviewApi.ICamera

The camera to be moved.

Aveva.VPD.ReviewApi.LookType

The method by which the camera should be moved.

hi ghl i ght

bool

A value indicating whether the element should be highlighted after the move.

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

Memb ers

Member

Description

El ement Mat er i al ChangedEvent

Occurs when the material of an element changes.

Member

Description

El ement Vi si bi l i t yTypeChangedEvent

Occurs when the visibility type of an element changes.

Member

Description

El ement Sel ect i onChangedEvent

Occurs when the active selection changes


A: 9

12.2


Member

Description

El ement Event s

Creates an ElementEvents object

Ar gu men t

Type

M

A.8

Descri pt io n

Aveva.VPD.ReviewApi.IElementManager

The Element Manager object.

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

Memb ers

Member

Description

Get El ement

Retrieves an IElement object for the specified element after checking the element exists. Throws an ArgumentException if the element doesn't exist.

Ar gu men t

Type

Desc ri pt io n

name

string

The name of the element to be retrieved.

Member

Description

Get El ement

Retrieves an IElement object for the specified element. If checkExists is set and the element does not exists then an ArgumentException is thrown.

Ar gu men t

Type

Desc ri pt io n

name checkExi st s

string

The name of the element to be retrieved.

bool

Check if the element exists.

Member

Description

Root El ement

Gets the root element for the current model

Member

Description

Sel ect edEl ement s

Gets an array of the elements in th e Active Selection


A: 10

12.2


Member

Description

Set Sel ect edEl ement s

Sets an array of elements to the Active Selection.

Ar gu men t

Typ e

Desc ri pt io n

sender el ement s

object

The request sender.

IElement []

The elements to be set.

Member

Description

Set Sel ect edEl ement Namess

Sets an array of element names to the Active Selection.

Ar gu men t

Type

Desc ri pt io n

sender el ement s

object

The request sender.

string[]

The element names to be set.

Member

Description

El ement Exi st s

Retrieves a Boolean value indicating whether the specified element exists

Ar gu men t

Type

Desc ri pt io n

name

string

The name of the element to be evaluated.

Member

Description

Set Al l El ement sVi si bi l i t yType Sets the visibility type for all elements in the current model Ar gu men t

Type

vi s i bi l i t yType

Desc ri pt io n

Aveva.VPD.ReviewApi. VisibilityType

The visibility type to be applied.

Member

Description

Set Al l El ement sMat er i al

Sets the material for all elements in the current model

Ar gu men t

Type

mat er i al


Desc ri pt io n

Aveva.VPD.ReviewApi.IMaterial

A: 11

The material to be applied

12.2


Member

Description

Set El ement sVi si bi l i t yType Sets the visibility type for the specified elements Ar gu men t

Type

Desc ri pt io n

el ement s

Aveva.VPD.ReviewApi.IElement[]

The elements to be changed

vi s i bi l i t yType


The visibility type to be applied

Member

Description

Set El ement sMat er i al

Sets the material for the specified elements

Ar gu men t

Typ e

el ement s mat er i al

Desc ri pt io n

Aveva.VPD.ReviewApi.IElement[]

The elements to be changed.


The material to be applied.

Member

Description

Fr eezeMat er i al s

Freeze the current associations state between elements and materials. This provides the state to which ResetMaterials method will revert.

Member

Description

Reset Mat er i al s

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.

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

Memb ers

Member

Description

Name

Gets the name of the material

Member

Description

Get Mat er i al I nf o

Retrieves a MaterialInfo object for the material


A: 12

12.2


Member

Description

Set Mat er i al I nf o

Sets the MaterialInfo object for the material

Ar gu men t

Type

mat er i al I nf o

Desc ri pt io n

Aveva.VPD.ReviewApi.MaterialInfo

The required MaterialInfo object.

Member

Description

Col our

Gets or sets the colour of the material

Member

Description

Ambi ent

Gets or sets the ambient value of the material [0 .. 100]

Member

Description

Specul ar

Gets or sets the specular value of the material [0 .. 100]

Member

Description

Met al ness

Gets or sets the metalness value of the material [0 .. 100]

Member

Description

Smoot hness

Gets or sets the smoothness value of the material [0 .. 100]

Member

Description

Tr anspar ency

Gets or sets the transparency value of the material [0 .. 100]

Member

Description

Vi s i bi l i t yType

Gets or sets the visibility type of the material

Member

Description

Del et e

Deletes the material


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

Memb ers

Member

Description

Mat er i al ChangedEvent

Occurs when a material changes

Member

Description

Mat er i al Cr eat edEvent

Occurs when a material is created

Member

Description

Mat er i al Del et edEvent

Occurs when a material is deleted

Member

Description

Mat er i al Event s

Creates a MaterialEvents object

Ar gu men t

Type

m

A.11

Desc ri pt io n

Aveva.VPD.ReviewApi.IMaterialManager

The Material Manager object.

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

Memb ers

Member

Description

Cr eat eMat er i al

Creates a material

Ar gu men t

Typ e

Desc ri pt io n

Name mat er i al I nf o

string

The name of the material to be created.

MaterialInfo

A MaterialInfo object for the material.


A: 14

12.2


Member

Description

Del et eMat er i al

Deletes the specified material

Ar gu men t

Typ e

Description The material to be deleted.

mat er i al


Member

Description

Del et eMat er i al

Deletes the specified material

Ar gu men t

Type

Desc ri pt io n

name

string

The name of the material to be deleted.

Member

Description

Get Mat er i al

Retrieves the material of the specified name

Ar gu men t

Type

Desc ri pt io n

name

string

Retrieves the material of the specified name.

Member

Description

Al l Mat er i al s

Gets an array of all the materials in the current model

Member

Description

Mat er i al Exi st s

Retrieves a Boolean value indicating whether the specified material exists.

Ar gu men t

Typ e

Desc ri pt io n

name

string

The name of the material to be evaluated.

A.12

IAnimationManager Interface for managing animations.

A.12.1

Member

Memb ers

Description

Get Cur r ent Ani m Get copy of the animation that is currently set in Review. Return Value is an at i on Animation instance that contains a copy of the current animation data.


A: 15

12.2


Member

Description

Set Cur r ent Ani m Sets the current animation at i on Ar gu men t

Typ e

ani mat i on

Animation

Member

Description

Desc ri pt io n

An Animation instance that contains the animation data to set into Review.

Get Cur r ent Ani m Returns the max animation time of the current animation. at i onMaxTi me

Member

Description

Set Cur r ent Ani m Sets the time of the currently set animation in Review. Any cameras or groups at i onFr ame specified in the animation will be moved to the position along the animation paths specified by the time. Ar gu men t

Typ e

Desc ri pt io n

t i me

Single

The animation time. Must be less than the animation max time retrieved from GetCurrentAnimationMaxTime (see above)

enabl eCl ash

Boolean

Set to true if clash detection should be enabled in the view for the frame.

A.13

Animation Specifies an entire animation. Defines the actors such as observer, lights and groups and their respective trajectories.

A.13.1

Memb ers

Member

Description

Get HashCode

Calculate hashcode for the Animation.

Member

Description

Equal s

Compare two Animation.

A.14

IGroupManager Interface to the Group Manager.


A: 16

12.2


A.14.1

Memb ers

Member

Description

Cr eat eGr oup

Creates a Group. Returns an IGroup object for the specified Group

Ar gu men t

Typ e

Desc ri pt io n

name Gr oupI nf o

String

The name of the Group to be created

GroupInfo

A GroupInfo object for the Group

Member

Description

Cr eat eGr oup

Creates a Group. Returns an IGroup object for the specified Group

Ar gu men t

Typ e

Desc ri pt io n

Gr oupI nf o

GroupInfo

A GroupInfo object for the Group

Member

Description

Del et eGr oup

Deletes the specified Group.

Ar gu men t

Typ e

Desc ri pt io n

Gr oup

IGroup

The Group to be deleted

Member

Description

Del et eGr oup

Deletes the specified Group.

Ar gu men t

Typ e

Desc ri pt io n

name

String

The name of the Group to be deleted

Member

Description

Get Gr oup

Retrieves the Group of the specified name. Returns an IGroup object for the specified Group.

Ar gu men t

Typ e

Desc ri pt io n

name

String

The name of the Group to be retrieved.

Member

Description

Gr oupExi st s

Retrieves a value indicating whether the specified Group exists. Returns a value indicating that the specified Group exists or not.

Ar gu men t

Typ e

Desc ri pt io n

name

String

The name of the Group to be evaluated.


A: 17

12.2


A.15

ITrajectoryManager Interface for managing trajectories/animations paths.

A.15.1

Memb ers

Member

Description

Get Tr aj ect or y

Get copy of named trajectory data. Return Value is an instance that contains the trajectory data.

Ar gu men t

Typ e

Desc ri pt io n

name

String

The name of the trajectory whose data should be returned.

Member

Description

Cr eat eTr aj ect or y

Create an empty trajectory. Return Value is an instance that contains the newly-created trajectory data.

Ar gu men t

Typ e

Desc ri pt io n

name

String

The name of the new trajectory to create.

Member

Description

Del et eTr aj ect or y

Delete a named trajectory.

Ar gu men t

Typ e

Desc ri pt io n

name

String

The name of the new trajectory to delete.

Member

Description

SaveTr aj ect or y

Set trajectory.

Ar gu men t

Typ e

Desc ri pt io n

t r aj ect or y

Trajectory

An instance that should be set in Review.

A.16

ILightManager Provides interface to light manager.


A: 18

12.2


A.16.1

Memb ers

Member

Description

Get Li ght

Get light definition. Return Value is an instance containing data for the specified light.

Ar gu men t

Typ e

Desc ri pt io n

l i ght Number

Int32

The number of the light to return data for. Should be in the range 1 to 7.

Member

Description

Get Ambi ent Li ght

Get ambient light definition. Return Value is an instance containing data on the ambient light.

Member

Description

Set Li ght

Set light definition.

Ar gu men t

Type

Desc ri pt io n

l i ght

Light

An instance containing data on the light to set.

Member

Description

Set Ambi ent Li ght

Set ambient light definition.

Ar gu men t

Type

l i ght

A.17

Desc ri pt io n

AmbientLight

An instance containing data on the ambient light to set.

UserMessage Provides a class that enables passing of user defined objects to other subscribers of user events.

A.17.1

Memb ers

Member

Description

User Mess age

Create new user message to raise through the API

Ar gu men t

Type

Desc ri pt io n

Message

Object

User defined object or class to pass through the API


A: 19

12.2


Member

Description

Message

Retrieve user-defined message payload

Ar gu men t

Type

Desc ri pt io n

None

A.18

IUserEventManager Provides an interface to events r aised within Review containing user defined objects.

A.18.1

Memb ers

Member

Description

Rai seUser Event

Raises a new user event with a user defined payload

Ar gu men t

Type

mes sage

A.19

Desc ri pt io n

Aveva.VPD.ReviewApi.UserMessage

The message to raise

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

Memb ers

Member

Description

User Event s

Creates a UserEvents object

Ar gu men t

Type

M

Desc ri pt io n

Aveva.VPD.ReviewApi.IUserEventMan ager

The UserEventManager object.

Member

Description

User Event

Occurs a user event is raised.

A.20

Other ReviewAPI Classes

A.20.1

Mater ialIn fo 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

Description

Red

System.Int32

The red value of the colour of the material in the range 0-100

Gr een

System.Int32

The green value of the colour of the material in the range 0-100

Bl ue

System.Int32

The blue value of the colour of the material in the range 0-100

Ambi ent

System.Int32

The ambient reflectivity of the material in the range 0-100

Specul ar

System.Int32

The specular reflectivity of the material in the range 0-100

Met al ness

System.Int32

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.

Smoot hness

System.Int32

Defines how smooth the material is. This is defined in the range 0-100 with 0 being rough and 100 being smooth.

Tr anspar en cy

System.Int32

Defines how transparent the material is. This is defined in the range 0-100 with 0 being opaque and 100 being transparent.

A.20.2

Revi ewA ct iv eSelec ti on 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

Sel ect i onChang ed

Sets the selection and fires an event to all subscribers that the selection has changed.

Ar gu men t

Type

Desc ri pt io n

sender

System.Object

The object selection.

s el ect i on

System.Collections.ArrayList

An ArrayList of String objects containing the names of the selected elements.

Member

Description

Subscr i beFor Se l ect i onChanged Event

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.


A: 21

that

is

setting

the

12.2

Review 12.2 .NET Addin User Guide

Recommend Documents