Frame Strata

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

Frame strata (sometimes called frameStrata) orders each Frame on the screen, affecting how they overlap. These strata divide the z-axis into nine intervals (from back to front):

1. WORLD (see details)
2. BACKGROUND
3. LOW
4. MEDIUM
5. HIGH
6. DIALOG
7. FULLSCREEN
8. FULLSCREEN_DIALOG
9. TOOLTIP

Frame levels further divide each strata into smaller intervals, numbered 0-10000. Higher numbers appear above lower ones, but only if they share the same strata.

Details

Frame Strata vs. Layer

• WORLD is reserved for the world frame and cannot be assigned.
• Frames further partition the z axis into Layers when drawing a LayeredRegion (e.g. Texture or FontString).
• Every frame defaults to appearing slightly above its parent, sharing the same strata but having one level higher.
• Set a frame's strata using:
  • Frame:SetFrameStrata(frameStrata)
  • <Frame frameStrata="FRAMESTRATA">
• Set a frame's level using:
  • Frame:SetFrameLevel(frameLevel) to choose any value
  • Frame:Raise() or <Frame toplevel="true"> to increase frameLevel to one higher than existing frames which were previously in front but within the same frameStrata
  • Frame:Lower() for the opposite (no equivalent in XML)
  • <Frame useParentLevel="true"> to make frameLevel the same as the parent frame (instead of normally being one higher)
• When a parent frame changes its level, the descendant frames will change levels respectively (e.g. if a child frame was set 2 levels higher than its parent, it will shift 2 levels higher after the parent moves)
  • If this effect would cause a frame level to be lower than 0 it will instead be set to 10000

Example

local parent = CreateFrame("FRAME", nil, UIParent)
local child1 = CreateFrame("FRAME", nil, parent)
local child2 = CreateFrame("FRAME", nil, parent)
print(parent:GetFrameLevel(), child1:GetFrameLevel(), child2:GetFrameLevel()) -- 1, 2, 2

parent:SetFrameLevel(10)
child1:SetFrameLevel(15)
child2:SetFrameLevel(5)
print(parent:GetFrameLevel(), child1:GetFrameLevel(), child2:GetFrameLevel()) -- 10, 15, 5

parent:SetFrameLevel(20)
print(parent:GetFrameLevel(), child1:GetFrameLevel(), child2:GetFrameLevel()) -- 20, 25, 15

parent:SetFrameLevel(1)
print(parent:GetFrameLevel(), child1:GetFrameLevel(), child2:GetFrameLevel()) -- 1, 6, 10000

Patch changes

• Patch 7.0.3 (2016-07-19): Frame Level may be manually set to any value from 0 to 10000.
  

Q u o t e:

“(17:49.46) With 7.0.3, frame levels will no longer change automatically.... (17:59.34) [They] used to "compress" which caused all sorts of weird behaviour, like just the ordering of creating child frames could adjust your frame levels differently. (18:00.07) [They] now always stay what you set them to, and always sort correctly using that frame level”

— TheDanW on IRC log for #wowuidev on 20160720