[ TIMEX ]

Startup Functions
Adding a Timex Entry
Checking a Timex Entry
Deleting a Timex Entry
Changing an Entry's Duration

Getting a Timex Bar
Formatting a Timex Bar
Starting a Timex Bar
An Example
Checking a Timex Bar
Stopping a Timex Bar

iii. Developers - Miscellaneous

Syntactic Mayhem

iv. Players

Timex Compatibility
Chat Commands

i. Developers - Timex Core

Startup Functions

Timex:AddStartupFunc

void Timex:AddStartupFunc(function f, object a1, object a2, object a3, ... object a20)

Adds a startup function to Timex. A startup function runs immediately after Timex has initialized. This is soon after the player logs in or has reloaded their UI, soon after the VARIABLES_LOADED event. It is similar to the Enable method of Ace addons, and is mostly there for use with non-Ace addons.

Parameters:: f - the startup function.; a1..a20 - the arguments (optional).

Example:

Timex:AddStartupFunc(self.AddonFunc, ace.print, ace, "I have entered the game!")

This will print "I have entered the game!" to the ChatFrame on login.

Adding a Timex Entry

Timex:AddSchedule

void Timex:AddSchedule(object id, number t, boolean r, number c, function/string f, object a1, object a2, object a3, ... object a20)

Adds a schedule entry to Timex. This is the fundamental method of Timex. This is used to schedule a function to run, or an event to be triggered, at some point in the future.

Argument subsitution: Timex supports argument substition. If you use one of the following values in the argument list, Timex will substitute the appropriate value when the function/event is called.

Timex.ARG_ID - the id of this schedule.

Timex.ARG_COUNT - the number of times this schedule has run.

Timex.ARG_ELAPSED - the elapsed time since this schedule last fired.

Parameters:: id - the id, for persistent entries (optional).; t - the time delay.; r - whether the schedule should be repeated continuously (optional, not to be used with c).; c - the number of times the schedule should be repeated before removal (optional).; f - the function (pointer) or event (string) to trigger.; a1..a20 - the arguments (optional).

Example #1:

Timex:AddSchedule("MyAddOn", 5, nil, nil, ace.print, ace, "Hello World!")

This is a standard Timex entry - after two seconds, "Hello World!" will be printed to the ChatFrame.

Example #2:

Timex:AddSchedule("MyAddOn", 2, TRUE, nil, ace.print, ace, "Yadda!")

In this example repeat is being used - this will print "Yadda!" to the ChatFrame every two seconds until the entry is manually deleted.

Example #3:

Timex:AddSchedule("MyAddOn", 2, nil, 5, ace.print, ace, "Blah.")

In this example we see count being used - this will print "Blah." to the ChatFrame every two seconds until it has done this five times, then it will stop.

Example #4:

Timex:AddSchedule(timexBar, 0.1, nil, time*10, timexHandler, self, timexBar, Timex.ARG_ELAPSED)

In this example we see count being used - this will print "Blah." to the ChatFrame every two seconds until it has done this five times, then it will stop.

Example #5:

Timex:AddSchedule("MyAddOn", 2, TRUE, nil, "MY_TIMEX_UPDATE", "% has seen %s counts", Timex.ARG_COUNT)

function AddOnName:Enable()
    self:RegisterEvent("MY_TIMEX_UPDATE")
end

