Structure/document

[toc]

第一章 概述

1.1 简介

​ DCiP是一个轻量级的软件开发工具，可在您的桌面上运行，适用于 Windows、macOS 和 Linux。可以快速开发跨平台的软件。

1.2 界面介绍

1.3 开发环境搭建

1. 下载并安装nodejs > Windows平台：Node.js (nodejs.org)官网上下载LTS版本安装包，比如：node-v14.18.1-x64.msi，双击开始安装。 > > 注意：安装过程中需要勾选下面这个选项 > > - [x] Automatically install the necessary tools. Note that will also install Chocolatey. The > > script will pop-up in a new window after the installation completes.
2. 安装YEOMAN工具： bash npm install -g yo
3. 安装NodeJS napi-addon工程配置工具： bash npm install -g generator-napi-module
4. 安装node-gyp: bash npm install -g node-gyp
5. 如果npm速度过慢，可以使用淘宝镜像： bash npm install -g cnpm --registry=https://registry.npmmirror.com 然后将2,3,4步骤中的三个命令中的 npm 修改为 cnpm 即可。
6. 首次启动前需要进行用户权限申请： bash npm run apply [username] 其中 [username] 替换为“单位缩写-姓名”，尽量不超过12个字，比如“大工汽车-张向奎”。之后等待审核通过即可。 如有问题可联系：zhangxk@dlut.edu.cn 13614112028
7. Windows平台：打开开始菜单，找到 “node.js command prompt” ，以管理员运行。cd 到安装目录，使用以下命令开启工具：

   npm run dev-win

第二章 Hello DCiP

2.1 创建我的第一个项目

1. 打开DCiP工具
2. 在界面左上角Unit输入框键入一个项目名称“lesson0”
3. 点击Unit输入框右侧的蓝色小加号“ + ”
4. 右键点击左侧项目树的根节点form，依次选择“Append a Top Constrain”（添加布局器） => "Horizontal Box"（横向布局器）
5. 右键点击根节点form下的hbox节点，依次选择“Append a Widget”（添加控件） => "Label"（标签）
6. 单击选中hbox节点下的label，在左下方的属性编辑区域找到 text 属性，将后面的值“label”改成“Hello DCiP”，回车确认
7. 单击上方的Execute按钮就可以看到刚刚做好的项目了

2.2 基础项目结构

​ 在第一个项目中，第二步我们输入了“lesson0”，代表着将这个Unit命名为“lesson0”，第三步点击加号后完成才创建了一个Unit，在这里可以理解为一个Unit就是一个项目工程，每个项目都要从Unit开始。当创建完一个Unit之后，工具自动生成了一个名为“mainfrm”的Form，可以理解为一个Form就是一个窗口，每个Unit都至少有一个Form，表示在左侧项目树上的根节点。第四步我们在这个窗口上添加了一个"Horizontal Box"，工具自动命名为hbox（这个名称仅仅用于区分元素的类型）并添加到树形结构中，这是一个横向的布局器，用来将内部控件横向展示。第五步我们在这个布局器当中添加了一个控件“Label”，工具自动命名为label并添加到树形结构中，用来显示一个固定的文本。最后再执行“Execute”按钮即可完成简单项目的创建了。

​ 项目代码保存在 comx_sdk.node/unit/lesson0 目录下，一般的，我们不需要对目录下的文件进行手动修改。并且对于工具自动生成的文件，请不要删改任何已存在的内容，包括注释。基础的项目结构如下：

lesson0
├── data
├── js
│  ├── _model.js
│  └── mainfrm_pane.js
├── js.ext
├── kul
│  ├── kul.entry.xml
│  └── mainfrm.kul
├── picture
├── src
├── _entry.js
└── _entry_preview.js

2.3 Form（窗口）

​ 每个窗口的根是都一个“form”，由工具自动创建，其中包含这个窗口的一些属性。

• title 窗口标题。显示在窗口栏左上角的文字。默认值：“Form”。

• titlebar 窗口栏是否显示。默认值：true。可能值：

  • true 显示窗口栏
  • false 不显示窗口栏

• icon 窗口图标。显示在窗口栏左上角的图标。默认值：“nil”。可以替换为本地图片文件夹（点击上方“View Icons”按钮所弹出的两个文件夹，其中 \comx_sdk.node\unit\lesson0\picture 的优先级高于 \comx_sdk.node\picture）中的图片。单击" ... "在弹出对话框中即可选择图片。

• bkcolor 窗口背景色。默认值：“gray”。有效值：“white”|“gray”|"darkGray"|"cyan"|"darkCyan"|"red"|"magenta"|"green"|"yellow"

• width 窗口宽度。默认值：auto。有效值：auto | 正数。

• height 窗口高度。默认值：auto。有效值：auto | 正数。

• center 窗口出现的位置。默认值：center。有效值：

  • none 出现在屏幕的中心。
  • center 出现在父窗口的中心。
  • mouse_center 出现在鼠标的附近，使鼠标在窗口的中心。

• resize 是否允许改变窗口大小。默认值：true。有效值：true | false。

• show 打开时的窗口大小。默认值：normal。有效值：

  • normal 正常大小，应用 width 和 height 属性。
  • maximize 打开时最大化。resize 为 false 时无此选择项。
  • minimize 打开时最小化。
  • hide 打开时不显示窗口。

• maximum_box 窗口栏是否显示最大化按钮。默认值：true。有效值：true | false。resize 为 false 时恒为false。

• minimum_box 窗口栏是否显示最小化按钮。默认值：true。有效值：true | false。

• close_box 窗口栏是否显示关闭按钮。默认值：true。有效值：true | false。

• style 窗口弹出模式。默认值：popup。有效值：

  • popup 单独弹出式的独立窗口。
  • child 依托父窗口弹出的子窗口。
    

• topmost 是否在最上层显示。默认值：true。有效值：true | false

• is_service 是否以服务的形式。默认值：false。有效值：

  • true 将程序最小化到托盘，不显示窗口。
  • false 普通的窗口程序。

• attachment 相对于父窗口的停靠模式。默认值：none。有效值：

  • none 不停靠于父窗口。
  • left_top 停靠于父窗口的内部左上角。
  • left_bottom 停靠于父窗口的内部左下角。
  • right_top 停靠于父窗口的内部右上角。
  • right_bottom 停靠于父窗口的内部右下角。

• attachment_size 相对于父窗口的停靠距离。默认值：5 。有效值：数字，可以为负值，比如：attachment（停靠模式）为 left_top ，attachment_size（停靠距离）为 -1 ，则子窗口在父窗口外部左侧并列表示。

• attach_dev 即时预览窗口相对于编辑器的停靠模式。默认值：right_bottom。有效值：

  • left_top 停靠于编辑器的内部左上角。
  • left_bottom 停靠于编辑器的内部左下角。
  • right_top 停靠于编辑器的内部右上角。
  • right_bottom 停靠于编辑器的内部右下角。

• attach_dev_size 即时预览窗口相对于编辑器的停靠距离。默认值：100 。有效值：数字，可以为负值，比如：attach_dev（停靠模式）为 left_top ，attach_dev_size（停靠距离）为 -1 ，则即时预览窗口在编辑器外部左侧并列表示。

• onHotKey 按下快捷键时触发的事件。需要搭配 ui.hot_key 先使用类似以下代码设置快捷键：

  ui.hot_key=[{key : "x", id : 1},{key : "Ctrl+m", id : 2}];

再设置 onHotKey 触发的方法为 OnHotKeyPush() ：

  function OnHotKeyPush(){
  	switch (ui.hot_key){
  		case 1: //键盘 x 按下时触发
  			//Do something
  		break;
  		case 2: //键盘 Ctrl 和 m 按下时触发
  			//Do something
  		break;
  	}
  }

• style 窗口类型。默认值：popup 。可能值：

  • popup 正常的窗口。
  • composite 组件类型窗口。上述的全部属性均无效隐藏（仅剩当前一个属性）。

2.4 Composite（组件）

​ 当子form的style属性为composite时，窗口则切换为组件。一般用于多个控件放在一起被多次复用的情况。

