Titan Logo

 Menu

 Developer

Titan API.

This section describes the Titan API - the various routines developers are welcome to use.

====== LDBToTitan.lua ======

Titan LDB overview
Titan will automatically convert a LDB type addon to a Titan plugin.
Only LDB types listed in the LDB 1.1 spec are supported. Custom types are not supported.

Supported
- "launcher" become "icon" plugins
icon* - always shown
OnClick* -
label^ -
right side^ - default
tooltip
- "data source" become "combo" plugins with icon; a tooltip/Click; and optional label
icon^ -
OnClick -
text*^ - or value & suffix
label^ -
OnEnter -
OnLeave -
tooltip
OnTooltipShow -

* required by LDB spec
^ user controlled show / hide

====== TitanMovable.lua ======

TitanMovable_GetPanelYOffset
Get the Y axis offset Titan needs (1 or 2 bars) at the given position - top or bottom.

Inputs
framePosition - TITAN_PANEL_PLACE_TOP or TITAN_PANEL_PLACE_BOTTOM

Outputs
Y axis offset, in pixels

Notes
- The prefered method to determine the Y offset needed by using TitanUtils_GetBarAnchors().

====== TitanPanelTemplate.lua ======

TitanPanelTemplate overview
See TitanPanelButtonTemplate.xml also.

A Titan plugin is a frame created using one of the button types in TitanPanelButtonTemplate.xml which inherits TitanPanelButtonTemplate.
The available plugin types are:
TitanPanelTextTemplate - A frame that only displays text ("$parentText")
TitanPanelIconTemplate - A frame that only displays an icon ("$parentIcon")
TitanPanelComboTemplate - A frame that displays an icon then text ("$parentIcon" "$parentText")

Most plugins use the combo template.

TitanPanelButtonTemplate.xml contains other templates available to be used.
TitanOptionsSliderTemplate - A frame that contains the basics of a slider control. See TitanVolume for an example.
TitanPanelChildButtonTemplate - A frame that allows a plugin within a plugin. The older version of TitanGold was an example. This may not be used anymore.

Each template contains:
- a frame to handle a menu invoked by a right mouse click ("$parentRightClickMenu")
- default event handlers for
<OnLoad>
TitanPanelButton_OnLoad(self);
</OnLoad>
<OnShow>
TitanPanelButton_OnShow(self);
</OnShow>
<OnClick>
TitanPanelButton_OnClick(self, button);
</OnClick>
<OnEnter>
TitanPanelButton_OnEnter(self);
</OnEnter>
<OnLeave>
TitanPanelButton_OnLeave(self);
</OnLeave>
If these events are overridden then the default routine needs to be included!


TitanOptionSlider_TooltipText
Set the color of the tooltip text to normal (white) with the value in green.

Inputs
text - the label for value
value - the value

Outputs
string - encoded color string of text and value


TitanPanelButton_OnLoad
Handle the OnLoad event of the requested Titan plugin. Ensure the plugin is set to be registered.

Inputs
isChildButton - boolean

Notes
- This is called from the Titan plugin frame in the OnLoad event - usually as the frame is created.
- This starts the plugin registration process. See TitanUtils for more details on plugin registration.
- The plugin registration is a two step process because not all addons create Titan plugins in the frame create. The Titan feature of converting LDB addons to Titan plugins is an example.


TitanPanelPluginHandle_OnUpdate
A method to refresh the display of a Titan plugin.

Inputs
table - the frame of the plugin
oldarg - nil or command

Notes
- This is used by some plugins. It is not used within Titan.
- The expected usage is either:
1) Table contains {<plugin id>, <update command>}
2) table = <plugin id> and oldarg = <update command>
- oldarg - nil or command
1 = refresh button
2 = refresh tooltip
3 = refresh button and tooltip


TitanPanelDetectPluginMethod
Poorly named routine that sets the OnDragStart & OnDragStop scripts of a Titan plugin.

Inputs
id - the string name of the plugin
isChildButton - boolean