function AddOnName:MY_TIMEX_UPDATE(msg, c)
    -- c is the current count.
    ace:print(format(msg, c)
    if c == 2 then
        ace:print("Second.")
    elseif c == 1 then
        ace:print("First.")
    end
end

The fifth example gets more complex. If you enter a string as the function, Timex will fire that event when the schedule is due (the "doTimexEvent" string will actually fire the "TIMEX_UPDATE" event for backwards-compatibility with older versions of Timex). This may be useful if you wish to use an event-driven timing system, rather than one that relies on function calls. Note that this only works for Ace-developed AddOns, due to the way the event is distributed.

Checking a Timex Entry

Timex:ScheduleCheck

boolean/number Timex:ScheduleCheck(object id, boolean r)

This method is used to check the current status of any Timex entries. It can also be used to check the time that has elapsed on a particular timer. This can be used to check how much time has passed from point A to point B. You can add a Timex entry without a function for this very purpose.

Parameters:: id - the id of the entry.; r - whether to return the time elapsed. (optional).
Returns:: If r is FALSE or nil, TRUE if the entry exists, nil otherwise. If r is not FALSE or nil, the time elapsed on the entry, nil otherwise.

Example #1:

local a = Timex:ScheduleCheck("MyAddOn")
if a then
    ace:print("Exists.")
end

This example will return true if the Timex entry with id "MyAddOn" is present, and nil otherwise.

Example #2:

local a = Timex:ScheduleCheck("MyAddOn", TRUE)
if a then
    ace:print(a)
end

This example will return the time remaining for the Timex entry with id "MyAddOn" is present, and nil otherwise.

Deleting a Timex Entry

Timex:DeleteSchedule

void Timex:DeleteSchedule(object id)

This method is used to remove a Timex entry.

Parameters:: id - the id of the entry.

Example:

Timex:DeleteSchedule("MyAddOn")

This will delete the "MyAddOn" entry from Timex's database.

Changing an Entry's Duration

This method is used to change a timer's duration while it is running. For example, it can be used to change the 'tick rate' of a repeating timer.

Timex:ChangeDuration

void Timex:ChangeDuration(object id number t)

This method is used to remove a Timex entry.

Parameters:: id - the id of the entry.; t - the new duration of the entry.

Example:

Timex:DeleteSchedule("MyAddOn", 15)

This will change the duration of the "MyAddOn" timer to 15 seconds.

ii. Developers - Timex Bars

This module of timex exists for providing timer bars to both players for their macros and to developers for AddOns that need to display a timer. The bar has two text elements, these are timer and text. The colour of the bar and text are both configurable along with the size and shape of the bar. Further, there's a button to the left of the bar which can display a spell/item texture for easy viewing of whatever's ticking down. Note that the interface for TimexBar has changed in R23.

Here's a visual example of a standard Timex Bar, as shown by the AceTimer AddOn:

These bars are currently at their default length and size. Once a bar has finished ticking down, it can fire off a function, so if you want to rearrange your GUI based on when bars show and hide, you can now do so. For example, you could create a bunch of bars which anchor off of each other to the right and when one disappears, the next bar over crops left to take its space.

The interface for creating and starting a bar has changed somewhat from pre-R23 versions of Timex. Essentially, you get Timex to assign a bar from its free pool to your id, then you format the bar and start it. Note that a bar is only truly reserved (ie removed from the free pool) once it has started. A bar returns to the free pool when it finishes running, or if it is stopped.

Getting a Timex Bar

TimexBar:Get

void TimexBar:Get(object id)

This will assign a bar to the id you provide. Note that you cannot 'Get' a bar, and then format/start it at some later stage. It is quite likely that the bar will be assigned to another id the next time another 'Get' call is made, so you will have to 'Get' a bar again. Generally you should get and format a bar at the time that you intend to start it.

Parameters:: id - the id of the bar.

TimexBar:GetName

string TimexBar:GetName(object id)

Gets the name of the TimexBar assigned to the given id. Returns nil if no TimexBar is assigned to the id.

Parameters:: id - the id of the bar.
Returns:: The name of the TimexBar assigned to id, or nil.

Formatting a Timex Bar

There are a number of formatting methods to change the appearance of a Timex bar...generally these are similar to the formatting options available on the standard UI Frame elements. All are optional (ie you don't have to set any of them if you don't wish to).

TimexBar:SetColor

void TimexBar:SetColor(object id number red, number green, number blue, number alpha)

Sets the color of the bar.

Parameters:: id - the id of the bar.; red - red channel.; green - green channel.; blue - blue channel.; alpha - alpha channel (optional).

TimexBar:SetTextColor

void TimexBar:SetTextColor(object id number red, number green, number blue, number alpha)

Sets the color of the text in the bar.

Parameters:: id - the id of the bar.; red - red channel.; green - green channel.; blue - blue channel.; alpha - alpha channel (optional).

TimexBar:SetPoint

void TimexBar:SetPoint(object id string point, string relativeFrame, string relativePoint, number xOffset, number xOffset)

Sets the position of the bar.

Parameters:: id - the id of the bar.; point - the anchor point of the bar.; relativeFrame - the anchor frame (that the bar's position will be relative to).; relativePoint - the anchor point of the anchor frame.; xOffset - X offset.; yOffset - Y offset.

TimexBar:SetScale

void TimexBar:SetScale(object id number scale)

Sets the scale of the bar. This is best suited to changing the size of the entire bar (the bar, the text, the icon, everything).

Parameters:: id - the id of the bar.; scale - the scale of the bar.

TimexBar:SetWidth

void TimexBar:SetWidth(object id number width)

Sets the width of the bar. This is best suited to changing the dimensions of the bar relative to the other elements (eg the icon or the text).

Parameters:: id - the id of the bar.; width - the width of the bar.

TimexBar:SetHeight

void TimexBar:SetHeight(object id number height)

Sets the height of the bar. This is best suited to changing the dimensions of the bar relative to the other elements (eg the icon or the text).

Parameters:: id - the id of the bar.; height - the height of the bar.

TimexBar:SetTimeWidth

void TimexBar:SetTimeWidth(object id number timeWidth)

Sets the width of the 'time' portion of the text display of the bar. This is best suited to changing the size of the timer relative to the other elements (eg the icon, the bar, or the text).

Parameters:: id - the id of the bar.; timeWidth - the width of the timer.

TimexBar:SetText

void TimexBar:SetText(object id string text)

Sets the text that the bar will display (ie the label).

Parameters:: id - the id of the bar.; text - the text of the bar.

TimexBar:SetTexture

void TimexBar:SetTexture(object id string texture)

Sets the texture (icon) that will be displayed next to the bar.

Parameters:: id - the id of the bar.; texture - path to the texture to display with the bar.

TimexBar:SetFunction

void TimexBar:SetFunction(object id, function f, object a1, object a2, object a3, ... object a20)

Sets a function that will be called when the bar finishes. This will not be called if the bar is stopped manually (ie through the TimexBar:Stop method.

Argument subsitution: TimexBars also support argument substition. If you use one of the following values in the argument list, Timex will substitute the appropriate value when the function/event is called.

Timex.ARG_ID - the id of this TimexBar.

Timex.ARG_ELAPSED - the elapsed time since this TimexBar was last updated.

Timex.ARG_REMAINING - the time remaining on this TimexBar.

Parameters:: id - the id of the bar.; f - the function to be run.; a1..a20 - the arguments (optional).

TimexBar:SetUpdateFunction

void TimexBar:SetUpdateFunction(object id, function f, object a1, object a2, object a3, ... object a20)

Sets a function that will be called every time the bar is updated. This method also supports argument substitution.

Parameters:: id - the id of the bar.; f - the function to be run.; a1..a20 - the arguments (optional).

Starting a Timex Bar

After assigning and formatting your bar, it is time to start it. This removes the bar from the free pool and displays it to the user. It will start running immediately.

TimexBar:Start

void TimexBar:Start(object id, number time, number res)

Starts a TimexBar. This removes the bar from the free pool and displays it. It is possible to alter the resolution of the bar's updates...by default the bar will update every 0.1 seconds, but for a long-running bar, u might want to update it only once every sec, in which case you would set the res parameter to 1.

Parameters:: id - the id of the bar.; time - The duration of the bar.; res - The resolution of the bar display in seconds (optional, default 0.1).
Returns:: The name of the bar assigned (eg TimexBar3).

An Example

The following code shows how to format and start a TimexBar.

local toggle;
local function toggleAppearance(id, remaining)
    if toggle then
        TimexBar:SetText(id, "My Bar #2 - " .. remaining);
        TimexBar:SetColor(id, 1.0, 1.0, 1.0);
        TimexBar:SetTextColor(id, 0, 0, 0);
    else
        TimexBar:SetText("MyBar", "My Bar #1 - " .. remaining)
        TimexBar:SetColor("MyBar", 1.0, 0.2, 0.2)
        TimexBar:SetTextColor("MyBar", 1.0, 1.0, 0.2)
    end
    toggle = not toggle;
end

TimexBar:Get("MyBar")
TimexBar:SetText("MyBar", "My Bar #1")
TimexBar:SetTexture("MyBar", "Interface\\Icons\\Spell_Nature_ResistNature")
TimexBar:SetColor("MyBar", 1.0, 0.2, 0.2)
TimexBar:SetTextColor("MyBar", 1.0, 1.0, 0.2)

TimexBar:SetPoint("MyBar", "BOTTOMLEFT", "UIParent", "CENTER", 40, 40)
TimexBar:SetWidth("MyBar", "200")
TimexBar:SetHeight("MyBar", "20")
TimexBar:SetTimeWidth("MyBar", "50")
TimexBar:SetScale("MyBar", "1.6")

TimexBar:SetFunction("MyBar", ace.cmd.msg, ace.cmd, "'%s' bar hidden.", TimexBar.ARG_ID)

toggle = true;
TimexBar:SetUpdateFunction("MyBar", toggleAppearance, TimexBar.ARG_ID, TimexBar.ARG_REMAINING);

local name = TimexBar:Start("MyBar", 10, 0.5)
ace:print(name.." is active.")

First we assign a bar to the id "MyBar" using Timex:Get. The next two lines set the text and icon of the bar. After this, we set the color of the bar, and the color of the text displayed.

Next we set the bar so that it's bottom-left corner is 40 pixels to the left and 40 pixels above the center of the screen. We set the width and height of the bar, and set the time display so that it takes up a quarter of the bar's width. Then we set the scale to 1.6 - the default scale is 0.8, so this bar will appear twice the size as the default.

We then set a function so that the bar will print, "'MyBar' bar hidden." to the chat log when it completes. We also set a function to toggle the appearance of the bar every time it is updated.

Lastly, we start the bar so that it updates every half second for 10 seconds, and print the name of the bar to the chat log with a message saying that it has started

Checking a Timex Bar

TimexBar:Check

boolean/number TimexBar:Check(object id, boolean r)

This method is used to check whether a TimexBar exists for the given id, and can optionally return the name of the TimexBar.

Parameters:: id - the id of the bar.; r - whether to return the name of the bar (optional).
Returns:: If r is FALSE or nil, TRUE if the bar exists, nil otherwise. If r is not FALSE or nil, the name of the bar, nil otherwise.

Example:

local a = TimexBar:Bar("MyBar")
if a then
    ace:print("Exists.")
end

This example will print, "Exists." to the chat log if a TimexBar exists for the id "MyBar".

Stopping a Timex Bar

TimexBar:Stop

boolean/number TimexBar:Stop(object id)

This method is used to stop a TimexBar.

Parameters:: id - the id of the bar.

Example:

local a = TimexBar:Bar("MyBar")

This example will stop TimexBar for the id "MyBar".

iii. Developers - Miscellaneous

Syntactic Mayhem

So you now know the ins and outs of developing using Timex and its Bars module, is there anything to add? Not really, though I would like to explain a few things about syntax first and how syntax differs through code formats.

Throughout your days coding for the World of Warcraft community you're going to see many kinds of coding styles, this is going to change how you use Timex as far as the syntax of calling functions is concerned. To avoid confusion later I've decided that it would be best to explain the differences between these and the best way to handle them. Note: I'll be using AddSchedule to demonstrate how these work but these examples will work for any part of Timex that accepts functions.

Scripting

This is a basic function format that's most frequently used.

Format:

function AddOn_Function_Blah(arg1, arg2)

Result:

Timex:AddSchedule(..., AddOn_Function_Blah, arg1, arg2)

Tabled

This is a slightly more advanced format used infrequently.

Format:

function Table.Function_Name(arg1, arg2)

Result:

Timex:AddSchedule(..., Table.Function_Name, arg1, arg2)

Object-Oriented

This is the most advanced form Lua has to offer, all the cool kids are using it. It has a few variations on the basic form.

Format #1:

function AddonName:DoSomething(arg1, arg2)

Format #2:

function AddonName.DoSomething(self, arg1, arg2)

Format #3:

AddOnName {
    DoSomething = function(self, arg1, arg2),
}

Result:

Timex:AddSchedule(..., self.DoSomething, self, arg1, arg2)

Note: You only need to pass self if the function you're passing too actually references self. Lua uses pseudo-OO so it's up to you, you can mix and match function types.

iv. Players

Timex Compatibility

The Chronos placeholder addon is provided in case people wish to use Timex in place of Chronos - the aim is to be fully compatible with Chronos where possible. Drop us a line if you find that in practice Timex is not working properly with Chronos-based addons.

Chat Commands

Timex has a chat-command system for options, it uses a one-line system for ease of typing and to allow for bigger macros (so you don't have to retype our chat-operator on every line). Further, the chat-command system isn't watered down in any way and provides as much of the power of Timex as we were able to cram in, so it is slightly complex but I shall endeavour to explain how each of the commands works.

The Do Command

Here's the basic layout of the system:

/tmx do n="[timer name]" t=[time] r=[repeat] c=[count] f=[function] a=[args]

The first thing to cover is: what's up with those quotation marks? The chat-command system separates by spaces, so if something you want to use (such as the name or an arg) has a space in it, you'll have to wrap it in quotation marks to ensure that the space inside isn't considered as a separator. Basically, if you're not actively typing spaces between the commands and you have a space that's not command related, wrap quotation marks around the entire thing, as shown by 'timer name'.

Parameters:

timer name - this is the name of your timer, you don't have to supply this at all but if you want to be able to stop your timer at any point, it's a good idea. The format of name is either n=mytimer or n="my timer".

time - this is the amount of time that will pass before the Timex does its stuff. If you set this to eight seconds then Timex will delay for 8 seconds before using the function that you gave it. The format of time is t=8.

repeat - repeat will make your timer continuous, so it'll cycle on a basis of the time you gave it. If you provide it with 8 seconds then every 8 seconds it will fire the function you gave it until it's stopped. To make repeat happen, supply r=TRUE as a command.

function - this is the function you wish to call. It is supplied as a pointer, so if your function is DoThis(a, b), you'll have to supply DoThis here. The format of function is f=DoThis.

args - these are the arguments you wish to supply along with your function, so if your function is DoThis(a, b), you'll have to supply 'a, b' here. The format of args is either a=arg if it's one arg or a="arg1, arg2, arg3 ... etcetera" if it's more.

Here's an example of the above in action:

/tmx do n="my print" t=5 f=SendChatMessage a="'Hello World!', SAY"

This would make you say 'Hello World!' after five seconds have passed.

The Stop Command

Now that adding timers is out of the way, how would you go about stopping them? That's easy too. There's a stop command that you can supply a timer name too, it will look for that timer name and stop it. So if you've decided you don't want a timer to run or you have something on a repeat or a count and you wish to stop it then you can easily do so with a quickly accessible chat-command.

/tmx stop my print

This would search for the 'my print' timer and stop it. Use both of these commands to your advantage in macros and really take command of your playing style.

Table of Contents

i. Developers - Timex Core

Timex:AddStartupFunc

Timex:AddSchedule

Timex:ScheduleCheck

Timex:DeleteSchedule

Timex:ChangeDuration

TimexBar:Get

TimexBar:GetName

TimexBar:SetColor

TimexBar:SetTextColor

TimexBar:SetPoint

TimexBar:SetScale

TimexBar:SetWidth

TimexBar:SetHeight

TimexBar:SetTimeWidth

TimexBar:SetText

TimexBar:SetTexture

TimexBar:SetFunction

TimexBar:SetUpdateFunction

TimexBar:Start

TimexBar:Check

TimexBar:Stop

Scripting

Tabled

Object-Oriented

Fin