RPTools.net

An Introduction to MapTool Macro Dialogs and Frames

Please note I will be using CSS and HTML in this tutorial but I
will not really be explaining them, if you need a refresher on
either a search on google will point you to many resources that
do a better job than I could

This post refers to functionality in 1.3 b48 or newer

The [dialog(): { }] and [frame(): { } ] "roll types" create a new
dialog or frame where all the output from the commands within the
{} will be displayed.
dialog create a dialog box that hovers over other windows.
frame creates a frame that can be docked like the other maptool
windows.
The dialog and frame windows can be used to display HTML and rolls
the same as the chat output window.

This tutorial starts with the standard blank campaign you get when
you start MapTool, anything else we need we will add along the way.

First steps
So lets jump in and create your first dialog, you can use the code
below to create a dialog.




I know its pretty boring but before we start adding more to it
lets create a frame so that you can see the difference





And a picture of your first frame docked with the other MapTool windows.



Back to the dialog you can spice it up a little with some dice rolls
and HTML formatting.

This will create a dialog box with some HTML formatting and dice rolls.
The dice rolls will have all the tooltips that you would normally get
in the chat output.

Still the title is boring (it defaults to the name of the dialog).
You can use the HTML <title> tag to change the title. Run the
code below, there is no need to close the dialog from the code
above.




Notice that the dialog command did not open a new dialog window,
instead it replaced the contents of the dialog you had open. When
you use [dialog()] with the name of a dialog that already exists
the contents of that dialog are replaced, ([frame()] works the
same way).

You can use this behavior to update your dialogs.
Create a token called Lib:Test with a macro called Test
Copy the following code into the Test macro.




The above macro uses the macroLink() function to create a link
that will call Test on Lib:Test when ever it is clicked (which
will update the dialog with new rolls).


The above would be really useful if you needed a window that provided
you with a bunch of dice rolls all the time. But I assume that is not
what most people will want to do with the dialogs.

Drag another token out on to the map, and fill in the token properties.
We can create a simple character sheet with a dialog.
On the Lib:Test token create a macro called CharSheet and paste the
following code into it.

On the new token that you placed on the map create a macro called
CharSheet and paste the following into it.

Click on the new macro button

Again we are not going to set the world on fire with this character sheet
dialog. Lets spice it up a little, I will show you how to use some CSS for
formating.

To use CSS you insert a line like the following into the HTML to be displayed

Although you can (and probably should) use the getMacroLocation() function to
make sure it comes from the same Lib: token as the macro. So,


Edit the CharSheet macro on the Lib:Test token and paste in the following.


Also create a new macro button on Lib:Test called CharSheet_css and paste
the following CSS code into it.


Click on the CharSheet macro button on your token.



Getting better... Lets make some more changes.

Change he CharSheet macro on Lib:Test to




Looks much better already!

Ok in Edit->Campaign Properties, Token Properties Tab, Basic Token type,
add the following properties

• *@MaxHP
• *@XP
• *@NextLevelXP

Then edit your token and some values to your new properties.

Time to create a new macro on the Lib:Test called TrafficLightBar and paste
the following code into it.


Create another macro on Lib:Test called StatusBar and paste the following code
into it.



I am really going to gloss over the previous two functions a bit as they are
not important to understanding how to use dialogs or frames, but so you know
what they do TrafficLightBar creates a red/yellow/green bar where the color
is based on how full the bar is. StatusBar just creates a bar that is one color.

Just a quick point for those who may not know this already, but when you
call a macro with [macro("blah"): arguments] the arguments are available in
the macro in the variable macro.args. To return a value from the macro you
read the variable macro.return, the calling macro can then read macro.return
to get this value.

Then we change the CharSheet macro on Lib:Test to



Click on the CharSheet macro button on your token again and you will have a
new character sheet.



The above example uses one of the new functions in b48 strformat() which
allows you to insert variables in a string using the %{var} syntax. It also
has other flags that can be used to format variable output, see the
b48 macro addition reference thread for more information.

Lets leave the character sheet at this for the moment and move on to a new
example.

Edit->Campaign Properties, Token Properties Tab, Basic Token type,
add the following properties

• Weapons
• Items

We are going to store our weapons in a string property list with the folowing
keys.

• NumWeapons - The number of weapons in our property list.
• UsingWeapon - The weapon we are currently using.
• WeaponXName - The name of weapon number X
• WeaponXDamage - The damage of weapon number X
• WeaponXBonus - The bonus of weapon number X

We could add a lot more, but lest keep it semi simple for this post.

The first thing we need is a way to enter weapons, we could use the input()
function but since this is a tutorial on frames and dialogs, I should probably
show you how to do it in a dialog.

