execLink: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
m (Clarify possible targets value)
m (Fixed typo and did some cleanup)
 
(7 intermediate revisions by 3 users not shown)
Line 10: Line 10:
|usage=
|usage=


<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
execLink(link)
execLink(link)
execLink(link, defer)
execLink(link, defer)
execLink(link, defer, targets)
execLink(link, defer, targets)
execLink(link, defer, targets, delim)
execLink(link, defer, targets, delim)
</source>
</syntaxhighlight>
'''Parameters'''
'''Parameters'''
{{param|link|The link to "execute".}}
{{param|link|The link to "execute".}}
{{param|defer|Executes the link after the current macro has completed if non zero, defaults to zero.}}
{{param|defer|Executes the link after the current macro has completed if non zero, defaults to zero.}}
{{param|targets|are the user names (so not token names) but the names of the users that are logged in. The options "gm", "gm-self", "self", "not-self", "not-gm", "not-gm-self", "none", and "all" are also valid parameters to give. E.g.: "tim, tom, tarra". Defaults to self (so if no parameter is given the link is executed locally only).
{{param|targets|are the user names (so not token names) but the names of the users that are logged in. The options "gm", "gm-self", "self", "not-self", "not-gm", "not-gm-self", "none", and "all" are also valid parameters to give. E.g.: "tim, tom, tarra". Defaults to self (so if no parameter is given the link is executed locally only). Here is a summary of the valid values:
::: '''''Player name''''': The named player.
::: '''self''': Self only (default, link is only executed locally).
::: '''self''': Self only (default, link is only executed locally).
::: '''gm''': GM only.
::: '''gm''': GM only.
::: '''gm-self''': Both the GM and self.
::: '''gm-self''': Both the GM and self.
::: '''all''': All connected players and GMs.
::: '''not-self''': Anyone but self.
::: '''not-self''': Anyone but self.
::: '''not-gm''': All non-GMs.
::: '''not-gm''': All non-GMs.
::: '''not-gm-self''': All players apart from the GM and self. }}
::: '''not-gm-self''': All players apart from the GM and self.
::: '''none''': No players. No GMs.}}
{{param|delim|The delimiter used to separate the values in the String List that is given, defaults to {{code|","}}. If {{code|"json"}} is specified, a JSON array is expected instead of a String List.}}
{{param|delim|The delimiter used to separate the values in the String List that is given, defaults to {{code|","}}. If {{code|"json"}} is specified, a JSON array is expected instead of a String List.}}


|examples=
|examples=
Execute a macro link immediately (any output will appear before the current macros output)
Execute a macro link immediately (any output will appear ''before'' the current macros output).
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: link = macroLinkText("Test@Lib:Test", "self")]
[h: link = macroLinkText("Test@Lib:Test", "self")]
[h: execLink(link)]
[h: execLink(link)]
</source>
</syntaxhighlight>


Execute a macro link after the execution of the current macro (any output will appear before the current macros output)
Execute a macro link after the execution of the current macro (any output will appear ''after'' the current macros output).
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: link = macroLinkText("Test@Lib:Test", "self")]
[h: link = macroLinkText("Test@Lib:Test", "self")]
[h: execLink(link, 1)]
[h: execLink(link, 1)]
</source>
</syntaxhighlight>


Copy a token and update its values.
Copy a token and update its values.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: newToken = copyToken("Hero")]
[h: newToken = copyToken("Hero")]
[h: link = macroLinkText("update@Lib:GM", "none", "", newToken)]
[h: link = macroLinkText("update@Lib:GM", "none", "", newToken)]
[h: execLink(link)]
[h: execLink(link)]
</source>
</syntaxhighlight>


Execute a macro link on all clients
Execute a macro link on all clients.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: link = macroLinkText("Test@Lib:Test", "none")]
[h: link = macroLinkText("Test@Lib:Test", "none")]
[h: execLink(link, 0, "all")]
[h: execLink(link, 0, "all")]
</source>
</syntaxhighlight>
 
Opening an overlay with arguments to the GM panel macro {{code|loadGMOverlay}} for all connected GMs.
 
