SecureStateDriver

From Wowpedia
Jump to: navigation, search

A SecureStateDriver allows code snippets to execute upon game state changes expressible using macro conditionals.

SecureStateDriver.lua implements two kinds of SecureStateDriver:

  • AttributeDriver (formerly StateDriver) securely controls any type of Frame by toggling its visibility or setting customizable attributes
  • UnitWatch securely controls a unit frame by toggling its visibility or state-unitexists attribute

Combined with SecureHandlerStateTemplate or SecureUnitButtonTemplate, these SecureStateDrivers faciliate code execution in the RestrictedEnvironment to alter protected values during combat.

AttributeDriver

RegisterAttributeDriver(frame, attribute, conditional)
UnregisterAttributeDriver(frame, attribute)
RegisterStateDriver(frame, state, conditional)         -- depreciated
UnregisterStateDriver(frame, state)                    -- depreciated

Creates or cancels an AttributeDriver. Frames execute code snippets insecurely using OnAttributeChanged or securely by inheriting SecureHandlerStateTemplate.

The depreciated StateDriver functions forward their arguments to AttributeDriver ones after prepending the second argument with "state-".

frame 
Frame - The AttributeDriver acts on this frame by toggling its visibility or setting its attributes
attribute 
String - Any arbitrary identifier, but converted to lower case with the following results:
  • "state-visibility" causes an AttributeDriver to securely call Region:Show() when the macro conditional evaluates to "show" or Region:Hide() when it evaluates to "hide"
  • Other values cause an AttributeDriver to securely call Frame:SetAttribute(state, result) using the outcome of the macro conditional's evaluation as result
state 
String - Prepended with "state-" and then used similar to attribute (ie. state "visibility" becomes attribute "state-visibility")
conditional 
String - A macro conditional parsable by SecureCmdOptionParse

UnitWatch

RegisterUnitWatch(frame, asState)
UnregisterUnitWatch(frame, asState)

Creates or cancels a UnitWatch. Frames must inherit SecureUnitButtonTemplate and have an assigned unitId using Frame:SetAttribute("unit", "unitId")

frame 
Frame - The UnitWatch acts on this frame by toggling its visibility or setting its attributes
asState 
Boolean - Controls the behaviour of a UnitWatch with the following results:
  • True causes the UnitWatch to securely call Frame:SetAttribute("state-unitexists", result) using the outcome of the macro conditonal's evaluation as result
  • False causes the UnitWatch to securely call Region:Show() when the macro conditional evaluates to "show" or Region:Hide() when it evaluates to "hide"

Examples

Showing/hiding a unit frame
local frame = CreateFrame("Button", "MyParty1", UIParent, "SecureUnitButtonTemplate")
frame:SetAttribute("unit", "party1")
RegisterUnitWatch(frame)
    
frame:SetPoint("CENTER")
frame:SetSize(50, 50)
frame:SetBackdrop({ bgFile = "Interface\\BUTTONS\\WHITE8X8", tile = true, tileSize = 8 })
frame:SetBackdropColor(1, 0, 0)

The snippet above will display a clickable unit frame for the "party1" unit (consisting solely of a red square in the center of your screen) only when the unit exists.

Responding to custom states
local frame = CreateFrame("Frame", "MyStatefulFrame", UIParent, "SecureHandlerStateTemplate")
RegisterStateDriver(frame, "petstate", "[@pet,noexists] nopet; [@pet,help] mypet; [@pet,harm] mcpet")
frame:SetAttribute("_onstate-petstate", [[ -- arguments: self, stateid, newstate
    if newstate == "nopet" then
        print("Where are you, kitty?")
    elseif newstate == "mypet" then
        print("Oh hai, kitty!")
    elseif newstate == "mcpet" then
        print("Curse your sudden but inevitable betrayal, kitty!") -- Your pet is hostile to you.
    end
]])
RegisterStateDriver just implements RegisterAttributeDriver
function RegisterStateDriver(frame, state, conditional)
  return RegisterAttributeDriver(frame, "state-"..state, values);
end

Notes

Patch changes

  • Mists of Pandaria Patch 5.0.4 (2012-08-28): Conditionals now evaluate on GROUP_ROSTER_UPDATE[2]
  • Cataclysm Patch 4.0.1 (2010-10-12): AttributeDriver added, but StateDriver remains as a bridge function.[3]
  • The Burning Crusade Patch 2.1.0 (2007-05-22): StateDriver and UnitWatch added.[4]

References

 
  1. ^ 2007-05-22, SecureStateDriver.lua, version 2.1.0.6692, near line 54, archived at Townlong-Yak
  2. ^ 2012-08-21, SecureStateDriver.lua, version 5.0.4.16016, near line 178, archived at Townlong-Yak
  3. ^ 2010-10-19, SecureStateDriver.lua, version 4.0.1.13164, near line 25, archived at Townlong-Yak
  4. ^ 2007-05-22, SecureStateDriver.lua, version 2.1.0.6692, near line 8, archived at Townlong-Yak