setMacroProps: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
mNo edit summary
mNo edit summary
 
(15 intermediate revisions by 7 users not shown)
Line 2: Line 2:
|name=setMacroProps
|name=setMacroProps
|version=1.3b48
|version=1.3b48
|description=
|description=Sets the properties for the specified [[Token:Macro Button|Macro Button]] on the given token. The properties are passed to this function as a [[String Property List]]. This function accepts either a [[getMacroButtonIndex|Macro Button Index]] or the label of a Macro Button. If it is a label, then all Macro Buttons on the token with a matching label are changed.
Sets the properties for the specified [[Token:Macro Button|Macro Button]] on the [[Token:Current Token|Current Token]] . The properties are passed to this function as a [[Macros:string_property_list|String Property List]]. This function accepts either a [[Token:Macro Button Index|Macro Button Index]] or the label of a [[Token:Macro Button|Macro Button]]. If it is a label then all of [[Token:Macro Button|Macro Button]]s on the [[Token:Current Token|Current Token]] with a matching label are changed. If the delimiter is not specified then the default value of ";" is used. As of MapTool 1.3b49 setMacroProps() accepts a [[Macros:json object|json object]] containing the button properties, no delimiter needs to be specified in this case.
 
'''Valid Properties for Macro Buttons'''
* {{code|applyToSelected}} - Should the macro be applied to the selected tokens.
* {{code|autoExec}} - If the macro will be automatically executed when the button is clicked, accepts {{true}} or {{false}}.
* {{code|color}} - The name of the color for the button.
* {{code|command}} - The command for the macro (only when using JSON version of function).
* {{code|fontColor}} - The name of the font color for the button.
* {{code|fontSize}} - The size of the font for the button.
* {{code|includeLabel}} - If the label will be output when the button is clicked. Accepts {{true}} or {{false}}.
* {{code|group}} - The name of the group that the button belongs to.
* {{code|sortBy}} - The sort by value of the macro button.
* {{code|label}} - The label for the button.
* {{code|maxWidth}} - The maximum width of the button.
* {{code|minWidth}} - The minimum width of the button.
* {{code|playerEditable}} - Is the button player editable, accepts {{true}} or {{false}}.
* {{code|tooltip}} - The tool tip for the macro button.
* {{code|compare}} - Takes a [[JSON array]] which can contain one or more of the following keywords (only usable with JSON version of the function).
** {{code|applyToSelected}} - Use the macro applyToSelected for common macro comparisons.
** {{code|autoExec}} - Use the macro autoExec for common macro comparisons.
** {{code|command}} - Use the macro command for common macro comparisons.
** {{code|group}} - Use the macro group for common macro comparisons.
** {{code|includeLabel}} - Use the macro includeLabel for common macro comparisons.
** {{code|sortPrefix}} - Use the macro sortPrefix for common macro comparisons.
 


|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
setMacroProps(index, props)
setMacroProps(index, props)
</source>
<source lang="mtmacro" line>
setMacroProps(index, props, delim)
setMacroProps(index, props, delim)
</source>
setMacroProps(index, props, delim, id)
<source lang="mtmacro" line>
setMacroProps(index, props, delim, id, mapRef)
</syntaxhighlight>
<syntaxhighlight lang="mtmacro" line>
setMacroProps(label, props)
setMacroProps(label, props)
</source>
<source lang="mtmacro" line>
setMacroProps(label, props, delim)
setMacroProps(label, props, delim)
</source>
setMacroProps(label, props, delim, id)
setMacroProps(label, props, delim, id, mapRef)
</syntaxhighlight>
'''Parameters'''
{{param|index|The index of the macro button.}}
{{param|label|The label of the macro button.}}
{{param|props|A [[String Property List]] or [[JSON Object]] containing the properties for the button.
** See {{func|createMacro}} for a complete list of properties.}}
{{param|delim|The delimiter used in the [[String Property List]] that is used in the {{code|props}} parameter.  Defaults to {{code|";"}} (semicolon) and can be omitted if you are sending a [[JSON Object]] as the {{code|props}} parameter. If you are sending a JSON object as the {{code|props}} parameter, and using the {{code|id}} parameter, you can set this to {{code|"json"}}.}}
{{param|id|OPTIONAL: The token {{code|id}} of the token that the macro button is located on. From v1.15, accepts "campaign" and "gm" as ids for the relevant panels.{{TrustedParameter}} }}
{{param|mapRef|The Name or ID of the map to find the token.  Defaults to the current map.}}


