An alternative to using Blizzard's SecureStateDriver for non-secure code. As this code is not secure, modification during combat is not an issue.
State determination is done through Blizzard's own SecureCmdOptionParse function, allowing for full use of macro-style parameters. As new parameters are encountered they are parsed, and the result cached, to determine the best way to keep their state accurate (OnEvent/OnUpdate).
CPU use is kept minimal with a couple of features:
- The parameter parse can detect if a portion of the parameters will never be reached, or if the state can never change, and adjust accordingly.
- Event usage is tracked to ensure that any unused event is unregistered to prevent unnecessary processing.
Example - Hide/Show a frame in/out of combat:
Code:
local frame = CreateFrame('Frame', nil, UIParent)
local function handler(object, method)
object[method](object)
end
local stateDriver = LibStub('LibStateDriver-1.1').New()
stateDriver:SetCallback(handler)
stateDriver:SetObject(frame)
stateDriver:SetParameters("[combat] Hide; Show")
stateDriver:SetEnabled(true)
Example - Hide a frame in a raid, dim it in combat or in a party:
Code:
local frame = CreateFrame('Frame', nil, UIParent)
local function handler(object, alpha)
alpha = tonumber(alpha) or 1
if alpha == 0 then
object:Hide()
else
object:SetAlpha(alpha)
object:Show()
end
end
local stateDriver = LibStub('LibStateDriver-1.1').New(true)
stateDriver:SetCallback(handler)
stateDriver:SetObject(frame)
stateDriver:SetParameters("[group:raid] 0; [combat][group:party] 0.5; 1")
Example - Hide/Show a frame in/out of combat (condensed):
Code:
local stateDriver = LibStub('LibStateDriver-1.1').New(true,
"SetCallback", function(object, method) object[method](object) end,
"SetObject", CreateFrame('Frame', nil, UIParent),
"SetParameters", "[combat] Hide; Show"
)
API
stateDriver = lib.New(enable [, ...])
Create a new state driver object.
Arguments:
enable - (boolean) If true then stateDriver will be enabled upon creation.
... - (any) Pairs of either method/argument to be run or key/value to be set on stateDriver.
Returns:
stateDriver - (table) The state driver object to be used by the calling code (see State Drivers below).
State Drivers
The object returned by lib.New() is an empty table with a metatable that provides several methods. The table itself is not utilized by the library and is completely at the disposal of the calling code to use as needed.
The stateDriver may be treated like a function with stateDriver(...) being the same as stateDriver:Update(...). A stateDriver has the following methods:
callback = stateDriver:GetCallback()
Get the callback function currently assigned to stateDriver.
Returns:
callback - (function or nil) The assigned callback.
object = stateDriver:GetObject()
Get the object (first argument) that is to be passed during stateDriver's callback.
Returns:
object - (any) The assigned object.
parameters = stateDriver:GetParameters()
Get the parameters currently assigned to stateDriver.
Returns:
parameters - (string) The assigned parameters.
state = stateDriver:GetState()
Get the state of stateDriver as determined by the last evaluation of it's assigned parameters.
Returns:
state - (string or nil) The state currently associated with stateDriver.
active = stateDriver:IsActive()
Gets the active status of stateDriver. A stateDriver is active if it is enabled, has a callback function assigned, and has parameters assigned that can potentially change state.
Returns:
active - (boolean) Whether stateDriver is active.
enabled = stateDriver:IsEnabled()
Get the enabled status of the stateDriver.
Returns:
enabled - (boolean) The current status of stateDriver, true if enabled.
stateDriver:Recycle()
Removes the metatable from stateDriver as well as removing all internal references so that it may be garbage collected.
stateDriver:SetCallback(callback)
Set the function to be called when stateDriver's state changes. The callback function is passed: object, state.
Arguments:
callback - (function or nil) The function to be called when a state change occurs.
stateDriver:SetEnabled(mode)
Set the enabled status of stateDriver. Passing
false (or
nil) will disable stateDriver, otherwise it will be enabled. A stateDriver must be enabled to respond to state changes and trigger callbacks. Upon creation stateDriver is automatically disabled unless the enable field was set.
Arguments:
mode - (boolean) The enabled status to set.
stateDriver:SetObject(object)
Set the object (first argument) that is to be passed to stateDriver's callback function. Upon creation of stateDriver it's object is set to itself.
Arguments:
object - (any) The object to be passed.
stateDriver:SetParameters(parameters [, force])
Set the macro-style parameters that are to be evaluated for stateDriver's state changes. Changing parameters immediately causes the state to be re-evaluated and if it changed, or force is set, a callback is triggered (unless stateDriver is disabled).
Arguments:
parameters - (string or nil) The parameters that are to be monitored for state changes.
force - (boolean) Indicates to trigger a callback even if the state doesn't change.
stateDriver:Update(stateOverride, enabledOverride)
Trigger an immediate state update of stateDriver if enabled or enabledOverride is set. If the state has changed, or stateOverride is set, then a callback is also triggered.
Arguments:
stateOverride - (boolean) Indicates to perform a callback even if the state did not change.
enabledOverride - (boolean) Indicates to treat stateDriver as enabled even if its not.