静态事务“平铺按钮”控件的应用 - .Net 平台应用与技巧

# 概述
目前，OrBit平台已提供下拉值列表（ViewList/ViewListEx/ViewListPK）及窗体值列表（ViewListWindow/ViewListWindowPage）两种选项的选取方式。其中窗体值列表可以支持模糊匹配、复选、分页，但两者都存在一个小问题，那就是触摸屏用手指选取不方便，容易选错。针对这一点，现已开发出平铺按钮控件（ViewListButton）。根据后端返回的数据集，支持配置样式（按钮布局、大小、背景色、图标等）、复选数量（任意数量，1为单选）以及使能的灵活配置。根据选项的数据源，动态生成按钮。用户通过点击按钮进行选取，亦支持多页显示或只显示选定项。下面，就为大家阐述具体的应用与实现（系统配置、后端配置）。

**特性介绍**
1、主要对于工控或者平板等触屏终端，用手指去选取选项，很容易选错。以按钮的方式平铺展开，极大程度的方便用户选取相关选项；
2、现有的方式需要下拉或者弹窗之后，再去选取，而平铺按钮可以直接选取；
3、**动态按钮**：根据ViewListButton的数据源，动态绘制按钮并排列布局，点击之后调用相应的业务接口；
4、动态切换按钮的显示文本，如 上模 -->下模，上工 -->下工等切换；

**应用场景**
1、所有值列表选项；
2、程序功能入口界面设计（管理分支功能）

**PWTileButtonGroup.dll 文件**
[【附件】PWTileButtonGroup.rar](/media/attachment/2024/05/PWTileButtonGroup.rar)

