Skip to content

Commit 1daf092

Browse files
committed
feat: add FormCancelReason for GuiAPI
1 parent 52a943f commit 1daf092

File tree

10 files changed

+395
-388
lines changed

10 files changed

+395
-388
lines changed

docs/apis/GuiAPI/Form.md

Lines changed: 76 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
> This API allows you to create, modify or affect the **GUI interface** in the game.
44
5-
Obviously, the clear and intuitive UI interface helps players quickly get started with the use of plugins and provides a good user experience.
5+
Obviously, the clear and intuitive UI interface helps players quickly get started with the use of plugins and provides a
6+
good user experience.
67

78
## 📊 Form Related API
89

@@ -14,65 +15,67 @@ A modal form contains a title, a text display, and two buttons.
1415

1516
`pl.sendModalForm(title,content,confirmButton,cancelButton,callback)`
1617

17-
- Parameters:
18-
- title : `String`
19-
Form title.
20-
- content : `String`
21-
Form content.
22-
- confirmButton : `String`
23-
Button 1 text.
24-
- cancelButton : `String`
25-
Button 2 text.
26-
- callback : `Function`
27-
Function called after player clicks a button.
28-
- Return value: The ID of the sent form.
18+
- Parameters:
19+
- title : `String`
20+
Form title.
21+
- content : `String`
22+
Form content.
23+
- confirmButton : `String`
24+
Button 1 text.
25+
- cancelButton : `String`
26+
Button 2 text.
27+
- callback : `Function`
28+
Function called after player clicks a button.
29+
- Return value: The ID of the sent form.
2930
- Return value type: `Integer`
30-
- If the return value is `Null`, it means the sending failed.
31+
- If the return value is `Null`, it means the sending failed.
3132

32-
- Parameter `callback` The callback function prototype: `function(player,result)`
33-
34-
- player : `Player`
35-
The player object that interacts with the form.
36-
37-
- result : `Boolean`
38-
Player clicks **Confirm** button is `true`, **Cancel** button is `false`.
39-
40-
If the id is `Null`, the player cancels the form.
41-
42-
43-
44-
### Send a Normal Form to the Player
45-
46-
A normal form contains a title, a text display box and several buttons, and the icon displayed on the button can be set.
47-
Due to the relatively complex content setup of buttons, it is recommended to use the form builder API in the next section to better accomplish this task.
33+
Parameter `callback` The callback function prototype: `function(player,result,reason)`
34+
- player : `Player`
35+
The player object that interacts with the form.
36+
- result : `Boolean`
37+
Player clicks **Confirm** button is `true`, **Cancel** button is `false`.
38+
If the id is `Null`, the player cancels the form.
39+
- reason : `Integer`
40+
The reason why the form is closed.
41+
0 = UserClosed, 1 = UserBusy
42+
The reason may be `null`.
43+
44+
### Send a Normal Form to the Player
45+
46+
A normal form contains a title, a text display box and several buttons, and the icon displayed on the button can be
47+
set.
48+
Due to the relatively complex content setup of buttons, it is recommended to use the form builder API in the next
49+
section to better accomplish this task.
4850

4951
`pl.sendSimpleForm(title,content,buttons,images,callback)`
5052

51-
- Parameters:
52-
53-
- title : `String`
54-
Form title.
55-
- content : `String`
56-
Form Content.
57-
- buttons : `Array<String,String,...>`
58-
String array of individual button texts.
59-
- images : `Array<String,String,...>`
60-
Image path corresponding to each button.
61-
- callback : `Function`
62-
The function called after the player clicks a button.
63-
- Return value: The sent form ID.
53+
- Parameters:
54+
55+
- title : `String`
56+
Form title.
57+
- content : `String`
58+
Form Content.
59+
- buttons : `Array<String,String,...>`
60+
String array of individual button texts.
61+
- images : `Array<String,String,...>`
62+
Image path corresponding to each button.
63+
- callback : `Function`
64+
The function called after the player clicks a button.
65+
- Return value: The sent form ID.
6466
- Return value type: `Integer`
65-
- If the return value is `Null`, it means the sending failed.
66-
67-
Parameter `callback` The callback function prototype: `function(player,id)`
67+
- If the return value is `Null`, it means the sending failed.
6868

