Monday, February 19, 2007

Multiple Callbacks Per Event

In 1.06, it will be possible to set up multiple GUI callbacks on a single UI event in XML. The syntax will be to use the event name and append a number to it. The engine will read in the callbacks until it fails to find the next sequential number.

For example, I could set up a UI Button to with the following callbacks:

OnUpdate=UIObject_OnUpdate_DisableIfLocalVarEquals(local:3,"true")
OnLeftClick=UIObject_Input_ScreenOpen("SCREEN_OPTIONS","false")
OnLeftClick0=UIObject_Input_SetLocalVarString(local:3,"true")

When I click that button, it would open the Options screen, then set the local var to "true". On its next update, it would become disabled because of the OnUpdate check.

Note that the callback without a number will be handled before the 0'th callback.
So OnLeftClick will be handled before OnLeftClick0.

Also note that the callback without the number is not required but is mostly just supported for backwards compatibility.

For example, it would be valid to have the following callbacks:

OnLeftClick0=
OnLeftClick1=
OnLeftClick2=

That will work fine, executing 0, then 1, then 2.

It is also valid to have:
OnLeftClick=
OnLeftClick0=
OnLeftClick1=
OnLeftClick2=

This will execute them in order.

It is not valid to start with any other number besides 0 however.

OnLeftClick1=
OnLeftClick2=
OnLeftClick3=

will result in no callbacks being loaded for that event for that UIObject.

Sometimes the engine assigns callbacks to UIObjects internally. The engine will only ever override the first callback, so if you are having a problem with the engine overriding your callback for some UI Object, you might need to insert a dummy callback first, before the callbacks you actually want to execute. This doesn't happen too often though, so I doubt this will be an issue for very many.

Note at this time, the only event that doesn't support multiple callbacks is OnTooltip, due to how the engine has to handle this event internally. I may or may not be able to fix OnTooltip by the time 1.06 comes out.

1 comment:

Anonymous said...

Aw. I do hope fixing OnTooltip is on your list though. It's the closest thing to OnMouseOver we have, and it's not always an option to sacrifice displaying tooltip for other actions.