​ 一般的，名为 ”mainfrm“ 的主窗体不要设置为组件。在style属性为popup的正常窗口内可以嵌套组件，通过“添加控件”的最后一个选项“Composite（组件）”，下级菜单选择源组件。组件无法嵌套组件。被嵌入到其他form时，composite含有以下属性：

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• ref 来源。默认值：添加后自动赋值。有效值：unit 内的 style 属性为 composite 的form的名称。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：fixed 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸
• margin 组件内部的内填充，4个方向都相同。默认值：1 。有效值：大于等于0的数字
• visible 可见性。默认值：true 。也可以通过代码取值或赋值。有效值：
  • true 组件可见
  • false 组件不可见，并且不占用空间

​ 组件内部依旧可以使用形如 ui.myLabel.value 来进行取值和赋值，但是在父窗口中却不能这么使用。需要在组件的Callback文件中封装成可以属性接口以供父窗口引用。方法如下：

• CW_DeclareVariable(name, setter, getter) 定义一个外部可以访问内部的变量。其中：

  • name 变量名，有效值：字符串，需要在该组件内部唯一，与控件的 name 属性无关。

  • setter 变量赋值时触发的回调函数。

  • getter 变量赋值时触发的回调函数。

  例如在父窗口中引入一个组件，并且命名为 myComposite ，在该组件中插入一个 label 并命名为 myLabel ，则可以在该组件的 Callback 文件中插入如下代码：

  CW_DeclareVariable(
      'myValue', // name
      (val) => { //setter
          ui.myLabel.value = val;
      },
      () => { //getter
          return ui.myLabel.value;
      }
  );
  

  如上代码定义了一个名为 myValue 的变量，可以在父窗口中当作该组件的属性直接使用。在父窗口的Callback 文件中：

  • ui.myComposite.myValue = "OK" 将组件中的 label 赋值为：“OK”
  • var poo = ui.myComposite.myValue 取出组件的 label 的值并赋给 poo 变量。

• CW_DeclareOuterVariable(name) 定义一个内部可以访问外部的变量。其中：

  • name 变量名，有效值：字符串，需要在该组件内部唯一，与控件的 name 属性无关。

  例如在父窗口中引入一个组件，并且命名为 myComposite ，在父窗体中插入一个 label 并命名为 myLabel ，则可以在该组件的 Callback 文件中插入如下代码，用来定义该变量：

  CW_DeclareOuterVariable('myOutValue');
  

  同时，需要在 父窗口 的 Callback 文件中插入如下代码，用来设置该变量的赋值与取值时的操作：

  ui.myComposite.RegisterCallback(
      'myOutValue',
      (val) => {
          ui.myLabel.value = val;
      },
      () => {
          return ui.myLabel.value;
      }
  );
  

  如上代码定义了一个名为 myOutValue 的变量，可以在 组件 中通过 pui 调用。在组件的Callback 文件中：

  • pui.myOutValue = "OK" 将父窗口中的 label 赋值为：“OK”
  • var poo = ui.myOutValue 取出父窗口的 label 的值并赋给 poo 变量。

第三章 布局器

3.1 布局器的作用

​ 布局器是一种容器，可以使界面快速美观的自动化排版。每个窗口都必须有且只有一个根布局器。布局器内可以放入子布局器也可以放入其他各种控件。布局器和控件的关系就好比箱子和砖头，箱子可以嵌套箱子，箱子里也可以横着或者竖着放砖头，但是砖头里是不能放箱子的，布局器也是如此。

​ 所有的布局器都包含以下两个属性：

• margin 布局器内部默认的内填充，4个方向都相同。默认值：1 。有效值：大于等于0的数字
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：auto 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸

3.2 Horizontal Box（横向布局器）

​ 打开DCiP工具，创建一个名为“lesson1”的Unit，在form中添加一个布局器“Horizontal Box”，再在其中添加一个控件“Label”，这些我们在“lesson0”中已经做过了，但是由于当前布局器“hbox”中只有一个控件，所以是居中表示，接下来我们使用同样的方法再添加两个“Label”，分别修改“text”属性为“label1”，“label2”，“label3”。点击“Execute”，可以看到三个“label”横向均匀的显示在窗口中，即使改变窗口大小也不会打乱布局。

​ 横向布局器仅作为画面的布局器使用，不包含任何操作控件属性的方法。

3.3 Vertical Box（纵向布局器）

​ 打开DCiP工具，创建一个名为“lesson2”的Unit，在form中添加一个布局器“Vertical Box”，再在其中连续添加三个“Label”控件，分别修改“text”属性为“label1”，“label2”，“label3”。为了美观，我们可以将“Label”控件的“align”属性修改为“center”，“adjust”属性修改为“auto”。点击“Execute”，可以看到三个“label”纵向均匀的显示在窗口中了。

​ 纵向布局器仅作为画面的布局器使用，不包含任何操作控件属性的方法。

3.4 Tabctrl（标签布局器）

​ 打开DCiP工具，创建一个名为“lesson3”的Unit，在form中添加一个布局器“Tabctrl”，再在其中连续添加三个“Label”控件，分别修改“text”属性为“label1”，“label2”，“label3”。为了美观，我们可以将“Label”控件的“align”属性修改为“center”，“adjust”属性修改为“auto”。点击“Execute”，可以看到主窗口中嵌入了三个标签，切换标签就可以看到不同的内容了。

​ 标签布局器除了含有一般布局器的 margin 和 adjust 属性外，还包含以下属性：

3.4.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• position 标签所在位置。默认值：top 。有效值：
  • top 按钮标签在容器的上方
  • bottom 按钮标签在容器的下方
  • left 按钮标签在容器的左侧
  • right 按钮标签在容器的右侧
• gray 有效性。默认值：false 。有效值：
  • true 容器变灰无效，不可点击切换标签
  • false 容器有效
• visible 可见性。默认值：true 。有效值：
  • true 容器可见
  • false 容器不可见，并且不占用空间
• data 标签内容。默认值：“Page1,nil,Page2,nil,Page3,nil”。以“ , ”分割的字符串，以默认值为例：Page1 Page2 Page3 为标签的文字，可任意修改。nil 为标签的配图，将显示在文字的左侧，nil 的含义即为不显示，可以替换为本地图片文件夹（点击上方“View Icons”按钮所弹出的两个文件夹，其中 \comx_sdk.node\unit\lesson3\picture 的优先级高于 \comx_sdk.node\picture）中后缀名是 .bmp 的图片的名称（不带 .bmp ）。有效值格式：
  • “文字,图片,文字,图片,文字,图片,...”
  • "文字,文字,文字,..."
• width 容器宽度。默认值：100 。有效值：自然数。
• height 容器高度。默认值：100 。有效值：自然数。
• onSwitch 标签切换时所触发的函数名称。 默认值：空白。

3.4.2 ui命名空间下的命名对象

• index 当前显示的元素索引。默认值：0 。有效值：自然数。仅能通过代码进行取值和赋值。
• handle 容器的句柄。可以使用代码操作。

3.5 Stack（栈布局器）

​ 栈布局器是一个自上而下的具有层级的布局器，默认状态下只有第一个子元素可以被看到。它不能是窗口的根布局器，需要其他的布局器来嵌套它。

​ 打开DCiP工具，创建一个名为“lesson4”的Unit，在form中添加一个布局器“Horizontal Box”，再在其中添加一个“Stack”。这次我们在其中添加一个“Pushbutton”（按钮）控件，再添加一个“Label”（标签）控件，这样可以使“pushbutton”在“label”的上面，这样初始化的时候显示“button”，而不显示“label”，点击“Execute”，可以看到确实如此。

​ 现在想要显示“label”该怎么做呢？首先要给这个“Stack”命名，单击树状图中的“stack”，找到 “name“ 属性，修改为”myStack“，再点击”pushbutton“，修改 onClick 属性为 “onBtnClick()”，这样当我们点击这个按钮的时候就触发了 onBtnClick() 这个方法，然后我们在右面编辑器看到自动新增了一个名为 “onBtnClick “的空函数。我们将其修改成如下代码：

function onBtnClick(){
        ui.myStack.index = 1; 
}

​ 然后点击“Execute”按钮，窗口中依旧只有“button”一个按钮，左键点击“button”，就会触发“button”的 onClick 事件，接下来会执行 onBtnClick() 方法，使“myStack”显示第二个元素，即可看到“button”按钮变成了“label”的文字。后续的触发事件的写法均一致。

3.5.1 属性和事件

​ 栈布局器除了含有一般布局器的 margin 和 adjust 属性外，还包含以下属性：

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• border 边框。默认值：group 。有效值：
  • flat 无边框
  • group 有带标题的边框
