getLibProperty: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
No edit summary
m (Added references for add-on libraries; cleaned up grammer/formatting)
Line 2: Line 2:
|name=getLibProperty
|name=getLibProperty
|version=1.3b48
|version=1.3b48
|description=Returns the value of a [[Token:token property{{!}}token property]] from a [[Token:library token{{!}}library token]]. If the lib argument is not specified then the [[Token:token property{{!}}token property]] will be retrieved from the [[Token:library token{{!}}library token]] that the macro is currently running from.
|description=Returns the value of a [[Token:token property|token property]] from a [[Token:library token|library token]]. If the lib argument is not specified then the [[Token:token property|token property]] will be retrieved from the [[Token:library token|library token]] that the macro is currently running from, or produce an error if the current macro is not on a library token.


Unlike {{func|getProperty}}, this function will not retrieve the default value of a campaign property.  Default values are generally programmed as local variables in a macro, then overridden with the result of this function if this function returns a value.  An example is shown below.
Unlike {{func|getProperty}}, this function will not retrieve the default value of a campaign property.  Default values are generally programmed as local variables in a macro, then overridden with the result of this function if this function returns a value.  An example is shown below.


|usage=
|usage=
<syntaxhighlight lang="mtmacro" line>
<source lang="mtmacro" line>
getLibProperty(name)
getLibProperty(name)
getLibProperty(name, lib)
getLibProperty(name, lib)
</syntaxhighlight>
</source>
 
{{Note|If the value of the property on the library token equals the default value, then MapTool will treat the property as though it were empty (because its content matches the default value that is used when the property is empty) and will return an empty string!}}
'''Important Note'''
For example, suppose a property named {{code|Weapons}} has a default value of "{{code|Shotgun, Pistol}}".
As mentioned in the introduction, if the value of the property on the Token equals the default value, the function will return nothing! This means that if e.g. you set the default property to
If you leave the value on the library token unchanged, it will appear to contain the value "{{code|Shotgun, Pistol}}" in places like the stat sheet, but this function will return an empty string.
<syntaxhighlight lang="mtmacro" line>
<source lang="mtmacro" line>
Weapons : Shotgun, Pistol, Revolver
</syntaxhighlight>
And you leave the e.g. the value on the token lib:Compendium unchanged, so it will also contain the value "Shotgun, Pistol, Revolver", then
<syntaxhighlight lang="mtmacro" line>
[getLibProperty("Weapons", "lib:Compendium")]
[getLibProperty("Weapons", "lib:Compendium")]
</syntaxhighlight>
</source>
will return nothing!
Returns an empty string.


It may help to review some relevant functions that apply to regular token properties, {{func|getProperty}}, {{func|getPropertyDefault}}, and {{func|resetProperty}}.


|examples=
|examples=
To get the "init" [[Token:token property{{!}}token property]] from the [[Token:library token{{!}}library token]] that a macro is running from use
To get the "init" [[Token:token property|token property]] from the [[Token:library token|library token]] that a macro is running from use
<syntaxhighlight lang="mtmacro" line>
<source lang="mtmacro" line>
[getLibProperty("init")]
[getLibProperty("init")]
</syntaxhighlight>
</source>


To get the "init" [[Token:token property{{!}}token property]] from the [[Token:library token{{!}}library token]] if the library token has such a property.  If not, use a default value of "default".
To get the "init" [[Token:token property|token property]] from the [[Token:library token|library token]] if the library token has such a property.  If not, use a default value of "{{code|default}}".
<syntaxhighlight lang="mtmacro" line>
<source lang="mtmacro" line>
[result = getLibProperty("init")]
[result = getLibProperty("init")]
[IF(result == ""): result = "default" ]
[if(result == ""): result = "default" ]
</syntaxhighlight>
</source>


To get the "init" [[Token:token property{{!}}token property]] from a [[Token:library token{{!}}library token]] called "lib:Attacks" use
To get the "init" [[Token:token property|token property]] from a [[Token:library token|library token]] called "lib:Attacks" use
<syntaxhighlight lang="mtmacro" line>
<source lang="mtmacro" line>
[getLibProperty("init", "lib:Attacks")]
[getLibProperty("init", "lib:Attacks")]
</syntaxhighlight>
</source>
 
'''Updated in 1.11:'''
MTscript functions for acting on library tokens have been modified to also work on [[MTscript_functions_related_to_Add-on_libraries|Add-on libraries]].
This modification allows the namespace of the add-on library to be used where the {{code|Lib:}} token name would normally appear.  For example,
 
<source lang="mtmacro" line>
[h: getLibProperty("defaultStrength", "com.myname.mt.my-first-addon")]
</source>
}}
}}
[[Category:Token Library Function]][[Category:Property Function]]
[[Category:Token Library Function]]
[[Category:Property Function]]

Revision as of 02:59, 11 February 2024

getLibProperty() Function

• Introduced in version 1.3b48
Returns the value of a token property from a library token. If the lib argument is not specified then the token property will be retrieved from the library token that the macro is currently running from, or produce an error if the current macro is not on a library token. Unlike getProperty(), this function will not retrieve the default value of a campaign property. Default values are generally programmed as local variables in a macro, then overridden with the result of this function if this function returns a value. An example is shown below.

Usage

getLibProperty(name)
getLibProperty(name, lib)
If the value of the property on the library token equals the default value, then MapTool will treat the property as though it were empty (because its content matches the default value that is used when the property is empty) and will return an empty string!

For example, suppose a property named Weapons has a default value of "Shotgun, Pistol". If you leave the value on the library token unchanged, it will appear to contain the value "Shotgun, Pistol" in places like the stat sheet, but this function will return an empty string. 

[getLibProperty("Weapons", "lib:Compendium")]

Returns an empty string.

It may help to review some relevant functions that apply to regular token properties, getProperty(), getPropertyDefault(), and resetProperty().

Examples

To get the "init" token property from the library token that a macro is running from use 
[getLibProperty("init")]

To get the "init" token property from the library token if the library token has such a property. If not, use a default value of "default". 

[result = getLibProperty("init")]
[if(result == ""): result = "default" ]

To get the "init" token property from a library token called "lib:Attacks" use 

[getLibProperty("init", "lib:Attacks")]

Updated in 1.11: MTscript functions for acting on library tokens have been modified to also work on Add-on libraries. This modification allows the namespace of the add-on library to be used where the Lib: token name would normally appear. For example, 

[h: getLibProperty("defaultStrength", "com.myname.mt.my-first-addon")]
Retrieved from "https://wiki.rptools.info/index.php?title=getLibProperty&oldid=17593"