|
Titan API.
This section describes the Titan API - the various routines developers are welcome to use.
====== DocTitanPlugin.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
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.
====== LDBToTitan.lua ======
LDB (LibDataBroker) to Titan notes
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 ======
Titan templates
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);
OnShow: TitanPanelButton_OnShow(self);
OnClick: TitanPanelButton_OnClick(self, button);
OnEnter: TitanPanelButton_OnEnter(self);
OnLeave: TitanPanelButton_OnLeave(self);
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
colored 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
self - the frame of the plugin
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>
Update commands include:
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.
Inputs
None
Outputs
frame - TitanPanelTopAnchor - Titan uses the space ABOVE this
frame - TitanPanelBottomAnchor - 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
value - of the MinimapAdjust option
TitanUtils_SetMinimapAdjust
Set the current setting of the Titan MinimapAdjust option.
Inputs
None
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; 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
table - of the button or nil
string - id of the plugin or nil
TitanUtils_GetRealPosition
Return whether the plugin is on the top or bottom bar.
Inputs
id - is the id of the plugin
Outputs
int - 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.
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
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
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
b (true) or c (false)
TitanUtils_Toggle
Flip the value assuming it is true or false
Inputs
value - value to start with
Outputs
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 of max (a, b)
TitanUtils_GetEstTimeText
Use the seconds (s) to return an estimated time.
Inputs
s - a time value in seconds
Outputs
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 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 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
nil or the control frame
TitanUtils_TableContainsValue
Determine if the table contains the value.
Inputs
table - table to search
value - value to find
Outputs
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
nil or the index
TitanUtils_GetCurrentIndex
Determine if the table contains the value.
Inputs
table - table to search
value - value to find
Outputs
nil or the index to value
TitanUtils_GetRedText
Make the given text red.
Inputs
text - text to color
Outputs
Red string with proper start and end font encoding
TitanUtils_GetYellowText
Make the given text yellow.
Inputs
text - text to color
Outputs
Yellow string with proper start and end font encoding
TitanUtils_GetGoldText
Make the given text gold.
Inputs
text - text to color
Outputs
Gold string with proper start and end font encoding
TitanUtils_GetGreenText
Make the given text green.
Inputs
text - text to color
Outputs
Green string with proper start and end font encoding
TitanUtils_GetBlueText
Make the given text blue.
Inputs
text - text to color
Outputs
Blue string with proper start and end font encoding
TitanUtils_GetNormalText
Make the given text normal (gray-white).
Inputs
text - text to color
Outputs
Normal string with proper start and end font encoding
TitanUtils_GetHighlightText
Make the given text highlight (brighter white).
Inputs
text - text to color
Outputs
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
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
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 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
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
true (successful) or false
TitanUtils_PrintArray
Debug tool that will attempt to output the index and value of the array passed in.
Inputs
array - array to output
Outputs
Array output to the chat window
====== 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
| 