• label 标题。默认值：“Group Box” 。有效值：空白 | 字符串。仅当 border 属性为 group 时生效。

3.5.2 ui命名空间下的命名对象

• index 当前显示的元素索引。默认值：0 。有效值：自然数。仅能通过代码进行取值和赋值。

第四章 控件

4.1 控件的作用

​ 控件是界面中具有实际功能的元素，可以用来展示字符，图片等，也可以用来接收用户的输入，或者选择。控件必须放置在布局器当中。所有的控件的添加方法一致，就不一一介绍了。

4.2 Bitmap（图片）

​ “Bitmap”控件用于显示一张图片。可以显示常见的后缀名的图片。包含：.jpg .bmp .png .tiff .gif 。

4.2.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• picture 图片名。默认值：“default.bmp”。点击上方“View Icons”按钮，将图片文件放到打开的文件夹中，然后将文件名填写在此处。其中以当前Unit名为 myUnit 的情况，打开的两个文件夹中， \comx_sdk.node\unit\myUnit\picture 的优先级高于 \comx_sdk.node\picture 。
• autoPlay 是否自动播放。默认值：false。有效值：
  • true 自动播放，当图片源是gif动画时有效
  • false 不自动播放
• width 图片宽度。默认值：50。有效值：正数。
• height 图片高度。默认值：50。有效值：正数。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：fixed 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸
• fit_origin_size 是否使用原图尺寸。默认值：false。有效值：
  • true 使用原图尺寸，width 和 height 属性失效。
  • false 不使用原图尺寸，使用 width 和 height 属性。
• transparent_background 是否使用透明背景。默认值：true。有效值：
  • true 使用透明背景，仅当图片背景是透明时有效。
  • false 透明的背景使用白色画布填充。
• border 图片边框。默认值：false。有效值：
  • true 图片添加边框
  • false 图片不加边框
• gray 有效性。默认值：false。有效值：
  • true 图片变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态
• visible 可见性。默认值：true。有效值：
  • true 可见
  • false 不可见，并且不占用空间
• onLButtonDown 当鼠标左键按下时触发的事件。
• onLButtonUp 当鼠标左键抬起时触发的事件。
• onMButtonDown 当鼠标中键按下时触发的事件。
• onMButtonUp 当鼠标中键抬起时触发的事件。
• onRButtonDown 当鼠标右键按下时触发的事件。
• onRButtonUp 当鼠标右键抬起时触发的事件。
• onMouseMove 当鼠标在图片上移动时触发的事件。
• onResize 当图片尺寸变化时触发的事件。

4.2.2 ui命名空间下的bitmap命名对象

• enable 图片是否有效。和 gray 属性相反。只能用代码进行取值或赋值。
• frame 当前播放进度。有效值：0 ~ 1 之间的数，包含0和1，只能用代码进行取值或赋值。
• handle 当前元素的操作句柄。
• play 播放gif动画。有效值：true | false 。只能使用代码赋值。
• value 可以使用图片的绝对路径进行赋值，如：“C:/xxx/a.png” 。只能写入，当初始化是gif文件时，不支持变更文件类型。

4.3 Checkbutton（多选按钮）

​ “Checkbutton”控件一般用于记录用户的选择，在同一个页面当中可以选择多个。

4.3.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• label 标签名。默认值：“Check”。有效值：空白 | 字符串，显示在选择方框的右面的文本。
• width 按钮宽度。默认值：39。有效值：正数。
• height 按钮高度。默认值：10。有效值：正数。
• auto 是否使用自动大小。默认值：true。有效值：
  • true 大小匹配刚好包含方框和标签，width 和 height 属性失效。
  • false 大小使用 width 和 height 属性。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：fixed 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸
• check 是否选中。默认值：false。有效值：
  • true 初始化默认选中
  • false 初始化默认不选中
• gray 有效性。默认值：false。有效值：
  • true 控件变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态
• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：
  • true 可见
  • false 不可见，并且不占用空间
• onClick 当项目被选中或者取消选中时触发的事件。

4.3.2 ui命名空间下的checkbutton命名对象

• enable 图片是否有效。和 gray 属性相反。只能用代码进行取值或赋值。
• valid 是否选中，初始化的值与 check 相同，只能用代码进行取值或赋值。
• handle 当前元素的操作句柄。
• value 显示的标签名，初始化的值与 label 相同。只能用代码进行取值或赋值。
• tip 鼠标悬浮时的提示文字。可以通过代码进行赋值，支持html语法。有效值：空白 | 字符串。

4.4 Combobox（下拉列表）

​ “Combobox”控件用于用户的多选一情况，还可以选择是否允许用户自定义值。

4.4.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• data 数据。默认值：“item1, item2, item3”。有效值：以“ , ”分割的字符串。代表各个选项的值。
• width 下拉列表的宽度。默认值：64 。有效值：正数。
• height 下拉列表的高度。默认值：10 。有效值：正数。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：fixed 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸

• type 下拉列表类型。默认值：down。有效值：

  • down 可以输入的下拉列表。
  • list 不可以输入的下拉列表。

• sort 是否对数据进行自动排序。默认值：false。有效值：true | false

• gray 有效性。默认值：false。有效值：

  • true 控件变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态

• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：

  • true 可见
  • false 不可见，并且不占用空间

• onChange 当 type 属性为 down 时生效。输入框内容变化时触发的事件。不要在这个事件中修改 value 的值，可能引发无限调用。

• onIndexChange 当选择项目变化时触发。

• onAccept 回车确认时触发的事件。

4.4.2 ui命名空间下的combobox命名对象

• enable 控件是否有效。和 gray 属性相反。只能用代码进行取值或赋值。

• handle 当前元素的操作句柄。

• index 当前显示的元素索引。默认值：0 。有效值：自然数。仅能通过代码进行取值和赋值。

• list 当前控件的全部数据列表。可以通过代码进行取值和赋值。如下以数组的形式进行赋值：

  ui.myCombobox.list=["item1","item2","item3"];

• value 当前显示的元素的值。仅能通过代码进行取值和赋值。

4.5 Edit（输入框）

​ “Edit”控件用于获取用户的输入值。

4.5.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• data 显示值。默认值：空白。有效值：任意输入值。
• width 输入框的宽度。默认值：40。有效值：正数。
• height 输入框的高度。默认值：12。有效值：正数。

• adjust 相对于父元素大小变化时的自动化调整模式。默认值：fixed 。有效值：

  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸

• align 输入值得对齐方式。默认值：left。有效值：

  • left 字符居左显示。
  • center 字符居中显示。
  • right 字符居右显示。

• valid_check 输入值合法检查。默认值：false。有效值：true | false 。当 multiline 为 true 时该属性无效。

• valid_okay 输入值合法检查正则表达式。默认值：“ .* ”。仅当 valid_check 为 true 时生效。检查通过的话文本表示绿色。

• valid_warning 输入值警告检查正则表达式。默认值：“ .* ”。仅当 valid_check 为 true 并且 valid_okay 的检测不通过时生效。检查通过的话文本表示黄色，不通过的话文本表示为红色。

• multiline 是否允许多行输入。默认值：false。有效值：true | false

• password 是否表示为密码输入框。默认值：false。有效值：

  • true 输入全部显示为“ · ”，并且不可复制出来。
  • false 正常的输入框。

• readonly 输入框是否是只读的。默认值：false。有效值：true | false

• wrap 是否自动折行。仅当 multiline 为 true 时生效。默认值：true。有效值：true | false

• gray 有效性。默认值：false。有效值：

  • true 控件变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态

• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：

  • true 可见
  • false 不可见，并且不占用空间

• onChange 输入框内容变化时触发的事件。不要在这个事件中修改输入框的内容 value，否则可能引发无限调用。

• onAccept 回车确认时触发的事件。

4.5.2 ui命名空间下的edit命名对象

• enable 控件是否有效。和 gray 属性相反。只能用代码进行取值或赋值。
• handle 当前元素的操作句柄。
• valid 当前元素是否通过正则检查。只能通过代码获取。
• value 当前输入框的内容。默认值与 data 属性一致。只能用代码进行取值或赋值。
• tip 鼠标悬浮时的提示文字。可以通过代码进行赋值，支持html语法。有效值：空白 | 字符串。

4.6 Glcanvas（GL画布）

​ “Glcanvas”控件是使用OpenGL引擎展示的3D立体模型的控件。

