Patch 2.1.0/API changes

Main Menu
WoW API Lua API FrameXML util Widget API Widget scripts XML schema Events CVars Macro commands Combat Log Escape sequences Hyperlinks API changes HOWTOs wowuidev

Highlights

• The UI memory limit has been removed, and memory profiling features are available.
• CPU profiling features are available (but must be enabled).
• Conditionals on #show and #showtooltip
• Improved interface loading time and reduced script memory usage by about 50%

Template Handlers

• Script handlers inherited from templates now share a single instance of the handler function, rather than a different closure for each one. This significantly reduces loading time and memory footprint of any frame that's using template handlers (but may behave unexpectedly if you use setfenv on handlers today).

Memory Profiling

• Script memory is now tracked on a per-addon basis, with functions provided to analyze and query usage.
• The script memory manager has been optimized and the garbage collection tuned so there is no longer any need for a hard cap on the amount of UI memory available.
• NEW - UpdateAddOnMemoryUsage() - Scan through memory profiling data and update the per-addon statistics
• NEW - usedKB = GetAddOnMemoryUsage(index or "name") - query an addon's memory use (in K, precision to 1 byte) - This returns a cached value calculated by UpdateAddOnMemoryUsage().

CPU Profiling

• CPU profiling is disabled by default since it has some overhead. CPU profiling is controlled by the scriptProfile cvar, which persists across sessions, and takes effect after a UI reload.
• When profiling is enabled, you can use the following functions to retrieve CPU usage statistics. Times are in seconds with about-a-microsecond precision:
• NEW - time = GetScriptCPUUsage() - Returns the total timeused by the scripting system
• NEW - UpdateAddOnCPUUsage() - Scan through the profiling data and update the per-addon statistics
• NEW - time = GetAddOnCPUUsage(index or \"name\") - Returns the total time used by the specified AddOn. This returns a cached value calculated by UpdateAddOnCPUUsage().
• NEW - time, count = GetFunctionCPUUsage(function[, includeSubroutines]) - Returns the time used and number of times the specified function was called. If 'includeSubroutines' is true or omitted, the time includes both the time spent in the function and subroutines called by the function. If it is false, then time is only the time actually spent by the code in the function itself.
• NEW - time, count = GetFrameCPUUsage(frame[, includeChildren]) - Returns the time used and number of function calls of any of the frame's script handlers. If 'includeChildren' is true or omitted, the time and call count will include the handlers for all of the frame's children as well.
• NEW - time, count = GetEventCPUUsage(["event"]) - Returns the time used and number of times the specified event has been triggered. If 'event' is omitted, the time and count will be totals across all events.
• NEW - ResetCPUUsage() - Reset all CPU profiling statistics to zero.

Frames

Frame alpha now propagates in the same way as scale (though is clamped between 0 and 1 on each object). This means you can cleanly fade the whole UI or specific frame assemblies.

• NEW - ScriptObject:HookScript("name", function) Previously called Frame:HookScript() - Exactly equivalent to hooksecurefunc(), but usable with frame script handlers. (Note that like hooksecurefunc, this is not intended as a general hooking replacement, but to allow hooking of secure frame handlers.)
• NEW - alpha = Region:GetEffectiveAlpha() Previously called Frame:GetEffectiveAlpha() - Returns the effective alpha of a frame, which is logically region:GetParent()}}:GetEffectiveAlpha * region:GetAlpha()

GameTooltip

• UPDATED - name, unitid = GameTooltip:GetUnit() - Added second 'unitid' return value
• NEW - hasComparison = GameTooltip:SetHyperlinkCompareItem(link, index) - Sets a comparison tooltip to show the index'th comparison item to the item specified as link. Will return a true value if there is an index'th comparison item (index is 1 or 2).
• REMOVED -specialized GameTooltip:Set*CompareItem(...) methods in favor of SetHyperlinkCompareItem. See GameTooltip:ShowCompareItem() for details.

API Functions

