LibScroll : Libraries : Elder Scrolls Online AddOns

(2 Kb)

Download

Updated: 02/17/21 02:26 AM

Add Favorite

Install Help

Portal

Bugs

Features

Compatibility:	Flames of Ambition (6.3.5) Markarth (6.2.5)
Updated:	02/17/21 02:26 AM
Created:	07/19/15 06:24 PM
Monthly downloads:	1,411
Total downloads:	133,086
Favorites:	18
MD5:

LibScroll

Version: 2

by: circonian, Baertram

What does it do?
It handles the basic code for creating a scrollList & updating the scrollList data for you.

Why did I write it?
I have no idea

I found it laying around in a folder...I think I worked on to many addons with scrollLists & got sick of copy/pasting/editing code & figured a simple lib to just drop in the addons would be easier. But, over time I've seen many questions about scrollLists & although this lib does not do a lot of work for you, I thought it might be useful to those who don't know the necessary code to create a scrollList. The lib can drastically cut down on what you need to know to create a working scrollList...and if you need to you can copy the setupCallback, OnRowSelect, SortScrollList, & SetupDataRow functions from my examples below & then you really don't need to know anything.

How do I create a scrollList with it?
I will give two complete addon examples at the end of this post, first lets look at the individual pieces of code you need.

Load the Library

At the top of your code file load the library:
Lua Code:
local libScroll = LibScroll

Create the ScrollList

You will need to create a table containing the necessary information for initializing your scrollList. Below is an example containing all possible information you may include. Only the name, parent, & setupCallback are necessary, the rest are optional.

ScrollData table example:
Warning: Spoiler
Lua Code:
local scrollData = {
    name    = "MyTestScrollList",
    parent  = EmoteItWin,
    width   = 300,
    height  = 500,
    
    rowHeight       = 23,
    rowTemplate     = "EmoteItRowControlTemplate",
    setupCallback   = setupDataRow,
    sortFunction    = SortScrollList,
    selectTemplate  = "EmoteItSelectTemplate",
    selectCallback  = OnRowSelection,
    
    dataTypeSelectSound = SOUNDS.BOOK_CLOSE,
    hideCallback    = OnRowHide,
    resetCallback   = OnRowReset,
    
    categories  = {1, 2},
}
Explanation of table items:

Warning: Spoiler

Required Values:
name -- A unique name for your scrollList control
parent -- The parent control for your scrollList (not GuiRoot)
setupCallback -- The function that will be called when each row control becomes visible.

Optional Values:
(optional) categories -- A table containing the integer values for your categories. Categories allow you to add items to the list with different categories & then you can show or hide groups of items based on their category ID without needing to clear & reload the scrollList with new data.
(optional) dataTypeSelectSound -- An optional sound to play when a row is selected.
(optional) height -- The height of your scrollList. If not supplied the default is 400.
(optional) hideCallback -- The function that will be called when the row control gets hidden.
(optional) resetControlCallback -- The function that will be called when the row control gets reset.
(optional) rowHeight -- The height for the rows in your scrollList. If not supplied the default is 30
(optional) rowTemplate -- The name of the virtual control template that will be used to hold this data. If not supplied the default is ZO_SelectableLabel
(optional) selectCallback -- The function that will be called when a data item is selected. NOTE: This does not fire when clicking on the item in the scrollList without you providing additional code (see complete example below with selectionCallback).
(optional) selectTemplate -- The template for the selected item (highlight). There is no default. This is to allow users to leave this value out if they want a selection callback without highlights. If you want highlights & don't know what to use, use "ZO_ThinListHighlight"
(optional) sortFunction -- The function that will be called to sort your scrollList. There is no default, if left out the list will be unsorted.
(optional) width -- The width of your scrollList. If not supplied the default is 250.

Then just call:
Lua Code:
local scrollList = libScroll:CreateScrollList(scrollData)

Update the scrollList with your data

Create your table of dataItems to be loaded into the scrollList. Then just call Update and pass in your table:
Lua Code:
scrollList:Update(dataItems)
dataItems table example:
The table for each individual data item can contain any data you want, this is only an example.
categoryId is optional, it is used to group items together in categories so you can show/hide groups of items by showing/hiding their categoryId.
Warning: Spoiler
Lua Code:
local dataItems = {
    [1] = {name = "first"},
    [2] = {name = "second", categoryId = 2},
    [3] = {name = "third", categoryId = 2},
    [4] = {name = "fourth", categoryId = 2},
    [5] = {name = "fifth", categoryId = 3},
    [6] = {name = "sixth", categoryId = 3},
    [7] = {name = "seventh", categoryId = 7},
    [8] = {name = "eigth", categoryId = 8},
    [9] = {name = "nineth", categoryId = 9},
}