69+
Parameter `callback` The callback function prototype: `function(player,id,reason)`
6970
- player : `Player`
70-
The player object that interacts with the form.
71+
The player object that interacts with the form.
7172
- id : `Integer`
72-
The serial number of the form button that the player clicked, starting from 0.
73-
If the id is `Null`, the player cancels the form.
74-
75-
73+
The serial number of the form button that the player clicked, starting from 0.
74+
If the id is `Null`, the player cancels the form.
75+
- reason : `Integer`
76+
The reason why the form is closed.
77+
0 = UserClosed, 1 = UserBusy
78+
The reason may be `null`.
7679

7780
Use the texture pack path or URL `images` to identify the icon corresponding to the button.
7881
For each button on the form, set the corresponding icon as follows:
@@ -81,30 +84,33 @@ For each button on the form, set the corresponding icon as follows:
8184
2. If you use a URL path, you can put the full URL here, like `https://www.baidu.com/img/flexible/logo/pc/result.png`
8285
3. If you don't need to display an image for this button, set the corresponding image path to an empty string.
8386

84-
85-
86-
### Send Custom Form to Player (JSON Format)
87+
### Send Custom Form to Player (JSON Format)
8788

8889
Custom forms can contain rich custom controls.
89-
Since the relevant JSON definition format is relatively complex, it is recommended to use the form builder API in the next section to better accomplish this task.
90+
Since the relevant JSON definition format is relatively complex, it is recommended to use the form builder API in the
91+
next section to better accomplish this task.
9092

9193
`pl.sendCustomForm(json,callback)`
9294

93-
- Parameters:
94-
- json : `String`
95-
Custom form JSON string.
96-
- callback : `Function`
97-
Callback function to be called after the player submits the form.
98-
- Return value: The sent form ID.
99-
- Return value type: `Integer`
100-
- If the return value is Null, it means the sending failed.
101-
102-
Parameter `callback` The callback function prototype: `function(player,data)`
95+
- Parameters:
96+
- json : `String`
97+
Custom form JSON string.
98+
- callback : `Function`
99+
Callback function to be called after the player submits the form.
100+
- Return value: The sent form ID.
101+
- Return value type: `Integer`
102+
- If the return value is Null, it means the sending failed.
103103

104+
Parameter `callback` The callback function prototype: `function(player,data)`
104105
- player : `Player`
105-
The player object that interacts with the form.
106+
The player object that interacts with the form.
106107
- data : `Array<...>`
107-
The returned form content array.
108-
In the array, the first item must be `Null`, starting from the second item, the content of each control is stored in the order of the controls on the form.
109-
If data is only `Null`, the player cancels the form.
110-
108+
The returned form content array.
109+
In the array, the first item must be `Null`, starting from the second item, the content of each control is stored
110+
in
111+
the order of the controls on the form.
112+
If data is only `Null`, the player cancels the form.
113+
- reason : `Integer`
114+
The reason why the form is closed.
115+
0 = UserClosed, 1 = UserBusy
116+
The reason may be `null`.

docs/apis/GuiAPI/Form.zh.md

Lines changed: 56 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -15,33 +15,32 @@
1515
`pl.sendModalForm(title,content,confirmButton,cancelButton,callback)`
1616

1717
- 参数:
18-
- title : `String`
19-
表单标题
20-
- content : `String`
21-
表单内容
22-
- confirmButton : `String`
23-
按钮1文本的字符串
24-
- cancelButton : `String`
25-
按钮2文本的字符串
26-
- callback : `Function`
27-
玩家点击按钮之后被调用的回调函数。
28-
- 返回值:发送的表单ID
18+
- title : `String`
19+
表单标题
20+
- content : `String`
21+
表单内容
22+
- confirmButton : `String`
23+
按钮1文本的字符串
24+
- cancelButton : `String`
25+
按钮2文本的字符串
26+
- callback : `Function`
27+
玩家点击按钮之后被调用的回调函数。
28+
- 返回值:发送的表单ID
2929
- 返回值类型:`Integer`
30-
- 如果返回值为`Null`,则代表发送失败
31-
32-
- 参数`callback`的回调函数原型:`function(player,result)`
33-
34-
- player : `Player`
35-
与表单互动的玩家对象
36-
37-
- result : `Boolean`
38-
玩家点击**确定**按钮为`true`**取消**按钮为`false`
39-
40-
如果id为`Null`,则代表玩家取消了表单
41-
30+
- 如果返回值为`Null`,则代表发送失败
4231

32+
参数`callback`的回调函数原型:`function(player,result,reason)`
33+
- player : `Player`
34+
与表单互动的玩家对象
35+
- result : `Boolean`
36+
玩家点击**确定**按钮为`true`**取消**按钮为`false`
37+
如果id为`Null`,则代表玩家取消了表单
38+
- reason : `Integer`
39+
表单被取消的原因
40+
0 = UserClosed, 1 = UserBusy
41+
reason可能会是`null`.
4342

44-
### 向玩家发送普通表单
43+
### 向玩家发送普通表单
4544

4645
普通表单包含一个标题、一个文本显示框以及若干按钮,可以设置按钮上显示的图标
4746
由于按钮的内容设置相对复杂,建议使用下一节的表单构建器API更好地完成这项任务。
@@ -50,29 +49,30 @@
5049

5150
- 参数:
5251

53-
- title : `String`
54-
表单标题
55-
- content : `String`
56-
表单内容
57-
- buttons : `Array<String,String,...>`
58-
各个按钮文本的字符串数组
59-
- images : `Array<String,String,...>`
60-
各个按钮对应的图片路径
61-
- callback : `Function`
62-
玩家点击按钮之后被调用的回调函数。
63-
- 返回值:发送的表单ID
52+
- title : `String`
53+
表单标题
54+
- content : `String`
55+
表单内容
56+
- buttons : `Array<String,String,...>`
57+
各个按钮文本的字符串数组
58+
- images : `Array<String,String,...>`
59+
各个按钮对应的图片路径
60+
- callback : `Function`
61+
玩家点击按钮之后被调用的回调函数。
62+
- 返回值:发送的表单ID
6463
- 返回值类型:`Integer`
65-
- 如果返回值为`Null`,则代表发送失败
66-
67-
参数`callback`的回调函数原型:`function(player,id)`
64+
- 如果返回值为`Null`,则代表发送失败
6865

66+
参数`callback`的回调函数原型:`function(player,id,reason)`
6967
- player : `Player`
70-
与表单互动的玩家对象
68+
与表单互动的玩家对象
7169
- id : `Integer`
72-
玩家点击的表单按钮的序号,从0开始编号
73-
如果id为`Null`,则代表玩家取消了表单
74-
75-
70+
玩家点击的表单按钮的序号,从0开始编号
71+
如果id为`Null`,则代表玩家取消了表单
72+
- reason : `Integer`
73+
表单被取消的原因
74+
0 = UserClosed, 1 = UserBusy
75+
reason可能会是`null`.
7676

7777
图片路径参数 `images` 使用材质包路径或者URL来标识按钮对应的图标。
7878
对于表单上的每个按钮,如下设置对应的图标
@@ -81,30 +81,31 @@
8181
2. 如果使用URL路径,那么在这里放入完整的URL即可,形如 `https://www.baidu.com/img/flexible/logo/pc/result.png`
8282
3. 如果这个按钮你不需要显示图片,那将对应的图片路径设置为空字符串即可
8383

84-
85-
86-
### 向玩家发送自定义表单(JSON格式)
84+
### 向玩家发送自定义表单(JSON格式)
8785

8886
自定义表单可以包含丰富的自定义控件。
8987
由于相关JSON定义格式相对复杂,建议使用下一节的表单构建器API更好地完成这项任务。
9088

9189
`pl.sendCustomForm(json,callback)`
9290

9391
- 参数:
94-
- json : `String`
95-
自定义表单json字符串
96-
- callback : `Function`
97-
玩家提交表单之后被调用的回调函数。
98-
- 返回值:发送的表单ID
99-
- 返回值类型:`Integer`
100-
- 如果返回值为`Null`,则代表发送失败
92+
- json : `String`
93+
自定义表单json字符串
94+
- callback : `Function`
95+
玩家提交表单之后被调用的回调函数。
96+
- 返回值:发送的表单ID
97+
- 返回值类型:`Integer`
98+
- 如果返回值为`Null`,则代表发送失败
10199

102-
参数`callback`的回调函数原型:`function(player,data)`
100+
参数`callback`的回调函数原型:`function(player,data,reason)`
103101

104102
- player : `Player`
105103
与表单互动的玩家对象
106104
- data : `Array<...>`
107105
返回的表单内容数组
108106
数组中,第一项一定为`Null`,从第二项开始,按表单上的控件顺序储存了每一个控件的内容
109107
如果data只为`Null`,则代表玩家取消了表单
110-
108+
- reason : `Integer`
109+
表单被取消的原因
110+
0 = UserClosed, 1 = UserBusy
111+
reason可能会是`null`.

0 commit comments

Comments
 (0)