Events & Callbacks

VirtualViewList exposes callbacks through SetCallbacks so you can respond to rendering, scrolling and loading milestones.

Callback Interface

Callback	When it fires	Typical usage
onItemInit(node, index)	Node created for the first time	Attach components, cache references.
onItemUpdate(node, index)	Node re-enters the viewport	Refresh UI with the latest data.
onScrolling(scrollRatio)	During scroll	Update progress bars, sticky headers, infinite-scroll triggers.
onLoadFinished()	Initial load / refresh completed	Hide loading indicators, trigger data requests.
onPullDownRefresh()	Pull-down refresh triggered	Load latest data, refresh list
onPullUpLoad()	Pull-up load triggered	Load more data, append to list

Example:

list.SetCallbacks({
  onItemInit: (node, index) => initNode(node, data[index]),
  onItemUpdate: (node, index) => updateNode(node, data[index]),
  onScrolling: ratio => updateIndicator(ratio),
  onLoadFinished: () => hideLoading(),
  onPullDownRefresh: () => loadNewData(),
  onPullUpLoad: () => loadMoreData()
});

Pull-to-Refresh & Pull-to-Load

Trigger Conditions (all must be met):

• Distance threshold: Pull over 50px (adjustable via mPullThreshold)
• Time interval: More than 1 second since last trigger (adjustable via mPullTriggerInterval)
• State check: Only active after initial load completes

Trigger Scenarios:

• Pull-down refresh: Pull down from the top by more than 50px
• Pull-up load: Pull up from the bottom by more than 50px

Reset Mechanism:

• Auto-resets when pull distance < 10px
• Next pull can trigger again (if time interval is satisfied)

Nested Touch Handling

• enableNestedSupport lets the component cooperate with parent/child scroll views.
• The list records touch start positions and directions to decide when to swallow or forward events.

Scroll Events

• ScrollToIndex, ScrollToTop, ScrollToBottom will internally trigger list updates and callbacks once scrolling ends.
• OnScrolling is throttled to avoid excessive updates while preserving responsiveness.

Loading Flow

• Internal queues (mLoadingQueue, mNeedFrameLoading) batch work across frames for smoother rendering.
• onLoadFinished fires after visible nodes are fully prepared.

Check Performance Tuning for deeper insight into frame splitting and caching behaviour.