SuperMap iDesktop 桌面端扩展开发自定义浮动面板（DockPanel） - 调整浮动面板标签位置

  目前 SuperMap iDesktop 桌面端提供了非常强大的扩展插件功能，用户可以轻易的通过插件配置文件 （*.config） 进行自定义扩展插件在 SuperMap iDesktop 桌面端上布局、状态等调整。此教程主要说明如何在 SuperMap iDesktop 上扩展开发自定义浮动面板 （如：工作空间管理器 WorkspaceControlManager、图层管理器 LayersControlManager 等浮动面板）。

---

1. 准备工作

  1.1. SuperMap iDesktop：10i 以其以上版本 - 下载地址 SuperMap iDesktop 下载；
  1.2. Visual Studio：推荐使用 VS 2022 以其以上版本 （VS 2022版本支持 SuperMap iObjects .NET 64 位组件拖拽使用） - 下载地址 Visual Studio 下载；
  1.3. .NET Framework框架：建议使用 4x 版本，暂不支持 .NET Core、.NET 5、.NET 6等后续版本。

  以下示例操作均基于 SuperMap iDesktop 10.2.1 桌面端和 Visual Studio 2022 实现，若使用其他版本软件，建议参考操作流程，具体功能的布局位置可能存在差异，不建议完全照搬。

2. 环境配置

 2.1. 新建插件项目

  2.1.1. 新建基于**.NET Framework** 框架的类库项目。

  2.1.2. 选择类库框架版本 - .NET Framework 4x （如：此处选择的 .NET Framework 4.5.2）。

 2.2. 配置项目属性

  2.2.1. 新建 .NET Framework 类库项目成功后，鼠标右键点击项目》属性，打开项目的属性配置面板，在 应用程序 属性面板配置 程序集名称 和 默认命名空间 （如：程序集名称 - SuperMap.Desktop.Ext.CDockPanel、默认命名空间 - SuperMap.Desktop.Ext）。

  2.2.2. 切换到 生成 配置面板，调整以下 2 处配置：
    1). 设置 目标平台 为 x64；
    2). 将 输出路径 设置为 SuperMap iDesktop 安装目录的插件子目录中（如：D:\SuperMap\SuperMap iDesktop 10i\Bin\Plugins\CDockPanel）。

  2.2.3. 切换到 生成事件 配置面板，配置如下图所示的项目 生成后事件命令行。

  该命令用于项目编译时将插件的配置文件拷贝到 SuperMap iDesktop 安装目录下的工作环境子目录，以便 SuperMap iDesktop 运行时能够正确读取自定义插件的配置内容。

Xcopy "$(ProjectDir)$(TargetName).config" "D:\SuperMap\SuperMap iDesktop 10i\WorkEnvironment\Default" /y

  2.2.4. 切换到 调试 配置面板，指定 启动外部程序 路径为 SuperMap iDesktop 启动文件 （SuperMap Desktop.exe）。
    注意： 此处需要指定 SuperMap iDesktop.exe 文件路径（即 Bin 目录下的文件），而不是 Bin 目录的同级目录下的快捷方式！

 2.3. 添加项目引用

    对于 SuperMap iDesktop 桌面端扩展插件 “自定义浮动面板” 开发，必须要引入的动态链接库（DLL）共以下 2 类：
      1). SuperMap 组件包；
      2). DevExpress 组件包。
    如下图截图中，在该示例中使用的类分别在以下 5 个动态链接库（DLL）中：
      1). SuperMap.Desktop.Core.dll - SuperMap iDesktop 桌面端核心库；
      2). SuperMap.Desktop.UI.Controls.dll - SuperMap iDesktop 桌面端 UI 控件库；
      3). DevExpress.Xpf.Core.v17.1.dll；
      4). DevExpress.XtraBars.v17.1.dll；
      5). DevExpress.XtraEditors.v17.1.dll。

  此时有以下 2 点需要注意：
    1. 由于 SuperMap iDesktop 桌面端 UI 控件是基于 DevExpress 组件库扩展的，且此处自定义浮动面板组件也是基于 SuperMap iDesktop 组件，所以此处需要引入 DevExpress 组件库。
    2. 引入的 SuperMap iDesktop 和 DevExpress 的动态链接库，均可在 SuperMap iDesktop 安装目录的 Bin 子目录中找到。

