eryar

AVEVA .Net 菜單自定義

AVEVA .Net Command and Menu Customisation

eryar@163.com

摘要Abstract：以一個具體實例詳細介紹AVEVA .Net中自定義菜單的原理及方法。掌握了自定義菜單的方法就可以對二次開發的程序進行分類和整理，便于用戶使用。

關鍵字Key words：AVEVA .Net、Addin Commands、Menu Customisation、PDMS、二次開發

一、概述 Introduction

通過《AVEVA .Net Quick Start Guide》這篇文章，大家對AVEVA .Net的二次開發有了個大概認識，但是這樣并不能編寫出實際有用的二次開發插件（Addin）。本文再深入一步，介紹自定義菜單方法，在菜單中調用二次開發的插件，便于用戶操作。

用戶通過菜單、右鍵菜單命令、工具條來調用開發的插件。通用程序框架CAF（The Common Application Framework）通過類CommandBarManager來提供了創建菜單、工具條等的接口。也提供了與這些工具交互事件的接口，這種方法CAF雖然支持但不推薦。

通用程序框架CAF還支持通過UIC（用戶界面自定義文件User Interface Customisation）文件來自定義菜單、工具條等，UIC文件是XML格式的。

基于XML定義的菜單及工具條需要有個機制將用戶界面實體與需要調用的相關功能關聯上。為了實現這人目的，插件（Addins）功能通過一些命令對象（command objects）暴露出來。插件通過類CommandManager來加載這些命令對象。XML定義中可以包含用戶界面實體如菜單入口、工具條的按鈕及與其相關的命令對象。選擇相應的菜單或點擊工具條上的按鈕都可以導致相關聯的命令被執行。

基于命令模型的一個好處就是將用戶界面或顯示層與邏輯層解耦。程序邏輯層就與顯示層沒有什么直接關系了。若程序的狀態需要對用戶界面上的操作做出反映，程序只需要修改命令的狀態即可。命令對象知道它與哪個用戶界面實體關聯，所以確保其內部狀態反映相應的用戶界面。這對一些狀態是很簡單的，如“enabled”、“visible、“checked”；但對動態程序狀態就有點復雜了，如“combo-box”。

二、編寫命令類 Writing a Command Class

如下所示的代碼是一個簡單的命令類示例，用來管理一個可停靠窗口的可見性，代碼中是控制AttributeBrowser 可停靠窗口。通用程序框架CAF提供了一個抽象的命令類Command，所有的命令類都必須派生自Command類。在其構造函數中應該設置屬性Key，在UIC文件中是通過Key這個屬性來找到相應的命令，后面將會以一個實例來說明。

  1using System; 
  2
  3using System.Collections.Generic; 
  4
  5using System.Text; 
  6
  7using Aveva.ApplicationFramework.Presentation; 
  8
  9namespace Aveva.Presentation.AttributeBrowserAddin 
 10
 11{ 
 12
 13/**//// <summary> 
 14
 15/// Class to manage the visibility state of the AttributeBrowser docked window 
 16
 17/// This command should be associated with a StateButtonTool. 
 18
 19/// </summary> 
 20
 21public class ShowAttributeBrowserCommand : Command 
 22
 23{ 
 24
 25private DockedWindow _window; 
 26
 27/**//// <summary> 
 28
 29/// Constructor for ShowAttributeBrowserCommand 
 30
 31/// </summary> 
 32
 33/// <param name="window">The docked window whose visibilty state will be managed.</param> 
 34
 35public ShowAttributeBrowserCommand(DockedWindow window) 
 36
 37{ 
 38
 39// Set the command key 
 40
 41this.Key = "Aveva.ShowAttributeBrowserCommand"; 
 42
 43// Save the docked window 
 44
 45            _window = window; 
 46
 47// Create an event handler for the window closed event 
 48
 49            _window.Closed += new EventHandler(_window_Closed); 
 50
 51// Create an event handler for the WindowLayoutLoaded event 
 52
 53            WindowManager.Instance.WindowLayoutLoaded += new EventHandler(Instance_WindowLayoutLoaded); 
 54
 55} 
 56
 57void Instance_WindowLayoutLoaded(object sender, EventArgs e) 
 58
 59{ 
 60
 61// Update the command state to match initial window visibility 
 62
 63this.Checked = _window.Visible; 
 64
 65} 
 66
 67void _window_Closed(object sender, EventArgs e) 
 68
 69{ 
 70
 71// Update the command state when the window is closed 
 72
 73this.Checked = false; 
 74
 75} 
 76
 77        /**//// <summary> 
 78
 79        /// Override the base class Execute method to show and hide the window 
 80
 81        /// </summary> 
 82
 83        public override void Execute() 
 84
 85        { 
 86
 87            if (this.Checked) 
 88
 89            { 
 90
 91                _window.Show(); 
 92
 93            } 
 94
 95            else 
 96
 97            { 
 98
 99                _window.Hide(); 
100
101            } 
102
103        } 
104
105    } 
106
107} 
108
109

