SecureStateDriver

From Wowpedia
Jump to: navigation, search

SecureStateDriver is a mechanism that allows secure handlers to register to be notified when conditions that are expressible using macro conditionals change. The handler can then respond by executing a snippet in the restricted environment, allowing (restricted) addon code to alter protected values while in combat. Additionally, a simplified interface is available for unit frames, allowing them to be shown only when the unit they track exists.

The implementation is included as part of FrameXML in FrameXML/SecureStateDriver.lua. Conditionals are generally evaluated every 0.2 seconds, as well as in response to events that are guaranteed to alter some secure conditionals.

API

There are four functions provided by the Secure State Driver API:


RegisterStateDriver(frame, stateid, conditional)

The generic state driver for any frame -- you can register to be notified when an arbitrary macro conditional evaluates to a different values. Updates are delivered via attributes; handle OnAttributeChanged or use SecureHandlerStateTemplate with a corresponding snippet to respond from a restricted environment. Repeated calls with the same frame and stateid will overwrite previous ones.
frame 
Frame-derived widget - notifications will be delivered by setting attributes on this frame.
stateid 
String - an arbitrary identifier string for this conditional (coerced to lower case), or "visibility". The latter is a special state -- rather than delivering an update through attribute changes, it shows or hides the frame when the conditional evaluates to "show" or "hide" respectively.
conditional 
String - macro conditional parsable by SecureCmdOptionParse. The value this conditional evaluates to will be set as the value of the "state-stateid" attribute on the frame.


UnregisterStateDriver(frame, stateid)

Cancels a previous generic state driver for the given frame and stateid


RegisterUnitWatch(frame, asState)

Assists in controlling unit frames -- can either show/hide the frame based on whether its unit exists; or deliver that information via a state attribute.
frame 
Frame-derived widget - The frame to be shown/hidden/notified when its unit exists / does not exist.
asState 
Boolean - if true, the "state-unitexists" attribute will be set to a boolean value denoting whether the unit exists; if false, the frame will be shown if its unit exists, and hidden if it does not.


UnregisterUnitWatch(frame, asState)

Cancels a previous generic state driver for the given frame and stateid

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
]])

The snippet above will print text to your chat frame when the state of your pet changes.