TitanPanelButton_OnShow
Handle the OnShow event of the requested Titan plugin.

Inputs
self - frame reference of the plugin


TitanPanelButton_OnClick
Handle the OnClick mouse event of the requested Titan plugin.

Inputs
self - frame reference of the plugin
button - mouse button that was clicked
isChildButton - boolean

Notes
- Only the left and right mouse buttons are handled by Titan.


TitanPanelButton_OnEnter
Handle the OnEnter cursor event of the requested Titan plugin.

Inputs
self - frame reference of the plugin
isChildButton - boolean

Notes
- The cursor has moved over the plugin so show the plugin tooltip.
- Save same hassle by doing nothing if the tooltip is already shown or if the cursor is moving.
- If the "is moving" is set the user is dragging this plugin around so do nothing here.


TitanPanelButton_OnLeave
Handle the OnLeave cursor event of the requested Titan plugin.

Inputs
self - frame reference of the plugin
isChildButton - boolean

Notes
- The cursor has moved off the plugin so hide the plugin tooltip.


TitanPanelButton_UpdateButton
Update the display of the given Titan plugin.

Inputs
id - string name of the plugin
setButtonWidth - new width


TitanPanelButton_UpdateTooltip
Update the tooltip of the given Titan plugin.

Inputs
self - frame reference of the plugin


TitanPanelButton_SetButtonIcon
Set the icon of the given Titan plugin.

Inputs
id - string name of the plugin
iconCoords - if given, this is the placing of the icon within the plugin
iconR - if given, this is the Red (RBG) setting of the icon
iconG - if given, this is the Green (RBG) setting of the icon
iconB - if given, this is the Blue (RBG) setting of the icon

====== TitanPluginDoc.lua ======

Titan API overview for developers
Updated Dec 2011

This documentation is intended for addon developers that wish to create a Titan plugin.

Terms:
Throughout the documentation and naming of routines and variables there are some terms that are used interchangably.
- Plugin / button / frame
- Character / player / toon
- Plugin ID / plugin name
Over time we desire to consolidate terms but it may take time.

Plugin Types:
Titan allows two types of plugins:
- Titan native
- LDB enabled addons
See http://code.google.com/p/titanpanel/downloads/list to download examples.

Titan Plugin Recognition:
Titan native plugins must use one of the Titan templates found in TitanPanelTemplates.xml.

LDB Plugin Recognition:
LDB enabled addons only need to adhere to the LDB (Lib Data Broker) 1.1 spec.
Titan uses the callback feature ("LibDataBroker_DataObjectCreated") to recognize LDB addons.
At player_login Titan registers the call back.
It then loops through the the LDB objects using :DataObjectIterator().
When any LDB object is found Titan will attempt to create a Titan native plugin for display.

Registration Steps:
Titan attempts to register each plugin it recognizes. Registration for Titan is a two step process.
Step one: On the creation of a Titan plugin frame place the plugin in a holding table until the "Player Entering World" (PEW) event is fired.
Step two: Once Titan is initialized it will take each plugin from this table and attempt to register it for display. The attempt uses a protected call (pcall) to protect the Titan core and (hopefully) prevents Titan from crashing.

Registration Attempts:
Each plugin attempt is placed in an 'attempted' table along with the results of the registration. This attempted table is accessible to the user in the Titan "Attempted" options. The developer can see what happened and users can report issues using that data.

Registry Table of Each Plugin:
Each plugin must contain a table called "registry".
self.registry = {}

The registry table must have a unique id across all Titan plugins that are loaded.
self.registry = {id = "MyPlugin"}
This is all that is required for successful registration. It will register but will be a rather dull plugin.
It is strongly recommended that you download the TitanStarter plugin example(see the link above). The example explains all the elements of the registry that Titan uses. The example is based on TitanBags so you can play with the code and compare it to a supported plugin.

Titan API:
The functions that Titan offers to the plugin developer are in a separate document. Within the Titan files you can recognize an API routine by the comment just before the function declaration. The comment block will have "API" as part of the starting block.

