Patch 11.0.0/API changes

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

Summary

• Regions can now be configured to propagate mouse input to other obscured regions. See Mouse input propagation.
• Hero Talent Trees are introduced into the C_ClassTalents and C_Traits APIs. See Dragonflight Talent System - Hero Talent Trees.

Resources

• TOC: 110000
• Diffs: wow-ui-source, BlizzardInterfaceResources

Breaking changes

• The GetMouseFocus function has been replaced by GetMouseFoci.
  • This new function returns a table that potentially contains multiple regions based upon the state of mouse input propagation.
  • For the common use case of checking if a region has focus, the ScriptRegion:IsMouseMotionFocus() function can be used. This API exists on all client flavors.

Mouse input propagation

Support has been added to allow configuring a region to propagate mouse click and mouse motion events to other regions in the frame stack.

The below example will create three frames stacked atop one another of varying sizes.

1. A 200x200 red frame will be at the bottom of the stack, positioned in the center of the screen.
2. A 100x100 blue frame will be in the middle of the stack, positioned in the middle of the first frame.
3. A 50x50 green frame will be at the top of the stack, positioned in the middle of the second frame.

Only the third of these frames is configured to propagate mouse click and motion events.

local function CreatePropagationTestFrame(name, color)
    local frame = CreateFrame("Frame")
    frame:SetScript("OnEnter", function() print(name .. ": OnEnter") end)
    frame:SetScript("OnLeave", function() print(name .. ": OnLeave") end)
    frame:SetScript("OnMouseDown", function() print(name .. ": OnMouseDown") end)
    frame:SetScript("OnMouseUp", function() print(name .. ": OnMouseUp") end)
    frame.Bg = frame:CreateTexture()
    frame.Bg:SetAllPoints(frame)
    frame.Bg:SetColorTexture(color:GetRGBA())
    return frame
end

local Frame1 = CreatePropagationTestFrame("Frame1", CreateColor(1, 0, 0))
Frame1:SetFrameLevel(100)
Frame1:SetPoint("CENTER")
Frame1:SetSize(200, 200)

local Frame2 = CreatePropagationTestFrame("Frame2", CreateColor(0, 1, 0))
Frame2:SetFrameLevel(200)
Frame2:SetPoint("CENTER", Frame1, "CENTER")
Frame2:SetSize(100, 100)

local Frame3 = CreatePropagationTestFrame("Frame3", CreateColor(0, 0, 1))
Frame3:SetFrameLevel(300)
Frame3:SetPoint("CENTER", Frame2, "CENTER")
Frame3:SetSize(50, 50)

Frame3:SetPropagateMouseClicks(true)
Frame3:SetPropagateMouseMotion(true)

Click events

• When pressing a mouse button over the third frame, the OnMouseDown script fires for the third and second frames in order.
• When releasing the previously held mouse button, the OnMouseUp script fires for the third and second frames in order.
• In neither case does the OnMouseDown or OnMouseUp script fire for the first frame at the bottom of the stack.
  • This is because the second frame in the stack has not been configured to propagate click events.

Motion events

The following can be observed while moving the cursor from left to right over the three frames.

1. Upon entering the first frame, the OnEnter script fires for the first frame.
2. Upon entering the second frame, the OnLeave and OnEnter scripts fire for the first and second frames respectively.
3. Upon entering the third frame, only the OnEnter script fires for the third frame.
4. Upon leaving the third frame, only the OnLeave script fires for the third frame.
5. Upon leaving the second frame, the OnLeave and OnEnter scripts fire for the second and first frames respectively.
6. Upon leaving the first frame, the OnLeave script fires for the first frame.

Details

• If propagation is enabled for the region on the top of the stack, events propagate to the next region in the stack.
• Propagation is recursive and continues until finding a region in the stack where propagation is disabled.
• Propagation does not consider parent and child relationships. Events can be passed through to unrelated regions if they're the next thing in the stack.
• Propagation can be configured in XML via the propagateMouseInput attribute, which accepts the strings "Motion", "Clicks", or "Both".
• All regions that are receiving mouse input in the stack can be obtained via the GetMouseFoci function.
• Toggling the state of propagation while actively hovering over a region will result in script handlers for obscured frames firing appropriately, but there is a variable delay to this.