setMacroProps: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
No edit summary
m (Cleaned up the text and examples)
Line 1: Line 1:
{{stub|Examples using the new functionality.}}
{{MacroFunction
{{MacroFunction
|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 [[Current 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 [[Token:Macro Button|Macro Button]]. If it is a label then all of [[Macro Button|Macro Button]]s on the [[Current Token]] with a matching label are changed.


|usage=
|usage=
Line 23: Line 21:
{{param|label|The label 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.
{{param|props|A [[String Property List]] or [[JSON Object]] containing the properties for the button.
** See {{func|createMacro}} for a complete list of properties.
** See {{func|createMacro}} for a complete list of properties.}}
{{param|delim|The delimiter used in the [[String Property List]] that is sent to the {{code|props}} parameter, defaults to {{code|";"}} and can be omitted if you are sending a [[JSON Object]] to the {{code|props}} parameter. If you are sending a [[JSON Object]] to the {{code|props}} parameter, and using the {{code|id}} parameter, you can set this to {{code|"json"}}.}}
{{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|The token {{code|id}} of the token that the macro button is located on. {{TrustedParameter}} }}
{{param|id|OPTIONAL: The token {{code|id}} of the token that the macro button is located on. {{TrustedParameter}} }}
{{param|mapname|The name of the map to find the token.  Defaults to the current map.}}
{{param|mapname|The name of the map to find the token.  Defaults to the current map.}}


|example=
|example=
Changes the macro button to be red with white text.  First by index and second by label(name).
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>
<syntaxhighlight lang="mtmacro" line>
[h: setMacroProps(1, "color=red;fontColor=white")]
[h: setMacroProps(1, "color=red;fontColor=white")]
Line 36: Line 33:
</syntaxhighlight>
</syntaxhighlight>


Somewhat silly example that changes the label (e.g. name) of the currently executing macro to the current time and randomly changes the button color.
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>
<syntaxhighlight lang="mtmacro" line>
[h: color = listget("Red, Blue, Green, White, Yellow, Orange",1d6-1)]
[h: color = listGet("Red, Blue, Green, White, Yellow, Orange", 1d6-1)]
[h: index = getMacroIndexes(getMacroName())]
[h: index = getMacroIndexes(getMacroName())]
[h: dt = json.get(getInfo("server"),"timeDate")]
[h: dt = json.get(getInfo("server"), "timeDate")]
[h: time = listget(dt,1," ")]
[h: time = listGet(dt, 1, " ")]
[h: myProps = setStrProp("","label",time)]
[h: myProps = setStrProp("", "label", time)]
[h: myProps = setStrProp(myProps,"color",color)]
[h: myProps = setStrProp(myProps, "color", color)]
[h: setMacroProps(index,myprops)]
[h: setMacroProps(index, myprops)]
</syntaxhighlight>
</syntaxhighlight>


Line 52: Line 49:
{{change|1.3b53|Added ability for {{code|command}}, {{code|compare}}, {{code|playerEditable}}, {{code|applyToSelected}}, {{code|autoExecute}}, {{code|group}}, and {{code|tooltip}} parameters.}}
{{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.5.11|Added {{code|mapname}} parameter option.}}
}}
}}
[[Category:Metamacro Function]]
[[Category:Metamacro Function]][[Category:Macro Function]]

Revision as of 05:23, 6 June 2023

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, mapname)
setMacroProps(label, props)
setMacroProps(label, props, delim)
setMacroProps(label, props, delim, id)
setMacroProps(label, props, delim, id, mapname)

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.

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

  • mapname - The name 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.