====== TitanUtils.lua ======

TitanUtils_GetBarAnchors
Get the anchors of the bottom most top bar and the top most bottom bar.
Intended for addons that modify the UI so they can adjust for Titan.
The anchors adjust depending on what Titan bars the user displays.

Inputs
None

Outputs
frame - TitanPanelTopAnchor frame reference - Titan uses the space ABOVE this
frame - TitanPanelBottomAnchor frame reference - Titan uses the space BELOW this

Notes
- The two anchors are implemented as 2 frames that are moved by Titan depending on which bars are shown.


TitanUtils_GetMinimapAdjust
Return the current setting of the Titan MinimapAdjust option.

Inputs
None

Outputs
The value of the MinimapAdjust option


TitanUtils_SetMinimapAdjust
Set the current setting of the Titan MinimapAdjust option.

Inputs
bool - true (off) or false (on)

Outputs
None


TitanUtils_AddonAdjust
Tell Titan to adjust (or not) a frame.

Inputs
frame - is the name (string) of the frame
bool - true if the addon will adjust the frame or false if Titan will adjust

Outputs
None


TitanUtils_GetButton
Return the actual button frame and the plugin id.

Inputs
id - is the id of the plugin

Outputs
frame - The button table
string - The id of the plugin


TitanUtils_GetRealPosition
Return whether the plugin is on the top or bottom bar.

Inputs
id - is the id of the plugin

Outputs
bottom(2) or top(1)-default

Notes
- This returns top or bottom NOT which bar (1-4) the plugin is on.


TitanUtils_GetButtonID
Return the plugin id of the given name. This can be used to see if a plugin exists.

Inputs
name - is the id of the plugin

Outputs
string - plugin id or nil


TitanUtils_GetParentButtonID
Return the plugin id of the parent of the given name, if it exists.

Inputs
name - is the id of the plugin

Outputs
string - plugin id or nil


TitanUtils_GetButtonIDFromMenu
Return the plugin id of whatever the mouse is over. Used in the right click menu on load.

Inputs
self - is the id of the frame

Outputs
string - plugin id or nil

Notes
- The plugin id returned could be the Titan bar or a plugin or nil.


TitanUtils_GetPlugin
Return the plugin itself (table and all).

Inputs
id - is the id of the plugin

Outputs
table - plugin or nil


TitanUtils_GetWhichBar
Return the bar the plugin is shown on.

Inputs
id - is the id of the plugin

Outputs
string - bar name or nil


TitanUtils_PickBar
Return the first bar that is shown.

Inputs
None

Outputs
string - bar name or nil


TitanUtils_ToRight
See if the plugin is to be on the right.
There are 3 methods to place a plugin on the right:
1) DisplayOnRightSide saved variable logic (preferred)
2) Create a plugin button using the TitanPanelIconTemplate
3) Place a plugin in TITAN_PANEL_NONMOVABLE_PLUGINS (NOT preferred)

Inputs
None

Outputs
bool - true or nil. true if the plugin is to be placed on the right side of a bar.


TitanUtils_Ternary
Return b or c if true or false respectively

Inputs
a - value to determine true or false
b - value to use if true
c - value to use if false or nil

Outputs
value - b (true) or c (false)


TitanUtils_Toggle
Flip the value assuming it is true or false

Inputs
value - value to start with

Outputs
bool - true or false


TitanUtils_Min
Return the min of a or b

Inputs
a - a value
b - a value

Outputs
- value of min (a, b)


TitanUtils_Max
Return the max of a or b

Inputs
a - a value
b - a value

Outputs
value - value of max (a, b)


TitanUtils_GetEstTimeText
Use the seconds (s) to return an estimated time.

Inputs
s - a time value in seconds

Outputs
string - string with localized, estimated elapsed time using spaces and leaving off the rest


TitanUtils_GetFullTimeText
break the seconds (s) into days, hours, minutes, and seconds