4.6.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• data 显示值。默认值：空白。有效值：任意输入值。
• width 画布的宽度。默认值：180。有效值：正数。
• height 画布的高度。默认值：180。有效值：正数。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：auto 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸
• border 控件是否含有边框。默认值：true。有效值：true | false
• gray 有效性。默认值：false。有效值：
  • true 控件变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态

• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：

  • true 可见
  • false 不可见，并且不占用空间

• onPickup 选取模式下，选中记录发生改变时触发的事件

• onContentMenu 右键菜单内容按下时触发的事件。

• onLButtonDown 鼠标左键按下时触发的事件。

• onLButtonUp 鼠标左键抬起时触发的事件。

• onMButtonDown 鼠标中键按下时触发的事件。

• onMButtonUp 鼠标中键抬起时触发的事件。

• onRButtonDown 鼠标右键按下时触发的事件。

• onRButtonUp 鼠标右键抬起时触发的事件。

• onMouseMove 鼠标在画布上移动时触发的事件。

• onResize 画布大小变化时触发的事件。

4.6.2 ui命名空间下的glcanvas对象：

IDE界面树添加glcanvas控件→选中该控件→设置name属性(property)的值(value)”canvas” →在DCiP预定义的ui命名空间内产生对象“ui.canvas”→该对象描述如下表所示：

4.7 Label（标签）

​ “Label”控件一般用来展示界面上的提示文字，可通过ui命名对象的value属性成员动态改变，从而实现软件状态信息提示。

4.7.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• text 文字。默认值：“label”。有效值：任意字符。
• width 标签的宽度。默认值：19。有效值：正数。
• height 标签的高度。默认值：8。有效值：正数。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：auto 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸
• auto_width 是否自动宽度。默认值：true。有效值：
  • true 控件的大小自适应文字的大小。width 和 height 属性失效。
  • false 控件的大小使用 width 和 height 属性。
• align 文字对齐。默认值：left。有效值：
  • left 文字居左对齐
  • center 文字居中对齐
  • right 文字居右对齐
• gray 有效性。默认值：false。有效值：
  • true 控件变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态

4.7.2 ui命名空间下的label命名对象

• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：
  • true 可见
  • false 不可见，并且不占用空间
• value 当前控件的文字内容。默认值与 text 属性一致。只能用代码进行取值或赋值。
• handle 当前元素的操作句柄。
• tip 鼠标悬浮时的提示文字。可以通过代码进行赋值，支持html语法。有效值：空白 | 字符串。

4.8 Listbox（列表）

​ “Listbox”控件用于展示所有选项并且可以选择，和“Combobox”类似，但是可以添加图片。

4.8.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• data 数据。默认值：“item1, item2, item3”。有效值：以“ , ”分割的字符串，代表着数据数组。
• width 下拉列表的宽度。默认值：50。有效值：正数。
• height 下拉列表的高度。默认值：50。有效值：正数。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：auto 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸
• type 列表类型。默认值：list 。 有效值：
  • list 仅表示文字的列表
  • icon 附带图标和文字的列表
• icon_size 图标大小，宽高一致。默认值：54。仅当 type 为 icon 时有效。有效值：正数。
• icon_hint 图标列表元素的间隔大小。默认值：30。仅当 type 为 icon 时有效。有效值：正数。
• icon_flow 图标列表的排列方式。默认值：horizontal。仅当 type 为 icon 时有效。有效值：
  • horizontal 横向展示图标列表
  • vertical 纵向展示图标列表
• icon_wrap 图标元素是否自动换行。默认值：true。仅当 type 为 icon 时有效。有效值：
  • true 根据 icon_flow 属性而变化。icon_flow 为 horizontal 时每行根据宽度可以显示多个元素。icon_flow 为 vertical 时每列根据高度可以显示多个元素。
  • false 每行或每列仅显示一个元素
• image_list 图标元素文件名。默认值：“development1,package1”。有效值：以“ , ”分割的字符串，代表着图片文件名数组。
• gray 有效性。默认值：false。有效值：
  • true 控件变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态
• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：
  • true 可见
  • false 不可见，并且不占用空间
• onChange 当选择的列表项目变化时触发的事件。
• onRightClick 当右键点击列表项目时触发的事件。
• onDoubleClick 当双击列表项目时触发的事件。
• onContentMenu 当右键菜单的项目被点击时触发的事件。选中了哪个项目通过 content_menu 和设置的 id 取得。

4.8.2 ui命名空间下的listbox命名对象

• content_menu 右键菜单的项目设置。代码取值时为被点击的项目的id。代码赋值时视为设置弹出菜单，有效值为菜单元素的数组，其中每个菜单元素是一个json对象，包含以下属性：

  • name 显示的名称，有效值：字符串。特殊的，当值为“-”并且未设置其他属性时，识别为分割线。

  • icon 显示的图标，有效值：字符串

  • id 当前菜单中的唯一ID，有效值：数字

  • children 子项目菜单，仅在根菜单下有效（仅支持2级菜单）。有效值：菜单元素的数组。

  当设置 content_menu 的时候，弹出菜单就会展示出来。

• enable 控件是否有效。和 gray 属性相反。只能用代码进行取值或赋值。

• handle 当前元素的操作句柄。

• list 元素文字的数组。可以通过代码取值或赋值。

• ii_list 元素图标的数组。仅当 type 为 icon 时有效。可以使用代码取值或赋值。类型为数组，个数需要和 list 的个数一致。每个元素的值是 image_list 的索引。例如：list为“item1, item2, item3” ，image_list 为“development1,package1”，list 的数量是3个，ii_list 就需要有3个元素。image_list有2个元素，ii_list 的元素取值就是0或1 。所以ii_list 可以是[0,0,0]或[0,0,1]或[0,1,0]或[1,1,0]等等.

• index 当前选中项目的元素索引

• value 当前选中项目的文字值

4.9 List（表格）

​ “List”控件用于显示表格类型的数据，单元格可以表示为输入框或者下拉列表。

​ 如果需要在表格元素事件中修改整个表格的数据，需要使用parent.setTimeout()进行包裹，不然会引发严重问题。

4.9.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• width 表格的宽度。默认值：100。有效值：正数。
• height 表格的高度。默认值：100。有效值：正数。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：auto 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸

• rows 行的数目。默认值：auto。有效值：

  • auto 显示全部数据
  • 正数 显示全部数据，如果大于数据的行数，则显示空行

• grid 是否显示栅格分割单元格。默认值：false。有效值：true | false

• behavior 单击时的选中模式。默认值：cell。有效值：

  • cell 单击时仅选中相应单元格
  • row 单击时选中整行
  • column 单击时选中整列

• mode 选中模式。默认值：single。有效值：

  • single 仅能选中一次，点击下一个目标时取消之前的选中
  • multi 可以多选，再次点击已选中目标时取消选中该目标。点击表头可选择整列，点击前面序号可以选择整行。

• sort 是否开启排序功能。默认值：none。有效值：

  • none 不排序，onHeaderClick事件不会触发
  • ascending 点击表头进行升序排序
  • descending 点击表头进行降序排序

• gray 有效性。默认值：false。有效值：

  • true 控件变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态

• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：

  • true 可见
  • false 不可见，并且不占用空间

• onClick 鼠标左键单击时触发的事件。

• onRightClick 鼠标右键单击时触发的事件

• onDoubleClick 鼠标左键双击时触发的事件。

• onHeaderClick 点击表头的时候触发的事件。

• onChange 表元素变化时触发的事件。

• onContentMenu 点击右键菜单项目时触发的事件。

4.9.2 ui命名空间下的list命名对象

• row 刚刚被点击的行的索引。默认值：0 。可以通过代码取值或赋值。但是值会被其他属性影响：

  • behavior 的值为 column 时，row 的值恒为 undefined 。

• column 刚刚被点击的列的索引。默认值：0 。可以通过代码取值或赋值。但是值会被其他属性影响：

  • behavior 的值为 row 时，column 的值恒为 undefined 。

• value 刚刚被点击的元素的值。默认值：第1行第1列的值。可以通过代码取值或赋值。但是值会被其他属性影响：

  • behavior 的值为 row 或 column 时，value 的值恒为 undefined 。

