eryar

AVEVA .Net 菜單自定義

AVEVA .Net Command and Menu Customisation

eryar@163.com

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

關(guān)鍵字Key words：AVEVA .Net、Addin Commands、Menu Customisation、PDMS、二次開發(fā)

一、概述 Introduction

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

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

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

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

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

二、編寫命令類 Writing a Command Class

如下所示的代碼是一個(gè)簡單的命令類示例，用來管理一個(gè)可?？看翱诘目梢娦裕a中是控制AttributeBrowser 可?？看翱凇Ｍㄓ贸绦蚩蚣蹸AF提供了一個(gè)抽象的命令類Command，所有的命令類都必須派生自Command類。在其構(gòu)造函數(shù)中應(yīng)該設(shè)置屬性Key，在UIC文件中是通過Key這個(gè)屬性來找到相應(yīng)的命令，后面將會(huì)以一個(gè)實(shí)例來說明。

  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()：必須被重載，在執(zhí)行命令時(shí)調(diào)用這個(gè)函數(shù)；

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

l String Description：命令的描述；

l void Refrest(string context)：當(dāng)CommandManager.ApplicationContext的屬性更改時(shí)都會(huì)調(diào)用這個(gè)方法。這也就給了一個(gè)更新其Enabled或visible狀態(tài)的機(jī)會(huì)。

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

l bool Checked：若命令與像StateButtonTool這樣的用戶界面關(guān)聯(lián)，則此屬性值與用戶界面上的狀態(tài)會(huì)同步；

l bool Enabled：此屬性值的改變將會(huì)影響所有與其關(guān)聯(lián)的用戶界面；

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

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

l object Value：此屬性保存了當(dāng)前關(guān)聯(lián)的用戶界面實(shí)體；

l bool ValueChanged：通用程序框架CAF在調(diào)用命令類的Execute方法之前，若用戶界面的值改變時(shí)會(huì)設(shè)置此屬性的值。當(dāng)命令執(zhí)行結(jié)束后此值會(huì)被清除；

l bool Visible：此屬性值的改變將會(huì)影響所有與其關(guān)聯(lián)的用戶界面；

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

三、命令事件 Command Events

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

四、菜單自定義 Menu Customisation

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

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

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

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

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

通過具體實(shí)例將會(huì)看出，通過自定義對話框，配置文件中的UIC文件將會(huì)被管理，不用自己手動(dòng)更改UIC文件中的內(nèi)容。

六、UIC文件的編輯 Editing UIC File

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

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

①　CommandBar Preview Area

②　Active Customisation File

③　Tree showing CommandBars

④　List of tools

⑤　Property grid

⑥　Action buttons

⑦　Resource Editor

以下將會(huì)以具體實(shí)例來介紹相應(yīng)的用法。更多細(xì)節(jié)請參考《AVEVA .NET Customisation User Guide》。通過自定義對話框，UIC文件中的內(nèi)容將會(huì)被AVEVA管理，所以創(chuàng)建自定義的菜單或工具欄按鈕，都從這個(gè)自定義對話框中編輯，還是很方便。

七、程序?qū)嵗?Codes

本節(jié)以一個(gè)具體實(shí)例來說明AVEVA .Net的菜單的自定義及與相關(guān)命令的關(guān)聯(lián)方法。步驟如下：

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

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

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

3. 編寫一個(gè)插件類HelloAddin，派生自IAddin，并實(shí)現(xiàn)那四個(gè)虛函數(shù)，程序代碼如下所示：

 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. 添加一個(gè)用戶控件（User Control）而不是一個(gè)窗口（Windows Form），如下圖所示：

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

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

7. 在派生自IAddin的類中的Start方法中添加創(chuàng)建可?？看翱诘拇a，并將命令添加通用程序框架的命令集合中去，程序如下所示：

 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），并將生成的動(dòng)態(tài)庫（HelloWorld.dll）復(fù)制到AVEVA的安裝目錄；

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

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

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

在對話框中間任意位置點(diǎn)鼠標(biāo)右鍵，添加一個(gè)按鈕（button），如下圖所示：

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

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

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

八、結(jié)論 Conclusion

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

若有術(shù)語用詞不當(dāng)之處，敬請指出。eryar@163.com

九、參考資料 Bibliography

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

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