createMacro

From RPTools Wiki
(Redirected from CreateMacro)
Jump to navigation Jump to search

 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

• Introduced in version 1.3b48
Creates a macro button for the Current Token and returns the index of the newly created button.

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, mapRef)

JSON-only syntax 

createMacro(props)
createMacro(props, tokenRef)
createMacro(props, tokenRef, mapRef)

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()). Accepts true(1) for yes, and false(0) for no.
    • autoExecute - Whether the macro will be automatically executed when the button is clicked. Accepts true(1) for yes, and false(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. Accepts true(1) for yes, and false(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). Accepts true(1) for yes, and false(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's applyToSelected value for common macro comparisons.
      • autoExecute - Use the macro's autoExec value for common macro comparisons.
      • command - Use the macro's command value for common macro comparisons.
      • group - Use the macro's group value for common macro comparisons.
      • includeLabel - Use the macro's includeLabel value for common macro comparisons.
      • sortPrefix - Use the macro's sortPrefix value for common macro comparisons.
  • delim - The delimiter used in the String Property List that is sent to the props parameter, defaults to ";". If you are sending a JSON Object to the props parameter, and using the id parameter, you should set this to "json".
  • tokenRef - Either the token id 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. 

  • mapRef - The Name or ID of the map to find the token. Defaults to the current map.
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.


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, 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=createMacro&oldid=34852"