ListView (리스트뷰) Widget Control

A list of the Widget Control members (Property · Method · Event) you use to control the ListView widget from a script. To learn about the widget itself and how to use it, visit ListView.

info

listviewID in the examples below is the name (ID) you assigned to the ListView widget on the canvas. In scripts, access members as widgetID.member.

Widget Control summary

Widget Control	Kind	Signature	Description
count	Property	count (read/write)	Read or set the number of repeated items
current	Property	current (read/write)	Index of the current item to use as the binding scope
select	Property	select (read/write)	Index of the selected item
overflowCount	Property	overflowCount (read-only)	Number of items clipped and hidden in clip mode
add	Method	add(): int	Append an empty item and return its new index
insert	Method	insert(index)	Insert an empty item at the given position
remove	Method	remove(index)	Remove the item at the given index
clear	Method	clear()	Remove every item
setState	Method	setState(index, function)	Update only the binding properties of a single item
setOnceAnimation	Method	setOnceAnimation()	Replay the staggered entrance animation once
scrollToIndex	Method	scrollToIndex(index, duration)	Scroll so the given item sits at the top
getFirstVisibleIndex	Method	getFirstVisibleIndex(): int	Return the index of the first visible item
onSelected	Event	onSelected = (index) => { ... }	Runs when the user taps an item
onScrollEnd	Event	onScrollEnd = () => { ... }	Runs when scrolling reaches the end of the list
onOverflowChanged	Event	onOverflowChanged = (count) => { ... }	Runs when the number of clipped items changes

Property

count

The number of items to render repeatedly. Set it to grow or shrink the bound data list to that count and redraw it. Read it to get the current item count.

• Kind: Property (read/write)
• Type: integer (int)

Example

listviewID.count = 10;
const n = listviewID.count;

current

The index of the current item to use as the binding scope. Once set, later property writes target that item's row. Reading it returns the current index, or -1 when none is set.

• Kind: Property (read/write)
• Type: integer (int)

Example

listviewID.current = 2;
const cur = listviewID.current;

select

The index of the selected item. Set it to mark that index as selected. Reading it returns the selected index, or -1 when nothing is selected.

• Kind: Property (read/write)
• Type: integer (int)

Example

listviewID.select = 0;
const sel = listviewID.select;

overflowCount

The number of items clipped and hidden to fit the area when overflowMode is clip. Read-only.

• Kind: Property (read-only)
• Type: integer (int)

Example

const hidden = listviewID.overflowCount;

Method

add

Appends an empty item to the end of the list and redraws it.

• Parameters: None
• Returns: integer (int) - the index of the newly added item

Example

const i = listviewID.add();

insert

Inserts an empty item at the given position and redraws the list.

• Parameters: index integer (int) - the position to insert at
• Returns: None

Example

listviewID.insert(0);

remove

Removes the item at the given index and redraws the list. Does nothing when the index is out of range.

• Parameters: index integer (int) - the index of the item to remove
• Returns: None

Example

listviewID.remove(0);

clear

Removes every item from the list and redraws it.

• Parameters: None
• Returns: None

Example

listviewID.clear();

setState

Runs a callback with the binding scope set to the item at the given index, then redraws only that item. Use it to update the binding properties of a single item.

• Parameters: index integer (int) - the index of the item to update · function callback function - runs while index is the active item
• Returns: None

Example

listviewID.setState(0, () => {
  // Update the binding properties of item 0
});

setOnceAnimation

Replays the staggered item entrance animation once on the next build. Handy for showing the entrance effect again after a data refresh.

• Parameters: None
• Returns: None

Example

listviewID.setOnceAnimation();

scrollToIndex

Scrolls so the item at the given index sits at the top. It works only when itemExtent (a fixed item size) is set — without it, nothing happens — and the target position is clamped to the maximum scroll extent.

• Parameters: index integer (int) - the index of the item to scroll into view · duration integer (int) or null - the animation time in milliseconds; with null or a value of 0 or less, it jumps immediately with no animation
• Returns: None

Example

listviewID.scrollToIndex(10, 300);

getFirstVisibleIndex

Returns the index of the item that is currently first visible. It computes this only when itemExtent is set; otherwise it returns 0.

• Parameters: None
• Returns: integer (int) - the index of the first visible item

Example

const index = listviewID.getFirstVisibleIndex();

Event

onSelected

Runs when the user taps an item in the list.

• Kind: Event
• Handler: index integer (int) - a callback function that receives the index of the tapped item
• Returns: None

Example

listviewID.onSelected = (index) => {
  // Handle the selected item
};

onScrollEnd

Runs once when scrolling reaches the end (bottom) of the list. It rearms as soon as you scroll away from the end.

• Kind: Event
• Handler: a callback function with no arguments
• Returns: None

Example

listviewID.onScrollEnd = () => {
  // Load the next page, and so on
};

onOverflowChanged

Runs only when the number of clipped items changes in clip overflow mode.

• Kind: Event
• Handler: count integer (int) - a callback function that receives the new number of clipped items
• Returns: None

Example

listviewID.onOverflowChanged = (count) => {
  // Handle the change in clipped item count
};

Common Widget Control (all widgets)

note

Every widget supports name-based common Widget Control methods such as setProperty, getProperty, and setStyleProperty. See the common reference doc (to be written).