• list 刚刚被点击的行或列的数组。默认值：第1行或第1列的值。可以通过代码取值或赋值。但是值会被其他属性影响：

  • behavior 的值为 row 时，list 的值为刚刚被点击的行的数组。

  • behavior 的值为 column 时，list 的值为刚刚被点击的列的数组。

  • behavior 的值为 cell 时，list 的值恒为 undefined 。

• records 所有被选中项目元素。仅能通过代码取值。值受其他元素影响：

  • mode 的值为 single 时，records 的值恒为 undefined 。
  • mode 的值为 multi ，并且 behavior 的值为 row 时，records 的值为选中的行的索引数组。如[0,1]
  • mode 的值为 multi ，并且 behavior 的值为 column 时，records 的值为选中的列的索引数组。如[0,1]
  • mode 的值为 multi ，并且 behavior 的值为 cell 时，records 的值为选中的元素的数组。其中每个元素有两个属性：
  • row 该元素的行的索引。如：第一个元素的行索引通过 ui.myList.records[0].row 取得。
  • column 该元素的列的索引。如：第二个元素的列索引通过 ui.myList.records[1].column 取得。
  • 选中元素的个数可以通过 ui.myList.records.length 取得。

• content_menu 右键菜单的项目设置。代码取值时为被点击的项目的id。代码赋值时视为设置弹出菜单，有效值为菜单元素的数组，其中每个菜单元素包含以下属性：

  • name 显示的名称，有效值：字符串。特殊的，当值为“-”并且未设置其他属性时，识别为分割线。
  • icon 显示的图标，有效值：字符串
  • id 当前菜单中的唯一ID，有效值：数字
  • children 子项目菜单，仅在根菜单下有效（仅支持2级菜单）。有效值：菜单元素的数组。

• enable 控件是否有效。和 gray 属性相反。只能用代码进行取值或赋值。

• filter 对单元格格式化为下拉列表。可以用代码赋值。有效值为一个3个元素的数组[x,y,z]，前两个元素x,y代表坐标（从0开始）：x行y列。第三个元素z是一个数组，代表下拉列表的选项，当选项类型不是基本类型时，自动调用其toString()方法进行显示。例如：

  ui.myList.filter=[0,1,[true,2,"OK"]];

将替换第1行第2列的元素为下拉列表，其中的选项为 “true，1，OK” 这三个选项。

对多个单元格进行格式化替换时，多次赋值即可。

• color 对单元格设置背景色。只能用代码赋值。有效值为一个3个元素的数组[x,y,z]，前两个元素x,y代表坐标（从0开始）：x行y列。第三个元素z是一个代表颜色的字符串，由“#”拼接RGB（红绿蓝）的16进制取值，取值从“#000000”到“#ffffff”，不区分大小写。默认值：auto，例如：

  ui.myList.color=[0,1,"#FF0000"];

将替换第1行第2列的元素背景色设置为红色。

对多个单元格进行设置背景色时，多次赋值即可。

• readOnly 对单元格设置为只读。只能用代码赋值。有效值为一个3个元素的数组[x,y,z]，前两个元素x,y代表坐标（从0开始）：x行y列。第三个元素z是一个boolean值，代表是否只读，有效值：true | false。例如：

  ui.myList.readOnly=[0,1,true];

将替换第1行第2列的元素设置为只读。

对多个单元格设置只读时，多次赋值即可。

• handle 当前元素的操作句柄。

• head_size 表头宽度。默认值：0 。有效值：

  • -1 列的宽度与列头的文字宽度一致
  • 0 自动调整列宽，存在多个0的时候等分
  • 正数 列宽设置为该宽度

• table 元素列表。默认值：[["Title-1","Title-2"],[1,2],[3,4]] 。有效值是一个数组。第一个元素为表头的数组，元素个数确定了列的个数。从第2个元素开始为每行的数据，也是数组，每行元素个数多于列数时不显示，少于列数时为空白。

• tip 鼠标悬浮时的提示文字。可以通过代码进行赋值，支持html语法。有效值：空白 | 字符串。

4.10 Horizontal Progressbar（横向进度条）

​ “Horizontal Progressbar”控件用于展示一个横向的进度条，并可以自定义最大值和最小值。

4.10.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• data 初始化数据。默认值：0,100,0 。有效值：以“ , ”分割的字符串，第一个是最小值，第二个是最大值，第三个是当前值。
• width 进度条的宽度。默认值：80。有效值：正数。
• height 进度条的高度。默认值：10。有效值：正数。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：auto 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸
• gray 有效性。默认值：false。有效值：
  • true 控件变灰，表示无效
  • false 正常状态

4.10.2 ui命名空间下的hprogbar命名对象

• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：
  • true 可见
  • false 不可见，并且不占用空间
• range 进度条的范围。可以通过代码取值或赋值。有两个属性：
  • low 进度条的最小值。默认值：0 。有效值为大于等于0的数。
  • high 进度条的最大值。默认值：100 。有效值为大于最小值的数。
• value 进度条的值。默认值：0 。有效值：大于等于 range .low （最小值）并且小于等于 range .high（最大值）
• enable 控件是否有效。和 gray 属性相反。只能用代码进行取值或赋值。
• handle 当前元素的操作句柄。

4.11 Vertical Progressbar（纵向进度条）

​ “Vertical Progressbar”控件用于展示一个纵向的进度条，属性和默认值与“Horizontal Progressbar”（横向进度条）完全一致。不做更多介绍。

4.12 Pushbutton（按钮）

​ “Pushbutton”控件用于展示一个按钮。可以设置为点击按钮，菜单按钮或者状态按钮。

4.12.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• label 展示在按钮上的文字。默认值：“button”。有效值：字符串。
• tip 鼠标悬浮时的提示文字。也可以通过代码进行赋值，支持html语法。默认值：空白。有效值：空白 | 字符串。
• bitmap 展示在按钮文字旁边的图片。默认值：“nil”。有效值：图片文件夹下的bmp图片名（不带后缀名.bmp）

• bitmap_align 展示图片显示的位置。默认值：left 。有效值：

  • left 图片显示在文字的左侧
  • right 图片显示在文字的右侧
  • top 图片显示在文字的上侧
  • bottom 图片显示在文字的下侧

• width 按钮的宽度。默认值：50。有效值：正数。

• height 按钮的高度。默认值：12。有效值：正数。

• adjust 相对于父元素大小变化时的自动化调整模式。默认值：auto 。有效值：

  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸

• can_check 是否表示为状态按钮。默认值：false。有效值：

  • true 表示为状态按钮。按下时不会弹，再次按下恢复初始状态。
  • false 正常的点击按钮。

• default 窗口打开后的焦点。默认值：false。有效值：

  • true 窗口打开后焦点在此按钮上，回车即可触发 onClick 事件。
  • false 不将焦点置于此控件上

• flat 按钮是否扁平化样式。默认值：false。有效值：

  • true 按钮按下时背景为暗色。can_check 属性为 true 时建议开启此选项。
  • false 普通的按钮样式。

• gray 有效性。默认值：false。有效值：

  • true 控件变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态

• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：

  • true 可见
  • false 不可见，并且不占用空间

• onClick 按钮点击时触发的事件。

• onContentMenu 点击右键菜单项目时触发的事件。

4.12.2 ui命名空间下的pushubtton命名对象

• content_menu 右键菜单的项目设置。代码取值时为被点击的项目的id。代码赋值时视为设置弹出菜单，有效值为菜单元素的数组，其中每个菜单元素包含以下属性：

  • name 显示的名称，有效值：字符串。特殊的，当值为“-”并且未设置其他属性时，识别为分割线。

  • icon 显示的图标，有效值：字符串

  • id 当前菜单中的唯一ID，有效值：数字

  • children 子项目菜单，仅在根菜单下有效（仅支持2级菜单）。有效值：菜单元素的数组。

  当设置 content_menu 的时候，弹出菜单就会展示出来。

• enable 控件是否有效。和 gray 属性相反。只能用代码进行取值或赋值。

• handle 当前元素的操作句柄。

• valid 按钮的按下状态。默认值：false。有效值：true | false。可以用代码进行取值或赋值。但是值会被其他属性影响：

  • can_check 属性的值为 false 时，valid 得值恒为 false 。

• value 按钮上的文字。默认值与 label 相同。可以用代码进行取值或赋值。

4.13 Radiobutton（单选按钮）

​ “Radiobutton”控件用于用户的单选的情况，在同一个组内只能最多有一个被选中。

