Extension-Druid/api/components/extended/data_list_api.md

druid.data_list API

at /druid/extended/data_list.lua

Druid component to manage a list of data with a scrollable view, used to manage huge list data and render only visible elements.

Setup

Create data list component with druid: data_list = druid:new_data_list(scroll, grid, create_function)

Notes

• Data List uses a scroll component for scrolling and a grid component for layout
• Data List only renders visible elements for better performance
• Data List supports caching of elements for better performance
• Data List supports adding, removing and updating elements
• Data List supports scrolling to specific elements
• Data List supports custom element creation and cleanup

Functions

• init
• set_use_cache
• set_data
• get_data
• add
• remove
• remove_by_data
• clear
• get_index
• get_created_nodes
• get_created_components
• scroll_to_index

Fields

• scroll
• grid
• on_scroll_progress_change
• on_element_add
• on_element_remove
• top_index
• last_index
• scroll_progress

init

---

data_list:init(scroll, grid, create_function)

The DataList constructor

• Parameters:
  • scroll (druid.scroll): The Scroll instance for Data List component
  • grid (druid.grid): The StaticGrid instance for Data List component
  • create_function (function): The create function callback(self, data, index, data_list). Function should return (node, [component])

set_use_cache

---

data_list:set_use_cache(is_use_cache)

Set use cache version of DataList. Requires make setup of components in on_element_add callback and clean in on_element_remove

• Parameters:

  • is_use_cache (boolean): Use cache version of DataList

• Returns:

  • self (druid.data_list): Current DataList instance

set_data

---

data_list:set_data(data)

Set new data set for DataList component

• Parameters:

  • data (table): The new data array

• Returns:

  • self (druid.data_list): Current DataList instance

get_data

---

data_list:get_data()

Return current data from DataList component

• Returns:
  • data (table): The current data array

add

---

data_list:add(data, [index], [shift_policy])

Add element to DataList

• Parameters:

  • data (table): The data to add
  • [index] (number|nil): The index to add the data at
  • [shift_policy] (number|nil): The constant from const.SHIFT.*

• Returns:

  • self (druid.data_list): Current DataList instance

remove

---

data_list:remove([index], [shift_policy])

Remove element from DataList

• Parameters:

  • [index] (number|nil): The index to remove the data at
  • [shift_policy] (number|nil): The constant from const.SHIFT.*

• Returns:

  • self (druid.data_list): Current DataList instance

remove_by_data

---

data_list:remove_by_data(data, [shift_policy])

Remove element from DataList by data value

• Parameters:

  • data (table): The data to remove
  • [shift_policy] (number|nil): The constant from const.SHIFT.*

• Returns:

  • self (druid.data_list): Current DataList instance

clear

---

data_list:clear()

Clear the DataList and refresh visuals

• Returns:
  • self (druid.data_list): Current DataList instance

get_index

---

data_list:get_index(data)

Return index for data value

• Parameters:

  • data (table):

• Returns:

  • `` (unknown|nil):

get_created_nodes

---

data_list:get_created_nodes()

Return all currently created nodes in DataList

• Returns:
  • List (node[]): of created nodes

get_created_components

---

data_list:get_created_components()

Return all currently created components in DataList

• Returns:
  • components (druid.component[]): List of created components

scroll_to_index

---

data_list:scroll_to_index(index)

Instant scroll to element with passed index

• Parameters:
  • index (number): The index to scroll to

Fields

• scroll (druid.scroll): The scroll instance for Data List component

• grid (druid.grid): The StaticGrid or DynamicGrid instance for Data List component

• on_scroll_progress_change (event): fun(self: druid.data_list, progress: number) The event triggered when the scroll progress changes

• on_element_add (event): fun(self: druid.data_list, index: number, node: node, instance: druid.component, data: table) The event triggered when a new element is added

• on_element_remove (event): fun(self: druid.data_list, index: number, node: node, instance: druid.component, data: table) The event triggered when an element is removed

• top_index (number): The top index of the visible elements

• last_index (number): The last index of the visible elements

• scroll_progress (number): The scroll progress