• UPDATED - isSecure, taint = issecurevariable() - Now returns a second value which is the name of the addon that tainted the variable (or the empty string if it was tainted by a macro script), if it is not secure.
• UPDATED: GetCursorInfo() will now return "merchant", index when the cursor holds a merchant item.
• NEW - link = GetSendMailItemLink()
• NEW - loggedIn = IsLoggedIn() - returns false before the PLAYER_LOGIN event, and true during and after the PLAYER_LOGIN event.
• NEW - isFeigned = UnitIsFeignDeath("unit") - returns true if the unit is the player, or in the player's party/raid and is feigning death.
• REMOVED - IsFeignDeath() - Replaced by UnitIsFeignDeath
• UPDATED - SendAddOnMessage("prefix","message"[,"type"][,"target"]) -- now accepts "WHISPER" as the message type, which will not be affected by the throtting of whispers.
• UPDATED - name, rank, icon, count, duration, timeLeft = UnitBuff("target", i) -- Now returns duration and timeLeft for buffs you can cast (those with times come first in the list)
• UPDATED - name, rank, icon, count, debuffType, duration, timeLeft = UnitDebuff("target", i); -- Now returns duration and timeLeft for debuffs you can cast (those with times come first in the list
• NEW - name, itemlink = "itemlink", index)("name) -- Takes an item with a gem in it, and an index from 1-3, and returns the name and link for the gem at that index. Note that using the name may be ambiguous if you have more than one of the named item.
• NEW - CanComplainChat(lineID) -- determines if we should show the menu for reporting a line of chat spam (lineID comes from the player link in the chat line)
• NEW - ComplainChat(lineID) -- complains about a particular line of chat spam
• NEW - CanComplainInboxItem(index) -- determines if we should show the “report spam” button on a mail item
• NEW - ComplainInboxItem(index) -- complains about a particular mail item

Observed additions

The following new global API functions were also added to the client.

• CancelShapeshiftForm()
• ClearPartyAssignment()
• DescendStop()
• GetBuybackItemLink()
• GetCraftItemNameFilter()
• GetCraftRecipeLink()
• GetDailyQuestsCompleted()
• GetDynamicMacros()
• GetMacroBody()
• GetMaxDailyQuests()
• GetQuestResetTime()
• GetTradeSkillItemLevelFilter()
• GetTradeSkillItemNameFilter()
• GetTradeSkillRecipeLink()
• InitWorldMapPing()
• IsFlyableArea()
• ResetChatWindows()
• SetCraftItemNameFilter()
• SetTradeSkillItemLevelFilter()
• SetTradeSkillItemNameFilter()
• SitStandOrDescendStart()
• StopTradeSkillRepeat()
• TradeSkillOnlyShowMakeable()
• UnitIsPossessed()
• UnitIsRaidOfficer()

Observed removals

• IsFeignDeath() - likely in favor of UnitIsFeignDeath()
• PitchDownStart()
• PitchDownStop()
• PitchUpStart()
• PitchUpStop()
• SitOrStand() - likely renamed to SitStandOrDescendStart()

Secure Templates

• For "item" buttons, name can be an item ID (prefixed with "item:") or full item link.
• Action buttons will automatically update if their action attribute changes (You can even do something like this ActionButton1:SetId(0) ActionButton1:SetAttribute("action", 1) ActionButton1:SetAttribute("shift-action*", 2) and when you hold down the shift key, it will show the icon, feedback and tooltip for action 2. :)
• The SecureStateHeaderTemplate now supports a small stack of saved states that can be used in state transition rules via push/pop/swap actions (See the header file for usage information)
• Added a generalized state driver that uses conditional macro syntax. e.g.: RegisterStateDriver(header, "stance", "[stance:1] 1; [stance:2] 2; [stance:3] 3; [stance:4] 4; [stance:5] 5; [stance:6] 6; [stance:7] 7; 0");

SecurePartyHeaderTemplate and SecureRaidGroupHeaderTemplate are now derived from a single template, SecureGroupHeaderTemplate, which can handle raids, groups, and solo play depending on the attributes set:

showRaid = [BOOLEAN] -- true if the header should be shown while in a raid

showParty = [BOOLEAN] -- true if the header should be shown while in a party and not in a raid

showPlayer = [BOOLEAN] -- true if the header should show the player when not in a raid

showSolo = [BOOLEAN] -- true if the header should be shown while not in a group (implies showPlayer)

Similar changes have been made for SecureRaidPetHeaderTemplate, with the addition of SecureGroupPetHeaderTemplate and SecurePartyPetHeaderTemplate

Macros

• New macro conditional [flyable] which is true if you're in a location where you could use a flying mount
• You can use %f in chat text to refer to your focus, the same way %t or %n refers to your target.
• Added macro option support for /dismount
• Macros containing conditionals will automatically update their visual feedback as appropriate during play.
• #show and #showtooltip can be given conditionals and will update dynamically
• #show and #showtooltip can be given a slot number, to display the appropriate feedback for that slot
• Added bag and slot number support to: /castsequence, /cast, /castrandom, /use, /userandom, /equip, /equipslot
• New slash command /cancelform
• The /equip command can take item identifiers specified as item:<id>: e.g. /equip [modifier:alt] item:25640
• You can provide several conditional clauses for a single action, which will be performed if any of the clauses evaluates to true. e.g. /cast [target=target,help,nodead] [target=targettarget,help,nodead] [target=player] Flash of Light

Raid Support Commands

The raid UI now has pullouts for the main tank and main assist, while the underlying API function is protected, they can be managed via the Raid UI or via the following new slash commands:

• /mt <name> - Set the main tank role for the named player, or the current target if not specified
• /mtoff <name> - Clear the main tank role for the named player, or the current target if not specified
• /clearmt - Clear all main tank roles
• /ma <name> - Set the main assist role for the named player, or the current target if not specified
• /maoff <name> - Clear the main assist role for the named player, or the current target if not specified
• /clearma - Clear all main assist roles

You can also use a the SecureActionButtonTemplate to control them:

• Set the "type" attribute to "maintank" or "mainassist"
• Set the "action" attribute to "set" or "clear" or "toggle"
• The "unit" attribute will indicate the unit/name to toggle

AddOn Features

• New TOC field: LoadManagers - When the game loads, each AddOn listed in this field is loaded in order until one successfully loads. If one of these are loaded, then the AddOn is then loaded on demand.

Default UI Code

• The Blizzard UI Code has been inspected and several instances of IsVisible corrected to use IsShown as appropriate.
• Spells that have reagent costs will show the number of uses left in the lower right corner of the action icon, just like consumable items on the action bar.
• Players will be able to see how much memory the UI is using and the top 3 addons using memory.
• Lua errors are no longer shown by default, but you can set the scriptErrors cvar to 1 to enable them. It is recommended that AddOn authors and testers leave this turned on so you can catch problems in your AddOns. This is implemented by code in the _ERRORMESSAGE() function, so if you already have an improved error message AddOn, this will not affect you.
• Slash command resolutions are cached in hash_SlashCmdList, so be sure to update it if you replace any existing slash commands in your code.

UIPanel Frame Management

The UI panel layout code now uses frame attributes instead of variables to manage layout. This allows well written AddOns to customize the layout without blocking protected panels in combat (Special thanks to Tem and AnduinLothar for initial work and suggestions).

UIParent Attributes:

• DEFAULT_FRAME_WIDTH - The default width of a single pane UI panel (default 384)
• TOP_OFFSET - The offset from the top of the screen (default -104)
• LEFT_OFFSET - The offset of the left panel from the left side of the screen (default 0)
• RIGHT_OFFSET_BUFFER - The amount of space to leave open on the right side of the screen (default 80)

UI Panel Attributes (initial values come from the UIPanelWindows table):

• UIPanelLayout-defined - True if the frame has layout attributes defined.
• UIPanelLayout-enabled - True if the frame should be handled by the UI panel layout system.
• UIPanelLayout-area - One of "left", "center", "right"
• UIPanelLayout-width - The effective width of the UI panel, used as an override for Region:GetWidth() Previously called Frame:GetWidth()
• UIPanelLayout-pushable - If specified as a value greater than 0, this is the priority used when sliding frames to the right when a new frame is opened.
• UIPanelLayout-whileDead - True if the frame can be opened while the player is dead.

Spam Reduction

• Unsolicited whispers sent via SendChatMessage() will be automatically throttled (to an unspecified, and as yet still undetermined limit), AddOns can use SendAddOnMessage instead, but be very careful to design their communication protocols effciently to avoid exponential growth in message rates.

Protected Actions

• Submitting or editing a GM ticket is now a protected action, and may not be done by third party AddOns.

Bug Fixes

• The raid pullout positions will be saved and restored between sessions
• Fixed a bug where frame alpha wasn't used b the Cooldown frame type
• Self cast works with items such as bandages
• Fixed errant 'this' in ContainerFrameItemButton_OnEnter
• Auction house sorting is fixed (There is now sorting by "bid", "buyout", and "buyoutthenbid". The main aucion house browse tab uses "buyoutthenbid" as requested by design. the other two tabs ("bids" and "auctions") use the proper sort ("bid vs. "buyout")).
• Fixed missing PLAYER_REGEN_ENABLED when zoning out of BG whilst in combat - event now fires before PLAYER_LEAVING_WORLD.
• Fixed rendering issues with lua-created ScrollFrames, and updated ScrollFrame:SetScrollChild(frame) so that it appropriately sets the parent of the child frame as expected (but which it previously did not do)

Other Observed Changes

• UPDATED - uiType, state, text, icon, dynamicIcon, tooltip, dynamicTooltip, extendedUI, extendedUIState1, extendedUIState2, extendedUIState3 = GetWorldStateUIInfo(i) -- Now has new uiType return at START of list, !!!! - Not backward compatible