抽象基類Command提供了以下方法，其派生類中可以重載：

l void Execute()：必須被重載，在執行命令時調用這個函數；

l CommandState GetState()：這個函數由通用程序框架CAF調用，以便更新用戶界面或上下文菜單。返回值是一個CommandState枚舉值，反應了命令的狀態。枚舉值用來位來表示命令狀態，這些狀態可以使用位的或OR操作。

l String Description：命令的描述；

l void Refrest(string context)：當CommandManager.ApplicationContext的屬性更改時都會調用這個方法。這也就給了一個更新其Enabled或visible狀態的機會。

抽象基類Command也有一些屬性可以用來更新用戶界面上的狀態：

l bool Checked：若命令與像StateButtonTool這樣的用戶界面關聯，則此屬性值與用戶界面上的狀態會同步；

l bool Enabled：此屬性值的改變將會影響所有與其關聯的用戶界面；

l ArrayList List：此屬性允許命令可以與有字符列表的用戶界面交流。如ComboBoxTool；

l int SelectedIndex：此屬性表示被用記選中的列表中的索引值；

l object Value：此屬性保存了當前關聯的用戶界面實體；

l bool ValueChanged：通用程序框架CAF在調用命令類的Execute方法之前，若用戶界面的值改變時會設置此屬性的值。當命令執行結束后此值會被清除；

l bool Visible：此屬性值的改變將會影響所有與其關聯的用戶界面；

在通用程序框架CAF中注冊一個命令是通過向CommanManagers.Commands的集合中添加一個命令實例來實現的。程序代碼如下所示：

三、命令事件 Command Events

命令基類Command提供了兩個事件BeforeCommandExecute和CommandExecuted給程序員，用來響應命令的執行，即在命令執行前后做些處理。示例代碼如下：

四、菜單自定義 Menu Customisation

用戶使用插件的方式通常都是通過使用菜單或命令欄上的按鈕。如前文所述，通用程序框架CAF提供了自定義菜單和命令欄的機制，即通過配置“User Interface Customisation”（UIC）文件。下面將會對UIC文件的細節進行描述，如怎樣配置通用程序框架CAF來加載UIC文件，通過用戶交互的自定義工具來編輯UIC文件等等。

五、配置要加載UIC文件的模塊 Configuring a Module to Load a UIC File

每個基于通用程序框架CAF的插件都有一個XML格式的配置文件，包含了程序啟動時需要加載的一系列UIC文件。此文件的默認路徑就是安裝目錄，文件名的命令方式為<模塊名>Customisation.xml。例如AVEVA Marine模塊Hull Design就有一個名為HullDesignCustomisation.xml的配置文件，文件內容如下所示。默認情況下UIC文件也希望在相同的目錄下。標專“$1”表示UIC文件的路徑將會由當前工程名代替。

配置文件中UIC文件的順序是很重要的，它表示了程序加載這些自定義界面的順序。一個新的UIC文件可以加載到一個模塊中，通過在其配置文件中簡單添加一行即可。

與在模塊的配置文件中添加UIC文件的功能類似的方法是在程序中編碼實現對UIC文件的添加，通過CommandBarManager的方法AddUICustomisationFile來編碼實現UIC文件的添加。程序代碼如下所示：

通過具體實例將會看出，通過自定義對話框，配置文件中的UIC文件將會被管理，不用自己手動更改UIC文件中的內容。

六、UIC文件的編輯 Editing UIC File

UIC文件是通過通用程序框架CAF的內置交互工具來創建與編輯的，不需要親自更其中內容。通過在工具欄上右鍵，選擇Customize來啟動自定義對話框，如下圖所示：

自定義對話框主要由七個部分組成：

①　CommandBar Preview Area

②　Active Customisation File

③　Tree showing CommandBars

④　List of tools

⑤　Property grid

⑥　Action buttons

⑦　Resource Editor

以下將會以具體實例來介紹相應的用法。更多細節請參考《AVEVA .NET Customisation User Guide》。通過自定義對話框，UIC文件中的內容將會被AVEVA管理，所以創建自定義的菜單或工具欄按鈕，都從這個自定義對話框中編輯，還是很方便。

七、程序實例 Codes

本節以一個具體實例來說明AVEVA .Net的菜單的自定義及與相關命令的關聯方法。步驟如下：

1. 創建一個C#的類庫（Class Library），工程名為HelloWorld，并選擇.NET Framework 3.5，如下圖所示：