* This is a very useful pattern to load an overlay with a library token using {{code|onCampaignLoad}}.
* In this example, the hypothetical overlay function can take text and background color arguments in a [[String_Property_List|String Property List]].
 
<syntaxhighlight lang="mtmacro" line>
[h: link = macroLinkText("loadGMOverlay@GM", "none", "text=white;background=black")]
[h: execLink(link, 0, "gm")]
</syntaxhighlight>


|changes=
|changes=
Line 63: Line 75:


}}
}}
===Notes===
Deferred functions/links which are queued within a deferred macro do not run directly after the queuing macro, but instead are added to the end of the stack of all the deferred functions and links. This means you cannot 'nest' deferrals or insert deferrals in the middle of the stack of deferred macros. For discussion of this functionality and possible workarounds you can [https://github.com/RPTools/maptool/issues/2633 read more on GitHub].
[[Category:Miscellaneous Function]]
[[Category:Miscellaneous Function]]

Latest revision as of 01:50, 13 October 2023

execLink() Function

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

Introduced in version 1.3b55
Executes a macro link that was created with macroLinkText(), output generated by the link is sent to players using the standard macroLinkText() logic. execLink() allows you to defer the running of the link until after the currently running macro has ended in which case the output will be displayed after any output generated by the current macro. If you defer a series of links, they will be queued in order and executed after the currently running macro. There is no software limit to the amount of links you can queue, but your hardware will impose its own limitations. If the execution of the link is not defered then any output generated will appear before any output generated by the current macro. You can use this function to update values in a token copied with copyToken() using the defered option. You can also use this function to send output selectivly to a list of players from the current macro, or to generate output that is not suppressed when the abort() function is called.

Usage

execLink(link)
execLink(link, defer)
execLink(link, defer, targets)
execLink(link, defer, targets, delim)

Parameters

  • link - The link to "execute".
  • defer - Executes the link after the current macro has completed if non zero, defaults to zero.
  • targets - are the user names (so not token names) but the names of the users that are logged in. The options "gm", "gm-self", "self", "not-self", "not-gm", "not-gm-self", "none", and "all" are also valid parameters to give. E.g.: "tim, tom, tarra". Defaults to self (so if no parameter is given the link is executed locally only). Here is a summary of the valid values:
Player name: The named player.
self: Self only (default, link is only executed locally).
gm: GM only.
gm-self: Both the GM and self.
all: All connected players and GMs.
not-self: Anyone but self.
not-gm: All non-GMs.
not-gm-self: All players apart from the GM and self.
none: No players. No GMs.
  • delim - The delimiter used to separate the values in the String List that is given, defaults to ",". If "json" is specified, a JSON array is expected instead of a String List.

Examples

Execute a macro link immediately (any output will appear before the current macros output).
[h: link = macroLinkText("Test@Lib:Test", "self")]
[h: execLink(link)]

Execute a macro link after the execution of the current macro (any output will appear after the current macros output).

[h: link = macroLinkText("Test@Lib:Test", "self")]
[h: execLink(link, 1)]

Copy a token and update its values.

[h: newToken = copyToken("Hero")]
[h: link = macroLinkText("update@Lib:GM", "none", "", newToken)]
[h: execLink(link)]

Execute a macro link on all clients.

[h: link = macroLinkText("Test@Lib:Test", "none")]
[h: execLink(link, 0, "all")]

Opening an overlay with arguments to the GM panel macro loadGMOverlay for all connected GMs.

  • This is a very useful pattern to load an overlay with a library token using onCampaignLoad.
  • In this example, the hypothetical overlay function can take text and background color arguments in a String Property List.
[h: link = macroLinkText("loadGMOverlay@GM", "none", "text=white;background=black")] 
[h: execLink(link, 0, "gm")]

See Also

Version Changes

  • 1.5.5 - Added the targets and delim parameters.
  • 1.5.7 - Added "not-self", "not-gm" and "not-gm-self" as valid targets.

Notes

Deferred functions/links which are queued within a deferred macro do not run directly after the queuing macro, but instead are added to the end of the stack of all the deferred functions and links. This means you cannot 'nest' deferrals or insert deferrals in the middle of the stack of deferred macros. For discussion of this functionality and possible workarounds you can read more on GitHub.