Download
(5Kb)
Download
Updated: 05-24-14 12:32 PM
Updated:05-24-14 12:32 PM
Created:07-22-09 09:27 PM
Downloads:2,664
Favorites:4
MD5:

LibStateDriver-1.3

Version: 1.3
by: Vrul [More]

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.

Version 1.3 (05/24/2014)
- Consolidated some code
- Additional optimizations to prevent unnecessary processing
- Combined the stateDriver methods Enable and Disable into SetEnabled
- Added the stateDriver method IsActive
- Removed the stateDriver methods Pack and Toggle, can use stateDriver:SetEnabled(not stateDriver:IsEnabled()) in place of Toggle
- Altered the stateDriver method SetObject to no longer default to stateDriver if nil is passed
- Changed the library method New to a function and it now behaves slightly different

Version 1.2.1 (09/27/2012)
- Fix for performing arithmetic on a nil value errors with macro conditionals: petbattle, possessbar, spec, stealth, vehicleui
- Changed the event used to detect gear changes to PLAYER_EQUIPMENT_CHANGED (from UNIT_INVENTORY_CHANGED)
- Slight reduction in memory use

Version 1.2 (09/02/2012)
- Updated for MoP

Version 1.1.1 (09/11/2010)
- Fix for using the methods Disable or Enable during a stateDriver update

Version 1.1 (05/24/2010)
- Parameter parsing changed slightly to allow for use of "@" and to further minimize OnEvent/OnUpdate use
- Callbacks are now executed safely via pcall
- GetArg/SetArg renamed GetObject/SetObject
- Added the stateDriver methods Recycle and Pack
- lib:New() and stateDriver() argument/behavior changed

Version 1.0.1 (09/27/2009)
- Added MMOUI Minion support to TOC file (X-WoWI-ID)
- Changed the event used to detect spec changes to ACTIVE_TALENT_GROUP_CHANGED (from PLAYER_TALENT_UPDATE)

Version 1.0 (07/22/2009)
- Initial release
Optional Files (0)


There have been no comments posted to this file.
Be the first to add one.



Category Jump: