selectTokens: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
No edit summary |
||
| (8 intermediate revisions by 4 users not shown) | |||
| Line 6: | Line 6: | ||
|usage= | |usage= | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
selectTokens() | selectTokens() | ||
</ | </syntaxhighlight> | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
selectTokens( | selectTokens(tokenRef, add) | ||
</ | </syntaxhighlight> | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
selectTokens(tokens, add, delim) | selectTokens(tokens, add, delim) | ||
</ | </syntaxhighlight> | ||
'''Parameter''' | '''Parameter''' | ||
* {{code| | * {{code|tokenRef}} - Either the token [[getSelected|{{code|id}}]] or [[getTokenName|Token Name]] of the token to select (the examples below use token ''names'', but IDs are also permitted); if left blank ''all'' visible tokens are selected. | ||
* {{code|add}} - if the value of add is {{code|true(1)}}, the selections will be added to the current set of selected tokens; if the value is {{code|false(0)}} currently selected tokens will be deselected before new tokens are selected. Defaults to false. | * {{code|add}} - if the value of add is {{code|true(1)}}, the selections will be added to the current set of selected tokens; if the value is {{code|false(0)}} currently selected tokens will be deselected before new tokens are selected. Defaults to false. | ||
* {{code|tokens}} - a [[String List]] of tokens to select. | * {{code|tokens}} - a [[String List]] of tokens to select. | ||
* {{code|delim}} - Specifies the delimiter used in the string list that is supplied. If the delimiter is "json", then the value for {{code| | * {{code|delim}} - Specifies the delimiter used in the string list that is supplied. If the delimiter is "json", then the value for {{code|tokens}} may be a [[JSON Array]] instead. '''Note: if using a JSON Array or String List, both {{code|add}} and {{code|delim}} must be specified.''' | ||
{{Note|Token IDs are unique, but Token Names can be duplicated. Using Token Name when more than one token has the same name can produce unexpected results.}} | |||
|example= | |example= | ||
To select a single token with the name "Adventurer": | To select a single token with the name "Adventurer": | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[h:selectTokens("Adventurer")] | [h:selectTokens("Adventurer")] | ||
</ | </syntaxhighlight> | ||
To select a list of [[Token]]s using a [[String List]], replacing the current selection | To select a list of [[Token]]s using a [[String List]], replacing the current selection | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[h:selectTokens("Adventurer, Orc 2, Goblin 1", 0, ",")] | [h:selectTokens("Adventurer, Orc 2, Goblin 1", 0, ",")] | ||
</ | </syntaxhighlight> | ||
To select a list of [[Token]]s using a [[JSON Array]], adding the specified tokens to the current set of selected [[Token]]s: | To select a list of [[Token]]s using a [[JSON Array]], adding the specified tokens to the current set of selected [[Token]]s: | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[h:selectTokens("['Adventurer', 'Orc 2', 'Goblin 1']", 1, "json")] | [h:selectTokens("['Adventurer', 'Orc 2', 'Goblin 1']", 1, "json")] | ||
</ | </syntaxhighlight> | ||
|also= | |||
[[deselectTokens|deselectTokens()]], | |||
[[getSelected|getSelected()]], | |||
[[getSelectedNames|getSelectedNames()]] | |||
|changes= | |changes= | ||
Latest revision as of 23:59, 22 May 2024
selectTokens() Function
• Introduced in version 1.3b68
Selects one or more visible tokens on the map.
Usage
selectTokens()selectTokens(tokenRef, add)selectTokens(tokens, add, delim)Parameter
tokenRef- Either the tokenidor Token Name of the token to select (the examples below use token names, but IDs are also permitted); if left blank all visible tokens are selected.add- if the value of add istrue(1), the selections will be added to the current set of selected tokens; if the value isfalse(0)currently selected tokens will be deselected before new tokens are selected. Defaults to false.tokens- a String List of tokens to select.delim- Specifies the delimiter used in the string list that is supplied. If the delimiter is "json", then the value fortokensmay be a JSON Array instead. Note: if using a JSON Array or String List, bothaddanddelimmust be specified.
Token IDs are unique, but Token Names can be duplicated. Using Token Name when more than one token has the same name can produce unexpected results.
Example
To select a single token with the name "Adventurer":
[h:selectTokens("Adventurer")]To select a list of Tokens using a String List, replacing the current selection
[h:selectTokens("Adventurer, Orc 2, Goblin 1", 0, ",")]To select a list of Tokens using a JSON Array, adding the specified tokens to the current set of selected Tokens:
[h:selectTokens("['Adventurer', 'Orc 2', 'Goblin 1']", 1, "json")]See Also
Version Changes
- 1.3b68 - Function added.