Updated Oct 05, 2008 by tristTitan
Labels:	Phase-Implementation, Phase-Design, Phase-Requirements, Featured

Developer_Changes_For_4_0_0_30000

Important changes in the next major update for Wrath of the Lich King.

Introduction

With the removal and replacement of the Rock framework with Ace3, plus several different implementations in the default UI, a decision was made to modify/rewrite several functions and methods, in order for the Panel to function properly in WoW 3.0. Below you will find a small list of changes, new methods/functions that are now being used, plus simple examples and notes to help you in updating your addons or creating new ones.

Changes in 4.0.0.30000

Declarations

TITAN_NIL has been removed. Use 1 and false for your plugin boolean savedvars.

Functions

You should only update/call the functions that your plugin was/is using (or may use in the future) after doing its own work in the relevant script handlers. You do not need to specify every single handler because you plugin button is inheriting a template that already does that.

1. TitanPanelButton_OnLoad(isChildButton) has been changed to TitanPanelButton_OnLoad(self, isChildButton)

self (frame) : frame reference to your Titan Button. This is now a required argument. If you omit it, your plugin simply won't get registered and thus will not show on Titan's plugin list (right-click menu).

isChildButton (boolean): true if your Titan Button is a child button. This is normally handled internally and you shouldn't mess with it unless you want to do something on your child button's OnLoad handler. In such a case, after your are done, you should be calling the function like this (from your OnLoad handler) : TitanPanelButton_OnLoad(self, true)

2. TitanPanelButton_OnShow() has been changed to TitanPanelButton_OnShow(self)

self (frame) : frame reference to your Titan Button. This is now a required argument. If you omit it, your plugin will not get updated when the OnShow handler is invoked.

3. TitanPanelButton_OnClick(button, isChildButton) has been changed to TitanPanelButton_OnClick(self, button, isChildButton)

self (frame) : frame reference to your Titan Button. This is now a required argument. If you omit it or use just the old argN argument, your button will not handle right-clicks properly. All previous TitanPanelButton_OnClick(arg1) calls should be converted to TitanPanelButton_OnClick(self, button), while obviously providing a proper 'self'.

isChildButton (boolean): true if your Titan Button is a child button. Use this only if you want to "catch" the right-click invoking the plugin menu, after you have called your own function(s). The call should look like this: TitanPanelButton_OnClick(self, button, true) instead of the "old" : TitanPanelButton_OnClick(arg1, 1)

4. TitanPanelButton_OnEnter(isChildButton) has been changed to TitanPanelButton_OnEnter(self, isChildButton)

self (frame) : frame reference to your Titan Button. This is now a required argument. If you omit it, the tooltip may not show up.

isChildButton (boolean): true if your Titan Button is a child button.

5. TitanPanelButton_OnLeave(isChildButton) has been changed to TitanPanelButton_OnLeave(self, isChildButton)

self (frame) : frame reference to your Titan Button. This is now a required argument. If you omit it, the tooltip may not hide properly and in addition the "Auto-Hide" feature may break.

isChildButton (boolean): true if your Titan Button is a child button.

6. TitanPanelButton_UpdateButton(id, setButtonWidth) hasn't changed but it will not do anything if your plugin isn't properly registered via TitanPanelButton_OnLoad (it won't break either).

7. TitanPanelButton_UpdateTooltip() has been changed to TitanPanelButton_UpdateTooltip(self)

self (frame) : frame reference to your Titan Button. This is now a required argument. If you omit it, the tooltip will not update "on-the-fly".

8. TitanUtils_GetButton(id, returnThis) has been changed to TitanUtils_GetButton(id)

id (string): id of your Titan object. It is required and must be valid for the function to return anything useful.

returnThis (boolean): Removed. Secondary arguments will now be ignored.

Returns 2 values, one being the frame of your Titan object (if it exists) plus the id. If a proper id isn't specified it returns nil.

9. TitanUtils_GetButtonID(name) has changed in regards to the values returned.

name (string): Must be in form of "TitanPanel"..id.."Button" for the function to return anything useful.

Returns id of the button passed in the argument or nil if not found. It will no longer return "something" if you call it without an argument.

10. TitanUtils_GetParentButtonID(name) has changed in regards to the values returned.

name (string): Assumed to be a string containing the name of the child button frame.

Returns id of the parent button to the child button passed in the argument or nil if not found. It will no longer return "something" if you call it without an argument.

11. TitanUtils_GetControlFrame(id) has changed in regards to the argument passed. You must now provide a valid id for the function to return a control frame, else it will return nil.

12. TitanUtils_GetPlugin(id) has changed in regards to the argument passed. You must now provide a valid id for the function to return the proper registry table of the plugin corresponding to the said id, else it will return nil.

13. TitanPanelPluginHandle_OnUpdate(id, updateType) has been changed to TitanPanelPluginHandle_OnUpdate(table) where the 'table' argument is now a table, as shown below.

TitanPanelPluginHandle_OnUpdate(table)

Arguments:

table

Should be in the form of {id, updateType} where :

id -- id string of the plugin

updateType -- TITAN_PANEL_UPDATE_BUTTON for text updates on the button or

-- TITAN_PANEL_UPDATE_TOOLTIP for tooltip updates or

-- TITAN_PANEL_UPDATE_ALL for both text and tooltip updates

Example:

local MY_ADDON_ID = "MyAddon"
TitanPanelPluginHandle_OnUpdate({MY_ADDON_ID, TITAN_PANEL_UPDATE_BUTTON})

will update the text on the button of the plugin with id = MY_ADDON_ID.

Notes:

The old implementation of the function will still work and not break (this was done for compatibility purposes), however it is highly recommended that you call the function using the new table, as previously explained.

14. TitanPanelRightClickMenu_AddCommand(text, value, funcname, level) has been modified so now the callback function passes the value as its first argument.

Example:

TitanPanelRightClickMenu_AddCommand("Menu Command to do stuff", Myvalue, MyFunction)

function MyFunction(value, ...)
  -- value will be equal to Myvalue
end

15. TitanPanelRightClickMenu_ToggleVar() is now TitanPanelRightClickMenu_ToggleVar(value) where value is a table in the form of : {id, var, toggleTable}.

id : Plug-in id.

var: Plug-in id's savedvar.

toggleTable: If toggleTable is present, it is a list of options, at least one of which must always be set.

16. TitanPanelRightClickMenu_ToggleColoredText() is now TitanPanelRightClickMenu_ToggleColoredText(value) where value is the id of your Titan plug-in.

Timer Methods

The old timer methods: :HasTimer, :AddRepeatingTimer and :RemoveTimer have been removed. While timed updates in Titan are still handled by implementing/setting an OnShow and OnHide script handler in your plugin, pointing to specific functions for simplicity (as explained in detail here: http://www.wowwiki.com/Titan_Panel#Recent_Changes_For_Developers), the code inside these functions will need to be modified.

Example:

Let's assume that we are dealing with a plugin with an id of: "MyAddon", eg:

local MY_ADDON_ID = "MyAddon"

At the beginning of our code, we need to define these locals :

local AceTimer = LibStub("AceTimer-3.0") -- local reference to LibStub("AceTimer-3.0")

local MyAddonTimer = nil -- local variable to hold our timer "handle"

In our OnShow/OnHide functions (we assume that the functions are named MyAddon_OnShow and MyAddon_OnHide):

function MyAddon_OnShow()
	if not MyAddonTimer then
		MyAddonTimer = AceTimer.ScheduleRepeatingTimer("TitanPanel"..MY_ADDON_ID, TitanPanelPluginHandle_OnUpdate, 1, {MY_ADDON_ID, TITAN_PANEL_UPDATE_BUTTON })
	end

-- Fires a timer with a 'self' string named: "TitanPanel"..MY_ADDON_ID
-- that will call the TitanPanelPluginHandle_OnUpdate function, every 1 second
-- using a table argument of { MY_ADDON_ID, TITAN_PANEL_UPDATE_BUTTON }
-- which in turn will update the button text

end

function MyAddon_OnHide()
	AceTimer.CancelTimer("TitanPanel"..MY_ADDON_ID, MyAddonTimer, true)
	MyAddonTimer = nil

-- Cancels the timer (silently) registered by the 'self' string named: "TitanPanel"..MY_ADDON_ID
-- and has a handle of: MyAddonTimer

end

Method usage:

.ScheduleRepeatingTimer(self, callback, delay, arg)

Returns a handle to the timer, to be used for canceling it.

callback (function or string)

direct function reference or method name in our object for the callback. Should normally be: TitanPanelPluginHandle_OnUpdate

delay (number)

delay for the timer (must be integer)

arg (variant)

any argument to be passed to the callback function. Should normally be {id, updateType}, assuming we are using Titan's update function.

.CancelTimer(self, handle, silent)

Cancels a timer with the given handle, registered by the same 'self' as given in ScheduleTimer or ScheduleRepeatingTimer. Returns true if successful.

handle (string)

handle returned from ScheduleTimer or ScheduleRepeatingTimer

silent (boolean)

If set to true, do not error if the timer does not exist or is already canceled. Defaults to false if omitted.

Notes:

A far better timer implementation would be to simply embed AceTimer into your plugin (call LibStub("AceTimer-3.0"):Embed(YourObject) at the beginning) and use it without potentially having to specify a custom 'self'. This goes outside the scope of this wiki entry, though. Last but not least, you don't have to distribute and/or reference AceTimer in your .toc, assuming that you are using Titan as a required dependency for your plugin.

And once again, our disclaimer: Timers are a powerful tool but as such, they can also be abused. For your sanity (and ours) it is recommended that you don't use them, unless you absolutely need them (and thoroughly test them). If you can base your updates on simple event triggering, you should be able to use TitanPanelButton_UpdateButton(id), TitanPanelButton_UpdateTooltip() or even TitanPanelPluginHandle_OnUpdate(table) to handle your updates without any real issues and most importantly without necessarily affecting performance. On the other hand, if you absolutely must use a timed update, make sure that you are only updating what needs to be updated and don't just use TITAN_PANEL_UPDATE_ALL if it's not required.