Finish adding the documentation for the DialogManager
Eldritch-Oliver
parent
b7d50e5198
commit
1d23b37f7d
1 changed files with 107 additions and 2 deletions
|
|
@ -1,3 +1,108 @@
|
||||||
The Dialog Manager is an API exposed by the module to help make writing macros that ask for information easier to write.
|
The Dialog Manager is an API exposed by the module to help make writing macros that ask for information from the player easier to write. It can be accessed globally by referencing `taf.DialogManager`.
|
||||||
|
|
||||||
## Interface
|
## Interface
|
||||||
|
|
||||||
|
### `DialogManager.ask`
|
||||||
|
> DialogManager.ask(data: [AskConfig](#askconfig), options: [AskOptions](#askoptions)): Promise<[AskResult](#askresult)>
|
||||||
|
|
||||||
|
Opens a dialog that prompts the user for a set of information. This is intended to be primarily used within macros. If there is an already-open dialog for the ID provided in the `data` parameter, that dialog will be focused instead of creating a new dialog.
|
||||||
|
|
||||||
|
The promise returned from this function does not always mean that the user has submitted the full amount of data, in order to determine if the user submitted data or not, you must check the `state` property of the [AskResult](#askresult).
|
||||||
|
|
||||||
|
### `DialogManager.close`
|
||||||
|
> DialogManager.close(id: string): void
|
||||||
|
|
||||||
|
Closes the specified dialog if it is open, if it isn't open it will do nothing.
|
||||||
|
|
||||||
|
### `DialogManager.size`
|
||||||
|
> DialogManager.size
|
||||||
|
|
||||||
|
Returns a count of how many currently open unique dialogs there are.
|
||||||
|
|
||||||
|
## Types
|
||||||
|
|
||||||
|
### `AskConfig`
|
||||||
|
|
||||||
|
| Property | Type | Description
|
||||||
|
| -------- | ---- | -----------
|
||||||
|
| `id` | `string` | A unique ID. Using the same ID for different sets of data will result in only getting one back.
|
||||||
|
| `description` | `string?` | A description that is displayed in the dialog above all of the inputs.
|
||||||
|
| `inputs` | [AskInput](#askinput)[] | An array of data that is requested by the user. At least one must be provided, but there is no upper limit on the amount allowed.
|
||||||
|
|
||||||
|
### `AskInput`
|
||||||
|
|
||||||
|
| Property | Type | Description
|
||||||
|
| -------- | ---- | -----------
|
||||||
|
| `id` | `string?` | A unique ID for this input. This is used to associate labels to the inputs, it is recommended to not provide it, however you are able to if there is a need for it. If it is not provided it will default to a random ID.
|
||||||
|
| `key` | `string?` | A unique identifier that will be used as the object key when the promise is resolved with answers. If this is not provided it will be the same as `label`.
|
||||||
|
| `autofocus` | `boolean?` | Whether or not to autofocus this input. Only the first input with autofocus set to true will be focused.
|
||||||
|
| `type` | [InputType](#inputtype) | What type this input represents, the rest of the properties in this object are determined based on the type provided.
|
||||||
|
|
||||||
|
### `InputType`
|
||||||
|
This type represents a string with any of the following values:
|
||||||
|
- [`checkbox`](#checkbox)
|
||||||
|
- [`details`](#details)
|
||||||
|
- [`divider`](#divider)
|
||||||
|
- [`input`](#input)
|
||||||
|
- [`select`](#select)
|
||||||
|
|
||||||
|
#### `Checkbox`
|
||||||
|
| Property | Type | Description
|
||||||
|
| -------- | ---- | -----------
|
||||||
|
| `label` | `string` | The user-facing label for the input.
|
||||||
|
| `defaultValue` | `boolean?` | The default value for the input, if not provided it defaults to `false`.
|
||||||
|
|
||||||
|
#### `details`
|
||||||
|
Used to display a simple paragraph of text in between inputs.
|
||||||
|
|
||||||
|
| Property | Type | Description
|
||||||
|
| -------- | ---- | -----------
|
||||||
|
| `details` | `string` | The text that should be displayed.
|
||||||
|
|
||||||
|
#### `divider`
|
||||||
|
Used to display a horizontal divider between inputs.
|
||||||
|
|
||||||
|
#### `input`
|
||||||
|
| Property | Type | Description
|
||||||
|
| -------- | ---- | -----------
|
||||||
|
| `label` | `string` | The user-facing label for the input.
|
||||||
|
| `inputType` | `string` | The HTML-defined input type. See [HTML Input Types](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types) for more accepted values.
|
||||||
|
| `defaultValue` | `unknown?` | The HTML-serialized value for the input's initial value, in most cases this will either be a string or a number. If this is not provided, it defaults to an empty input.
|
||||||
|
| `valueAttribute` | `string?` | The HTML attribute name used on the input, if you don't know HTML, this property is best left out as the default will be what you want 99% of the time.
|
||||||
|
|
||||||
|
#### `select`
|
||||||
|
| Property | Type | Description
|
||||||
|
| -------- | ---- | -----------
|
||||||
|
| `label` | `string` | The user-facing label for the input.
|
||||||
|
| `defaultValue` | `string?` | The default value of the select.
|
||||||
|
| `options` | [SelectOption](#selectoption)[] | An array of valid options that can be picked from.
|
||||||
|
|
||||||
|
### `SelectOption`
|
||||||
|
| Property | Type | Description
|
||||||
|
| -------- | ---- | -----------
|
||||||
|
| `value` | `string`,`number` | The value that will be submitted if this option is selected.
|
||||||
|
| `label` | `string?` | The user-friendly label to display for the option. If not provided this defaults to the same value as `value`.
|
||||||
|
| `disabled` | `boolean?` | Whether or not the user is capable of selecting this option.
|
||||||
|
|
||||||
|
### `AskOptions`
|
||||||
|
|
||||||
|
| Property | Type | Default | Description
|
||||||
|
| -------- | ---- | ------- | -----------
|
||||||
|
| `onlyOneWaiting` | `boolean?` | `true` | When this is set to false, the `ask` method will return the same Promise that was returned the first time that the method was called with the ID provided, resulting in potentially multiple macros executions doing the same thing once the data is submitted. If this is set to true it will instead resolve a different promise with a different return value (see [AskResult](#askresult) for more details about the differences).
|
||||||
|
| `alwaysUseAnswerObject` | `boolean?` | `true` | When this is set to false, and the dialog only has one value being submitted, it will instead resolve the answers object to the single value instead of an object. Setting this to true makes the resolution always use the object form, providing an object with a single key-value pair in it instead of just the value.
|
||||||
|
|
||||||
|
### `AskResult`
|
||||||
|
| Property | Type | Description
|
||||||
|
| -------- | ---- | -----------
|
||||||
|
| `state` | [ResultState](#resultstate) | A value describing what happened with the dialog.
|
||||||
|
| `answers` | `object?`,`string?`,`number?` | The data that the user submitted in the form. The type of this depends on the `state` and the [AskOptions](#askoptions) provided.
|
||||||
|
| `error` | `string?` | The error message detailing what was wrong. Only present when `state` is `errored`.
|
||||||
|
|
||||||
|
#### `ResultState`
|
||||||
|
This type represents an enum of the following values.
|
||||||
|
|
||||||
|
| Value | Meaning
|
||||||
|
| ----- | -------
|
||||||
|
| `fronted` | The dialog was previously displayed and was focused for the user, but nothing else occurred.
|
||||||
|
| `prompted` | The user finished submitting the data requested in the dialog.
|
||||||
|
| `errored` | Something about the data provided to the method is invalid. See the error message in the returned data for more details about what was wrong.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue