|This article documents API changes made in Patch 5.0.5.
This article covers the cumulative AddOn UI Customization and Macro API changes from WoW 4.3.x through 5.0.5 for Mists of Panderia (Mists/MoP).
- Party and Group member APIs have been consolidated and renamed.
- Instance and Zone API semantics have changed.
- Some Specialization and Talent APIs have been renamed.
- Some Achievement APIs have been split, to simplify access by differnt types of IDs.
- Item link text has been extended yet one more optional parameter for 5.0.x.
- UIPanelButtonTemplate has changed dramaticaly, using layer textures to paint the button rather than the button's normal mechanism.
- New Lua execution time limit while in combat.
- The XML 'parentKey' functionality has been extended to be consumed in XML for Anchors and Animations.
- As of 9/27/2012 the Blizzard WoW AddOn Kit is out of date. It is not representative of 5.0.4 or newer UI art and code.
- 5.0.4 API Update Summary and ParentKey, RelativeKey details
- Patch 5.0.4 Survival Guide or MMO Champ Blue Post style (easier to read)
- 5.0.5 Cumulative Known Issues
- 5.0.4 AddOn Update Suvival Guide (Green Post)
Party and Group APIs
Several of the specialized Party and Raid functions and events have been consolidated. The naming convention cleanup is basically that: 'Party' and 'Raid' groups have semantically become just a 'Group'; and 'Party' within a 'Raid' has semantically become just a 'SubGroup'. This effectively means that a Group is now a 'Group', whether raid or party. And a raids' parties are now 'SubGroups'. There were some return value type changes where the new GetNum functions return Lua 'true' and 'false' instead of '1' and 'nil', as is the growing trend with new fuctions after WoW went to Lua 5.0.
- group counts - GetNumPartyMembers, GetNumRaidMembers and GetRealNumRaidMembers to GetNumGroupMembers
- subgroup counts - GetNumPartyMembers (within a raid) and GetRealNumPartyMembers (within a raid) to GetNumSubgroupMembers
Similarly, the party and raid leaders have converged, while 'UnitIs..' covers 'Is..' now.
- group leader - IsRaidLeader, IsPartyLeader and UnitIsPartyLeader are now covered by UnitIsGroupLeader
- group assistant - IsRaidOfficer and UnitIsRaidOfficer are now covered by UnitIsGroupAssistant
- raid status - 'GetNumRaidMembers() ~= 0' becomes IsInRaid()
- party status - 'GetNumRaidMembers() == 0 and GetNumPartyMembers() ~= 0' becomes 'not IsInRaid() and GetNumGroupMembers() ~= 0'
- group status - 'GetNumRaidMembers() ~= 0 or GetNumPartyMembers() ~= 0' becomes 'IsInGroup()'
- party status - 'GetNumRaidMembers() == 0 and GetNumPartyMembers() ~= 0' also becomes 'not IsInRaid() and IsInGroup()'
And the coresponding events have merged.
Instance and Zone API
With all the changes to the back-end for greater cross-realm functionality, instance and zone semantics have changed more on the client, causing API updates or further clarification of those to fit the new world and server constructs. This is a partial grand summary of the current state.
- instance - GetInstanceInfo() adds return value 'mapID', for transparency and disambiguation. each instanceable area has an id, incl contenents
- instance - GetRealZoneText() will behave irratically. like at the start of a BG will sometimes report a zone/subzone rather than map name.
- home - GetInstanceInfo() will solidly report the contenent now, which wasnt 100% the case before.
- units - GetRaidRosterInfo() and UnitName() on zone change can provide invalid names for many minutes, for cross-realm players
- tooltip - char info changed to support Pandarians by adding faction at the bottom, but above PvP if flagged. this affects tooltip zone lookup.
The 'instance' concept on the client is even more aligned now with the natural world load chunks, like when you have to see a loading screen. The basic containership for areas, from the servers persective, is instance/map (whether its a "persistant" one or not) -> zone -> sub-zone. Your base-line given tools are (theorectically): tooltip method works only if in zone, in a group, or on a list
- self home instance: GetInstanceInfo() -> GetRealZoneText() -> GetSubZoneText() (works perfectly)
- others home instance (in zone/radius): none -> none/tooltip -> none
- others home instance (out zone/radius): none -> none/tooltip -> none
- self party instance: GetInstanceInfo() -> (unreliable)GetRealZoneText() -> GetSubZoneText()
- others party instance (in instance): none/tooltip -> none -> none
- others party instance (out instance): none -> none/tooltip -> none
- self raid instance: GetInstanceInfo() -> (unreliable)GetRealZoneText() -> GetSubZoneText()
- others raid instance (in instance): GetRaidRosterInfo()(really zone, but atm matches inst name) /tooltip -> none -> none
- others raid instance (out instance): none -> GetRaidRosterInfo() /tooltip -> none
Basically using the base API, thats it... unless a player is on your friends/bnet/guild/etc... list, or by using 'who' API. The API for the Lua side has changed real meanings for these several times, towards what zone means. Normally in a regular 'home' zone, you cant target or get updates for those outside your zone or a certain radius, so theres no normal mechanism as its irrelivant to the regular WoW UI needs. Furthermore this holds true across instances as well, as it would (whether you think of instance in terms of 'specific map' or 'running copy'.) Only if you have some other association does the client get updates or potentially have the data, without specific other request. However, like the friends list, updates occur for those in a raid, party, and presumably 'senarios', together. In this case the client intends to be able to recieve and cache info for that extended set of players, besides those in your zone. Other than GetRaidRosterInfo there is no other API for accessing these, but there are workarounds.
Specialization and Talent APIs
Several of the player Talent and Specialization functions have been renamed for clarity and to be more general, and more follow the naming for Party and Groups functions.
- spec counts - GetNumTalentTabs to GetNumSpecializations, and GetNumTalentGroups to GetNumSpecGroups
- spec info list - GetSpecializationInfoByID (added 5.0.4)
- spec info - GetPrimaryTalentTree to GetSpecialization, and GetTalentTabInfo to GetSpecializationInfo
- group info - GetActiveTalentGroup to GetActiveSpecGroup, and SetActiveTalentGroup to SetActiveSpecGroup
- spec role - GetTalentTreeRoles to GetSpecializationRole
- unspent talents - GetUnspentTalentPoints to GetNumUnspentTalents
There was some specialized Achievement API rework where function has been split, getting info by 'index' or 'id' seperately and less awkwardly. The parameter differneces are via 'criteriaIndex' and 'criteriaID' respectively.
- crit info - GetAchievementCriteriaInfo split or simplified into GetAchievementCriteriaInfo and GetAchievementCriteriaInfoByID
XML Lua Object References
In addition to the existing 'parentKey' there are now a few more standard reference and related attributes. These 'key' references are used to automatically set an object reference at runtime to a its LayoutFrame object instance, which would be directly avaible to the inline script functions and other functionality. Two of the new additions, realtiveKey and targetKey, allow setting targets based on object references directly from XML.
- parentKey (existing)
- target - directly set the animation target by name
- targetKey - use a 'reference' to find the target rather than a global name
- relativeTo (existing)
- relativeKey - alternative to 'relativeTo' that uses a 'reference' instead of a global name
General notation for 'Keys' (object refrences) follows similar convention as the relative naming convention for 'names' in LayoutFrames, like '$parentMyChildName'. One difference is that each key reference for 'parentKey' implicitly refers to the parent already. For example
where the child frame will place a reference, named 'Child', to itself on the outer frame. However, an inner frame using 'relativeKey' for an anchor must use '$parent.Child' to refer to the same key on the outer parent, as otherwise it could be refering to a key placed on itself. For example
<Frame><Frames> <Frame parentKey="Child"/> <Frame><Anchors><Anchor point="TOP" relativeKey="$parent.Child" relativePoint="BOTTOM"/><Anchors></Frame> </Frames></Frame>
where the second inner frame will be positioned the bottom of the first inner frame.
- The original UIPanelButtonTemplate is gone, and is now replaced by a renamed UIPanelButtonTemplate2, that existed previously. This causes all buttons (that use UIPanelButtonTemplate) to use the new scheme for rendering by tiling rather than stretching, using layer textures rather than the 'NormalTexture' and friends. This could be a visually or funcitonally breaking change for some. The stretchy buttons were argualbly simpler, but had pretty bad stretching artifacts.
- from |cXXXXXXXX|Hitem:[6 positive integers][4 negative or positive integers]|h[item name]|h|r
- to |cXXXXXXXX|Hitem:[6 positive integers][5 negative or positive integers]|h[item name]|h|r
- Inline X and Y values for XML Anchors have been officially changed from 'int' to 'float'. There were already anchors in the game resource files with float values prior to 5.0.4.