# 自定义操作窗
本模块的目的是为了提供一个可以多次点击按钮触发某项操作（而不会自动关闭）的小窗口。
支持的操作类型：
+ 显示操作窗：显示操作窗后继续执行后面的步骤。
+ 显示操作窗并等待关闭：显示操作窗，并等待操作窗关闭后，再执行后面的步骤。
+ 关闭操作窗：关闭通过窗口标识指定的操作窗。
+ 切换展开状态：根据给定的操作窗标识，切换操作窗展开、折叠的状态。
+ 获取操作窗状态：根据给定的操作窗标识，返回操作窗状态、窗口句柄。
# 显示操作窗
显示操作窗后继续执行后面的步骤。
## 参数
### 操作项定义
**【操作项定义】**
定义操作窗上所显示的按钮和它们的行为。
数据格式基本与[显示菜单模块的菜单数据](https://getquicker.net/kc/help/doc/showmenu#HkDla)参数一致，请参考该文档，同时注意以下区别：
+ 本模块不支持分隔符。
+ 当操作类型为“显示操作窗并等待关闭”时，支持使用`operation=close&data=返回值`方式指定用于关闭操作窗的按钮以及该按钮所需要返回的“操作项数据”值。
+ 支持使用`operation=sp&spname=子程序名称`的形式调用动作中所定义的子程序。更详细的说明请参考本文后面部分。
+ 最多支持一级子项。数据通常有两种形式：（1）全部都不带子项，所有操作项按设定的方式平铺排列。（2）首层节点带子项。此时首层节点作为分组处理（可选多种分组方式）。
+ 使用`[]`作为操作项的标题，可以创建按钮占位符，用于在创建按钮时跳过某些位置以便实现特定布局方式。（1.39.42+）
**缩进格式的子项定义**
如下面的定义：
生成的效果如图。 如果按钮本身不需要实现其它操作，可以在标题后面加`|`或`|operation=&data=`表示空操作，这是点主按钮，也可直接展开子项菜单。
示例动作：[CAD命令板 - 动作信息 - Quicker](https://getquicker.net/Sharedaction?code=6085f206-34f6-4ee7-97b7-08db3d4a9dcd)
**按钮的默认右键菜单 (v1.39.32)**
如果按钮所需要的右键菜单类似，可以在步骤中设置“默认的按钮右键菜单”参数。
当菜单调用子程序（operation=sp）时，按钮的相关信息将通过子程序输入变量传入子程序中。
**缩进格式的右击菜单定义**
使用缩进格式时，在按钮条目下，可在缩进后使用 `- `（短横线加空格）作为开始，为CommonOperationItem设置Menu数据。（菜单项的子菜单不再需要添加 `- `)。
注：按钮的右键菜单缩进比按钮本身的缩进多一级。
```plain
[fa:Light_Play]执行动作|operation=action&data=Hello&action=自定义操作窗示例
[fa:Light_Pen]子程序|operation=sp&data=Hello&spname=testsp&num=100
[icon:c:\windows\notepad.exe]记事本|operation=run&data=notepad
[url:https://helperservice.getquicker.cn/favicon/get/baidu.com]打开baidu|operation=open&data=http%3A%2F%2Fbaidu.com
[url:https://helperservice.getquicker.cn/favicon/get/baidu.com]打开Google|operation=open&data=http%3A%2F%2Fgoogle.com
- [url:https://helperservice.getquicker.cn/favicon/get/baidu.com]打开Google|operation=open&data=http%3A%2F%2Fgoogle.com
- ----
- 子菜单
[url:https://helperservice.getquicker.cn/favicon/get/baidu.com]打开Google|operation=open&data=http%3A%2F%2Fgoogle.com
[fa:Light_Pen]模拟输入文本Hello|operation=sendkeys&data=Hello
```
对应的右键菜单：
**右键点击按钮直接触发操作**（1.39.33）
如果希望在按钮点击右键时直接执行某个操作，可以这样定义：有且仅有一个右键菜单项，且其标题为`=`。
例如：
```plain
父操作项
- =|operation=xxxx......
```
也可在默认的按钮右键菜单中按此方式设置：`=|operation=xxx&data=xxxx`
**缩进格式的内容注释**
如果需要注释某一行，可以在缩进后添加`////`字符。此时该行以及它所有子节点会被注释。
```plain
aaaaa
////bbbb
cccc
////dddd
eeee
////ffff
ggggg
```
**设置单个按钮的额外属性**
+ 通过额外的参数`.background`可设置单个按钮的背景颜色。如果要固定按钮颜色，不要鼠标悬浮效果，可以附加`.fixed`参数，如：`...&.background=#ff0000&.fixed=true`。
+ `.foreground`可设置按钮文字颜色（在设置按钮背景色的情况下，`.foreground`可以设置为`auto`，以根据背景色亮度自动将文字显示为黑色或白色）（1.39.24+）。
+ `.bordercolor`可设置按钮的边框颜色（1.39.24+）。
+ `.width`可以设置按钮的固定宽度，`.height`可以设置按钮的固定高度。（1.40.16+）
+ `.iconSize`可设置图标大小。
**缩进格式：**
` [fa:Light_Play]执行动作|operation=action&data=Hello&action=_this_&.background=#66FF0000`
**JSON格式：**
```json
{
"Title": "执行动作",
"Icon": "fa:Light_Play",
"Description": null,
"Data": "Hello",
"DataType": null,
"Operation": "action",
"Action": "_this_",
"Menu": null,
"SecondaryIcon": null,
"ExtraData": {
".background": "#66FF0000"
}
}
```
**表达式创建：**
```csharp
$=new CommonOperationItem(){
Title = "执行动作",
Icon = "fa:Light_Pen:#000000",
Description = "描述",
Operation = "action",
Action = "_this",
ExtraData = new Dictionary(){
{".background", "#20FF0000"}
}
}
```
**使用操作项编辑器**
注意：
+ 使用此功能会自动清除原始数据中的注释内容，也可能会造成一些原始数据格式变化或丢失。
+ 不支持在开启插值或表达式的情况下使用。仅支持编辑缩进格式或json格式数据。
点击参数输入框右侧的编辑按钮，可以打开操作项编辑器。
在打开的编辑窗口中修改或添加操作项，然后保存即可。
****
**【默认Operation】**可以为空。
默认的操作项Operation值，在1.38.23+版本中，也支持附带更多默认参数值。
当大部分的按钮具有相同的工作方式时，可以通过本参数指定操作项的默认参数，然后在具体操作项定义中，只需要设置`标题部分|data值`即可。
默认Operation支持如下两种格式：
+ 仅提供Operation值，如`paste`，表示点击按钮后，向当前窗口粘贴文本。更多的operation值请参考[这里](https://getquicker.net/kc/help/doc/showmenu#mpGhI)。
+ 提供包含多个operation的参数，如`operation=sp&spname=send`表示点击按钮后执行名称为`send`的子程序，并将操作项data数据作为参数传递给子程序的data输入变量（参考示例动作“文字窗”）。
设置默认Operation后，操作项的数据定义可以简化为以下格式中的一种：
+ `内容`按钮标题和data值一样的情况。
+ `标题|值`分别指定按钮标题和data值，适用于data内容较长不易识别的情况。
+ `[图标]标题|值`带有图标的按钮。
示例动作：
+ [示例：默认Operation](https://getquicker.net/Sharedaction?code=62cb23a0-fdc5-4616-9791-08db3d4a9dcd)
+ [文字窗](https://getquicker.net/Sharedaction?code=c132bcb5-9cc1-476d-eba4-08db754ee2c2)
注：
+ 如果某个操作项的operation和默认的不同，可以按上面章节中所描述的完整格式写。
### 其它参数
**【空隙】**按键之间的间隙。
**【背景颜色】**操作窗的背景颜色。
**【列数】【列宽】**
确定按钮的排列方式。
列数大于0时，按钮按指定列数对齐排列，宽度固定。此时列宽应设置为 0 或 -1 。
列数等于 0 时，按钮自动折行排列。此时根据列宽的数值，分为几种情况：
+ 列宽如果为 -1，则表示每个按钮根据其内容自动设置宽度。
+ 列宽如果为 0，则表示所有按钮等宽，宽度根据内容最多的按钮确定。
+ 列宽为大于 0 的值，表示使用固定的宽度。
**【分组方式】**
操作项数据一级节点包含子项时，一级作为分组，二级作为按钮显示。
**【操作窗标题】** 窗口左上角的标题文字。
**【窗口标识】**
如果需要先显示窗口，后面再根据需要更新窗口内容或通过动作关闭窗口，可设定一个自定义的文本作为窗口标识。 后面使用相同的窗口标识再次调用“显示操作窗”即可更新窗口内容。或使用“关闭操作窗”操作来关闭它。
为避免和其它动作重复，尽量使用较为特殊一点的文字，或使用`=`表示使用当前动作ID作为窗口标识（在多个动作中使用=作为窗口标识时，各动作之间互不影响）。
**【失败后停止】**
遇到异常后是否停止动作。
特别的，当操作方式为“显示操作窗并等待关闭”，并且输出了“选择的操作项数据”或“选择的操作项”时，如果通过点击窗口右上角的关闭按钮或双击空白区域等方式关闭了窗口，则视为步骤执行失败。如需继续执行后续的步骤，请取消本选项。
**【窗口位置】**选择操作窗的显示位置类型。
**【窗口尺寸/位置】**与“窗口位置”参数结合使用。在“窗口位置”参数选择“自定义位置”时，指定窗口的坐标范围。其他情况指定窗口的尺寸。
可以使用百分比或像素值。如：
+ 50%,50%：设定窗口尺寸为屏幕的一半宽一半高。
+ 300,50%：宽度为300像素，高度为屏幕一半。
+ 600,300：宽度为600像素，高度为300像素。
+ 10%,10%,50%,50%：指定窗口的左、顶、右、底边在屏幕上的位置（百分比位置）
+ 100,100,50%,50%：指定窗口的左、顶、右、底边在屏幕上的位置（百分比单位和像素单位结合）
支持增加!(英文半角叹号)前缀表示禁止调整操作窗大小。如：`!300,200`创建固定大小的窗口。(1.39.42+)
**【记忆位置等状态】**保存操作窗的位置、分组折叠展开状态、当前标签页等信息，并在下次显示此操作窗时自动使用之前的状态。
**【按钮内容对齐方式】**按钮中的图标和文字的对齐方向。
**【按钮颜色】**按钮的背景颜色。使用自定义按钮颜色后，鼠标悬浮时的颜色对比就会变得不是很明显了。
**【字体大小】**按钮文字字体大小（逻辑像素数）。
**【图标大小】**按钮图标大小（逻辑像素数）。
**【窗口右键菜单】**必要时用于自定义窗口的右键菜单内容。 格式与“操作项定义”一致。
**【自动关联到进程】**指定自动关联的进程名。关联进程后，只有该进程在前台时，操作窗才显示。
绑定多个进程时，可使用英文半角分号或逗号隔开，如`notepad;winword;excel`。
如果指定“-”，则表示禁用此功能，将从操作窗隐藏关联进程按钮。如果留空，则可以在操作窗界面上根据需要手动关联到当前前台进程。
【自动折叠】是否开启自动折叠操作窗。可选“开启”“关闭”或“禁用此功能”。开启时，如果鼠标离开操作窗，操作窗会自动收缩到只显示标题栏。禁用功能时，将从操作窗移除此按钮。
## 操作窗的使用
**折叠：**点击标题栏最小化按钮，或双击标题栏或窗口内部，可将操作窗折叠为一个横条。也可使用轮盘、手势的窗口最小化、最大化功能来折叠。
**拖动位置：**按住标题栏或窗口空白区域即可拖动窗口。
**切换分组：**点击标签页，或在标签页标题区使用滚轮可以快速切换页面。
**关闭操作窗：**
+ 点击右上角关闭按钮；
+ 通过窗口右键菜单；
+ 使用轮盘、手势等功能中的关闭窗口；
+ 在设置中开启后，可双击关闭操作窗。
**重置操作窗位置**
如果因为某种原因，操作窗未能显示到屏幕内（如副屏断开等造成了上次显示的位置不存在），可以通过右键菜单重置操作窗状态（1.40.34+）：
## 调用子程序并传递参数
示例动作：[示例：自定义操作窗_子程序 - by CL - 动作信息 - Quicker](https://getquicker.net/Sharedaction?code=bfc36f54-2bfb-44b9-9d15-08dbb6a8337d)
+ 无论按钮本身或按钮的菜单，都可以使用operation类型为sp的操作项定义。
+ 文本格式的例子：`[图标]标题(提示内容)|operation=sp&spname=子程序名&data=data数据&其他参数.....`的格式定义。
将会为子程序传递如下数据：
+ **data**：点击的按钮或按钮的子菜单、右键菜单对应的操作项（CommonOperationItem）的data数据。
+ **num**：示例：一个自定义变量。当需要为子程序传递自定义的内容时，可以添加自定义变量并且设置为子程序的输入。在操作项定义中，为其传递参数即可：
或：
+ **spname**：子程序名称。
+ **_group**：当前分组名称。
+ **_groupData**：当前分组条目的data参数值。(1.43.55+版本）
+ **_handle**：操作窗的窗口句柄（非窗口标识，每次创建窗口时由Windows所赋予的一个数字）
+ **_buttonItemData**：当点击按钮的子项菜单或右键菜单时，保存所对应按钮的操作项data数据。下图显示了，当点击“菜单3”时，数据的对应关系。
+ **_buttonItemTitle**：按钮所对应操作项的标题。
+ **_buttonItemAll**：当操作项以文本缩进方式定义时，返回对应的原始文本。
+ **_buttonItem**：按钮所对应的操作项对象，类型为CommonOperationItem。
# 显示操作窗并等待关闭
显示并等待操作窗关闭后再继续后面的步骤。
### 返回所点击的按钮
此方式时，支持输出所点击的用于关闭窗口的操作项数据。
如下图，使用`operation=close`定义了两个用于关闭窗口的按钮，并通过`data`参数定义了关联的数据。
如果通过点击这两个按钮关闭窗口，即可从“选择的操作项数据”中得到对应的操作项的`data`参数（`关闭1`或`关闭2`)。
如果通过点击窗口右上角的关闭按钮或双击窗口空白区域等方式关闭窗口，步骤会执行失败。（此时如果需要继续执行动作，需要取消`失败后停止`选项）。
# 关闭操作窗
通过指定“窗口标识”的方式，关闭前面步骤打开的操作窗。
# 注意事项
1）尽量避免在Quicker的窗口上使用自定义操作窗。
同一个进程的窗口会互相抢占焦点，在操作窗里模拟的按键消息，可能会作用到操作窗自身，从而导致一些意外的情况。（如模拟空格，会导致再次按下操作窗按钮，从而循环触发动作）。
# 更新历史
+ 20230105：
- 增加多行多列分组布局方式；
- 缩进格式增加Menu数据定义格式；
+ 20230111
- 增加注意事项。
+ 20230415：增加“默认Operation”的参数说明；增加【自动关联进程】【自动折叠】参数说明。
+ 20230505：增加缩进格式的注释说明。
+ 20230525：增加绑定多个进程的说明。
+ 20230908：1.39.24 增加为单独按钮设置字体和边框颜色功能。
+ 20230916：1.39.32
- 增加“默认的按钮右键菜单”参数。
- 支持为子程序传递按钮的操作项信息。
- 文档增加“调用子程序并传递参数”章节。
+ 20231202：1.40.16 按钮支持.width, .height的说明。
+ 20240109: 增加如何重置状态的说明。
+ 20241122：完善文字。
+ 20241219：增加_groupData子程序参数。