3. 插件开发

 3.1. 新建用户控件

  3.1.1. 新建 用户控件（Windows 窗体） 文件（如下图：CDockPanel.cs）。

  3.1.2. 在新建的 用户控件（Windows 窗体） 文件中编码，建议参考以下流程：

  若只是自定义浮动面板，不需要调整浮动面板的标签显示位置，建议只考虑下述 步骤1，其他 步骤X 可以忽略。

    1). 修改 用户控件（CDockPanel） 继承的父类：UserControl -> UIUserControl；
    2). 至少引入 4 个命名空间：using DevExpress.XtraBars.Docking、using SuperMap.Desktop.UI、using System 以及 using System.Windows.Forms；
    3). 挂载 Application.ActiveApplication.MainForm 对象的 UILoaded 事件 （该事件在 SuperMap iDesktop 主界面加载完成后触发），在 UILoaded 事件中实现调整自定义浮动面板的标签显示位置 （目前DevExpress共支持 4 个方位：上（Top）、下（Bottom）、左（Left）、右（Right））；

using DevExpress.XtraBars.Docking;
using SuperMap.Desktop.UI;
using System;
using System.Windows.Forms;

namespace SuperMap.Desktop.Ext
{
    public partial class CDockPanel : UIUserControl
    {
        public CDockPanel()
        {
            InitializeComponent();
            Application.ActiveApplication.MainForm.UILoaded += MainForm_UILoaded;
        }

        private void MainForm_UILoaded(object sender, EventArgs e)
        {
            var dockBarManager = Application.ActiveApplication.MainForm.DockBarManager;
            var dockBar = dockBarManager[typeof(CDockPanel)];
            if (dockBar != null && (dockBar as Control) != null)
            {
                Control control = dockBar as Control;
                DockPanel dockPanel = control.Parent as DockPanel;
                if (dockPanel != null)
                {
                	// 调整浮动面板的标签显示位置
                    dockPanel.TabsPosition = TabsPosition.Top;
                    Application.ActiveApplication.MainForm.UILoaded -= MainForm_UILoaded;
                }
            }
        }
    }
}

 3.2. 新建配置文件

  3.2.1. 新建 应用程序配置文件 文件（如下图：SuperMap.Desktop.Ext.CDockPanel.config）。

  3.2.2. 由于上述步骤已经配置了项目的 生成后事件命令 用于拷贝新建的 应用程序配置文件 （如：SuperMap.Desktop.Ext.CDockPanel.config），所以不需要再将配置文件在编译时输出。

  3.2.3. 此处将新建的浮动面板和 SuperMap iDesktop 桌面端的 工作空间管理器 放在一起，将新建的 应用程序配置文件 内容修改为如下即可：

<?xml version="1.0" encoding="utf-8"?>
<plugin xmlns="http://www.supermap.com.cn/desktop"
		name="Frame"
		author="SuperMap"
		url="www.supermap.com.cn"
		description="Frame Plugin"
		helpLocalRoot="..\Help\WebHelp\"
		helpOnlineRoot="http://support.supermap.com.cn/onlinedoc/deskpronet/">
	<runtime assemblyName="./Plugins/Frame/SuperMap.Desktop.Frame.dll" className="SuperMap.Desktop._PluginFrame" loadOrder="1000" enabled="True" />
	<dockbar>
		<barGroup id="Left"
				  groupStyle="horizontal"
				  dockstate="Docked"
				  docksite="Left"
				  visible="true"
				  autoHide="false"
				  floatingLocation="0,0"
				  size="265,726"
				  customProperty="">
			<barGroup id="Left1"
					  groupStyle="vertical"
					  dockstate="Floating"
					  docksite="Left"
					  visible="true"
					  autoHide="false"
					  floatingLocation="0,0"
					  size="265,726"
					  customProperty="">
				<bar index="1"
					 label="自定义浮动窗口"
					 dockstate="Docked"
					 docksite="Left"
					 visible="true"
					 autoHide="false"
					 floatingLocation="0,200"
					 size="270,327"
					 control="SuperMap.Desktop.Ext.CDockPanel"
					 assemblyName="./Plugins/CDockPanel/SuperMap.Desktop.Ext.CDockPanel.dll"
					 helpURL=""
					 customProperty="" />
			</barGroup>
		</barGroup>
	</dockbar>
</plugin>

• <dockbar> - 浮动窗口组标签属性详解：
    可以确定目前 SuperMap iDesktop 桌面端并没有开放修改 浮动窗口 标签位置的控制属性，若需要调整浮动面板的标签显示位置，可参考上述 C# 实现代码，通过调整 浮动面板父级容器 (DockPanel) 的 TabsPosition 属性进行调整。