|example=
|example=
<source lang="mtmacro" line>
Changes the macro button to be red with white text.  First one is by index and the second one by label (name).
<syntaxhighlight lang="mtmacro" line>
[h: setMacroProps(1, "color=red;fontColor=white")]
[h: setMacroProps(1, "color=red;fontColor=white")]
[h: setMacroProps("Attack", "color=red;fontColor=white")]
[h: setMacroProps("Attack", "color=red;fontColor=white")]
</source>
</syntaxhighlight>
 
Somewhat silly example that changes the label (name) of the currently executing macro to the current time and randomly changes the button color.
<syntaxhighlight lang="mtmacro" line>
[h: color = listGet("Red, Blue, Green, White, Yellow, Orange", 1d6-1)]
[h: index = getMacroIndexes(getMacroName())]
[h: dt = json.get(getInfo("server"), "timeDate")]
[h: time = listGet(dt, 1, " ")]
[h: myProps = setStrProp("", "label", time)]
[h: myProps = setStrProp(myProps, "color", color)]
[h: setMacroProps(index, myprops)]
</syntaxhighlight>


|changes=
|changes=
{{change|1.3b49|Added ability for {{code|props}} to accept a JSON object.}}
{{change|1.3b49|Added ability for {{code|props}} to accept a JSON object.}}
{{change|1.3b53|Added ability for {{code|command}}, {{code|compare}}, {{code|playerEditable}}, {{code|applyToSelected}}, {{code|autoExec}}, {{code|group}}, and {{code|tooltip}} parameters.}}
{{change|1.3b51|Added {{code|id}} parameter option.}}
 
{{change|1.3b53|Added ability for {{code|command}}, {{code|compare}}, {{code|playerEditable}}, {{code|applyToSelected}}, {{code|autoExecute}}, {{code|group}}, and {{code|tooltip}} parameters.}}
{{change|1.5.11|Added {{code|mapname}} parameter option.}}
{{change|1.15|Addition of "gm" and "campaign" options for id}}
}}
}}
[[Category:Metamacro Function]]
[[Category:Metamacro Function]][[Category:Macro Function]]

Latest revision as of 23:59, 17 March 2024

setMacroProps() Function

• Introduced in version 1.3b48
Sets the properties for the specified Macro Button on the given token. The properties are passed to this function as a String Property List. This function accepts either a Macro Button Index or the label of a Macro Button. If it is a label, then all Macro Buttons on the token with a matching label are changed.

Usage

setMacroProps(index, props)
setMacroProps(index, props, delim)
setMacroProps(index, props, delim, id)
setMacroProps(index, props, delim, id, mapRef)
setMacroProps(label, props)
setMacroProps(label, props, delim)
setMacroProps(label, props, delim, id)
setMacroProps(label, props, delim, id, mapRef)

Parameters

  • index - The index of the macro button.
  • label - The label of the macro button.
  • props - A String Property List or JSON Object containing the properties for the button.
  • delim - The delimiter used in the String Property List that is used in the props parameter. Defaults to ";" (semicolon) and can be omitted if you are sending a JSON Object as the props parameter. If you are sending a JSON object as the props parameter, and using the id parameter, you can set this to "json".
  • id - OPTIONAL: The token id of the token that the macro button is located on. From v1.15, accepts "campaign" and "gm" as ids for the relevant panels.

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

  • mapRef - The Name or ID of the map to find the token. Defaults to the current map.

Example

Changes the macro button to be red with white text. First one is by index and the second one by label (name). 
[h: setMacroProps(1, "color=red;fontColor=white")]
[h: setMacroProps("Attack", "color=red;fontColor=white")]

Somewhat silly example that changes the label (name) of the currently executing macro to the current time and randomly changes the button color. 

[h: color = listGet("Red, Blue, Green, White, Yellow, Orange", 1d6-1)]
[h: index = getMacroIndexes(getMacroName())]
[h: dt = json.get(getInfo("server"), "timeDate")]
[h: time = listGet(dt, 1, " ")]
[h: myProps = setStrProp("", "label", time)]
[h: myProps = setStrProp(myProps, "color", color)]
[h: setMacroProps(index, myprops)]


Version Changes

  • 1.3b49 - Added ability for props to accept a JSON object.
  • 1.3b51 - Added id parameter option.
  • 1.3b53 - Added ability for command, compare, playerEditable, applyToSelected, autoExecute, group, and tooltip parameters.
  • 1.5.11 - Added mapname parameter option.
  • 1.15 - Addition of "gm" and "campaign" options for id
Retrieved from "https://wiki.rptools.info/index.php?title=setMacroProps&oldid=35710"