2. 添加引用Aveva.ApplicationFramework.dll和 Aveva.ApplicationFramework.Presentation.dll，如下圖所示：

添加完后的引用庫如下圖所示：

3. 編寫一個插件類HelloAddin，派生自IAddin，并實現那四個虛函數，程序代碼如下所示：

 1 using System; 
 2 
 3 using System.Collections.Generic; 
 4 
 5 using System.Text; 
 6 
 7 using Aveva.ApplicationFramework; 
 8 
 9 using Aveva.ApplicationFramework.Presentation; 
10 
11 namespace HelloWorld 
12 
13 { 
14 
15 public class HelloAddin : IAddin 
16 
17 { 
18 
19 #region IAddin Members 
20 
21 public string Description 
22 
23 { 
24 
25             get 
26 
27 { 
28 
29 return "AVEVA .Net Menu Customisation Demo."; 
30 
31 } 
32 
33 } 
34 
35 public string Name 
36 
37 { 
38 
39             get 
40 
41 { 
42 
43 return "HelloAddin"; 
44 
45 } 
46 
47 } 
48 
49 public void Start(ServiceManager serviceManager) 
50 
51 { 
52 
53 // Stop for attaching to the process. 
54 
55             System.Windows.Forms.MessageBox.Show("Debug"); 
56 
57 } 
58 
59 public void Stop() 
60 
61 { 
62 
63 } 
64 
65 #endregion 
66 
67 } 
68 
69 } 
70 
71 

4. 添加一個用戶控件（User Control）而不是一個窗口（Windows Form），如下圖所示：

5. 自定義用戶控件上內容，本例僅在其上添加最簡單的label為例，添加后并將其內容改為“Hello World”，如下圖所示：

6. 添加命令類HelloWorldCommand，派生自抽象基類Command，并實現幾個關鍵的方法。如在其構造函數中添加Key屬性，Key屬性在后面添加菜單時很重要。還有必須實現的Execute方法。程序代碼如下所示：

7. 在派生自IAddin的類中的Start方法中添加創建可停靠窗口的代碼，并將命令添加通用程序框架的命令集合中去，程序如下所示：

 1 public void Start(ServiceManager serviceManager) 
 2 
 3 { 
 4 
 5 // Stop for attaching to the process. 
 6 
 7             System.Windows.Forms.MessageBox.Show("Debug"); 
 8 
 9 // Get the WindowManager service. 
10 
11             WindowManager windowManger = (WindowManager)serviceManager.GetService(typeof(WindowManager)); 
12 
13 // Create a docked window to host and Hello World User control. 
14 
15             DockedWindow myWindow = windowManger.CreateDockedWindow("Aveva.HelloAddin.UserControl", 
16 
17 "HelloWorld", 
18 
19 new HelloAddinControl(), 
20 
21                 DockedPosition.Right); 
22 
23 // Create and register Addin's command. 
24 
25             CommandManager commandManager = (CommandManager)serviceManager.GetService(typeof(CommandManager)); 
26 
27             HelloWorldCommand showCommand = new HelloWorldCommand(myWindow); 
28 
29             commandManager.Commands.Add(showCommand); 
30 
31 } 
32 
33 

8. 編譯工程（Build HelloWorld），并將生成的動態庫（HelloWorld.dll）復制到AVEVA的安裝目錄；

9. 修改配置文件，使其加載該插件，修改方法如下圖所示：

10. 添加自定義菜單，方便插件的調用。在工具欄的任意位置點擊鼠標右鍵，選擇Customize，出現自定義的對話框，并在Active Customization File 的選項框中選擇Module，如下圖所示：

在Menubar中添加自定義菜單項，將其名稱改為MenuTest，如下圖所示：

在對話框中間任意位置點鼠標右鍵，添加一個按鈕（button），如下圖所示：

修改按鈕的標題為ButtonTest，修改其命令（Command），在Core Command中選擇我們創建的命令類的Key，如下圖所示：

將按鈕拖到左邊的菜單下后，Apply結束。如下圖所示：

11. 自定義后的菜單如下圖所示：

八、結論 Conclusion

通過實例對AVEVA .Net的二次開發有了便全面的認識，可以通過自定義菜單方便調用二次開發的插件。自定義菜單或者工具欄按鈕主要是通過自定義對話框來實現，不需要程序員手動修改UIC文件，交互操作使用方便。

若有術語用詞不當之處，敬請指出。eryar@163.com

九、參考資料 Bibliography

1. AVEVA .Net Customisation User Guide 本文基本上是對這個Guide的部分翻譯。

2. GoF book: Design Patterns Elements of Reusable Object-Oriented Software 對Command模式感興趣的可以一讀。