ScrollFrame

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

ScrollFrame (inherits from Frame) may be customized to vertically or horizontally scroll other widgets.

The logic and textures to operate the ScrollFrame may be inherited from a template:

• UIPanelScrollFrameCodeTemplate - The logic for vertial scrolling without any textures. {⁠, ⁠}
• UIPanelScrollFrameTemplate - Adds vertical scroll bar textures beyond the right edge of the ScrollFrame. {⁠, ⁠}
• FauxScrollFrameTemplate - Adds vertical scroll bar textures but without logic to move the child frame. {⁠, ⁠}
• HybridScrollFrameTemplate - Reuses child widgets by passing them a new ID to display different list entries. {⁠, ⁠}

Defined Methods

ScrollFrame:GetHorizontalScroll()

ScrollFrame:GetHorizontalScrollRange()

ScrollFrame:GetScrollChild() - Returns the frame that scrolls when moving the scroll bar(s)

ScrollFrame:GetVerticalScroll()

ScrollFrame:GetVerticalScrollRange()

ScrollFrame:SetHorizontalScroll(offset)

ScrollFrame:SetScrollChild(frame) - Assigns the frame to scroll when moving the scroll bar(s).

ScrollFrame:SetVerticalScroll(offset)

ScrollFrame:UpdateScrollChildRect() - no longer required after patch 2.3

Defined Script Handlers

OnHorizontalScroll(self, offset) - Run when the horizontal scroll position changes.

OnScrollRangeChanged(self, xrange, yrange) - Run when the scroll position changes.

OnVerticalScroll(self, offset) - Run when the vertical scroll position changes.

Details

• Scroll frames are good for scrolling large portions of text, or a large EditBox.
• Faux and Hybrid scroll frames give the impression of scrolling a long list without the performance cost of making widgets for off-screen list elements.
• Multiple textures, positioned one to another, may start "fidgeting" when the ScrollFrame's ScrollChild containing them is resized/moved/scrolled. And "fidgeting" may mean quite serious distortions, with textures shifting up to 3-4 pixels in an unpredictable direction. Speculation here - apparently this happens because ScrollFrames are (seemingly) created by rendering all their content onto a texture in memory, and treating the ScrollFrame's ScrollChild as a mere Texture, taking its contents from the in-memory texture using SetTexCoord. Now when the 0-1 texture coordinates suffer from precision errors, everything starts to shake. Surprisingly, though, text does NOT suffer much. Bottom line - use ScrollFrames for large images or blocks of text, but not for a large number of multi-textured relatively-positioned controls.^{[citation needed]} 

Example

Creates a ScrollFrame inside the Interface window (see Using the Interface Options Addons panel):

local panel = CreateFrame("Frame")
panel.name = "MyAddOn"
InterfaceOptions_AddCategory(panel)

-- Create the scrolling parent frame and size it to fit inside the texture
local scrollFrame = CreateFrame("ScrollFrame", nil, panel, "UIPanelScrollFrameTemplate")
scrollFrame:SetPoint("TOPLEFT", 3, -4)
scrollFrame:SetPoint("BOTTOMRIGHT", -27, 4)

-- Create the scrolling child frame, set its width to fit, and give it an arbitrary minimum height (such as 1)
local scrollChild = CreateFrame("Frame")
scrollFrame:SetScrollChild(scrollChild)
scrollChild:SetWidth(InterfaceOptionsFramePanelContainer:GetWidth()-18)
scrollChild:SetHeight(1) 

-- Add widgets to the scrolling child frame as desired
local title = scrollChild:CreateFontString("ARTWORK", nil, "GameFontNormalLarge")
title:SetPoint("TOP")
title:SetText("MyAddOn")

local footer = scrollChild:CreateFontString("ARTWORK", nil, "GameFontNormal")
footer:SetPoint("TOP", 0, -5000)
footer:SetText("This is 5000 below the top, so the scrollChild automatically expanded.")