That is all there is to it.

Available Functions:

scrollList:Clear() -- Clears all data from the scrollList
scrollList:Update (table dataItems) -- Pass in a table containing all of your data items for the scrollList to update the list with new data.

** Do note for the show/hide category functions to work the category values must be assigned to the scrollList by including them in the scrollData table that you pass to libScroll:CreateScrollList(scrollData) **
** Also these will only effect data items that have a categoryId assigned to them. As an example if you did not assign a categoryId to a data item & call HideAllCategories it will not be hidden **
scrollList:ShowAllCategories() -- Shows all data items that have a categoryId that matches one of the categories assigned to the scrollList. Data items that do not have a categoryId that matches one of the scrollList categories will not be effected.
scrollList:ShowOnlyCategory(integer categoryId) -- Shows only data items that have the given categoryId, all other data items are hidden (if they have a categoryId, items without a categoryId will not be effected).
scrollList:ShowCategory(integer categoryId) -- Shows data items that have the given categoryId.
scrollList:HideAllCategories() -- Hides all data items that have a categoryId that matches one of the categories assigned to the scrollList. Data items that do not have a categoryId that matches one of the scrollList categories will not be effected.
scrollList:HideCategory(integer categoryId) -- Hides data items that have the given categoryId.

A Complete (simple) example for creating a scrollList (no highlights, no select callbacks, & no sorting):

Warning: Spoiler

Lua Code:

local ADDON_NAME    = "TestAddon"
 
local libScroll = LibScroll
 
-- This function creates a top level window to hold our scrollList
local function CreateMainWindow()
    -- Create a top level window:
    local tlw = WINDOW_MANAGER:CreateTopLevelWindow("TestScrollList")
    tlw:SetAnchor(CENTER, GuiRoot, CENTER)
    tlw:SetDimensions(300, 250)
    
    -- create a background for it (optional)
    tlw.bg = WINDOW_MANAGER:CreateControlFromVirtual("TestScrollListBg", tlw, "ZO_DefaultBackdrop")
    tlw.bg:SetAnchorFill()
    
    return tlw
end
 
-- Create the row setup callback function
local function SetupDataRow(rowControl, data, scrollList)
    -- Do whatever you want/need to setup the control
    rowControl:SetText(data.name)
    rowControl:SetFont("ZoFontWinH4")
end
 
-- Function that creates the scrollList 
local function CreateScrollList()
    local mainWindow = CreateMainWindow()
    
    -- Create the scrollData table for your scrollList
    local scrollData = {
        name = "EmoteScrollListTest",
        parent = mainWindow,
        
        width = 200,
        height = 150,
        rowHeight = 23,
        
        setupCallback = SetupDataRow,
    }
    
    -- Call the libraries CreateScrollList
    local scrollList = libScroll:CreateScrollList(scrollData)
    -- Anchor it however you want
    scrollList:SetAnchor(TOPLEFT, mainWindow, TOPLEFT, 50, 50)
    
    -- create the tables for your scrollLists data items
    local dataItems = {
        [1] = {name = "first"},
        [2] = {name = "second"},
        [3] = {name = "third"},
        [4] = {name = "fourth"},
        [5] = {name = "fifth"},
        [6] = {name = "sixth"},
        [7] = {name = "seventh"},
        [8] = {name = "eigth"},
        [9] = {name = "nineth"},
    }
      -- Call Update to add the data items to the scrollList
    scrollList:Update(dataItems)
end
 
-------------------------------------------------------------------
--  OnAddOnLoaded  --
-------------------------------------------------------------------
local function OnAddOnLoaded(event, addonName)
    if addonName ~= ADDON_NAME then return end
    
    -- Create the scrollList
    local scrollList = CreateScrollList()
    
    EVENT_MANAGER:UnregisterForEvent(ADDON_NAME, EVENT_ADD_ON_LOADED)
end
 
---------------------------------------------------------------------
--  Register Events --
---------------------------------------------------------------------
EVENT_MANAGER:RegisterForEvent(ADDON_NAME, EVENT_ADD_ON_LOADED, OnAddOnLoaded)

A Complete example with selection callbacks, row highlights, & a sorting function:

Warning: Spoiler

Lua Code:

local ADDON_NAME    = "TestAddon"
 
local libScroll = LibScroll
 
-- This function gathers information about emotes to 
-- be placed in our scrollList. You can get your data
-- from wherever
local function GetScrollData()
    local dataItems = {}
    
    for emoteIndex=1, GetNumEmotes() do
        local emoteSlashName, emoteCategory, emoteId = GetEmoteInfo(emoteIndex)
    
        -- Organize your data for each item inside of a table
        local data =   {
            emoteName = string.sub(emoteSlashName,2),
            emoteId = emoteId,
            emoteIndex = emoteIndex,
            categoryId = emoteCategory,
        }
 
        -- and use table.insert to put them into the dataItems table
        table.insert(dataItems, data)
    end
    return dataItems
