Updated for 1.3b46
Several new functions are available to macros (some added in b42, some added later). I'll discuss how to use them here.
I'm recommending that all GMs add a new token property called "Private" to their campaigns. That property should probably also be added to the default token property list MapTools uses. A big advantage of the new StrProp functions below is that they allow macros to store multiple custom settings in a token without having to ask every GM to add new token properties to their campaign. (See the example Attack macro posted below.) But you still need one token property to be defined, to provide a place to store all those custom settings. To avoid issues caused by having an empty token property, the Private property should be defined with a default value as follows:
Code: Select all
Private: ;
Abort and assert functions
- abort(status) - if status is zero, aborts execution and the rest of the macro is skipped
- assert(condition, message) - if condition is zero, halts execution and prints a custom error message
These functions operate on a string of the form "item1, item2, item3, ..."
Each of them takes an optional last argument that gives an alternate list separator (the default is ",").
Note that the original list is never modified. If a function alters a list, it does so by returning a new list with the alterations.
- listGet(list, index) - returns the entry in the index position (first position is index 0)
- listDelete(list, index) - returns a new list with the item at index position deleted.
- listCount(list) - returns the number of list entries
- listFind(list, target) - returns the index of the target string in the list, or -1 if none of the list entries match.
- listAppend(list, target) - adds target to the end of the list
- listInsert(list, index, target) - inserts target before the entry at position index
- listReplace(list, index, target) - replaces the entry at position index with the target
- listSort(list, sortType) - returns a sorted list. The sortType determines the type of sort to use.
If sortType is "A", normal alphabetic sorting is used, and "Monster11" comes before "Monster3". (Default behavior)
If sortType is "N", the first number in each entry is effectively padded to 4 digits, so that "Monster3" comes before "Monster11".
The sortType can have a second character of "+" or "-" to specify an ascending or descending sort. - listContains(list, target) - returns number of occurrences of target in list
- listFormat(list, listFormat, itemFormat, separator) - returns a custom-formatted version of the list.
listFormat is a string that is emitted once. It should contain the text "%list", which is replaced with the formatted items.
itemFormat is emitted once per item. Each instance of "%item" in the string is replaced with the value of the list item.
separator is emitted in between the formatted items.
Example (prints items on separate lines):Code: Select all
[listFormat("apple,bear,cat", "BEGIN LIST<br>%list<br>END LIST", "This item is: %item", "<br>")]
These functions operate on a "property string", which contains multiple settings:
Code: Select all
"key1=value1; key2=value2; ..."
To avoid confusion, I'll call each of these settings a "string property", to distinguish them from the "token properties" that already exist in MapTool.
The functions access and modify a property string. Note that the original string is never altered! When a function modifies a property string, it returns a new property string with the modifications.
- getStrProp(properties, key) - find a key and return the value, or "" if not found.
You can provide an optional 3rd argument, which will be returned if the key is not found. - setStrProp(properties, key, value) - set the value for a key, inserting it if not present. Returns the new property string.
- deleteStrProp(properties, key) - delete a key. Returns the new property string.
- countStrProp(properties) - returns how many key/value settings are in the string.
- indexKeyStrProp(properties, N) - returns the Nth key in the list.
- indexValueStrProp(properties, N) - returns the Nth value in the list.
- varsFromStrProp(properties, nameStyle) - creates variables for each key and assigns the corresponding value. Returns the number of assignments made.
nameStyle can be one of three settings:
"NONE" - no assignments are made
"SUFFIXED" - assignments are made to variable names with an underscore appended
"UNSUFFIXED" - assignments are made to unmodified variable names
The SUFFIXED option is preferred over UNSUFFIXED, so that you don't unexpectedly overwrite token properties or other variables.
Use UNSUFFIXED in special cases, such as when you really do intend to overwrite token properties. - strPropFromVars(varList, varStyle) - creates a property string from the names and values of the variables listed in the varList string.
varStyle is either "SUFFIXED" or "UNSUFFIXED". When fetching the values of the variables, the "SUFFIXED" option will look for variables with underscores appended to the given names. The output property string does not contain the underscores.
Example (returns "c=cow ; a=3 ; b=bob ; "):Code: Select all
[H: props = "a=3 ; b=bob ; c=cow ; "] [H: varsFromStrProp(props, "SUFFIXED")] <!-- creates variables a_, b_, c_ --> [strPropFromVars("c,a,b", "SUFFIXED")]
- formatStrProp(props, listFormat, entryFormat, separator) - returns a custom-formatted version of the property string.
listFormat is a string that is emitted once. It should contain the text "%list", which is replaced with the formatted items.
entryFormat is emitted once per item. Any instances of "%key" and "%value" in the string are replaced with the key or value for that setting.
separator is emitted in between the formatted items.
Example (prints settings in a formatted table):Code: Select all
[h: props = "Strength=14 ; Constitution=8 ; Dexterity=13 ; Intelligence=4 ; Wisdom=18 ; Charisma=9"] [formatStrProp(props, "<table border=1>%list</table>", "<tr> <td><b>%key</b></td> <td>%value</td> </tr>", "")]
- getStrProp(props, "b") returns "bob"
- setStrProp(props, "d", 44) returns "a=3 ; b=bob ; c=cow ; d=44 ; "
- deleteStrProp(props, "a") returns "b=bob ; c=cow ; "
- countStrProp(props) returns 3
- indexKeyStrProp(props, 0) returns "a"
- indexValueStrProp(props, 0) returns 3
- varsFromStrProp(props, "SUFFIXED") assigns values to the variables a_, b_, and c_.
- strPropFromVars("a,c,b", "SUFFIXED") then constructs the property string "a=3 ; c=cow ; b=bob ; "
New function: input()
The input() function allows you to ask the user to input several values at once. The function takes one or more string arguments, one for each variable you want to assign to. It returns 1 if the user clicked the OK button, and 0 if they clicked Cancel (or hit Esc to exit the dialog). If input() returns 0, no variable assignments were made. (You can use the abort() function to cancel the rest of your macro if input() returns 0.)
As a simple example, the following statement
Code: Select all
[input("AtkBonus", "DmgBonus", "CombatAdvantage")]
However, more choices are available. For example, a macro can create this dialog box:
Each argument must be a string with the following format:
Code: Select all
"varname | value | prompt | inputType | options"
- varname is the variable name to assign to.
- value is the initial value present in the dialog box. If not present, it defaults to "0". In some cases you use a special syntax to indicate multiple values.
- prompt is a friendly prompt that appears next to the input field in the dialog box. If not present, it defaults to the variable name.
- inputType describes what type of input control to use in the dialog. They are described below.
- options is a series of option settings in the form OptionName=OptionValue.
There are several user interface choices for each variable. The inputType can be any of the following.
- TEXT is the default, and yields a text input box. The contents typed in the box are assigned to the variable.
- Option: WIDTH=nnn -- Sets the width of the text box. (Default WIDTH=16)
- LIST creates a dropdown list of choices. The variable is assigned the index (starting at 0) of the item that was selected.
- Option: SELECT=nnn -- Sets the initial selection in the listbox (the first item is number 0). (Default SELECT=0)
- Option: VALUE=STRING -- The variable is assigned the string contents of the selected item. (Default VALUE=NUMBER)
- Option: TEXT=FALSE -- No text is shown in the list entries. (Default TEXT=TRUE)
- Option: ICON=TRUE -- If the string for the item contains an image asset URL, the image is displayed in the entry. Text before the URL is used for the entry's text. The getTokenImage() and getStateImage() functions can be used to obtain asset URLs. (Default ICON=FALSE)
- Option: ICONSIZE=nnn -- The size of the icon. (Default ICONSIZE=50)
- CHECK creates a checkbox. The variable is assigned either 0 or 1.
- RADIO creates a group of radio buttons. This option works much like LIST, returning the index of the choice that was selected.
- Option: ORIENT=H -- Arranges the radio buttons horizontally on a single line. (Default ORIENT=V)
- Option: VALUE=STRING and SELECT=nnn -- Same as the LIST options above.
- LABEL creates a static label. The varname is ignored, and nothing is assigned to it.
- Options: The TEXT, ICON, and ICONSIZE options work the same way they do for a LIST.
- PROPS creates a sub-area with multiple text boxes, one for each entry in the "property string" (see below) stored in value. The varname is assigned a new property string containing all the entries with their updated values.
- Option: SETVARS=SUFFIXED -- Makes a variable assignment for each of the sub-values, with an underscore appended to the name. (Default SETVARS=NONE)
- Option: SETVARS=UNSUFFIXED -- Makes variable assignments to unmodified variable names. (SUFFIXED is usually preferred, unless you specifically intend to overwrite token properties.)
- TAB creates a tab for a tabbed dialog box. The varName variable gets assigned a property string containing all the variable assignments made on this tab. Since some of the variables may be property strings themselves, the tab property string uses the non-default separator "##".
- Option: SELECT=TRUE -- Causes this tab to be displayed when the dialog appears. (Default SELECT=FALSE)
When using the LIST or RADIO options, the value section is a comma-delimited list of options, e.g. "item1, item2, item3". When using the PROPS option, the value section is a "property string" of the form "key1=value1; key2=value2;". Property strings can be created and manipulated using the various StrProp functions (getStrProp(), setStrProp(), etc.).
Here are some example formats for the parameters to input().
- [H: input("Bonus")] [Bonus]
A text value is read and assigned to the variable called Bonus. - [H: input("AtkBonus|2|Attack bonus")] [AtkBonus]
The text box starts with a value of 2, and has a friendly prompt in front of it. - [H: input("CA | 1 | Combat Advantage | CHECK")] [CA]
A checkbox is shown, already checked. - [H: input("Spell | Magic missile, Fireball, Wish || LIST |SELECT=1")] [Spell]
The dialog box will have a listbox with Fireball selected. Note that the prompt section has been skipped. A number from 0 to 2 will be assigned to the variable Spell. - [H: input("YourName | Bob , Andy , Joe , Karl | Pick a name | RADIO | orient=h value=string")] [YourName]
The options are shown as radio buttons on a single line, and the variable YourName will be assigned the text of the chosen option. - [H: input("props | Name=Longsword +1 ; Damage=1d8 ; Keyword=fire | Weapon info | PROPS")] [props]
Three text boxes are created, and the props variable is assigned a new property string with the user's modified values. - [H: input("tab0 | Info || TAB", "Name ## Rank ## Serial number | 1,2,3 || LIST",
"tab1 | Abilities || TAB", "Strength ## Dexterity ## Wisdom")]
Here's the macro that generated the elaborate example above. It assumes that your campaign file has image states called "Dazed", "Immobilised", "Slowed", and "Quarry_yellow". If you want to try it out yourself, download this campaign settings file, and load it in MapTool (Edit > Campaign Properties > Import). If the user clicks OK to the dialog box, the Creature, CA, MainWpn, OffWpn, FlavorText and State variables will contain the user's choices and can be used in further macro steps.
Code: Select all
[H: dazestr = "Dazed" + getStateImage("Dazed") + ","]
[H: immobstr = "Immobilised" + getStateImage("Immobilised") +","]
[H: slowstr = "Slowed" + getStateImage("Slowed") + ","]
[H: quarrystr = "Quarry" + getStateImage("Quarry_yellow") + ","]
[H: input(
"Creature | (None) | Creature to be attacked",
"CA || Combat Advantage | CHECK",
"MainWpn | Battleaxe, Longsword, Bastard sword | Select main hand weapon | RADIO | select=1 value=string",
"OffWpn | (None), Dagger, Short sword | Select off hand weapon | RADIO | orient=h",
"FlavorText | Conan swings high and strikes his foe.,
Conan smashes his enemy with a swift blow.,
With desperate fury Conan hacks left and right. | Attack description | LIST",
"State | " + dazestr + immobstr + slowstr + quarrystr
+"| Select a state to apply to target | LIST | ICON=true iconsize=45 select=2"
)]
The issue involves the listboxes. Here's an example to give you several lists to test with.
Code: Select all
[H: input(
"a|1,2,3,4,5|Pick a number|LIST",
"b|aardvark, beagle, cow, deer|Animals|LIST",
"c|99|Just a text box|TEXT",
"d|D&D, GURPs, Hero|Games|LIST",
"e|a,b,c,d,e||LIST",
"f|2,3,5,7,11,13,15|Primes|LIST")]
- Use the Tab key to jump from item to item. Does it take you more than one press of the Tab key to go from one list to the next? If so, how many?
- When you use the Tab key, does the highlight stop at each list, or does it skip any of them (making it impossible to select them using the keyboard)?
- With one of the lists selected, hit the down arrow key to drop the list down. With the list down, hit the Tab key to jump to the next input field. Does the dropdown list go away as it should, or does it remain visible?
- Use the mouse to drop down a list by clicking on the text. When you hit Tab, does the list close immediately and does the selection jump to the next input field?
- Use the mouse to drop down a list by clicking on the little arrow. When you hit Tab, does the list close immediately and does the selection jump to the next input field?
--k.fan
EDIT: 15-Sep-2008 Added b43 info for getStrProp()
EDIT: 16-Sep-2008 Updated settings file provided to solve a problem on Linux
EDIT: 1-Oct-2008 Updated for b46 changes