Custom Dynamic Group

Dynamic Group Custom Functions

WeakAuras 2.12 introduces the ability to write custom functions for a dynamic group's Grow and Sort options, which will allow you to define what your group should look like very precisely.

aura_env

In a dynamic group, aura_env has a slightly different meaning. There is no state information, so aura_env.state is always nil. Additionally, there is no such thing as a cloned group, so aura_env.cloneId is always nil. There is a new value which is provided to you, which can be accessed at aura_env.child_envs. This is a table which contains all of the aura_env tables of the group's children, in dataIndex order.

RegionData

Both custom sort and custom grow will give you some special tables, which are called regionData (for the simple reason that they contain the region and the data). RegionData is structured as follows:

regionData = {
    id = "string", -- name of the child,
    cloneId = value, -- the cloneId. Usually string, but can be any value, including nil. If this child does not clone, then this value will be nil or empty string "".
    dataIndex = 1, -- number which indicates the order the child appears in the options Pane, starting at 1.
    data = {...}, -- table containing data with which to construct the child's aura
    region = {...}, -- the region object which was built from the data for this child.
    xOffset = 0, -- x offset from previous layout function execution. This may be nil on the first layout.
    yOffset = 0, -- y offset from previous layout function execution. This may be nil on the first layout.
    show = true, -- Boolean indicating if the region was allowed to be shown (note that this is not the same as a region being active)
}

Note: regionData objects are intended to be read only, but for performance reasons this is not enforced. Writing to the regionData object will result in undefined behavior.

Custom Sort

Custom Sort is the more straightforward of the two new functions. You are given two regionData objects, and are expected to return true if the second must be sorted before the first:

function(a, b)
    -- this is roughly equivalent to the "None" sort option
    return a.dataIndex <= b.dataIndex
end

WeakAuras uses a perturbative insertion sort to maintain order. This means that WeakAuras assumes that most of the list is in sorted order already, and that only small perturbations will need to be made when a child wants to be shown, in order to maintain sorted order. If your custom sorting requires that a child must be re-ordered without being shown (e.g. the progress info changes on an already visible child), then you must set the changed attribute on the relevant state to true in order for it to be resorted. If you use the builtin triggers (such as buff or cooldown trackers), then these will be automatically flagged to be resorted when appropriate.

Custom Grow

Custom Grow is slightly more involved, but still straightforward. You are given 2 parameters. The first is an empty table which is expected to be filled with positioning data, and the second's is a table containing the regionData of all active children, in sorted order (note that positioning always occurs after sorting). You are not expected to return anything, and anything you do return from this function are ignored.

function(newPositions, activeRegions)
    -- this function will produce a parabola shape
    local mid = #activeRegions / 2
    for i = 1, #activeRegions do
        newPositions[i] = {
            40 * (i - mid),
            0.5 * (i - mid)^2
        }
    end
end

If a child is not given any position data, then it is hidden, and moved to position 0, 0. You may hide a child at a particular spot other than 0, 0 (useful if you use the animated expand/collapse option) by setting the third value in the position data to false.