Inputs
s - a time value in seconds

Outputs
string - string with localized days, hours, minutes, and seconds using commas and including zeroes


TitanUtils_GetAbbrTimeText
break the seconds (s) into days, hours, minutes, and seconds

Inputs
s - a time value in seconds

Outputs
string - string with localized days, hours, minutes, and seconds using spaces and including zeroes


TitanUtils_GetControlFrame
return the control frame, if one was created.

Inputs
id - id of the plugin

Outputs
frame - nil or the control frame


TitanUtils_TableContainsValue
Determine if the table contains the value.

Inputs
table - table to search
value - value to find

Outputs
int - nil or the index to value


TitanUtils_TableContainsIndex
Determine if the table contains the index.

Inputs
table - table to search
index - index to find

Outputs
int - nil or the index


TitanUtils_GetCurrentIndex
Determine if the table contains the value.

Inputs
table - table to search
value - value to find

Outputs
int - nil or the index to value


TitanUtils_PrintArray
Debug tool that will attempt to output the index and value of the array passed in.

Inputs
array - array to output

Outputs
table - Array output to the chat window


TitanUtils_GetRedText
Make the given text red.

Inputs
text - text to color

Outputs
string - Red string with proper start and end font encoding


TitanUtils_GetGoldText
Make the given text gold.

Inputs
text - text to color

Outputs
string - Gold string with proper start and end font encoding


TitanUtils_GetGreenText
Make the given text green.

Inputs
text - text to color

Outputs
string - Green string with proper start and end font encoding


TitanUtils_GetBlueText
Make the given text blue.

Inputs
text - text to color

Outputs
string - Blue string with proper start and end font encoding


TitanUtils_GetNormalText
Make the given text normal (gray-white).

Inputs
text - text to color

Outputs
string - Normal string with proper start and end font encoding


TitanUtils_GetHighlightText
Make the given text highlight (brighter white).

Inputs
text - text to color

Outputs
string - Highlight string with proper start and end font encoding


TitanUtils_GetColoredText
Make the given text a custom color.

Inputs
text - text to color
color - color is the color table with r, b, g values set.

Outputs
string - Custom color string with proper start and end font encoding


TitanUtils_GetThresholdColor
Flexable routine that returns the threshold color for a given value using a table as input.

Inputs
ThresholdTable - table holding the list of colors and values
value -

Outputs
string - The color value from the treshhold table


TitanUtils_ToString
Routine that returns the text or an empty string.

Inputs
text - text to check

Outputs
string - string of text or ""


TitanPanelRightClickMenu_AddTitle
Menu - add a title at the given level in the form of a button.

Inputs
title - text to show
level - level to put text

Outputs
None


TitanPanelRightClickMenu_AddCommand
Menu - add a command at the given level in the form of a button.

Inputs
title - text to show
value - value of the command
functionName - routine to run when clicked
level - level to put command

Outputs
None


TitanPanelRightClickMenu_AddSpacer
Menu - add a blank line at the given level in the form of an inactive button.

Inputs
level - level to put the line

Outputs
None


TitanPanelRightClickMenu_Hide
This will remove the plugin from the Titan bar.

Inputs
value - id of the plugin

Outputs
None


TitanPanelRightClickMenu_AddToggleVar
Menu - add a toggle variable command at the given level in the form of a button.

Inputs
text - text to show
id - id of the plugin
var - the saved variable of the plugin to toggle
toggleTable - control table (called with other than nil??)
level - level to put the line

Outputs
None


TitanPanelRightClickMenu_AddToggleIcon
Menu - add a toggle Icon (localized) command at the given level in the form of a button. Titan will properly control the "ShowIcon"

Inputs
id - id of the plugin
level - level to put the line

Outputs
None


TitanPanelRightClickMenu_AddToggleLabelText
Menu - add a toggle Label (localized) command at the given level in the form of a button. Titan will properly control the "ShowLabelText"

Inputs
id - id of the plugin
level - level to put the line

