setMacroProps: Difference between revisions

Revision as of 23:55, 30 March 2009

This article is a stub, you can help the RPTools Wiki project by contributing content to expand this article.
This article needs: Examples using the new functionality.

setMacroProps() Function

• Introduced in version 1.3b48

Sets the properties for the specified Macro Button on the Current 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 of Macro Buttons on the Current Token with a matching label are changed.

Usage

setMacroProps(index, props)

setMacroProps(index, props, delim)

setMacroProps(index, props, delim, id)

setMacroProps(label, props)

setMacroProps(label, props, delim)

setMacroProps(label, props, delim, id)

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.
- applyToSelected - Should the macro be applied to the selected tokens.
- autoExec - If the macro will be automatically executed when the button is clicked, accepts true(1) or false(0).
- color - The name of the color for the button.
- command - The command for the macro (only when using JSON version of function).
- fontColor - The name of the font color for the button.
- fontSize - The size of the font for the button.
- includeLabel - If the label will be output when the button is clicked. Accepts true(1) or false(0).
- group - The name of the group that the button belongs to.
- sortBy - The sort by value of the macro button.
- label - The label for the button.
- maxWidth - The maximum width of the button.
- minWidth - The minimum width of the button.
- playerEditable - Is the button player editable, accepts true(1) or false(0).
- tooltip - The tool tip for the macro button.
- compare - Takes a JSON array which can contain one or more of the following keywords (only usable with JSON version of the function).
  - applyToSelected - Use the macro applyToSelected for common macro comparisons.
  - autoExec - Use the macro autoExec for common macro comparisons.
  - command - Use the macro command for common macro comparisons.
  - group - Use the macro group for common macro comparisons.
  - includeLabel - Use the macro includeLabel for common macro comparisons.
  - sortPrefix - Use the macro sortPrefix for common macro comparisons.
delim - The delimiter used in the String Property List that is sent to the props parameter, defaults to ";" and can be omitted if you are sending a JSON Object to the props parameter. If you are sending a JSON Object to the props parameter, and using the id parameter, you can set this to "json".
id - The token id of the token that the macro button is located on.
Note: This parameter can only be used in a Trusted Macro.

Example

[h: setMacroProps(1, "color=red;fontColor=white")]
[h: setMacroProps("Attack", "color=red;fontColor=white")]

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, autoExec, group, and tooltip parameters.

@@ Line 1: / Line 1: @@
+{{stub|Examples using the new functionality.}}
 {{MacroFunction
 |name=setMacroProps
 |version=1.3b48
 |description=
-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.
+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 [[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.
-'''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=
@@ Line 35: / Line 12: @@
 <source lang="mtmacro" line>
 setMacroProps(index, props, delim)
+</source>
+<source lang="mtmacro" line>
+setMacroProps(index, props, delim, id)
 </source>
 <source lang="mtmacro" line>
@@ Line 42: / Line 22: @@
 setMacroProps(label, props, delim)
 </source>
+<source lang="mtmacro" line>
+setMacroProps(label, props, delim, id)
+</source>
+'''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.
+** {{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.}}
+{{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|id|The token {{code|id}} of the token that the macro button is located on. {{TrustedParameter}} }}
 |example=
@@ Line 51: / Line 61: @@
 |changes=
 {{change|1.3b49|Added ability for {{code|props}} to accept a JSON object.}}
+{{change|1.3b51|Added {{code|id}} parameter option.}}
 {{change|1.3b53|Added ability for {{code|command}}, {{code|compare}}, {{code|playerEditable}}, {{code|applyToSelected}}, {{code|autoExec}}, {{code|group}}, and {{code|tooltip}} parameters.}}
 }}
 [[Category:Metamacro Function]]