prestidigitator wrote:So it seems pretty obvious when 'onChangeImpersonated' and 'onChangeSelection' fire, but what about 'onChangeToken'? Is there more information than just "doesn't always work perfectly"? What token has to change in order for the event to fire? Is it the token that was current when the [frame:] call was made? What is it that makes it "not perfect"? It seems like this is the functionality people might be searching for to handle manual or automated updates, so what are the deficiencies, and when--if ever--CAN we rely on this event? Is it so poorly implemented and/or badly understood that we should just ignore its existence entirely?
From Craig's comments:
The change token one is kinda tricky, it gets fired often even when it appers there has been no change to the token -- but MapTool has updated something internally that is not visible to either the user or macros -- this is why it is reccomended to have your macro update the dialog/frame when changing a token if possible, it will lead to the code being executed a lot less often
What constitutes a "change" to a token is not strictly a change in a property manipulable by macro functions or by the UI. It could - in addition to a property value change or changing it to an NPC or something - be something internal to the token's XML that is handled entirely within MapTool, and therefore I wouldn't consider it a reliable means to update a frame or dialog. Now, such an internal change may be irrelevant to any value important to the user, meaning that the macro being called by onChangeToken is run for no particular reason, but doesn't fail.
In all cases, what constitutes an event intuitively might not be the same way internally (hence why "onChangeSelection" may fire anywhere between 1 to 4 times every time you select a token). I would expect that onChangeToken probably works as reliably as the others, but you can't predict how many times it will fire, and it may fire when you haven't done anything yourself to change the token (but MapTool
has made a modification).
Automatic updating is trivially handled via macro anyway; an explicit call to the frame-generating macro does the trick as easily as a callback.
Edit: Some specifics
I put together a very small campaign file that tests what might fire onChangeToken.
First off, I get a null pointer exception thrown every time I try it - something in the code is having some troubles. However, the events still fire (and the testing frame still does the trick).
So:
Moving a token fires the event twice.
Opening the Edit Token dialog (whether you change anything or not) fires the event twice
Running a macro that changes token properties fires the event twice (including things like the special token.whatever variables, it seems)
Changing a token's type (from NPC to PC) fires an additional change event on top of any property change events being fired
Setting a state or clearing it via right-click fires the event once
changing size fires the event once
Adding a light source fires the event once
Initiative actions have no effect on onChangeToken
Flipping a token horizontally or vertically seems to throw MapTool into and endless loop of onChangeToken events
Halo changes fire the event once
Snap to grid changes fire the event once
There are probably others I couldn't think of, but I ran through the right click menu and some experimental macros. The biggest problem I had was that every onChangeToken event also triggered a null pointer exception.