4.13.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• label 标签名。默认值：“Radio”。有效值：空白 | 字符串，显示在选择圆圈的右面的文本。
• group_id 用于区分单选项的组的id，同一个组内只能有一个被选中。默认值：1 。有效值：数字。
• default_group_item 是否为当前组内的默认选中项目。同一个组内多个为默认选中项目时，该组最后一个默认选中。默认值：false。有效值：true | false。
• width 按钮宽度。默认值：50。有效值：正数。
• height 按钮高度。默认值：10。有效值：正数。
• auto 是否使用自动大小。默认值：true。有效值：
  • true 大小匹配刚好包含圆圈和标签，width 和 height 属性失效。
  • false 大小使用 width 和 height 属性。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：fixed 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸
• gray 有效性。默认值：false。有效值：
  • true 控件变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态
• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：
  • true 可见
  • false 不可见，并且不占用空间
• onSwitch 当项目选中项目变化时触发的事件。同一组只需要设置一次onSwitch即可，不用重复设置。

4.13.2 ui命名空间下的radiobutton命名对象

• enable 是否有效。和 gray 属性相反。只能用代码进行取值或赋值。
• valid 是否选中，初始化的值与 default_group_item 相同，只能用代码进行取值或赋值。
• handle 当前元素的操作句柄。
• value 显示的标签名，初始化的值与 label 相同。只能用代码进行取值或赋值。

4.14 Scintilla（文本编辑器）

​ “Scintilla”控件是用于自由编辑文本的编辑器。支持多种语言。

4.14.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• width 编辑器的宽度。默认值：50。有效值：正数。
• height 编辑器的高度。默认值：50。有效值：正数。

• adjust 相对于父元素大小变化时的自动化调整模式。默认值：auto 。有效值：

  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸

• line_number 是否显示行号。默认值：true。有效值：true | false

• readonly 内容是否只读。默认值：false。有效值：true | false

• wrap 文本是否自动折行。默认值：false。有效值：

  • true 文本到达宽度时自动折行，不会出现内部的横滚动条
  • false 文本到达宽度时不会自动折行，超长时出现内部的横滚动条

• gray 有效性。默认值：false。有效值：

  • true 控件变灰，表示无效，挂载的所有事件均不能触发
  • false 正常状态

• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：

  • true 可见
  • false 不可见，并且不占用空间

• onChange 内容变化时触发的事件。

• onCusorChange 光标位置变化时触发的事件。使用delete键删除光标后面文字时不触发。

• onSelectionChange 当选中内容变化时触发的事件。

4.14.2 ui命名空间下的scintilla命名对象

• lexer 文本编辑器的语法高亮支持。

  • 右值：返回有效值列表["avs","bash","batch","cmake","coffeescript","cpp","csharp","css","d","diff","edifact","fortran","fortran77","html","idl","java","javascript","json","lua","makefile","markdown","matlab","octave","pascal","perl","po","postscript","pov","poperties","python","ruby","spice","sql","tex","tcl","verilog","vhdl","xml","yaml"] 。
  • 左值：从有效值列表中选择一个元素进行赋值。

• keywords：设置自定义的附加关键字列表

  • 右值：N/A
  • 左值：自定义关键字列表
  • 注意事项：
  • 只对如下列表中的语言有效，[“cpp”，“avs”，“cmake”，“coffeescript”，“csharp”，“d”，“idl”，“java”，“javascript”，“lua”，“pov”，“sql”，“tcl”，“vhdl”]
  • 在lexer变量被赋值之前才会起作用

• regex：为该变量赋值一个正则表达式，实现对scintilla中的内容进行搜索

  • 右值：N/A
  • 左值：正则表达式
  • 注意事项：
  • 该变量带有记忆功能，从当前光标位置向后搜索

• autoComplete：设置自定义的自动补全关键字

  • 右值：N/A
  • 左值：自定义自动补全关键字列表

• autoCompleteCallback: 设置自定义自动补全回调函数

  • 右值：N/A

  • 左值：自定义自动补全回调函数

  • 使用举例如下：

  ui.sci.autoCompleteCallback = function(ns_list){
          ui.info.value =ns_list.length + ':' + ns_list.map(item=>"'" + item + "'").join('-');
              
          if(ns_list.length == 2 && ns_list[0] == 'ui')
          {
                  return ['abc', 'def'];
          }
  };
  

  • ui$\rightarrow$[‘ui’]
  • ui.$\rightarrow$[‘ui’,’’]
  • ui.abc$\rightarrow$[‘ui’,’abc’]
  • ui.abc.$\rightarrow$[‘ui’,’abc’,’’]
  • ui.abc.fa$\rightarrow$[‘ui’,’abc’,’fa’]

• enable 图片是否有效。和 gray 属性相反。只能用代码进行取值或赋值。

• handle 当前元素的操作句柄。

• value 选中的内容。可以通过代码取值或赋值。当光标未选中内容时，该属性与 document 等价。有效值：字符串。

• document 整个文档的内容。可以通过代码取值或赋值。有效值：字符串。

• inserter 在光标处插入内容。只写属性。当光标选中内容时，将内容与该属性的值进行替换。有效值：字符串。

• dirty 编辑器是否有内容变更。可以通过代码取值或赋值。当编辑器内容变更时会自动将该属性变为 true 。有效值：true | false

• row 光标所在的行，从 0 开始计算，也就是行号 -1。可以通过代码取值或赋值。赋值小于0时光标移到最后一行。

• column 光标所在的列，从 0 开始计算。可以通过代码取值或赋值。赋值小于0时光标移到行首。

• firstVisibleLine 当前可见的第一行内容的行号（0-索引）

• index 光标所在位置在整个文档中的索引。每个汉字占3个位置。

• range 选中内容的范围。包含两个属性：

  • low 选择内容开始所在位置在整个文档中的索引。每个汉字占3个位置。未选中状态的值：0

  • high 选择内容结束所在位置在整个文档中的索引。每个汉字占3个位置。未选中状态的值：整个文档的 index

  未选中内容时令 range.low=0 会选中整个文档。

• line 光标所在行的内容。可以通过代码取值或赋值。赋值后自动换行。

4.15 Horizontal Sliderbar（横向滑块）

​ “Horizontal Sliderbar”控件用于显示进度或者横向拖动控制进度。属性和进度条类似，多了一个onChange事件。

4.15.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• data 初始化数据。默认值：0, 100, 50 。有效值：以“ , ”分割的字符串，第一个是最小值，第二个是最大值，第三个是当前值。
• width 滑块条的宽度。默认值：100。有效值：正数。
• height 滑块条的高度。默认值：15。有效值：正数。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：fixed 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸
• gray 有效性。默认值：false。有效值：
  • true 控件变灰，表示无效
  • false 正常状态
• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：
  • true 可见
  • false 不可见，并且不占用空间
• onChange 滑块位置变更时触发的事件。

4.15.2 ui命名空间下的hslider命名对象

• range 进度条的范围。可以通过代码取值或赋值。有两个属性：
  • low 进度条的最小值。默认值：0 。有效值为大于等于0的数。
  • high 进度条的最大值。默认值：100 。有效值为大于最小值的数。
• value 进度条的值。默认值：0 。有效值：大于等于 range .low （最小值）并且小于等于 range .high（最大值）
• enable 控件是否有效。和 gray 属性相反。只能用代码进行取值或赋值。
• handle 当前元素的操作句柄。

4.16 Vertical Sliderbar（纵向滑块）

​ “Vertical Sliderbar”控件用于显示进度或者纵向拖动控制进度。属性和默认值与“Horizontal Sliderbar”（横向滑块）完全一致。不做更多介绍。

4.17 Spin（数字输入框）

​ “Spin”控件用于显示整数或者记录用户输入整数的控件。每次点击上箭头数字-1，点击下箭头数字+1。到达上下限时不变化。

4.17.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• data 初始化数据。默认值：0, 100, 50 。有效值：以“ , ”分割的字符串，第一个是最小值，第二个是最大值，第三个是当前值。
• width 输入框的宽度。默认值：51。有效值：正数。
• height 输入框的高度。默认值：14。有效值：正数。
• adjust 相对于父元素大小变化时的自动化调整模式。默认值：fixed 。有效值：
  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸
• readonly 是否只读。默认值：false。有效值：true | false
• gray 有效性。默认值：false。有效值：
  • true 控件变灰，表示无效
  • false 正常状态
• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：
  • true 可见
  • false 不可见，并且不占用空间
• onChange 数字变更时触发的事件。

4.17.2 ui命名空间下的spin命名对象

• range 进度条的范围。可以通过代码取值或赋值。有两个属性：
  • low 进度条的最小值。默认值：0 。有效值为大于等于0的数。
  • high 进度条的最大值。默认值：100 。有效值为大于最小值的数。
• value 进度条的值。默认值：0 。有效值：大于等于 range .low （最小值）并且小于等于 range .high（最大值）
• enable 控件是否有效。和 gray 属性相反。只能用代码进行取值或赋值。
• handle 当前元素的操作句柄。

4.18 Tree（树）

​ “Tree”控件用于展示一个树形结构的数据。可以折叠节点，设置左键点击事件和右键菜单事件。

4.18.1 属性和事件

• name 名称。默认值：空白。有效值：空白 | 字符串，需要全Form唯一，赋值后即可使用全局变量 ui 进行调用。
• width 树形结构外框的宽度。默认值：100。有效值：正数。
• height 树形结构外框的高度。默认值：100。有效值：正数。
• virtual_width 树型内容的宽度。如果大于 width 则展示出横滚动条。小于 width 则没有实际效果。默认值：200 。有效值：正数。

• adjust 相对于父元素大小变化时的自动化调整模式。默认值：auto 。有效值：

  • auto 横向纵向均可拉伸
  • horizontal 横向拉伸
  • vertical 纵向拉伸
  • fixed 固定不拉伸

• check_box 未实装。默认值：false。

• edit_label 未实装。默认值：false。

• has_button 未实装。默认值：true。

• has_line 未实装。默认值：true。

• single_expand 未实装。默认值：false。

• gray 有效性。默认值：false。有效值：

  • true 控件变灰，表示无效
  • false 正常状态

• visible 可见性。默认值：true。也可以通过代码取值或赋值。有效值：

  • true 可见
  • false 不可见，并且不占用空间

• onClick 鼠标左键点击时触发的事件。

• onRightClick 鼠标右键点击时触发的事件。

• onContentMenu 点击弹出菜单元素时触发的事件。

4.18.2 ui命名空间下的tree命名对象

• content_menu 右键菜单的项目设置。代码取值时为被点击的项目的id。代码赋值时视为设置弹出菜单，有效值为菜单元素的数组，其中每个菜单元素包含以下属性：

  • name 显示的名称，有效值：字符串。特殊的，当值为“-”并且未设置其他属性时，识别为分割线。

  • icon 显示的图标，有效值：字符串

  • id 当前菜单中的唯一ID，必须项。有效值：数字

  • children 子项目菜单，仅在根菜单下有效（仅支持2级菜单）。有效值：菜单元素的数组。

  当设置 content_menu 的时候，弹出菜单就会展示出来。

• tree 设置或获取树的数据。有效值是一个根节点的json对象，根节点具有以下属性：

  • name 节点的显示名称。默认值：“tree”。有效值：字符串
  • icon 节点的显示图标。默认值：“tree”。有效值：图片文件夹下的png图片的文件名（不包含扩展名.png）
  • id 节点的id。默认值：1 。有效值：数字，要保证整棵树唯一。
  • children 子节点（可选）。有效值为节点的数组。每个子节点元素的属性与根节点属性一致。没有层数限制。

• position 选中元素的的id。可以赋值或取值。赋值时表现为变更当前选中的节点。

• children 选中元素的子元素的id数组。只读属性。当选中的节点没有子节点时，该属性的值为undefined。

• parent 选中元素的父元素的id。只读属性。当选中根节点时，该属性的值为undefined。

• next 选中元素的兄弟节点中，选中元素的下一个元素的id值。如果该元素是最后一个元素，该属性的值为undefined。

• previous 选中元素的兄弟节点中，选中元素的上一个元素的id值。如果该元素是第一个元素，该属性的值为undefined。

• node 选中元素的节点json对象。可以赋值或取值。点击根节点时与 tree 属性相同。有以下特殊用法：

  • 赋值为一个节点的json对象的数组，则将该节点的子节点进行赋值。
  • 赋值为undefined，则将该节点删除。

• inserter 在选中元素的节点前面插入一个节点并选中新节点。有效值为一个节点的json对象。

• head 在选中元素的第一个兄弟节点的前面插入一个节点并选中新节点。有效值为一个节点的json对象。

• tail 在选中元素的最后一个兄弟节点的后面插入一个节点并选中新节点。有效值为一个节点的json对象。

• enable 控件是否有效。和 gray 属性相反。只能用代码进行取值或赋值。

• handle 当前元素的操作句柄。

第五章 弹力器

5.1 Space（弹簧）

​ “Space”控件是用来调节界面布局的组件，可以通过在“Horizontal Box”或者“Vertical Box”上右键选择“Append a Stretch”（添加弹力器） => "Space"（弹簧）添加。它只有一个属性：

• size 弹簧的长度。默认值：auto。有效值：
  • auto 尽可能的占用更多的宽度，例如两个固定宽度的控件会在布局器中居中显示，当其中插入一个弹簧后，会将两侧的控件顶到两侧，一个居左，一个居右。
  • 数字 固定的宽度或长度，相当于固定长度宽度的空白内容的控件。

5.2 Separator（分割线）

​ “Separator”控件用于在界面中划出一根分割线，可以通过在“Horizontal Box”或者“Vertical Box”上右键选择“Append a Stretch”（添加弹力器） => "Separator"（分割线）添加。当父元素是“Horizontal Box”时，显示的是一根贯穿的竖线。当父元素是“Vertical Box”时，显示的是一根贯穿的横线。

• margin 与相邻控件的距离。默认值：2 。有效值：数字。
• gray 有效性。默认值：false。有效值：
  • true 控件变灰，表示无效
  • false 正常状态
• visible 可见性。默认值：true。有效值：
  • true 可见
  • false 不可见，并且不占用空间

第六章 界面与模型

6.1 Callback（界面函数）

​ “Callback”是当前“Form（窗口）”所关联函数的文件。与“Form”是一对一的关系。包含了窗口的生命周期函数和控件触发函数以及自定义函数。点击纵向的Callback标签即可查看当前Form的Callback文件。默认打开该文件。

​ 每个窗口包含三个生命周期，触发相应的函数如下：

• OnInitializeData() ：当界面初始化完成时触发的函数。可以在这里进行数据的初始化和控件状态的初始化操作。

• OnCloseForm()：当窗口要关闭时触发的函数。可以在这里进行数据的销毁和内存的释放等操作。返回false时可以阻止关闭窗口。

• OnException(err)：当窗口发生异常时触发的函数。可以在这里对所捕获的异常进行处理。

这个文件中含有以下几个全局变量：