But first we need to do some set up, when the player creates a new weapon we
will need to get NumWeapons add 1 to it, save it back to the property and use
that number (lets not worry about what happens if a player cancels the entry
of the weapon as we are not really that worried if we have gaps in our
numbering scheame). One problem is though what do we do first time around
snce the property list would be empty so trying to use the token property
Weapons in strProp*() functions would result in the user being prompted for
a value. We could add a default value in the campaing for the token, but
there are also other methods.
One thing we can do is use the isPropertyEmpty() function to check if the
property is empty and if so use a initial value for it, or the
getProperty() function that will just return an empty string ("") not
prompt if there is no property.

So lets create a macro that returns the number of a new weapon. Create
a macro called NextWeaponNumber and then paste the following code into it.


You can test it by running running the following code from chat a few times

When you are done you can reset the weapon count simply by editing the token
properties and clearing out the text for weapons.

Lets also make a macro called AddWeapon which takes a property list with the
following keys

• Name
• Damage
• Bonus
• Number

And adds or updates the weapon in the string property list.


You can test this macro too by a little typing at the command line.


Look at the Weapons property and see how its built up our string propety list
for us. It wont have modified NumWeapons but that is ok we are going to assume
that NextWeaponNumber is always used before adding a new weapon. Before clearing
out the Weapons property to reset it lets write a function to retrieve a
weapon.

Create a macro called GetWeapon on your Lib:Test token and paste the following
into it.


Test it with


Lets add a way to delete items. Create a macro called DeleteWeapon and paste
the following code.



One more "setup" function then we should be good to go.
Lets create a function that returns a string list of all the item numbers
(remember we can have gaps because a user could cancel the addition of the
item after calling NextWeaponNumber or they could delete a weapon).
Create a macro on Lib:Test called GetWeaponNumbers

The string() around the arguments in listAppend() is to convert the
arguments to strings, as of b48 listAppend() seems to have problems
with arguments that could be interpreted as numbers.


So now we can get back to the dialogs. Lets create a dialog to edit weapons.
Create a macro on your Lib:Test called EditWeaponDialog and paste the following
into it.

A Couple of things to notice, for the second argument to dialog() I have
undecorated=1. This is the same as using <meta name="input" content="1">.
Unfortionately the meta tag option has a bug at the moment so for now
you should use "undecorated=1", when I submit the patch to fix the
meta tag either option will work. The second thing to note is @this will
not work in a macro link, so I build the @ portion of the macro to
call when the form is submitted.

The action=... portion of the form tag specifies which macro to call when
any submit button is pushed for the form. If the dialog is specified as
a input dialog, the close button down the bottom is not displayed and when
any form on the dialog is submitted it is closed.

The arguments to the macro that is called when the form is submitted is
a string property list with the names of the input fields as the keys and
the entered value as the values. Since I named all my inputs the same
as the keys in the parameter for the AddWeaponMacro I can call that
straight from the submit action on the form (some times is seems like
I almost know what I am doing).

The only problem is our edit weapon is kinda plain compared to our character
sheet so time to add a little bling.

Change your EditWeaponDialog button on Lib:Test to


And add EditWeapon_css to Lib:Test that contains


And you might as well add a AddWeapon button to your Token that contains


Now our dialog looks like



Ok now lets make a quick dialog to display our weapons. Create a new
macro on your Lib:Test called ViewWeapons and paste in the following


For good measure create a macro button called ViewWeapon_css on Lib:Test
paste in the following.


Add a button to your token called ViewWeapons which contains

And this is what it looks like




* Edited to correct syntax errors