end
 
-- This function creates a top level window to hold our scrollList
local function CreateMainWindow()
    -- Create a top level window:
    local tlw = WINDOW_MANAGER:CreateTopLevelWindow("TestScrollList")
    tlw:SetAnchor(CENTER, GuiRoot, CENTER)
    tlw:SetDimensions(300, 400)
    
    -- create a background for it (optional)
    tlw.bg = WINDOW_MANAGER:CreateControlFromVirtual("TestScrollListBg", tlw, "ZO_DefaultBackdrop")
    tlw.bg:SetAnchorFill()
    
    return tlw
end
 
-- Create the row selection function (if needed)
local function OnRowSelect(previouslySelectedData, selectedData, reselectingDuringRebuild)
    if not selectedData then return end
    d("Now playing emote: "..selectedData.emoteName)
    
    PlayEmoteByIndex(selectedData.emoteIndex)
end
 
-- Create the sort function (if needed)
local function SortScrollList(objA, objB)
    return objA.data.emoteName < objB.data.emoteName
end
    
-- Create the row setup callback function
local function SetupDataRow(rowControl, data, scrollList)
    -- Do whatever you want/need to setup the control
    rowControl:SetText(data.emoteName)
    rowControl:SetFont("ZoFontWinH4")
    
    rowControl:SetHandler("OnMouseUp", function()
        ZO_ScrollList_MouseClick(scrollList, rowControl)
    end)
end
 
-- Function that creates the scrollList 
local function CreateScrollList()
    -- Creates the top level window to hold our scrollList
    local mainWindow = CreateMainWindow()
    
    -- Create the scrollData table for your scrollList
    local scrollData = {
        name = "EmoteScrollListTest",
        parent = mainWindow,
        
        width = 200,
        height = 300,
        rowHeight = 23,
        
        setupCallback = SetupDataRow,
        selectCallback  = OnRowSelect,
        dataTypeSelectSound = SOUNDS.BOOK_CLOSE,
        sortFunction    = SortScrollList,
    }
    
    -- Call the libraries CreateScrollList
    local scrollList = libScroll:CreateScrollList(scrollData)
    -- Anchor it however you want
    scrollList:SetAnchor(TOPLEFT, mainWindow, TOPLEFT, 50, 50)
    
    return scrollList
end
 
local function InitializeScrollList()
    -- Create the scrollList
    local scrollList = CreateScrollList()
    
    -- Get your data from wherever & update the scrollList
    local scrollData = GetScrollData()
    scrollList:Update(scrollData)
end
 
 
-------------------------------------------------------------------
--  OnAddOnLoaded  --
-------------------------------------------------------------------
local function OnAddOnLoaded(event, addonName)
    if addonName ~= ADDON_NAME then return end
    
    InitializeScrollList()
    
    EVENT_MANAGER:UnregisterForEvent(ADDON_NAME, EVENT_ADD_ON_LOADED)
end
 
---------------------------------------------------------------------
--  Register Events --
---------------------------------------------------------------------
EVENT_MANAGER:RegisterForEvent(ADDON_NAME, EVENT_ADD_ON_LOADED, OnAddOnLoaded)

Version 2 (2021-02-17)
-Added own manifest txt with ## IsLibrary: true and ## AddOnVersion: 2
-Removed LibStub
-Added global variable LibScroll

Archived Files (1)

File Name	Version	Size	Uploader	Date
LibScroll	1	2kB	circonian	07/19/15 06:29 PM

Comment Options

02/17/21, 04:31 AM

Baertram

Super Moderator

Forum posts: 5183

File comments: 6253

Uploads: 78

Re: Thank you!

Yw, I'm not using it, as you can see how it works from the ZOs code (well, you need to test and see in detail what is called when but adding some debug messages helped to understand it for me

). All examples and work done here credit to Circonian!
But an older addon still used it so I thought having a non LibStub + txt version would be good.

Originally Posted by Calamath

Thank you for updating.
I just needed to understand how UI controls work, so these samples are very helpful.　

Last edited by Baertram : 02/17/21 at 04:44 AM.

02/17/21, 04:10 AM
Calamath Forum posts: 42 File comments: 251 Uploads: 7	Thank you! Thank you for updating. I just needed to understand how UI controls work, so these samples are very helpful.

07/20/15, 08:02 AM
kerb9729 Forum posts: 57 File comments: 121 Uploads: 2	Sweet LOL I guess you got tired of answering my questions about scrolllists =P This will help someone greatly I am sure!

Report this File