# 应用实例展示
**1 安灯异常呼叫入口界面**
![](/media//202304/2023-04-07_094553.png)

**2 安灯异常呼叫界面**
![](/media//202304/2023-04-07_094239.png)

**3 异常处理入口界面**
![](/media//202304/2023-04-07_094335.png)

**4 作业计划**
![](/media//202304/2023-04-07_110702.png)

**其他**
![](/media//202304/2023-04-07_101514.png)
# 实现步骤
**1 服务器插件（PluginService）目录下，添加相关的dll文件： PWTileButtonGroup.dll。**

**2 平台系统参数中配置Always DowLoad参数，则每次登录Broswer时，会自动从PluginService目录下载文件到本地的Broswer安装目录。**
![](/media//202304/2023-04-07_095947.png)

**3. 静态事务 或 元对象 中添加引用（PWTileButtonGroup.dll）**
静态事务：
![](/media//202304/2023-04-07_100216.png)

元对象：
![](/media//202304/2023-04-07_100355.png)

**4. 平铺按钮参数配置**
静态事务：
![](/media//202304/2023-04-07_100740.png)

元对象：
![](/media//202304/2023-04-07_142240.png)

**5. 后端ViewListButton数据集配置，及相关sql脚本编写**
![](/media//202304/2023-04-07_101817.png)
```sql
create PROCEDURE [dbo].[Test_ViewListButton]
@I_PlugInCommand varchar(5)='',--插件命令
@I_OrBitUserId char(12)='',--用户ID
@I_OrBitUserName nvarchar(100)='',--用户名
@I_ResourceId char(12)='',--资源ID(如果资源不在资源清单中，那么它将是空的)
@I_ResourceName nvarchar(100)='',--资源名
@I_PKId char(12)='', --主键ID
@I_ParentPKId char(12)='', --父元对象主键ID
@QueryParameter nvarchar(100)= null
--以上个变量为系统服务固定接口参数，必须在每一个ViewListEx过程中实现.>
as
begin

SET NOCOUNT ON;
	SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED
	
	-- 按钮组整体配置
	select	 		
		1 AutoButtonSize, 
		5 RowInt, /* 行数 */
		4 ColInt, /* 列数 */
		1 MultipleSelectInt  /* 可选数量规则 0:可选任意项目 1:单选 >2:可选数量为指定的数量 */

-- 单个按钮项目配置集合
	select top 20
		t.PluginId AS ButtonName,
		t.PluginName AS ButtonText
	from
		SysPlugIn t
	order by
		t.PluginId

return 0
end
```
**6 对象脚本实例化窗体控件，及相关业务脚本编写**
**静态事务：**
![](http://121.37.203.18:8006/media//202202/AbnormalCalling4_1645856641.png)

脚本代码：
```csharp
private PWUserControl.PWTileButtonGroup btg_ExceptionType = null;// 平铺按钮(异常类型) 控件

/// <summary>
/// 脚本对象实例化时加载时的方法
/// </summary>
public void ScriptLoad()
{
	this.Debug("ScriptLoad()");
	this.btg_ExceptionType = new PWUserControl.PWTileButtonGroup(this.Scripter, "ExceptionType");
	this.btg_ExceptionType.GroupSelectChanged += Btg_ExceptionType_GroupSelectChanged;
}

private void Btg_ExceptionType_GroupSelectChanged(object sender, PWUserControl.GroupSelectChangedEventArgs e)
	{
		if (e.SeletedItems.Count == 1)
		{
			//this.Scripter.HideTab("AbnormalReporting", false);
			//this.Scripter.ActiveTab("AbnormalReporting");
			string jumpToTab;
			this.JumpToTab(this.Scripter, "GotoAbnormalReporting", out jumpToTab);
		}
	}

/// <summary>
	/// 脚本在退出前的询问方法
	/// </summary>
	/// <returns>True则退出，False则取消退出</returns>
	public bool ScriptClosing()
	{
		if (this.btg_ExceptionType != null) this.btg_ExceptionType.Dispose();
		//to do..
		return true;
	}

/// <summary>
	/// MES事务对象在关闭时卸载此脚本对象的方法
	/// </summary>
	public void ScriptUnLoad()
	{
		//to do..
		if (this.btg_ExceptionType != null) this.btg_ExceptionType.Dispose();
	}
```
**元对象：**
![](/media//202304/2023-04-07_143117.png)

脚本代码：
```csharp
        public OrBitScript.OrBitMetaAPI Scripter = new OrBitScript.OrBitMetaAPI();

private PWTileButtonGroup tbg_ExceptionTypeItemValue = null;
        /// <summary>
        /// 脚本对象实例化时加载时的方法
        /// </summary>
        public void ScriptLoad()
        {
            this.tbg_ExceptionTypeItemValue = new PWTileButtonGroup(this.Scripter, "ExceptionType Default Group.ExceptionTypeItemValue");
            this.tbg_ExceptionTypeItemValue.Enabled = false;  
        }

public void ScriptUnLoad()
        {
            //to do..
            if (this.tbg_ExceptionTypeItemValue != null) { this.tbg_ExceptionTypeItemValue.Dispose(); this.tbg_ExceptionTypeItemValue = null; }
        }

public void MainRowSelected(string CellA, string CellB, string CellC, string CellD)
        {
            if (this.Scripter.TreeViewGrid.Rows.Count == 0)
            {
                this.tbg_ExceptionTypeItemValue.ClearSelet();
            }
        }

public void EditEnter(int ModifyType, string PKId, string ParentPKId)
        {
            this.tbg_ExceptionTypeItemValue.Enabled = true;
            return;
        }

public void EditLeave(int ModifyType, string PKId, string ParentPKId)
        {
            this.tbg_ExceptionTypeItemValue.Enabled = false;
            return;
        }
```

# 控件使用详述
# 1 c#脚本使用控件API
下面介绍在c#脚本使用该控件时，可以使用那些属性、方法、事件。
# 1.1 控件属性

| 属性名 | 类型 | 说明 |
| --- | --- | --- |
| SelectedValues | string | 用来获取和设置平铺按钮选择是项目，其值是按钮项ButtonName值的逗号分隔形式 |
| QueryParameter | string | 获取构造控件是设置的查询参数 |

# 1.2 控件方法

| 方法名 | 返回类型 | 说明 |
| --- | --- | --- |
| Dispose | void | 释放资源  |
| ClearSelet | void | 清除所有选择 |
| BindData | void | 从数据源获取数据绑定 |

# 1.3 控件事件

| 事件名 | 类型 | 说明 | 事件数说明 |
| --- | --- | --- | --- |
| GroupSelectChanged | GroupSelectChangedEventHandler | 在平铺按钮选择项发生改变的时候触发的事件 | 参数中可以获取目前已选择按钮项的集合 |
| GroupClick | GroupClickEventHandler | 在点击按钮的时候触发的事件 | 参数中可以获取点击标注所属的按钮项信息 |
| GroupTagClick | GroupTagClickEventHandler | 在点击按钮中标注的时候触发的事件 | 参数中可以获取点击标注所属的按钮项信息 |

# 2 ViewListButton过程配置参数说明
ViewListButton存储过程需要返回两个查询语句
1：一个是返回单条记录，平铺按钮组整体参数配置
2：一个是返回每个按钮项的配置参数集合。
# 2.1 平铺按钮组整体参数配置

| 配置参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| ColInt | int | 3 | 列数 |
| RowInt | int | 3 | 行数 |
| MultipleSelectInt | int | 0 | 0:可选任意项目、1:单选、>2:可选数量为指定的数量 |
| BoundaryLineSize | int | 3 | 每个按钮之间的距离大小(单位:像素) |
| ButtonHeight | int | 60 | 按钮高度(单位:像素)(如果AutoButtonSize为true将被忽略) |
| ButtonWidth | int | 180 | 按钮宽度(单位:像素)(如果AutoButtonSize为true将被忽略) |
| AutoButtonSize | bool | true | 是否自动计算按钮高宽。true:忽略设置的按钮高宽,根据控件整体大小和行列数来计算按钮高宽,以布满整个控件而不出现滚动条、false:严格使用设置的按钮高宽值  |
| ButtonGroupMargin | int | 3 | 按钮集合相对于空间边框的距离大小(单位:像素) |
| GroupBorderSize | int | 0 | 整个大控件边框大小(单位:像素),如果想去掉空间边框设置为0即可 |
| FontFamilyName | string |  | 按钮文本字体 |
| TextMargin | string |  | 按钮文本的相对父容器的边距 值如"2,3,4,5" 则一次为上右下左的边距 |
| ClickTagCanSelect | bool | true | 当有标注的时候点击的是标注是否也选择或者取消选择按钮 |
| MultiPageIsScroll | bool| false | 当出现多页的时候是否使用滚动条方式显示(而不进行分页) |
| AvoidHorizontalScrollSubductionWidth | int | 17 | 当前不分页使用滚动垂直滚动显示的时候为了不出现水平滚动按钮显示区域消减的宽度(默认17) |
| ButtonBorderSize | int | 1 | 每个按钮的边框线厚度大小 |
| ButtonBorderColor | string | 'Silver' | 每个按钮的边框线颜色 |
| SelectedButtonBorderColor | string |  | 已选择按钮的边框线颜色 |
| EnableEnterStyle | bool | true | 是否使用鼠标经过样式 |
| MouseEnterBackColor | string |  | 鼠标经过时候的背景颜色 |
| MouseEnterForeColor | string |  | 鼠标经过时候的字体颜色 |
| MouseEnterButtonBorderColor | string |  | 鼠标经过时候的按钮的边框颜色 |
| IsUniformButtonBackColor | bool | false | 所有按钮是否统一背景颜色(设置为true时BackColor属性才有效果，如果设置为ture但BackColor为空则自动随机生成一个背景颜色) |
| BackColor | string |  | 当IsUniformButtonBackColor设置为true的嘶吼使用的按钮统一背景颜色 |
| BackColorDepth | int | 1 | 自动生成背景色的颜色深度 1-3 数字越大深度越深 |
| IsUniformButtonForeColor | bool | false | 所有按钮是否统一字体颜色(设置为true时ForeColor属性才有效果，如果设置为ture但ForeColor为空则字体颜色默认黑色) |
| ForeColor |  string |  | 当IsUniformButtonForeColor设置为true的是否使用的按钮统一字体颜色 |
| DiaplaySelected | bool | true | 是否显示选中后的样式状态 |
| SelectBlockDirection | Direction | Bottom | 选择标识块的方向 Top = 1,  Right = 2, Bottom = 3, Left = 4 |
| SelectBlockMargin | int | 0 | 选择标识块相对按钮的贴边边距 |
| SelectBlockBorderSize | int | 0 | 选择标识块的边框线厚度 |
| SelectBlockSize | int |  | 选择标识块的厚度大小(如果不设置默认为 按钮高度的1/6 或 宽度的1/12) |
| SelectBlockBorderColor | string | 'White' | 选择标识块的边框线颜色 |
| SelectBlockBackColor | string | 'Red' | 选择标识块的背景颜色 |
| SelectSytleType | int | 0 | 0:按钮内部底下出现红色 1:外围选择样式 用一个线条框框主按钮 |
| SelectedEncloseBorderColor | string | 'Yellow' | 用外围选择样式的时候才有用,外围线框的颜色 |
| SelectedEncloseBorderSize | int | 3 | 用外围选择样式的时候才有用,外围线框的宽度大小 |
| ButtonInnerOutSize | int | 2 | 用外围选择样式的时候才有用,按钮内边和选择外边之间的距离 |
# 2.2 单个按钮项参数配置

| 配置参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| ButtonName | string |  | 按钮项目标识名 |
| ButtonCode | string |  | 按钮项目标识码 |
| ButtonText | string |  | 按钮显示的文本内容 |
| ButtonIcon | string |  | 按钮代表图片 |
| BackColor | string |  | 按钮背景颜色 |
| ForeColor | string |  | 按钮背景颜色 |
| FontSize | float |  | 按钮文本字体大小(如果没有设置则自动调整大小适应按钮框大小) |
| FontStyle | FontStyle | Regular | 按钮字体样式 Regular = 0, Bold = 1, Italic = 2, Underline = 4, Strikeout = 8 |
| Enabled | bool | true | 按钮是否可以点击使用(使能状态) |
| TagFontStyle | FontStyle | Regular | 标注内容字体样式 Regular = 0, Bold = 1, Italic = 2, Underline = 4, Strikeout = 8 |
| TagFontSize | float |  | 标注内容字体大小(如果不设置,则默认字体高度为按钮高度的4分之一) |
| TagText | string |  | 标注文本内容 |
| TagBackColor | string |  | 标注内容背景颜色 |
| TagForeColor | string |  | 标注内容字体颜色 |
| TagLeft | int |  | 标注相对按钮左边的距离 |
| TagTop | int |  | 标注相对按钮顶部的距离 |
| TagRight | int |  | 标注相对按钮右边的距离 |
| TagBottom | int |  | 标注相对按钮底部的距离 |

# 版本迭代说明
目前只在异常管理模块中应用，后续可能会进一步优化迭代。