Up until now I havent talked at all about frames, but don't worry , change
[dialog(...] to [frame(...] above and it will work (except you cant have
a frame that closes when you submit a form, what would be the point?).

But lets make some final changes to show some frames, I am going to make
all of these in one go as everything in them has been discussed previously
in this post.

First we are going to completely change the CharSheet macro on Lib:Test to


Create CharSheetHeader on Lib:Test


Create CharSheetMain on Lib:Test


Also create CharSheetWeapons on Lib:Test


And the last change to make is to CharSheet_css on Lib:Test


So what does this give us? A sihny new frame. Unlike Dialogs, Frames act like
any of the other maptool windows and can be docked on the sides, or with other
windows (forming a tab).



Where it says Main and Weapons on the top, they are links, if you click on
Weapons it will change the CharacerSheet frame to



And as an added bonus, the weapon names are links, if you click on them it
will open up the edit dialog where you can edit them. (note this will
not update the character sheet at this time, but that is left as an
exercise for the reader).

This has just been a short example of what can be done, I am sure people will
come up with some great ideas how to use this.

You can also have dialogs/frames update themselves depending on which tokens
are selected or impersonated (so if you select a new set or impersonate a
different token it can update itself) for the commands you use to do that see
b48 macro addition reference thread for more information.

Nice tutorials. Can't wait to look at them completely when I have more time this weekend. Just wonder but are all the dialog boxes setup to do HTML? I only know some basic HTML but at first glance it looks like HTML coding style.

Also it would be great to have a working example to see and play around with . Is there any chance you can upload the campaign file with your tutorial tokens and macros in them?

Craig, Pyromancer2k mentioned in another thread that these dialogs are private (or can be made to display to only the GM, for instance) - how would that be done (or can it be done)?

It might solve a problem I've been thinking about that came up elsewhere on the forums.

You can't pop up a dialog on someone else, the reason being the potential issues (just think of all those dialog boxes popping up when players start mucking around aieee). Plus to display a dialog box you need to run a macro I am not sure we want to go down the path of someone else automatically running a macro on your machine.

What you can do is send a link to someone else and clicking on the link runs a macro which displays the dialog. macro links have a tooltip which pops up that lets you verify exactly what macro is going to be run, on which tokens and with which arguments.

*Edit:
I may look at the possibility of allowing trusted macros to do something, but that will have to wait until after I complete some other stuff.

It's actually less of a big deal than I thought - it was originally in the attempt to develop the "fudging skill rolls" system where the GM has a chance to see a roll before the player does, and fudge it "automatically." I came up with a macro-handoff sequence that worked out.

I don't know how useful it would have been; it was mostly just to see if I could do it.

I would agree that perhaps we don't want to flood each other with dialogs, or allow other people to run anything on each others' machines.

Campaign


Its not 100% the same as the tutorial as I made some changes to it but its very close.

Also I know it has problems with changing impersonated tokens but its only a short tutorial
You could easily fix them by either setting up a macro to be called from the dialog when impersonated token changes, or when the dialog first runs grab the token id and make sure you are always using [token(): ] or switchToken() so you are accessing the correct token. It all depends on if you want the sheet to always refer to same token or always refer to impersonated token. It also wont fail gracefully if there is no token impersonated and you click on the links up the top.

I have been working on a character sheet and struggling with a couple of points.

1) If I use an abort(0) in a library called macro, a message goes to the chat window stating "Abort() function called."

Calling Campaign Macro:


Library Macro:


2) I want the character sheet to stay up and autorefresh. I have it partially working IF the token has been impersonated. But if I do not have a token impersonated, the Frame loses focus as to what it is working on. I see from your comments that I should be getting the token.ID and using that ... but I do not see where the Frame has any variable persistence... are you saying I should store the token.ID in a Library property?

Ugh, I will take a look at this me no likey how abort() is implemented...



You can do that but if multiple players are running the token you can get into trouble.
If you are wanting to make sure you get the correct token when a link is on the dialog is clicked on you can pass the token id as an argument. (macroLink() allows you to pass arguments).

So when the dialog is run you get the value of say tokenId from macro.args (as a property list) if its not there then you set tokId = currentToken(), otherwise you set tokId to what ever tokenId= in the properties.

Is it at all possible to have a macro run by a player create a frame that only the GM can see? I want to be able to compare attack rolls against defenses, but have the "player x has hit/missed enemy y" appear on a frame that only I can see.

Since I finished my token updates and Gallery is messed up so I can't post pics to update my Documentation I figured I'd check out all the new stuff.

Anyway I was taking your tutorial and have noticed some errors.

1) The code where you show a person to do their first frame is the same as the Dialog.
2) The Get Weapon Calling Macro has a syntax error. There should he a comma not a colon after the h.
3) For some reason I can't run the edit weapon dialog box. It does the chat fills up and won't run.
4) On the Weapon View Calling Macro you have a comma at the end where there should be a colon.
5) When I try to change to the weapons page I get this error Messages.


I tracked down the 2 macros that use that line and both ran fine on their own. I then tried it on your tutorial campaign and the same thing happen. I did found a weird work around though. If I open char sheet first with the macro. Then click the AddWeapon Macro the chat fills up but doesn't run. Then I click on the Weapons link at the top of the frame it then opens up the list of weapons?? I tried this multiple times and it seems you always have to do that to get it to work. Also I still can't open the Weapon Edit frame when running it from your campaign.

The chat fills up and doesn't run is a problem with how MapTool handles input text. Depending on how your java is set up and the amount of memory you have allocated and who wrote your JVM you may have enough stack space to avoid the problem or you may not. I already simplified that dialog box to the point where it ran ok on my computer as it was causing that error on my system (the original dialog box had more bling ). It is happening on a lot of macros recently because they are now starting to push towards the point where they complex enough to hit that limit.

I am looking at that problem now and trying to fix it.