getTokenStates: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
No edit summary
No edit summary
 
(9 intermediate revisions by 3 users not shown)
Line 3: Line 3:
|version=1.3b51
|version=1.3b51
|description=
|description=
Returns the valid states in the campaign settings in either a [[String List]] or [[JSON Array]].  
Returns the valid states in the campaign settings in either a [[String List]] or [[JSON Array]]. Alternatively, if a token id is specified, instead returns the list of the states that are set to {{true}} for the token.


|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
getTokenStates()
getTokenStates()
</source>
<source lang="mtmacro" line>
getTokenStates(delim)
getTokenStates(delim)
</source>
<source lang="mtmacro" line>
getTokenStates(delim, groupName)
getTokenStates(delim, groupName)
</source>
getTokenStates(delim, groupName, tokenRef)
getTokenStates(delim, groupName, tokenRef, mapRef)
</syntaxhighlight>
'''Parameter'''
'''Parameter'''
* {{code|delim}} - Specifies the delimiter used in the string list that is returned, defaultis {{code|","}}. If the value is set to {{code|json}}, the function returns a JSON array instead.
{{param|delim|Specifies the delimiter used in the string list that is returned, default is {{code|","}}. If the value is set to {{code|json}}, the function returns a JSON array instead.}}
* {{code|groupName}} - Specifies the name of the group to get the states for. '''Note that if you wish to use the {{code|groupname}} parameter, you MUST set a delimiter.
{{param|groupName|Specifies the name of the group to get the states for. If set to "*", get all states.}}
{{param|tokenRef|Either the token [[getSelected|{{code|id}}]] or [[getTokenName|Token Name]] of the token to get the states set to {{true}}. If the parameter is not used, instead returns all valid states in the campaign settings. {{TrustedParameter}} }}
{{param|mapRef|The Name or ID of the map where the token is. Set to the current map by default.}}
{{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 get a [[String List]] of the valid [[Token State]]s in the campaign.
To get a [[String List]] of the valid [[Token State]]s in the campaign.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: states = getTokenStates()]
[h: states = getTokenStates()]
</source>
</syntaxhighlight>


To get a [[JSON Array]] of the valid [[Token State]]s in the campaign.
To get a [[JSON Array]] of the valid [[Token State]]s in the campaign.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: states = getTokenStates("json")]
[h: states = getTokenStates("json")]
</source>
</syntaxhighlight>


To get a [[JSON Array]] of the valid [[Token State]]s in the ''Damage'' group in the campaign in 1.3b55 or later.
To get a [[JSON Array]] of the valid [[Token State]]s in the ''Damage'' group in the campaign in 1.3b55 or later.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: states = getTokenStates("json", "Damage")]
[h: states = getTokenStates("json", "Damage")]
</source>
</syntaxhighlight>


To get a [[JSON Array]] of the [[Token State]]s set to {{true}} for the "Dragon" token:
<syntaxhighlight lang="mtmacro" line>
[h: states = getTokenStates("json", "*", "Dragon")]
</syntaxhighlight>




|changes=
|changes=
* '''1.3b55''' - Added the {{code|groupName}} parameter.
{{change|1.3b55|Added the {{code|groupName}} parameter.}}
{{change|1.5.7|Added {{code|id}} and {{code|mapname}} parameter options.}}


}}
}}
[[Category:State Function]]
[[Category:State Function]]

Latest revision as of 23:59, 11 May 2024

getTokenStates() Function

• Introduced in version 1.3b51
Returns the valid states in the campaign settings in either a String List or JSON Array. Alternatively, if a token id is specified, instead returns the list of the states that are set to true(1) for the token.

Usage

getTokenStates()
getTokenStates(delim)
getTokenStates(delim, groupName)
getTokenStates(delim, groupName, tokenRef)
getTokenStates(delim, groupName, tokenRef, mapRef)

Parameter

  • delim - Specifies the delimiter used in the string list that is returned, default is ",". If the value is set to json, the function returns a JSON array instead.
  • groupName - Specifies the name of the group to get the states for. If set to "*", get all states.
  • tokenRef - Either the token id or Token Name of the token to get the states set to true(1). If the parameter is not used, instead returns all valid states in the campaign settings.

     Note: This parameter can only be used in a Trusted Macro. 

  • mapRef - The Name or ID of the map where the token is. Set to the current map by default.
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 get a String List of the valid Token States in the campaign. 
[h: states = getTokenStates()]

To get a JSON Array of the valid Token States in the campaign. 

[h: states = getTokenStates("json")]

To get a JSON Array of the valid Token States in the Damage group in the campaign in 1.3b55 or later. 

[h: states = getTokenStates("json", "Damage")]

To get a JSON Array of the Token States set to true(1) for the "Dragon" token: 

[h: states = getTokenStates("json", "*", "Dragon")]


Version Changes

  • 1.3b55 - Added the groupName parameter.
  • 1.5.7 - Added id and mapname parameter options.
Retrieved from "https://rptools.hyperbooks.com/index.php?title=getTokenStates&oldid=35093"