Custom Triggers

Custom triggers are an advanced feature that is only intended for users who know Lua. As such, the following page will assume you are familiar with Lua and related programming concepts.

(For more information on Lua, see Programming in Lua.)

---

Custom triggers are a way for you to trigger a WeakAuras display using any arbitrary Lua code. There are two types of custom triggers: Status and Event.

Status

Status type custom triggers are based on the assumption that they will be used to check a value that can always be determined. Status type custom triggers can be set to be checked on certain events, or simply every frame. Either way, the main ways they differ from Event type custom triggers is that they will be forced to update at certain times even when their specified events do not occur - e.g., when you close the WeakAuras configuration window.

Event

Event type custom triggers are based on the assumption that they will be used with events that pass relevant information. As such, the main way in which they differ from Status type custom triggers is that they will not be forced to update at time when Status type custom triggers would. Event type custom triggers can be set to hide on a timer, or they can have a custom untrigger.

To use events that you specify in the Event(s) field you need to set up your functions in a specific way. Say for example you wanted to check on events ENCOUNTER_START and ENCOUNTER_END and you want to use these events in your trigger function:

--Event(s): ENCOUNTER_START, ENCOUNTER_END
--Trigger
function(event, arg1, arg2, ...)
    if event == "ENCOUNTER_START" then
        --Use the arguments for this event
        return true
    end
end

--Untrigger
function(event, arg1, arg2, ...)
    if event == "ENCOUNTER_END" then
        --Use the arguments for this event, or dont, just untrigger.
        return true
    end
end

The actual event is always passed into the function first, then all of its arguments. Remember to check for the event first before assigning variable names to the argument if you are using more than one event. You can use an ellipsis (...) to store arguments in an event and use select() to pick out the ones you want and give differing variable names to differing position of arguments. You can learn more about ellipsis in lua via their documentation.

Trigger State Updater

Trigger State Updater directly modify the structures that contain information about the trigger state. The main benefit to the other two trigger methods is, that it allows for creating multiple displays from your custom trigger function.

---

Trigger Options

Check On...

Only available for Status type custom triggers. When set to Every Frame, the trigger will not require any events, but will instead be checked using an OnUpdate script.

Event(s)

A list of events which will cause the custom trigger function to be called (as well as the untrigger function, if the trigger function returns false). Multiple events can be separated by whitespace and/or commas.

Custom Trigger

The custom trigger field should be an anonymous function which returns true if the trigger should become active. The function will be passed all the arguments that are specified for the event that triggered, starting with the name of the event. If the function returns false, nil, or nothing, the trigger will not automatically become inactive - instead, failure of the trigger function will cause the untrigger function to be called. For trigger state updater triggers, please refer to the section at the bottom.

Custom Untrigger

The custom untrigger field, just like the custom trigger field, should be an anonymous function, and will be passed the same arguments as the trigger function. However, it should return true if the trigger should become inactive - i.e., the trigger's display should be hidden. If the untrigger function returns false, nil, or nothing, no change will be made to the display. It will remain visible if it is already visible, or it will remain invisible if it is already invisible. Most of the time, for status type custom triggers, the untrigger function can always return true. However, it can be useful to define a trigger and untrigger in such a way that there is a grey area. See Triggers and Untriggers for more info.

Hide

Only available for Event type custom triggers. If set to Timed, the Custom Untrigger field will be hidden, and the custom trigger will simply last for a pre-defined amount of time. If set to Custom, a custom untrigger function can be defined.

Dynamic Information

The status and event custom triggers can return dynamic information by implementing the duration, name, icon, stacks, and texture functions. The return values of the name, icon,texture and stacks function is simply the value of that dynamic information. The duration function for timed progress should be two values: duration, expirationTime and for static progress, three values: value, total, true.

---

Trigger State Updater

Note: Trigger State Updater will not work until it is inside a dynamic group. For the trigger state updater functions, the first argument sent is the states table, which the trigger function should update.

Each entry in the states table will be shown as a separate display. For each individual state, the following properties can be set:

• changed: Always set this to true for states that were changed, otherwise those changes won't become visible
• show: Controls whether the display is visible. Note, that states that have show set to false are automatically removed.
• name: The name, returned by %n
• icon: The icon
• stacks: The stack count, returned by %s
• index: Sets the order the output will display in a dynamic group (if sorting isn't selected on the group)

Progress information can be set by either setting:

• progressType to static and
• value and total

Or by setting:

• progressType to timed and
• expirationTime and duration
• Note, if you change expirationTime, you need to also set resort to true.
• Also if autoHide is set to true, the display is automatically hidden after expirationTime.

A full list of state table values

state.show = boolean
state.changed = boolean
state.name = string
state.stacks = number
state.index = string or number -- but don't mix types!
state.resort = boolean
state.progressType = "static" or "timed" -- string
state.value = number -- used if "static"
state.total = number -- used if "static"
state.duration = nunber -- used if "timed"
state.expirationTime = number -- used if "timed", value of GetTime()
state.autohide = boolean -- used if "timed", hides when expirationTime passed
state.icon = number or string -- icon ID or path, used in icons and progress bars
state.texture = number or string -- icon ID or path, used in textures
state.customField = value -- custom fields can be added to state as required

An example:

function(allstates, event)
    for _, v in pairs(allstates) do
        v.show = false;
        v.changed = true;
    end

    for i = 1, GetCurrencyListSize() do
        local name, isHeader, isExpanded, isUnused, isWatched, count, icon, maximum, hasWeeklyLimit, currentWeeklyAmount, unknown = GetCurrencyListInfo(i)
        if (not isHeader and not isUnused) then
            allstates[i] = allstates[i] or {};
            local state = allstates[i];
            state.show = true;
            state.changed = true;
            state.name = name;
            state.progressType = "static";
            state.value = count;
            if (maximum == 0) then
                state.total = math.pow(10, floor(log(count) / log(10)) +1)
            else
                state.total = maximum;
            end
            state.icon = icon;
        end
    end
    return true
end

Each state is also passed into the Animations and Display functions for you in the aura_env.state variable. Animations example:

function()
    if not aura_env.state then return 0, 0, 0, 1 end  -- error checking.
    if aura_env.state.name == "Green" then
        return 0, 1, 0, 1 -- Reminder: return R, G, B, Alpha (using numbers between 0 and 1)
    elseif aura_env.state.name == "Red" then
        return 1, 0, 0, 1
    elseif aura_env.state.name == "Blue" then
        return 0, 0, 1, 1
    else
        return 1, 1, 1, 1
    end 
end

Each variable that you save in the state can be accessed like this and will run these scripts for each state.