Skip to content

Commit

Permalink
feat: add FormCancelReason for GuiAPI
Browse files Browse the repository at this point in the history
  • Loading branch information
@ShrBox
ShrBox committed Jan 23, 2025
1 parent 52a943f commit 1daf092
Show file tree
Hide file tree
Showing 10 changed files with 395 additions and 388 deletions.
146 changes: 76 additions & 70 deletions docs/apis/GuiAPI/Form.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

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

## 📊 Form Related API

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

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

- Parameters:
- title : `String`
Form title.
- content : `String`
Form content.
- confirmButton : `String`
Button 1 text.
- cancelButton : `String`
Button 2 text.
- callback : `Function`
Function called after player clicks a button.
- Return value: The ID of the sent form.
- Parameters:
- title : `String`
Form title.
- content : `String`
Form content.
- confirmButton : `String`
Button 1 text.
- cancelButton : `String`
Button 2 text.
- callback : `Function`
Function called after player clicks a button.
- Return value: The ID of the sent form.
- Return value type: `Integer`
- If the return value is `Null`, it means the sending failed.
- If the return value is `Null`, it means the sending failed.

- Parameter `callback` The callback function prototype: `function(player,result)`

- player : `Player`
The player object that interacts with the form.

- result : `Boolean`
Player clicks **Confirm** button is `true`, **Cancel** button is `false`.

If the id is `Null`, the player cancels the form.



### Send a Normal Form to the Player

A normal form contains a title, a text display box and several buttons, and the icon displayed on the button can be set.
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.
Parameter `callback` The callback function prototype: `function(player,result,reason)`
- player : `Player`
The player object that interacts with the form.
- result : `Boolean`
Player clicks **Confirm** button is `true`, **Cancel** button is `false`.
If the id is `Null`, the player cancels the form.
- reason : `Integer`
The reason why the form is closed.
0 = UserClosed, 1 = UserBusy
The reason may be `null`.

### Send a Normal Form to the Player

A normal form contains a title, a text display box and several buttons, and the icon displayed on the button can be
set.
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.

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

- Parameters:

- title : `String`
Form title.
- content : `String`
Form Content.
- buttons : `Array<String,String,...>`
String array of individual button texts.
- images : `Array<String,String,...>`
Image path corresponding to each button.
- callback : `Function`
The function called after the player clicks a button.
- Return value: The sent form ID.
- Parameters:

- title : `String`
Form title.
- content : `String`
Form Content.
- buttons : `Array<String,String,...>`
String array of individual button texts.
- images : `Array<String,String,...>`
Image path corresponding to each button.
- callback : `Function`
The function called after the player clicks a button.
- Return value: The sent form ID.
- Return value type: `Integer`
- If the return value is `Null`, it means the sending failed.

Parameter `callback` The callback function prototype: `function(player,id)`
- If the return value is `Null`, it means the sending failed.

Parameter `callback` The callback function prototype: `function(player,id,reason)`
- player : `Player`
The player object that interacts with the form.
The player object that interacts with the form.
- id : `Integer`
The serial number of the form button that the player clicked, starting from 0.
If the id is `Null`, the player cancels the form.


The serial number of the form button that the player clicked, starting from 0.
If the id is `Null`, the player cancels the form.
- reason : `Integer`
The reason why the form is closed.
0 = UserClosed, 1 = UserBusy
The reason may be `null`.

