createMacro
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.
createMacro() Function
Usage
createMacro(label, command)
createMacro(label, command, props)
createMacro(label, command, props, delim)
createMacro(label, command, props, delim, tokenRef)
createMacro(label, command, props, delim, tokenRef, mapname)
JSON-only syntax
createMacro(props)
createMacro(props, tokenRef)
createMacro(props, tokenRef, mapname)
Parameters
label
- The label for the macro button.command
- The command to run when the macro button is clicked, or the macro is called.props
- A String Property List or JSON Object containing the properties for the button.applyToSelected
- Whether the macro should be applied to the selected tokens. If not selected and the macro is supposed to operate on tokens, the macro will need to create a list of token ids to manipulate (such as via getTokens()). Acceptstrue
(1
) for yes, andfalse
(0
) for no.autoExecute
- Whether the macro will be automatically executed when the button is clicked. Acceptstrue
(1
) for yes, andfalse
(0
) for no.color
- The name of the color for the button. Can use standard CSS color values.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
- Whether the label will be output when the button is clicked. Acceptstrue
(1
) for yes, andfalse
(0
) for no.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
- Whether the button is player editable. If yes, the macro is considered untrusted (see Trusted Macro). Acceptstrue
(1
) for yes, andfalse
(0
) for no.tooltip
- The tooltip for the macro button. Tooltips that start with{
or[
will be treated as MTscript and executed with the result being used as the content of the tooltip. To embed formatting (bold, italics, etc), ensure that the content of the tooltip ends up starting with<html>
and contains the HTML3.2 content that produces your desired result.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'sapplyToSelected
value for common macro comparisons.autoExecute
- Use the macro'sautoExec
value for common macro comparisons.command
- Use the macro'scommand
value for common macro comparisons.group
- Use the macro'sgroup
value for common macro comparisons.includeLabel
- Use the macro'sincludeLabel
value for common macro comparisons.sortPrefix
- Use the macro'ssortPrefix
value for common macro comparisons.
delim
- The delimiter used in the String Property List that is sent to theprops
parameter, defaults to";"
. If you are sending a JSON Object to theprops
parameter, and using theid
parameter, you should set this to"json"
.tokenRef
- Either the tokenid
or Token Name of the token that the macro is created 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.
mapname
- The name of the map to find the token. Defaults to the current map.
Note: It appears that if a JSON object is passed as props
that contains a key of index
and that macro index already exists in the destination token, the existing macro will be overwritten. A workaround is to remove that key from the JSON object prior to calling this function.
Example
[createMacro("Test", "this is a test", "autoExecute=true;color=blue", ";") ]
[createMacro("Another Test", "this is a test",
"autoExecute=true;color=red;fontColor=white", ";") ]
Will create the following buttons on the current token.
Note that if you want to provide a macro command in the command section, you will have issues with quotations as you cannot use double quotes " inside, so macro commands need to be with single ' quotes.
[h: createMacro("myMacro", "[macro('aMacro@Lib:Test'): 'aParameter']",
"autoExecute=true;group=Weapons") ]
Version Changes
- 1.3b49 - Added
json
delimiter option. - 1.3b51 - Added
id
parameter option, and JSON-only parameter syntax. - 1.3b53 - Added ability for
command
,compare
,playerEditable
,applyToSelected
,autoExec
,group
, andtooltip
parameters.
- 1.5.11 - Added
mapname
parameter option. - 1.15 - Addition of "gm" and "campaign" options for id