index：用于排序浮动窗口的 barGroup 组织，即当存在多个 barGroup 组织时，每个 barGroup 组织将通过该属性的值来确定其排列次序。
id：浮动窗口的 barGroup 组织支持多个不同配置文件里的项进行合并显示，合并的依据就是通过 id 来实现的，也就是说我们可以在 A 插件的配置文件中配置一个 barGroup 组织，指定一个 id，同时在 B 插件里面也配置一个 barGroup 组织，指定相同的 id，在系统显示时，这两个 barGroup 组织中的浮动窗口将会合并到一起组织和管理，即合并为一个 barGroup 组织。
dockstate：指定浮动窗口的 barGroup 组织的停靠模式，该属性的值有两种：docked 和 floating，docked 表示为停靠状态； floating 表示为浮动状态。
docksite：指定浮动窗口的 barGroup 组织停靠时的停靠位置，即相对于主窗口的位置，该属性的值有四种：left、right、bottom、top，分别表示相对于主窗口的左、右、底部、顶部位置。
visible：指定浮动窗口 barGroup 组织是否可见，该属性的值为 true 时，表示可见，false 为不可见。
floatingLocation：指定浮动窗口 barGroup 组织浮动时的位置，该属性的值的格式必须为：“x，y”，其中，x 表示水平坐标值，y 表示垂直坐标值。
size：指定浮动窗口 barGroup 组织区域的大小，该属性的值的格式必须为：“x，y”，其中，x 表示宽度，y 表示高度。
autoHide：指定浮动窗口 barGroup 组织是否自动隐藏，该属性只有在浮动窗口 barGroup 组织的停靠模式为 docked 时有效。该属性的值为 true 时，表示自动隐藏，为 false 时，为一直显示。
groupStyle：指定浮动窗口 barGroup 组织中的浮动窗口按照什么方式排列，该属性的值有三种：horizontal、vertical 和 tab，其中，horizontal 表示水平排列，vertical 表示垂直排列，tab 表示选项卡模式排列。
另外，<barGroup>…</barGroup> 标签可以嵌套，即浮动窗口 barGroup 组织里面还可以有浮动窗口 barGroup 组织。

• <bar> - 浮动窗口标签属性详解：

index：用于排序浮动窗口，即当存在多个浮动窗口时，每个浮动窗口将通过该属性的值来确定其排列次序。
label：浮动窗口的标题。
dockstate：指定浮动窗口的停靠模式，该属性的值有两种：docked 和 floating，docked 表示浮动窗口为停靠状态； floating 表示浮动窗口为浮动状态。
docksite：指定浮动窗口停靠时的停靠位置，即相对于主窗口的位置，该属性的值有四种：left、right、bottom、top，分别表示相对于主窗口的左、右、底部、顶部位置。
visible：指定浮动窗口是否可见，该属性的值为 true 时，表示可见，false 为不可见。
floatingLocation：指定浮动窗口浮动时的位置，该属性的值的格式必须为：“x，y”，其中，x 表示水平坐标值，y 表示垂直坐标值。
size：嵌入在浮动窗口中控件的大小，该属性的值的格式必须为：“x，y”，其中，x 表示控件的宽度，y 表示控件的高度。
control：嵌入在浮动窗口中的控件类的全名。
assemblyName：嵌入在浮动窗口中的控件类，即 control 属性所指定的类所在的程序集文件的名称，可以是相对于可执行程序的相对路径，也可以是绝对路径，该属性的值必须正确设置。
autoHide：指定浮动窗口是否自动隐藏，该属性只有在浮动窗口的停靠模式为 docked 时有效。该属性的值为 true 时，表示自动隐藏，为 false 时，为一直显示。

4. 插件构建

  4.1. 项目生成过程中会根据上述步骤配置的 生成后事件命令 将配置文件拷贝到 SuperMap iDesktop 安装目录\WorkEnvironment\Default 目录下，如下图所示：

 4.2. 项目构建成功后，会根据上述步骤配置的 输出路径 将插件包输出到 SuperMap iDesktop 安装目录\Bin\Plugins\CDockPanel 目录下，如下图所示：

5. 运行结果

  由于上述实现代码是将浮动窗口的标签位置设置为顶部 (Top) 显示，运行结果如下图所示 （也可以根据自己的喜好调整其他方位进行显示）：