目前
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) 显示,运行结果如下图所示 (也可以根据自己的喜好调整其他方位进行显示):