Druid Data List Component

Description

The Data List component provides an efficient way to display and manage large collections of data in a scrollable list. It creates and reuses a limited number of visual items to represent potentially unlimited data, optimizing performance for large datasets.

Features

Efficient display of large data collections
Item recycling for optimal performance
Integration with Grid and Scroll components
Support for different item visual representations
Dynamic data updates
Customizable item creation and binding

Basic Usage

-- Create a data list with a grid
local grid = self.druid:new_grid("grid_node", "item_prefab", 1)
local scroll = self.druid:new_scroll("view_node", "content_node")
scroll:bind_grid(grid)

-- Create a data list with the grid
local data_list = self.druid:new_data_list(grid, function(self, data, index, node)
    -- Bind data to visual item
    local text_node = gui.get_node(node .. "/text")
    gui.set_text(text_node, data.text)
end)

-- Set data to the list
local data = {
    { text = "Item 1" },
    { text = "Item 2" },
    { text = "Item 3" },
    -- ... more items
}
data_list:set_data(data)

Parameters

grid: The grid component to use for item layout
bind_function: Function to bind data to visual items with parameters (self, data, index, node)

Methods

-- Set data to the list
data_list:set_data(data_array)

-- Get current data
local data = data_list:get_data()

-- Update specific data item
data_list:update_item(5, { text = "Updated Item 5" })

-- Add new items to the list
data_list:add(new_data_array)

-- Remove items from the list
data_list:remove(5) -- Remove item at index 5
data_list:remove(5, 3) -- Remove 3 items starting from index 5

-- Clear all data
data_list:clear()

-- Get visual item node by data index
local node = data_list:get_node_by_index(10)

-- Get data index by visual item node
local index = data_list:get_index_by_node(node)

-- Set in-flight items (number of items created beyond visible area)
data_list:set_in_flight(2)

Events

-- Subscribe to data changes
data_list.on_data_changed:subscribe(function(self)
    print("Data list data changed")
end)

-- Subscribe to item creation
data_list.on_create_item:subscribe(function(self, node, index, data)
    print("Created item at index: " .. index)
end)

-- Subscribe to item removal
data_list.on_remove_item:subscribe(function(self, node, index)
    print("Removed item at index: " .. index)
end)

-- Subscribe to item binding
data_list.on_bind_item:subscribe(function(self, node, index, data)
    print("Bound data to item at index: " .. index)
end)

Examples

-- Create a data list with custom item creation
local grid = self.druid:new_grid("grid_node", "item_prefab", 1)
local scroll = self.druid:new_scroll("view_node", "content_node")
scroll:bind_grid(grid)

local data_list = self.druid:new_data_list(grid, function(self, data, index, node)
    -- Bind data to visual item
    local text_node = gui.get_node(node .. "/text")
    local icon_node = gui.get_node(node .. "/icon")
    
    gui.set_text(text_node, data.title)
    gui.set_texture(icon_node, data.icon_texture)
    
    -- Set up item interaction
    local button = self.druid:new_button(node, function()
        print("Clicked on item: " .. data.title)
    end)
end)

-- Set data with different item types
local data = {
    { title = "Item 1", icon_texture = "icon1" },
    { title = "Item 2", icon_texture = "icon2" },
    { title = "Item 3", icon_texture = "icon3" },
}
data_list:set_data(data)

-- Add new items dynamically
function add_new_item()
    data_list:add({ { title = "New Item", icon_texture = "new_icon" } })
end

Notes

The Data List component requires a Grid component for layout and typically a Scroll component for scrolling
It creates only enough visual items to fill the visible area plus a few extra for smooth scrolling
As the user scrolls, the component reuses existing items and rebinds them with new data
This approach is much more efficient than creating one visual item per data entry
The bind function is called whenever an item needs to be updated with data
You can customize the appearance and behavior of each item in the bind function
The component supports dynamic data updates, allowing you to add, remove, or modify items at runtime
For best performance, keep your bind function efficient and avoid expensive operations
The in-flight parameter controls how many extra items are created beyond the visible area

4.5 KiB Raw Blame History