• ui 代表这个form对象。包含以下几个属性和方法：

  • geometry 窗口的大小以及位置，可以通过代码取值或赋值。包含以下4个属性：

  • x 窗口左上角在屏幕的横向位置

  • y 窗口左上角在屏幕的纵向位置

  • width 窗口的宽度

  • height 窗口的高度

  • hot_key 参照 form 的 onHotKey 使用方法。

  • clipboard 剪贴板的内容，可以通过代码取值或赋值。

  • attachment 子窗口在父窗口附着的位置。只能赋值。只能在子窗口中使用。需要嵌套PUI(()=>{})中在用法：

  PUI(()=>{
      ui.attachment={type: Attachment.LEFT_BOTTOM, size:1, parent: pui.myBtn.handle};
  });
  

  第一个属性 type 是附着位置，可选项：Attachment.

  LEFT_BOTTOM | LEFT_TOP | NONE | RIGHT_BOTTOM | RIGHT_TOP

  第二个属性 size 是距离边界的位置，有效值：数字

  第三个属性 parent 是关联父窗口中控件 myBtn 的句柄。在子窗口中要使用 pui 调用父窗口的 ui 。

  如果需要写在OnInitializeData()中，需要使用parent.setTimeout()进行包裹，不然无法识别父窗口的控件句柄。

  • block_event 界面是否正在执行任务。

  • OpenFileDialog 打开文件选择对话框，用法：

  var path = ui.OpenFileDialog("这里是标题","D:/testFolder/","图片| *.jpg;*.png;*.bmp");
  

  第一个参数 "这里是标题" 是文件选择对话框的标题，显示在弹出窗口的左上角。第二个参数 "D:/testFolder/" 是打开时所显示的路径。第三个参数 "图片| *.jpg;*.png;*.bmp" 是文件筛选，“ | ”前面代表所要的文件类型，可以自定义，后面代表文件的后缀名，使用“ ; ”分隔多个可选后缀名。

  返回值 path 即为所选择文件的绝对路径。如果关闭对话框或者取消选择，path 的值为空字符串。

  • OpenFilesDialog 打开文件选择对话框，可以多选。用法同 OpenFileDialog 。多选时返回值 path 为选择文件的路径数组。

  • OpenFolderDialog 打开文件夹选择对话框。用法同 OpenFileDialog 。不过只有前两个参数，没有第三个参数。

  • SaveFileDialog 保存文件对话框。用法同 OpenFileDialog 。相同文件名会有提示是否覆盖。

  • SetFocus 将焦点转移至对象的句柄。用法：

  ui.SetFocus(ui.myEdit.handle);
  

  将焦点转移到名为 myEdit 的控件上。

  • MessageBox 弹出对话框。用法：

  var result = ui.MessageBox ("这里是标题", "这里是内容", MessageBox.Icon.Question, MessageBox.Button.Ok | MessageBox.Button.Close);
  

  • 第一个参数 "这里是标题" 是弹出对话框的标题。

  • 第二个参数 "这里是内容" 是显示在对话框内部的内容。

  • 第三个参数 MessageBox.Icon.Question 是显示在内容左侧的图标。可选项：MessageBox.Icon.

  Critical (禁止) | Information (消息) | NoIcon (无图标) | Question (问询) | Warning (警告)

  • 第四个参数是附带的按钮。多个组合时使用 " | " 分隔。可选项：MessageBox.Button.

  Abort | Apply | Cancel | Close | Discard | Help | Ignore | No | NoButton | NoToAll | Ok | Open | Reset | RestoreDefaults | Retry | Save | SaveAll | Yes | YesToAll

  • 返回值是按钮的枚举值，使用设置的按钮与之进行比较即可判断用户点击了哪个按钮。如 ：

    if(result == MessageBox.Button.Ok){
      //点击了 Ok 按钮
    }
  

• model 代表这个unit 的模型对象。用来调用在 Model中定义的方法。

• parent 代表整个项目的根节点，一般只需要使用其中以下关于计时器的方法：

  • setTimeout 设置一个延时执行的函数。返回延迟函数的id值。用法：

  var id = parent.setTimeout(()=>{
      //do something
  },200)
  

  200是延时的时间，单位ms（毫秒），可以省略。只执行一次。

  • setInterval 设置一个延时执行的函数。用法与 setTimeout 相同 ，会一直执行。

  • setImmediate 设置一个延时执行的函数。用法与 setTimeout 相同 ，只执行一次。一般用于多层的复杂的结构。

  • clearTimeout 停止延时执行的函数。仅针对setTimeout，用法：

  parent.clearTimeout(id);
  

  id即为设置延迟函数时返回的id。

  • clearInterval 停止延时执行的函数。仅针对setInterval，用法与 clearTimeout 相同 。

  • clearImmediate停止延时执行的函数。仅针对setImmediate，用法与 clearTimeout 相同 。

6.2 Model （模型）

​ “Model ”模型是整个Unit都可以访问的文件。与“Unit”是一对一的关系。使用的是nodejs的语法。包含了加载插件和各个窗口共通的方法。点击纵向的Model标签即可查看当前Unit的Model文件。

​ “AutoLoadPlugins()”方法和“AutoLoadGlobalPlugins()”方法是用来加载插件的方法，请不要进行任何更改。自己添加的方法一般放到 //Put you codes here 下面。使用 nodejs 语法。在这里定义的方法可以在当前Unit中任意一个Callback文件中通过全局变量model进行调用。参考自带的ide_info() 方法，作用是在界面上方的文本框中输出调试信息。可以在Callback文件中使用 model.ide_info("this is my message"); 即可输出。

​ 如果需要使用npm的nodejs插件，需要在comx_sdk.node 根目录进行npm install，就可以在model文件里require到了。由于npm库里代码良莠不齐，下载需谨慎，及时做好整个工具的备份。

6.3 多窗口

​ 有时一个窗口不足以显示全部业务，那么就需要多个窗口来显示。

​ 在界面左上角Form输入框键入一个新的子窗口名称，如 "myForm"。点击Form输入框右侧的蓝色小加号“ + ”，即可完成创建名为"myForm"的子窗口。可以通过Form输入框的下拉选项切换窗口。想要通过父窗口弹出子窗口只需要使用

unit.form.myForm.Show();

即可弹出刚创建的子窗口了。

​ 由于model文件是全unit可访问的，而两个form都属于这个unit，所以数据通信可以通过model来进行。

6.4 “沙箱”机制（sandbox)

第七章 插件

​ 项目中可以引用高性能的C/C++代码来辅助计算。想要使用C/C++代码，需要按照规范来进行。

7.1 创建第一个插件

1. 打开DCiP工具

2. 在界面左上角Unit输入框键入一个项目名称“testUnit”

3. 点击Unit输入框右侧的蓝色小加号“ + ”

4. 在界面左上角Plugin输入框键入一个项目名称“testPlugin”

5. 点击Unit输入框右侧的蓝色小加号“ + ”

6. 点击侧栏的Plugin标签，在下方Namespace输入框输入"myNamespace"，勾选旁边的Sample Codes选项，点击右侧的蓝色小加号“ + ”，稍等片刻即可创建该命名空间。

7. 在上方Function List (方法名)输入框输入"myPlusFun"，在右侧Parameters Number (参数个数)输入框选择2，点击右侧的蓝色小加号“ + ”

8. 在自动创建的JS_EXT_FUNC_BEGIN(myFun, 2, MYFUN_FUNC_USAGE) 方法中在空白位置插入如下代码：

   int a = JS_EXT_PARA(int, 0);
   int b = JS_EXT_PARA(int, 1);
   JS_EXT_FUNC_ASSIGN_RET( a + b );

1. 点击下方工具栏按钮组的第二个编译按钮（Compile current plugin and integrated it.），稍等片刻进行编译。

2. 右键点击左侧项目树的根节点form，依次选择“Append a Top Constrain”（添加布局器） => "Horizontal Box"（横向布局器）

3. 右键点击根节点form下的hbox节点，依次选择“Append a Widget”（添加控件） => "Label"（标签）

4. 单击选中hbox节点下的label，在左下方的属性编辑区域找到 name 属性，输入"myLabel"，回车确认。

5. 点击侧栏的Callback标签，在初始化函数 OnInitializeData() 中添加以下代码：

   ui.myLabel.value = testUnit.myNamespace.myPlusFun(5,6);
   

6. 如果右下角的预览窗口显示11，则证明已经可以正常加载刚刚写好的加法插件了。

7.2 插件的写法

​ 上一节已经写好了一个简单的加法的插件，而且顺便创建了一些示例代码（不勾选旁边的Sample Codes选项则不生成示例代码），使用方法在函数的上面有提示，现在介绍这些函数：

• JS_EXT_PARA 获取从js传过来的参数。用法：

  [value_type] val = JS_EXT_PARA([value_type], [index]);

[value_type]替换成已知的参数类型，如：int，string等，如果是回调函数类型，设置为TComxCallback 类型。

​ [index]替换成已知的参数索引，从0开始。

• JS_EXT_FUNC_ASSIGN_RET 向js返回一般值。用法：

  JS_EXT_FUNC_ASSIGN_RET([value]);

[value]替换成需要返回的值。

• JS_EXT_FUNC_ASSIGN_RET_EX 向js返回buffer值。用法：

  JS_EXT_FUNC_ASSIGN_RET_EX([buffer], 1);

[buffer]替换成需要返回的buffer。

​ 每次修改插件都需要点击编译按钮进行编译，然后就可以在Callback或Model文件中使用了。

var result = [unit].[namespace].[functionName](parm1,parm2,...);

​ [unit]替换为当前Unit的名称。

​ [namespace]替换为已创建的命名空间名称。

​ [functionName]替换为已创建的函数名称。

​ parm1替换为参数，多个参数时用 " , " 分割。

​ 创建命名空间默认是在当前的Unit下，可以在Category输入框选择"Global Field"选项，使其变为全局命名空间，全局的Unit名称为"comx"。