Outputs
None


TitanPanelRightClickMenu_AddToggleColoredText
Menu - add a toggle Colored Text (localized) command at the given level in the form of a button. Titan will properly control the "ShowColoredText"

Inputs
id - id of the plugin
level - level to put the line

Outputs
None


TitanPanelRightClickMenu_AddHide
Menu - add a Hide (localized) command at the given level in the form of a button. When clicked this will remove the plugin from the Titan bar.

Inputs
id - id of the plugin
level - level to put the line

Outputs
None


TitanPanelRightClickMenu_ToggleVar
This will toggle the Titan variable and the update the button.

Inputs
value - table of (id of the plugin, saved var to be updated, control table)

Outputs
None


TitanPanelRightClickMenu_AllVarNil
Check if all the variables in the table are nil/false.

Inputs
id - id of the plugin
toggleTable - table of saved var to be checked

Outputs
bool - true (1) or nil


TitanPanelRightClickMenu_AddToggleColoredText
This will toggle the "ShowColoredText" Titan variable then update the button

Inputs
id - id of the plugin
level - level to put the line

Outputs
None


TitanUtils_IsPluginRegistered
See if the given plugin was registered successfully.

Inputs
- id - id of the plugin

Outputs
None

====== TitanVariables.lua ======

TitanGetVar
Get the value of the requested plugin variable.

Inputs
id - the plugin name (string)
var - the name (string) of the variable

Outputs
None

Notes
- 'var' is from the plugin <button>.registry.savedVariables table as created in the plugin lua.


TitanVarExists
Determine if requested plugin variable exists.

Inputs
id - the plugin name (string)
var - the name (string) of the variable

Outputs
None

Notes
- 'var' is from the plugin <button>.registry.savedVariables table as created in the plugin lua.
- This checks existence NOT false!


TitanSetVar
Get the value of the requested plugin variable to the given value.

Inputs
id - the plugin name (string)
var - the name (string) of the variable
value - new value of var

Outputs
None

Notes
- 'var' is from the plugin <button>.registry.savedVariables table as created in the plugin lua.


TitanToggleVar
Toggle the value of the requested plugin variable. This assumes var value represents a boolean

Inputs
id - the plugin name (string)
var - the name (string) of the variable

Outputs
None

Notes
- Boolean in this case could be true / false or non zero / zero or nil.


TitanPanelGetVar
Get the value of the requested Titan variable.

Inputs
var - the name (string) of the variable

Outputs
value of the requested Titan variable

Notes
- 'var' is from the TitanPanelSettings[var].


TitanPanelSetVar
Set the value of the requested Titan variable.

Inputs
var - the name (string) of the variable
value - new value of var

Outputs
None

Notes
- 'var' is from the TitanPanelSettings[var].


TitanPanelToggleVar
Toggle the value of the requested Titan variable. This assumes var value represents a boolean

Inputs
var - the name (string) of the variable

Outputs
None

Notes
- Boolean in this case could be true / false or non zero / zero or nil.


TitanAllGetVar
Get the value of the requested Titan global variable.

Inputs
var - the name (string) of the variable

Outputs
None

Notes
- 'var' is from the TitanAll[var].


TitanAllSetVar
Set the value of the requested Titan global variable.

Inputs
var - the name (string) of the variable
value - new value of var

Outputs
None

Notes
- 'var' is from the TitanPanelSettings[var].


TitanAllToggleVar
Toggle the value of the requested Titan global variable. This assumes var value represents a boolean

Inputs
var - the name (string) of the variable

Outputs
None

Notes
- Boolean in this case could be true / false or non zero / zero or nil.


TitanVariables_GetPanelStrata
Return the strata and the next highest strata of the given value

Inputs
value - the name (string) of the strata to look up

Outputs
string - Next highest strata
string - passed in strata


TitanVariables_SetPanelStrata
Set the Titan bars to the given strata and the plugins to the next highest strata.

Inputs
value - strata name (string)

Outputs
None