WoW:RestrictedEnvironment
Jump to navigation
Jump to search
Restricted environment refers to the environment in which restricted addon code (SecureHandler snippets) is executed. A limited subset of the WoW API is available within the environment.
Available API[edit]
- SecureCmdOptionParse("conditionalString") : parses a macro conditional.
- GetShapeshiftForm() : returns current shape shift form.
- IsStealthed() : returns 1 if the player is stealthed
- UnitExists("unit") : returns 1 if the unit exists.
- UnitIsDead("unit") : returns 1 if the unit is dead.
- UnitIsGhost("unit") : returns 1 if the unit is a ghost.
- UnitPlayerOrPetInParty("unit") : returns 1 if the unit is a player or a pet in your party.
- UnitPlayerOrPetInRaid("unit") : returns 1 if the unit is a player or a pet in your raid.
- IsRightAltKeyDown(), IsLeftAltKeyDown(), IsAltKeyDown() : return 1 if the relevant key is held down.
- IsRightControlKeyDown(), IsLeftControlKeyDown(), IsControlKeyDown() : return 1 if the relevant key is held down.
- IsRightShiftKeyDown(), IsLeftShiftKeyDown(), IsShiftKeyDown() : return 1 if the relevant key is held down.
- IsModifierKeyDown() : returns 1 if any alt, control or shift key is held down.
- IsModifiedClick("modifierType") : returns 1 if the associated modifier is held down.
- GetMouseButtonClicked() : returns the mouse button responsible for the hardware click.
- GetActionBarPage() : returns the current action bar page.
- GetBonusBarOffset() : returns the current action bar "bonus" offset (stance-specific bars).
- IsMounted() : returns 1 if the player is mounted.
- IsSwimming() : returns 1 if the player is swimming.
- IsFlying() : returns 1 if the player is flying.
- IsFlyableArea() : returns 1 if the player is in a flyable area (Northrend, Outland).
- IsIndoors() : returns 1 if the player is indoors.
- IsOutdoors() : returns 1 if the player is outdoors.
- GetBindingKey("key") : returns the action bound to a key.
- HasAction(slot) : returns 1 if an action is placed in the specified action bar slot.
- IsHarmfulSpell(slot[, bookType] or "spellName") : returns 1 if the spell can be cast on hostile targets.
- IsHarmfulItem(slot[, bookType] or "spellName") : returns 1 if the item can be used on hostile targets.
- IsHelpfulSpell(slot[, bookType] or "spellName") : returns 1 if the spell can be cast on friendly targets.
- IsHelpfulItem(slot[, bookType] or "spellName") : returns 1 if the item can be used on friendly targets.
- PlayerCanAttack("unit") : returns 1 if the player can attack the specified unit.
- PlayerCanAssist("unit") : returns 1 if the player can assist the specified unit.
- PlayerIsChanneling() : returns 1 if the player is channeling a spell.
- PlayerPetSummary() : returns pet creature family and pet name.
- PlayerInCombat() : returns 1 if the player or his pet is in combat.
- PlayerInGroup() : returns "party" or "raid" if the player is in one of those group types.
- UnitHasVehicleUI("unit") : returns 1 if the unit is in a vehicle that provides special UI.
- RegisterStateDriver(frame, state, conditional) : registers a SecureStateDriver for a specific frame.
- GetActionInfo(slot) : returns limited information about an action in a specific action slot.
Restricted tables[edit]
Only restricted tables are accessible within the restricted environment -- essentially, the real table instances are kept local to prevent unrestricted access to variables within the restricted environment. Most table functions within the restricted environment have been replaced by restricted table-aware versions, with the exception of the gsub function (use the restricted table-aware rtgsub instead of table lookup functionality is desired).
The following table-related functions are usable inside the restricted environment:
| Restricted Table Library | ||||||
| rtable.next | rtable.pairs | rtable.ipairs | rtable.unpack | rtable.newtable | rtable.maxn | rtable.insert |
| rtable.remove | rtable.sort | rtable.concat | rtable.wipe | rtable.type | rtable.rtgsub | |
| Table Library (restricted-table aware) | ||||||
| table.maxn | table.insert | table.remove | table.sort | table.concat | table.wipe | table.new |
| Global API | ||||||
| newtable | pairs | ipairs | next | unpack | wipe | tinsert |
| tremove | type | rtgsub | ||||
Note that as the restricted environment doesn't contain proper function references, table.sort's second argument (comparison function) may not be used from within the restricted environment.
Other functions[edit]
The math and string standard library tables are provided in their entirety. The following table lists additional global functions that are also available in the restricted environment
| select | tonumber | tostring | format | gmatch | gsub | strbyte | strchar | strconcat | strfind | |
| strjoin | strlen | strlower | strmatch | strrep | strrev | strsplit | strsub | strtrim | strupper | abs |
| acos | asin | atan | atan2 | ceil | cos | deg | exp | floor | frexp | ldexp |
| log | log10 | max | min | mod | rad | random | sin | tan |
Frame handle methods[edit]
Real frame userdata values may not exists within the restricted environment; instead, it the restricted environment may contain frame references (introduced via the :SetFrameRef("name", frame) method). A limited subset of the widget API can be invoked upon those references; only methods marked with a star may be called on references to non-protected frames.
| * | Method | Purpose |
|---|---|---|
| Accessor methods | ||
| * | handle:GetName() | Returns frame name. |
| * | handle:GetObjectType() | Returns widget type. |
| * | handle:IsObjectType("widgetType") | Returns 1 if the frame is of the specified widget type. |
| * | handle:IsProtected() | Returns 1 if the frame is protected. |
| handle:GetID() | Returns the ID value associated with the frame. | |
| handle:IsShown() | Returns 1 if the frame is shown (even if its ancestors are not). | |
| handle:IsVisible() | Returns 1 if the frame is visible (i.e. it and all its ancestors are shown). | |
| handle:GetWidth() | Returns frame width. | |
| handle:GetHeight() | Returns frame height. | |
| handle:GetRect() | Returns left, bottom, width, height specification of the frame's rectangle. | |
| handle:GetScale() | Returns frame scale. | |
| handle:GetEffectiveScale() | Returns effective frame scale (its own scale multiplied with that of all of its ancestors). | |
| handle:GetFrameLevel() | Returns frame level. | |
| handle:GetAttribute("name") | Returns the value of an attribute; name must not begin with an underscore. | |
| handle:GetFrameRef("name") | Retrieve a restricted handle to a frame set by SetFrameRef(). | |
| handle:GetEffectiveAttribute("name", "button", "prefix", "suffix") | Returns the effective value of a modified attribute. Attribute name must not begin with an underscore. | |
| handle:GetChildren() | Returns restricted references to the frame's children in a list(?). | |
| handle:GetChildList(tbl) | Returns restricted references to the frame's children in a table(?). | |
| handle:GetParent() | Returns a restricted reference to the frame's parent. | |
| handle:GetMousePosition() | Returns mouse position relative to the frame, where (0,0) is the bottom left corner. | |
| handle:IsUnderMouse(recursive) | Returns 1 if the frame, or, if recursive is true, any of the frame's children (and their children) are under the mouse. | |
| handle:GetNumPoints() | Returns the number of anchoring points used by the frame. | |
| handle:GetPoint(i) | Returns information about an anchoring point. | |
| Setter methods | ||
| handle:Show(skipAttr) | Shows a frame, and, unless skipAttr is true, set the "statehidden" attribute to nil. | |
| handle:Hide(skipAttr) | Hides a frame, and, unless skipAttr is true, set the "statehidden" attribute to true. | |
| handle:SetID(id) | Sets the ID value associated with the frame | |
| handle:SetWidth(width) | Sets frame width. | |
| handle:SetHeight(height) | Sets frame height. | |
| handle:SetScale(scale) | Sets frame scale | |
| handle:SetAlpha(alpha) | Sets frame alpha | |
| handle:ClearAllPoints() | Clears all anchoring points | |
| handle:SetPoint(point, relframe, relpoint, ofsx, ofsy) | Sets an anchoring point. | |
| handle:SetAllPoints([relframe]) | Sets points to fill relframe, or the frame's parent if relframe is not specified. | |
| handle:SetAttribute("name", value) | Sets an attribute on the frame. Name must not begin with an underscore. | |
| handle:ClearBindings() | Clears all override bindings the frame is registered as an owner of. | |
| handle:ClearBinding(key) | Clears a specific override binding this frame is the registered owner of. | |
| handle:SetBindingClick(priority, key, name, button) | Creates an override click binding to click button specified by name (button name or reference), when key is pressed. The handle acts as the override binding's owner | |
| handle:SetBindingSpell(priority, key, spell) | Creates an override spell binding; the handle specifies the binding's owner. | |
| handle:SetBindingMacro(priority, key, macro) | Creates an override macro binding; the handle specifies the binding's owner. | |
| handle:SetBindingItem(priority, key, item) | Creates an override item binding; the handle specifies the binding's owner. | |
| handle:Raise() | Makes frame top-most. | |
| handle:Lower() | Lowers the frame's frame level. | |
| handle:SetFrameLevel(level) | Alters frame level. | |
| handle:SetParent(parent) | Changes frame's parent. | |
| handle:RegisterAutoHide(duration) | Registers the frame to be hidden after the mouse leaves the frame for duration seconds. | |
| handle:UnregisterAutoHide() | Unregisters the frame from automatic hiding. | |
| handle:AddToAutoHide(childFrame) | Adds a child frame to this frame's automatic hiding. The duration now applies to the mouse being out of both the frame and the childFrame. | |
| handle:Disable() | Disables a button, disabling click handling. | |
| handle:Enable() | Enables a button, enabling click handling. | |
Control methods[edit]
Additional methods are available as part of the control table; allowing functionality somewhat resembling proper functions within the protected environment.
- control:CallMethod("methodName", ...)
- insecurely calls methodName method of the restricted environment's owner.
- control:Run("body", ...)
- executes Lua code in body with the provided arguments; self is the handle of the environment's owner.
- control:RunFor(handle, "body", ...)
- executes Lua code in body with the provided arguments; self is the argument value.
- control:RunAttribute("snippetAttr", ...)
- executes the method contained in the snippetAttr attribute of the restricted environment owner with self, ... as arguments.
- control:ChildUpdate("snippetid", message)
- executes the contents of "_childupdate-snippetid" (or, if that attribute is nil/false, "_childupdate"), on all protected children (and children of children) of the restricted environment owner with (self, scriptid, message) arguments.
| |||||||||||||||||