Use the texture pack path or URL `images` to identify the icon corresponding to the button.
For each button on the form, set the corresponding icon as follows:
Expand All @@ -81,30 +84,33 @@ For each button on the form, set the corresponding icon as follows:
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`
3. If you don't need to display an image for this button, set the corresponding image path to an empty string.



### Send Custom Form to Player (JSON Format)
### Send Custom Form to Player (JSON Format)

Custom forms can contain rich custom controls.
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.
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.

`pl.sendCustomForm(json,callback)`

- Parameters:
- json : `String`
Custom form JSON string.
- callback : `Function`
Callback function to be called after the player submits the form.
- Return value: The sent form ID.
- Return value type: `Integer`
- If the return value is Null, it means the sending failed.

Parameter `callback` The callback function prototype: `function(player,data)`
- Parameters:
- json : `String`
Custom form JSON string.
- callback : `Function`
Callback function to be called after the player submits the form.
- Return value: The sent form ID.
- Return value type: `Integer`
- If the return value is Null, it means the sending failed.

Parameter `callback` The callback function prototype: `function(player,data)`
- player : `Player`
The player object that interacts with the form.
The player object that interacts with the form.
- data : `Array<...>`
The returned form content array.
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.
If data is only `Null`, the player cancels the form.

The returned form content array.
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.
If data is only `Null`, the player cancels the form.
- reason : `Integer`
The reason why the form is closed.
0 = UserClosed, 1 = UserBusy
The reason may be `null`.
111 changes: 56 additions & 55 deletions docs/apis/GuiAPI/Form.zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,33 +15,32 @@
`pl.sendModalForm(title,content,confirmButton,cancelButton,callback)`

- 参数：
- title : `String`
表单标题
- content : `String`
表单内容
- confirmButton : `String`
按钮1文本的字符串
- cancelButton : `String`
按钮2文本的字符串
- callback : `Function`
玩家点击按钮之后被调用的回调函数。
- 返回值：发送的表单ID
- title : `String`
表单标题
- content : `String`
表单内容
- confirmButton : `String`
按钮1文本的字符串
- cancelButton : `String`
按钮2文本的字符串
- callback : `Function`
玩家点击按钮之后被调用的回调函数。
- 返回值：发送的表单ID
- 返回值类型：`Integer`
- 如果返回值为`Null`，则代表发送失败

- 参数`callback`的回调函数原型：`function(player,result)`

- player : `Player`
与表单互动的玩家对象

- result : `Boolean`
玩家点击**确定**按钮为`true`，**取消**按钮为`false`

如果id为`Null`，则代表玩家取消了表单

- 如果返回值为`Null`，则代表发送失败

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

### 向玩家发送普通表单
### 向玩家发送普通表单

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

- 参数：

- title : `String`
表单标题
- content : `String`
表单内容
- buttons : `Array<String,String,...>`
各个按钮文本的字符串数组
- images : `Array<String,String,...>`
各个按钮对应的图片路径
- callback : `Function`
玩家点击按钮之后被调用的回调函数。
- 返回值：发送的表单ID
- title : `String`
表单标题
- content : `String`
表单内容
- buttons : `Array<String,String,...>`
各个按钮文本的字符串数组
- images : `Array<String,String,...>`
各个按钮对应的图片路径
- callback : `Function`
玩家点击按钮之后被调用的回调函数。
- 返回值：发送的表单ID
- 返回值类型：`Integer`
- 如果返回值为`Null`，则代表发送失败

参数`callback`的回调函数原型：`function(player,id)`
- 如果返回值为`Null`，则代表发送失败

参数`callback`的回调函数原型：`function(player,id,reason)`
- player : `Player`
与表单互动的玩家对象
与表单互动的玩家对象
- id : `Integer`
玩家点击的表单按钮的序号，从0开始编号
如果id为`Null`，则代表玩家取消了表单


玩家点击的表单按钮的序号，从0开始编号
如果id为`Null`，则代表玩家取消了表单
- reason : `Integer`
表单被取消的原因
0 = UserClosed, 1 = UserBusy
reason可能会是`null`.

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



### 向玩家发送自定义表单（JSON格式）
### 向玩家发送自定义表单（JSON格式）

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

`pl.sendCustomForm(json,callback)`

- 参数：
- json : `String`
自定义表单json字符串
- callback : `Function`
玩家提交表单之后被调用的回调函数。
- 返回值：发送的表单ID
- 返回值类型：`Integer`
- 如果返回值为`Null`，则代表发送失败
- json : `String`
自定义表单json字符串
- callback : `Function`
玩家提交表单之后被调用的回调函数。
- 返回值：发送的表单ID
- 返回值类型：`Integer`
- 如果返回值为`Null`，则代表发送失败

参数`callback`的回调函数原型：`function(player,data)`
参数`callback`的回调函数原型：`function(player,data,reason)`

- player : `Player`
与表单互动的玩家对象
- data : `Array<...>`
返回的表单内容数组
数组中，第一项一定为`Null`，从第二项开始，按表单上的控件顺序储存了每一个控件的内容
如果data只为`Null`，则代表玩家取消了表单

- reason : `Integer`
表单被取消的原因
0 = UserClosed, 1 = UserBusy
reason可能会是`null`.
Loading

0 comments on commit 1daf092

Please sign in to comment.