WoW:Making a scrollable list using FauxScrollFrameTemplate

Note: more knowledgable people please feel free to edit this to your heart's content. I don't profess to know all the ins and outs of scrollbars, just enough to get them to work. Those reading this to learn how to make a scrollbar, read this as an example and not gospel. Poking and prodding bits to see how they work is a good way to learn.

---

Before starting out, it helps to visualize that the Scrollbar is nothing more than a verticle slider. We set a min, max, steps to the slider and then react to changes in its offset. The slider doesn't keep tabs of any of our data beyond this. It's up to us to handle the actual movement of data as the user moves the thumb.

You can look at ItemTextFrame.xml/lua, QuestFrame.xml/lua for other examples of how to make ScrollFrames. This will focus on the FauxScrollFrameTemplate route, for a series of rows we define in detail.

FauxScrollFrameTemplate is inherited from UIPanelScrollFrameTemplate, both in UIPanelTemplates.xml. FriendsFrame.xml is a good reference for how to flesh out a FauxScrollFrame with things such as highlights and "gutter" textures. But for simplicity's sake ours will be very basic: An up+down arrow at the ends of the scrollbar and a thumb to move the data.

First, we need data to scroll through:

 MyMod_OnLoad()
   MyModData = {};
   for i=1,50 do
     MyModData[i] = "Test "..math.random(100);
   end
 end

Now we have an array of 50 entries with "Test (some random number up to 100)"

Next, we need a scrollbar on the window:

 <ScrollFrame name="MyModScrollBar" inherits="FauxScrollFrameTemplate">
   <Size>
     <AbsDimension x="30" y="80"/>
   </Size>
   <Anchors>
     <Anchor point="TOPRIGHT"/> 
   </Anchors>
   <Scripts>
     <OnVerticalScroll>
       FauxScrollFrame_OnVerticalScroll(16, MyModScrollBar_Update);
     </OnVerticalScroll>
   </Scripts>
 </ScrollFrame>

The above is a scrollbar of <Size> with <Anchors> and the most important part, a FauxScrollFrame_OnVerticalScroll that points to our function. The 16 is the pixel height of each entry we'll eventually make. We're only doing 5 lines in this example, 16x5 is 80 so that's the height of the scrollbar.

The all-important MyModScrollBar_Update will look something like this in its most essential form:

 function MyModScrollBar_Update()
   FauxScrollFrame_Update(MyModScrollBar,50,5,16);
     -- 50 is max entries, 5 is number of lines, 16 is pixel height of each line
 end

In UIPanelTemplates.lua, the function is documented as:

 -- Function to handle the update of manually calculated
    scrollframes.  Used mostly for listings with an indeterminate
    number of items
 function FauxScrollFrame_Update(frame, numItems, numToDisplay,
    valueStep, button, smallWidth, bigWidth, highlightFrame,
    smallHighlightWidth, bigHighlightWidth )

If the function that's the second parameter of FauxScrollFrame_OnVerticalScroll doesn't contain a FauxScrollFrame_Update, we will get an error. Once we have an update function within <OnVerticalScroll>, and a FauxScrollFrame_Update call within that function, the scrollbar is functional. We can test it by getting the offset and printing it:

 function MyModScrollBar_Update()
   FauxScrollFrame_Update(MyModScrollBar,50,5,16);
   -- 50 is max entries, 5 is number of lines, 16 is pixel height of each line
   DEFAULT_CHAT_FRAME:AddMessage("We're at "..FauxScrollFrame_GetOffset(MyModScrollBar));
 end

Try that and scroll the bar around. You'll see that _GetOffset will return from 0 to 45, which happens to be 50-5.

We now have an indexed array of data and a scrollbar. Now we need to display the data based on the scrollbar's position. First we need to construct the xml elements of the display.

Start simple and make one button template to play around with:

 <Button name = "MyModEntryTemplate" virtual="true">
   <Size>
     <AbsDimension x="150" y="16" />
   </Size>
   <Layers>
     <Layer level="BORDER">
       <FontString name="$parent_Text" inherits="GameFontHighlight" wraponspaces="false"
               justifyH="LEFT" text="MyModEntry"/>
     </Layer>
   </Layers>
 </Button>

This is a virtual button, 150 pixels wide and 16 pixels tall, that contains a FontString named $parent_Text

Now use this template to draw our series of buttons:

 <Button name="MyModEntry1" inherits="MyModEntryTemplate">
   <Anchors>
     <Anchor point="TOPRIGHT" relativeTo="MyModScrollBar" relativePoint="TOPLEFT"/>
   </Anchors>
 </Button>
 <Button name="MyModEntry2" inherits="MyModEntryTemplate">
   <Anchors>
     <Anchor point="TOPLEFT" relativeTo="MyModEntry1" relativePoint="BOTTOMLEFT"/>
   </Anchors>
 </Button>
 <Button name="MyModEntry3" inherits="MyModEntryTemplate">
   <Anchors>
     <Anchor point="TOPLEFT" relativeTo="MyModEntry2" relativePoint="BOTTOMLEFT"/>
   </Anchors>
 </Button>
 <Button name="MyModEntry4" inherits="MyModEntryTemplate">
   <Anchors>
     <Anchor point="TOPLEFT" relativeTo="MyModEntry3" relativePoint="BOTTOMLEFT"/>
   </Anchors>
 </Button>
 <Button name="MyModEntry5" inherits="MyModEntryTemplate">
   <Anchors>
     <Anchor point="TOPLEFT" relativeTo="MyModEntry4" relativePoint="BOTTOMLEFT"/>
   </Anchors>
 </Button>

The above draws the first with top-right aligned to top-left of the scrollbar, then it draws each one below aligned with top-left of next one aligned to bottom-left of previous.

Now we go back to the update function and add the code to display our data depending on the position of the bar:

We have 5 lines on the screen at all times: MyModEntry1, MyModEntry2, etc. Each entry has a text inside named MyModEntry1_Text, MyModEntry2_Text, etc.

 function MyModScrollBar_Update()
   local line; -- 1 through 5 of our window to scroll
   local lineplusoffset; -- an index into our data calculated from the scroll offset
   FauxScrollFrame_Update(MyModScrollBar,50,5,16);
   for line=1,5 do
     lineplusoffset = line + FauxScrollFrame_GetOffset(MyModScrollBar);
     if lineplusoffset < 50 then
       getglobal("MyModEntry"..line.."_Text"):SetText(MyModData[lineplusoffset]);
       getglobal("MyModEntry"..line):Show();
     else
       getglobal("MyModEntry"..line):Hide();
     end
   end
 end

Now we have a scrollbar that scrolls through the data and redisplays it when we move. Now you can customize it to your mod's needs. First step would be to make the values fit your mod, especially the size and shape of the data.

Remember to check out FriendsFrame.xml/.lua to see how to select entries by locking/unlocking its highlight, how to draw a gutter, create multiple columns, etc.