TIO Developer Guide

This guide will cover how to hook your add-on into Topbar Information Overload to allow users to take advantage of the Add-on Manager in it.

You can add your add-on to the Add-on Manager even if your add-on doesn’t have options so the user can see the developer and version information for your add-on.

To be able to hook into the Add-on Manager there’s a few things which needs to be done.

You can download an example file here: http://dl.dropbox.com/u/21497376/TSW/UI/Viper_TIOExampleAddon.zip

Setting up your code

You need to import the DistributedValue class as this will be used to communicate between Topbar Information Overload and your add-on.

import com.GameInterface.DistributedValue;

Then create 2 variables, one for monitoring if Topbar Information Overload has loaded and one for your add-on information.

var m_VTIOIsLoadedMonitor:DistributedValue;
var VTIOAddonInfo:String = "MyAddOnName|MyName|1.2.3| MyAddOn_OptionWindowOpen|_root.myaddon\\myaddon.m_MyAddOnIcon";

Whitespace added in front of “MyAddOn_OptionWindowOpen” to allow for line break in the above code.

The VTIOAddonInfo string is separated into sections using the | character, so do not use that in any of your information.

The first part is the name of your add-on.

Second part is your name, to be shown as the developer in the tooltip inside the Add-on Manager.

Third part is the current version of your add-on likewise to be shown in the tooltip inside the Add-on Manager. Feel free to use any format you like.

Fourth part is the name of the distributed value used to open and close your option window – more on this in the “Setting up your option window distributed value” section. Can be undefined if you don’t have any options. Make sure this is a unique name as distributed values exist across add-ons.

Fifth and last part is the location of the icon for your add-on – more on this in the “Setting up your icon” section. Can be undefined if you don’t have any icon (this will also mean that your add-on won’t be slotable).

You then need to setup the monitor to check for the loaded state of Topbar Information Overload. You can put this in the onLoad function of your add-on.

m_VTIOIsLoadedMonitor = DistributedValue.Create("VTIO_IsLoaded");
m_VTIOIsLoadedMonitor.SignalChanged.Connect(SlotCheckVTIOIsLoaded, this);

This sets up a listener for when the distributed value VTIO_IsLoaded changes, meaning that when Topbar Information Overload is ready to accept registration of your add-on this will be broadcast and set to true.

When you are ready to register your add-on, likely in the onLoad or OnModuleActivated functions, you call the SlotCheckVTIOIsLoaded function that we will create next. This is being called in case Topbar Information Overload has loaded before your add-on and already broadcast its loaded state. If Topbar Information Overload gets loaded after your add-on the loaded monitor we just setup is needed to catch the broadcast.

The SlotCheckVTIOIsLoaded function is pretty simple and looks like this:

function SlotCheckVTIOIsLoaded() {
 if (DistributedValue.GetDValue("VTIO_IsLoaded")) DistributedValue.SetDValue("VTIO_RegisterAddon", VTIOAddonInfo);
}

The function checks if Topbar Information Overload is actually loaded and if so sends the string with your add-on information to register it.

Setting up the option window distributed value

For the Add-on Manager to be able to open and close your option window you need to have a distributed value created that will handle this. It’s done much like the monitor you setup to check for the loaded broadcast from Topbar Information Overload.

First create a variable for the option window state monitor.

var m_OptionWindowState:DistributedValue;

In your onLoad function put in the following code to hook it up.

m_OptionWindowState = DistributedValue.Create("MyAddOn_OptionWindowOpen");
m_OptionWindowState.SignalChanged.Connect(SlotOptionWindowState, this);

Notice that in the Create() function it’s been given the same name as was defined in your VTIOAddonInfo string. This, of course, is pretty important. :)

You then create another function that will handle the changes to your distributed value that you just setup. This is done because the Add-on Manager will use the distributed value to send the open/close commands to your add-on.

function SlotOptionWindowState() {
  var isOpen:Boolean = DistributedValue.GetDValue("MyAddOn_OptionWindowOpen");
  MyAddOnOptionWindowInstanceName._visible = isOpen;
}

As obvious it sets the visible state of your option window to the value of the distributed value for your window state monitor. You can of course expand this function but that there is the basics of it.

Setting up your icon

Setting up an icon for your add-on is needed if you want your add-on to be slotable. This means that the user can choose to display your icon in any of the pre-defined slots in the topbar to quickly access the functions you setup for your icon.

In terms of requirements for the icon there are a few things to take note of:

It has to be square because I resize it as such (and makes the most sense for dealing with it in the slot system), but the actual size doesn’t matter. It should however be noted that the resulting size will be about 18×18 pixels, so that might be worth keeping in mind when making it.
To make your symbol square and create the proper “click area” I suggest creating a 32×32 (or whatever) box and then convert it to a symbol that will be your icon. While designing your icon set the box’ alpha to like 50%, so you have the contraints of your icon visible, then when all done reduce the alpha to 0%. Of course create your actual icon on different layers than the box you just made.

It has to be placed at depth_layer Top and sub_depth 2 as the minimum in Modules.xml, otherwise it will be placed behind the topbar. I will try and see if I can solve this in the future.
If this isn’t possible due to your add-on needing to be placed differently  you can create a separate .swf file with your icon in it and communicate between the icon .swf file and your actual add-on using distributed values to make sure everything is loaded in the right order before you send your add-on information to Topbar Information Overload. If the icon isn’t present at the time you send the information your icon won’t show up for the user to be able to use it.

Setting up your icon in code isn’t all that important. You’d most likely place it somewhere already for users who don’t use Topbar Information Overload, so what you need to do is pass the location of your icon on to the Add-on Manager. The location needed you can find by pressing Ctrl + Shift + F2 in-game to open the debug window and then find your add-on and the full path to your icon. This is what you need to pass on in the VTIOAddonInfo string. If the path has \‘s in it you need to write them as \\ in the VTIOAddonInfo string.
When you register your add-on with Topbar Information Overload I will hide your icon so you don’t need any extra code to hide it for those who use Topbar Information Overload and keep showing it for those who do not.

Otherwise you will just create the functions you need for your icon as per usual and the Add-on Manager will use those when the user interacts with your icon. The functions supported by the Add-on Manager are:

onPress
onRollOver
onRollOut
onMousePress
onMouseDown
onMouseUp
onRelease
onReleaseOutside

Do you need anything?

Please let me know if there’s something specific you would like to see possible for add-ons to do and I will try to accomedate you. :)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s