@maccesar/titools 5.3.0 → 5.4.0

package/skills/ti-ui/references/listviews-and-performance.md

@@ -1,749 +1,146 @@
-# ListViews and performance optimization
-
-<!-- TOC-START -->
-## Contents
-
-- [1. Overview](#1-overview)
-- [2. Basic ListView structure](#2-basic-listview-structure)
-- [3. Templates](#3-templates)
-- [4. Data binding](#4-data-binding)
-- [5. Section operations](#5-section-operations)
-- [6. Events](#6-events)
-- [7. Critical performance rules](#7-critical-performance-rules)
-- [8. iOS action items (swipe actions)](#8-ios-action-items-swipe-actions)
-- [9. Editing mode (iOS)](#9-editing-mode-ios)
-- [10. Search](#10-search)
-- [11. Performance best practices](#11-performance-best-practices)
-- [12. Transitioning from TableView](#12-transitioning-from-tableview)
-- [13. Common patterns](#13-common-patterns)
-- [14. Platform differences](#14-platform-differences)
-- [15. Debugging](#15-debugging)
-
-<!-- TOC-END -->
-
-## 1. Overview
-
-ListView is a data-oriented, high-performance replacement for TableView. It handles large datasets by recycling native views and managing the item lifecycle for you.
-
-### Core concepts
-
-| Concept          | Description                                                   |
-| ---------------- | ------------------------------------------------------------- |
-| ListView         | Container for sections                                        |
-| ListSection      | Organizes items, supports CRUD operations                     |
-| ListItem         | Virtual view object (not directly accessible after rendering) |
-| ItemTemplate     | Defines row structure and binding                             |
-| ListDataItem     | Raw data bound to templates                                   |
-
-## 2. Basic ListView structure
-
-### Declarative (Alloy XML)
-
-```xml
-<Alloy>
-  <Window>
-    <ListView id="myList">
-      <ListSection name="section1">
-        <ListItem title="Item 1"/>
-        <ListItem title="Item 2"/>
-        <ListItem title="Item 3"/>
-      </ListSection>
-    </ListView>
-  </Window>
-</Alloy>
-```
-
-### Programmatic data binding
-
-```javascript
-const items = [
-  { properties: { title: "Item 1" } },
-  { properties: { title: "Item 2" } },
-  { properties: { title: "Item 3" } }
-];
-
-$.myList.sections[0].setItems(items);
-```
-
-### Mapping external data
-
-```javascript
-const externalData = [
-  { name: "Item 1", value: 100 },
-  { name: "Item 2", value: 200 }
-];
-
-// Map to ListDataItem format
-const items = _.map(externalData, (item) => {
-  return {
-    properties: {
-      title: item.name
-    },
-    // Custom binding
-    value: { text: item.value.toString() }
-  };
-});
-
-$.myList.sections[0].setItems(items);
-```
-
-## 3. Templates
-
-### Default template
-
-Built-in template with:
-- ImageView (left on iOS, right on Android)
-- Title label (left-aligned, black)
-- Optional accessory icon
-
-```xml
-<ListView id="myList">
-  <ListSection>
-    <ListItem title="Title" image="icon.png" accessoryType="Ti.UI.LIST_ACCESSORY_TYPE_DISCLOSURE"/>
-  </ListSection>
-</ListView>
-```
-
-### Custom templates
-
-Create with `<Templates>` and `<ItemTemplate>`:
-
-```xml
-<ListView id="elementsList" defaultItemTemplate="elementTemplate">
-  <Templates>
-    <ItemTemplate name="elementTemplate">
-      <!-- Bindable elements with bindId -->
-      <Label bindId="symbol" id="symbol" />
-      <View id="atomProperties">
-        <Label bindId="name" id="name" />
-        <View id="secondLine">
-          <Label class="line2" bindId="number" id="number" />
-          <Label class="line2" bindId="mass" id="mass" />
-        </View>
-      </View>
-      <ImageView bindId="image" id="image" />
-    </ItemTemplate>
-  </Templates>
-  <ListSection>
-    <!-- Bind data using bindId:property syntax -->
-    <ListItem symbol:text="H" symbol:color="#090" name:text="Hydrogen" number:text="1" mass:text="1.00794"/>
-  </ListSection>
-</ListView>
-```
-
-### Multiple templates
-
-```xml
-<ListView id="dynamicListView">
-  <Templates>
-    <ItemTemplate name="image_title" height="100">
-      <View layout="horizontal" left="15">
-        <ImageView bindId="image" id="image"/>
-        <Label bindId="label" id="label1"/>
-      </View>
-    </ItemTemplate>
-    <ItemTemplate name="title_only" height="50">
-      <View left="15">
-        <Label bindId="label"/>
-      </View>
-    </ItemTemplate>
-  </Templates>
-  <ListSection/>
-</ListView>
-```
-
-Assign template per item:
-
-```javascript
-const items = [
-  {
-    label: { text: "Full item" },
-    image: { image: "photo.png" },
-    template: "image_title"  // Use this template
-  },
-  {
-    label: { text: "Text only" },
-    template: "title_only"  // Use this template
-  }
-];
-
-$.dynamicListView.sections[0].setItems(items);
-```
-
-### iOS built-in templates (iOS only)
-
-iOS provides four built-in templates you can use without defining custom templates:
-
-| Constant                            | Layout                                                          |
-| ----------------------------------- | --------------------------------------------------------------- |
-| `Ti.UI.LIST_ITEM_TEMPLATE_DEFAULT`  | Left-justified title only (default)                             |
-| `Ti.UI.LIST_ITEM_TEMPLATE_SUBTITLE` | Title with subtitle below in smaller gray text                  |
-| `Ti.UI.LIST_ITEM_TEMPLATE_SETTINGS` | Left-justified title on left, right-justified subtitle on right |
-| `Ti.UI.LIST_ITEM_TEMPLATE_CONTACTS` | Right-justified title with left-justified subtitle              |
-
-```javascript
-const section = Ti.UI.createListSection({
-  items: [
-    { properties: { title: 'Title', subtitle: 'Subtitle' } }
-  ]
-});
-
-const listView = Ti.UI.createListView({
-  sections: [section],
-  defaultItemTemplate: Ti.UI.LIST_ITEM_TEMPLATE_SUBTITLE
-});
-```
-
-### Supported template view classes
-
-The following views can be used as child elements in custom templates: ActivityIndicator, Button, ImageView, Label, MaskedImage, ProgressBar, Slider, Switch, TextArea, TextField.
-
-## 4. Data binding
-
-### Binding syntax
-
-XML (Alloy): `bindId:property="value"` JavaScript: `{ bindId: { property: value } }`
-
-### Programmatic binding with custom templates
-
-```javascript
-const items = [
-  {
-    mass: { text: "1.00794" },
-    name: { text: "Hydrogen" },
-    number: { text: "1" },
-    symbol: { color: "#090", text: "H" }
-  },
-  {
-    mass: { text: "4.002602" },
-    name: { text: "Helium" },
-    number: { text: "2" },
-    symbol: { color: "#090", text: "He" }
-  }
-];
-
-$.elementsList.sections[0].setItems(items);
-```
-
-## 5. Section operations
-
-### CRUD methods
-
-| Method                                | Description        |
-| ------------------------------------- | ------------------ |
-| `setItems(items)`                     | Replace all items  |
-| `appendItems(items)`                  | Add to end         |
-| `insertItemsAt(index, items)`         | Insert at position |
-| `replaceItemsAt(index, count, items)` | Replace range      |
-| `deleteItemsAt(index, count)`         | Delete range       |
-
-### Example operations
-
-```javascript
-const section = $.myList.sections[0];
-
-// Replace all (clears first)
-section.setItems(items);
-
-// Append to end
-section.appendItems(newItems);
-
-// Insert at position 5
-section.insertItemsAt(5, moreItems);
-
-// Replace 3 items starting at index 2
-section.replaceItemsAt(2, 3, replacementItems);
-
-// Delete 2 items starting at index 10
-section.deleteItemsAt(10, 2);
-```
-
-### Row animation (iOS)
-
-You can pass animation styles to append, delete, insert, replace, and update methods:
-
-```javascript
-section.deleteItemsAt(0, 1, {
-  animationStyle: Ti.UI.iOS.RowAnimationStyle.LEFT
-});
-
-section.appendItems(newItems, {
-  animationStyle: Ti.UI.iOS.RowAnimationStyle.FADE
-});
-```
-
-Available styles: `Ti.UI.iOS.RowAnimationStyle.BOTTOM`, `FADE`, `LEFT`, `NONE`, `RIGHT`, `TOP`.
-
-## 6. Events
-
-### Item click
-
-```xml
-<ListView id="list" onItemclick="handleClick">
-```
-
-```javascript
-function handleClick(e) {
-  // e.sectionIndex: which section
-  // e.itemIndex: which item
-  // e.bindId: which template element (null if row clicked)
-  // e.itemId: custom itemId if set
-
-  const section = $.list.sections[e.sectionIndex];
-  const item = section.getItemAt(e.itemIndex);
-
-  // Update item
-  item.properties.title += " (clicked)";
-  item.properties.color = 'red';
-  section.updateItemAt(e.itemIndex, item);
-}
-```
-
-### Marker events (infinite scroll)
-
-Markers act as tripwires for loading more data:
-
-```javascript
-// Set initial marker at item 100
-$.myList.setMarker({ sectionIndex: 0, itemIndex: 99 });
-
-// Handle marker event
-function markerReached(e) {
-  // Load more data
-  const moreData = loadNextPage();
-
-  // Append to list
-  e.section.appendItems(moreData);
-
-  // Set next marker
-  const nextMarker = e.itemIndex + moreData.length - 1;
-  $.myList.setMarker({ sectionIndex: e.sectionIndex, itemIndex: nextMarker });
-}
-
-$.myList.addEventListener('marker', markerReached);
-```
-
-Since SDK 4.1.0, use `addMarker()` to add additional markers after the initial `setMarker()`:
-
-```javascript
-$.myList.addMarker({ sectionIndex: 0, itemIndex: 149 });
-```
-
-### Scroll events
-
-Since SDK 4.1.0, use `scrollstart` and `scrollend` to monitor scrolling:
-
-```javascript
-$.myList.addEventListener('scrollstart', (e) => {
-  Ti.API.info(`Scroll started at section ${e.firstVisibleSectionIndex}, item ${e.firstVisibleItemIndex}`);
-  Ti.API.info(`Visible items: ${e.visibleItemCount}`);
-});
-
-$.myList.addEventListener('scrollend', (e) => {
-  Ti.API.info(`Scroll ended at section ${e.firstVisibleSectionIndex}, item ${e.firstVisibleItemIndex}`);
-});
-```
-
-Event properties: `firstVisibleSectionIndex`, `firstVisibleItemIndex`, `visibleItemCount`.
-
-### Template element events
-
-```xml
-<ListView id="likeList" onItemclick="handleItemClick">
-  <Templates>
-    <ItemTemplate name="custom">
-      <Label bindId="label" left="15" />
-      <ImageView bindId="icon" right="15" />
-    </ItemTemplate>
-  </Templates>
-  <ListSection>
-    <ListItem label:text="Like me?" icon:image="star_grey.png" />
-  </ListSection>
-</ListView>
-```
+# Lists & tables
 
-```javascript
-function handleItemClick(e) {
-  // Check which element was clicked
-  if (e.bindId === "icon") {
-    const item = e.section.getItemAt(e.itemIndex);
-
-    // Toggle image (update data, not e.source)
-    if (item.icon.image === "star_grey.png") {
-      item.icon.image = "star_gold.png";
-    } else {
-      item.icon.image = "star_grey.png";
-    }
+> ListView, TableView, and which of the two to reach for.
 
-    e.section.updateItemAt(e.itemIndex, item);
-  }
-}
-```
+- Source: https://titaniumsdk.com/docs/build/ui/lists
+- Written for Titanium SDK 13.4.0 and later.
+- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
+- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.
 
-## 7. Critical performance rules
+---
 
-### Rule 1: Avoid Ti.UI.SIZE in templates
+Titanium has two scrolling list types. **Reach for `ListView`.**
 
-Bad (jerky scrolling):
+`TableView` represents rows as view proxies. `ListView` describes row layouts
+as templates and supplies item data separately, so it is the recommended
+approach for long lists.
 
-```xml
-<ItemTemplate name="bad">
-  <Label bindId="title" height="Ti.UI.SIZE"/>  <!-- DON'T -->
-</ItemTemplate>
-```
+Neither is deprecated, and `TableView` is still the simpler thing to reach for
+when a "list" is a settings screen of eight fixed rows. Past that, use
+`ListView`.
 
-Good (fixed height or FILL):
+## A list in three parts
 
-```xml
-<ItemTemplate name="good">
-  <Label bindId="title" height="40"/>  <!-- Fixed -->
-</ItemTemplate>
-```
+A `ListView` holds `ListSection`s, and a section holds items. An item is plain
+data, not a view: it says which template to use and what to put in it.
 
-### Rule 2: Cannot access children directly
+```js
+const win = Ti.UI.createWindow({ backgroundColor: 'white' });
 
-Views are recycled. Always update via data.
+const section = Ti.UI.createListSection({ headerTitle: 'Modules' });
+section.setItems([
+  { properties: { title: 'ti.map' } },
+  { properties: { title: 'ti.barcode' } },
+  { properties: { title: 'ti.coremotion' } }
+]);
 
-Bad:
+const list = Ti.UI.createListView({ sections: [section] });
 
-```javascript
-// DON'T - Will be lost when recycled
-function handleClick(e) {
-  e.source.image = "star_gold.png";
-}
-```
-
-Good:
-
-```javascript
-// DO - Update the data item
-function handleClick(e) {
+list.addEventListener('itemclick', (e) => {
   const item = e.section.getItemAt(e.itemIndex);
-  item.icon.image = "star_gold.png";
-  e.section.updateItemAt(e.itemIndex, item);
-}
-```
-
-### Rule 3: Minimize template count
-
-Fewer templates means better native cell reuse.
-
-Good: one template with conditional visibility
-
-```xml
-<ItemTemplate name="flexible">
-  <ImageView bindId="icon"/>
-  <Label bindId="title"/>
-  <Label bindId="subtitle"/>  <!-- Hidden if not needed -->
-</ItemTemplate>
-```
-
-Bad: multiple similar templates
-
-```xml
-<ItemTemplate name="withIcon">...</ItemTemplate>
-<ItemTemplate name="withoutIcon">...</ItemTemplate>
-<ItemTemplate name="withSubtitle">...</ItemTemplate>
-```
-
-### Rule 4: Use updateItemAt for changes
-
-```javascript
-// Get item data
-const item = section.getItemAt(index);
-
-// Modify properties
-item.properties.backgroundColor = 'blue';
-item.customField.text = 'Updated';
-
-// Update in list
-section.updateItemAt(index, item);
-```
-
-### Rule 5: Animations are limited
-
-ListView items have limited animation support. For complex animations, consider TableView.
-
-## 8. iOS action items (swipe actions)
-
-```javascript
-const section = $.myList.sections[0];
-
-// Define edit actions as plain objects with title, style, and optional color
-section.editActions = [
-  {
-    title: 'Delete',
-    style: Ti.UI.iOS.ROW_ACTION_STYLE_DESTRUCTIVE
-  },
-  {
-    title: 'More',
-    color: 'blue',
-    style: Ti.UI.iOS.ROW_ACTION_STYLE_NORMAL
-  }
-];
-section.canEdit = true;
-
-// Handle actions - e.action is the title string of the tapped action
-$.myList.addEventListener('editaction', (e) => {
-  if (e.action === 'Delete') {
-    e.section.deleteItemsAt(e.itemIndex, 1);
-  } else if (e.action === 'More') {
-    // Handle more action
-    Ti.API.info(`More tapped on item ${e.itemIndex} in section ${e.sectionIndex}`);
-  }
+  Ti.API.info(`tapped ${item.properties.title}`);
 });
-```
-
-Available action styles:
-- `Ti.UI.iOS.ROW_ACTION_STYLE_DEFAULT` - gray background
-- `Ti.UI.iOS.ROW_ACTION_STYLE_DESTRUCTIVE` - red background (default)
-- `Ti.UI.iOS.ROW_ACTION_STYLE_NORMAL` - custom color background
-
-Event properties: `action` (string, the title), `itemId`, `itemIndex`, `section`, `sectionIndex`.
-
-## 9. Editing mode (iOS)
-
-Set `editing` to toggle edit mode and let users delete or reorder items:
 
-```javascript
-// Toggle edit mode
-$.myList.editing = true;
-
-// Auto-remove sections that become empty during editing
-$.myList.pruneSectionsOnEdit = true;
+win.add(list);
+win.open();
 ```
 
-### Delete event
-
-Fires when a user deletes an item in edit mode:
-
-```javascript
-$.myList.addEventListener('delete', (e) => {
-  Ti.API.info(`Deleted item ${e.itemIndex} from section ${e.sectionIndex}`);
-});
-```
+`properties` sets properties on the row itself. With no template, `title` is
+the one that shows.
 
-### Move event
+## Templates
 
-Fires when a user reorders an item in edit mode:
+A template names the views in a row and gives each one a `bindId`. Items then
+address those views by that id, so the data and the layout stay separate.
 
-```javascript
-$.myList.addEventListener('move', (e) => {
-  Ti.API.info(`Moved item from ${e.itemIndex} to ${e.targetItemIndex}`);
-});
-```
-
-## 10. Search
-
-```javascript
-const searchView = Ti.UI.createSearchBar({
-  showCancel: true
-});
-
-$.myList.searchView = searchView;
-
-// Mark searchable text in items
-const items = [
-  {
-    properties: {
-      title: "Apple",
-      searchableText: "Apple fruit red delicious"  // Extra keywords
+```js
+const template = {
+  childTemplates: [
+    {
+      type: 'Ti.UI.Label',
+      bindId: 'name',
+      properties: { left: 16, font: { fontSize: 16, fontWeight: 'bold' } }
+    },
+    {
+      type: 'Ti.UI.Label',
+      bindId: 'detail',
+      properties: { right: 16, color: '#888', font: { fontSize: 14 } }
     }
-  }
-];
-```
-
-### Search properties
-
-- `keepSectionsInSearch: true` preserves section headers while filtering results.
-- `caseInsensitiveSearch: true` enables case-insensitive filtering.
-
-```javascript
-const listView = Ti.UI.createListView({
-  searchView: searchView,
-  keepSectionsInSearch: true,
-  caseInsensitiveSearch: true
-});
-```
-
-### No results event
-
-Since SDK 3.3.0, when items are filtered using `searchView` or `searchText`, the `noresults` event fires when there are no matches:
+  ]
+};
 
-```javascript
-$.myList.addEventListener('noresults', (e) => {
-  Ti.API.info('No matching items found');
+const list = Ti.UI.createListView({
+  templates: { row: template },
+  defaultItemTemplate: 'row',
+  sections: [section]
 });
-```
-
-## 11. Performance best practices
-
-Do:
-- Use fixed heights in templates.
-- Minimize number of templates.
-- Use `updateItemAt()` for changes.
-- Cache `sections[0]` reference.
-- Use markers for infinite scroll.
-- Test with real device data volumes.
-
-Don't:
-- Use `Ti.UI.SIZE` for row dimensions.
-- Access `e.source` in itemclick events.
-- Create too many similar templates.
-- Add complex animations to list items.
-- Ignore the recycled nature of views.
-
-## 12. Transitioning from TableView
-
-### Core logic differences
-
-| TableView            | ListView                     |
-| -------------------- | ---------------------------- |
-| TableViewRow         | ListItem (Virtual)           |
-| `add()` views to row | `childTemplates` in Template |
-| `data` property      | `sections` property          |
-| Direct child access  | Bound data updates only      |
-| `appendRow()`        | `appendItems()`              |
-| `updateRow()`        | `updateItemAt()`             |
-| `deleteRow()`        | `deleteItemsAt()`            |
-
-### API differences
-
-Properties not available for ListItem:
-- `accessibilityLabel`, `className`, `editable`, `hasCheck`, `hasChild`, `hasDetail`, `leftImage`, `moveable`, `rightImage`.
-- Alternatives: use `accessoryType` for indicators, and `image` or custom templates for images.
-
-TableViewSection methods not supported by ListSection:
-- `add`, `remove`, `rowAtIndex`.
-- Alternatives: use `getItemAt` and `appendItems` or `deleteItemsAt`.
-
-TableView methods not available to ListView:
-- `appendRow`, `deleteRow`, `deselectRow`, `insertRowAfter`, `insertRowBefore`, `selectRow`, `updateRow`, `scrollToIndex`.
-- Alternatives: use `scrollToItem` and `selectItem` (iOS). For row manipulation, use the containing ListSection.
-
-## 13. Common patterns
-
-### Infinite scroll with markers
-
-```javascript
-const PAGE_SIZE = 25;
-let currentPage = 0;
 
-function loadPage(page) {
-  const data = fetchDataFromAPI(page);
-
-  if (page === 0) {
-    $.myList.sections[0].setItems(data);
-  } else {
-    $.myList.sections[0].appendItems(data);
-  }
-
-  // Set marker for next page
-  const markerIndex = (page * PAGE_SIZE) + data.length - 1;
-  $.myList.setMarker({ sectionIndex: 0, itemIndex: markerIndex });
-}
-
-// Initial load
-loadPage(0);
-
-// Marker handler
-$.myList.addEventListener('marker', (e) => {
-  currentPage++;
-  loadPage(currentPage);
-});
+section.setItems([
+  { name: { text: 'ti.map' }, detail: { text: '5.7.0' } },
+  { name: { text: 'ti.barcode' }, detail: { text: '4.2.0' } }
+]);
 ```
 
-### Multiple selection
+Each key in an item that is not `properties` or `template` is a `bindId`, and
+its value is the properties to set on that view.
 
-```javascript
-const selectedItems = {};
+> [!IMPORTANT]
+> Row views are recycled. Every property a template sets on a row must be set
+> by **every** item that uses it, or a row will inherit whatever the last item
+> in that slot left behind. Set `color` on one item and not the next and the
+> colour follows the recycled view down the list.
 
-$.myList.addEventListener('itemclick', (e) => {
-  const item = e.section.getItemAt(e.itemIndex);
-  const key = `${e.sectionIndex}-${e.itemIndex}`;
-
-  if (selectedItems[key]) {
-    // Deselect
-    delete selectedItems[key];
-    item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_NONE;
-  } else {
-    // Select
-    selectedItems[key] = item;
-    item.properties.accessoryType = Ti.UI.LIST_ACCESSORY_TYPE_CHECKMARK;
-  }
-
-  e.section.updateItemAt(e.itemIndex, item);
-});
-```
+## Changing the contents
 
-### Section index (A-Z)
+Replace everything with `setItems`. Add to the end with `appendItems`. Change
+one row in place with `updateItemAt`, which is what to use for a checkbox or a
+"favourited" state, because it does not rebuild the section.
 
-```javascript
-$.myList.sectionIndexTitles = ["A", "B", "C", ...];
+```js
+section.updateItemAt(0, { name: { text: 'ti.map' }, detail: { text: '5.8.0' } });
 ```
 
-## 14. Platform differences
-
-### iOS vs Android
+Sections are managed on the list: `appendSection`, `insertSectionAt`,
+`replaceSectionAt`, `deleteSectionAt`.
 
-| Feature                | iOS          | Android       |
-| ---------------------- | ------------ | ------------- |
-| Action items (swipe)   | Full support | Not supported |
-| Section index titles   | Full support | Not supported |
-| Search bar             | Full support | Full support  |
-| Default template image | Left side    | Right side    |
-| cacheSize property     | Supported    | Not supported |
+## Which events fire
 
-### Grouped style (iOS)
+`itemclick` is the one you want, and it gives you `sectionIndex`, `itemIndex`,
+`section` and `bindId` - the last being which view inside the row was tapped,
+which is how one row can have a tappable button and a tappable body.
 
-Set `style: Ti.UI.iOS.ListViewStyle.GROUPED` to display sections as separate visual groups with rounded corners and inset spacing:
+`scrollstart`, `scrolling`, `scrollend`, `dragstart` and `dragend` cover
+scrolling. `marker` fires when a row you nominated with `setMarker` comes into
+view, which is the hook for loading the next page of results.
 
-```javascript
-const listView = Ti.UI.createListView({
-  style: Ti.UI.iOS.ListViewStyle.GROUPED,
-  sections: [sectionA, sectionB]
-});
-```
+## TableView
 
-### Pull-to-refresh (iOS)
+`TableView` builds rows as real views, so a row is a view you can hold onto and
+change directly:
 
-The `pull` event fires when the user pulls past the top of the list, and `pullend` fires when they release. Use `pullView` to set a custom view:
-
-```javascript
-const pullView = Ti.UI.createView({
-  height: 60,
-  backgroundColor: '#eee'
-});
-pullView.add(Ti.UI.createLabel({ text: 'Pull to refresh...' }));
-
-$.myList.pullView = pullView;
-
-$.myList.addEventListener('pull', (e) => {
-  // User is pulling - update UI as needed
-  pullView.children[0].text = e.active ? 'Release to refresh...' : 'Pull to refresh...';
-});
-
-$.myList.addEventListener('pullend', (e) => {
-  // User released - trigger data refresh
-  refreshData();
+```js
+const table = Ti.UI.createTableView({
+  data: [
+    { title: 'General' },
+    { title: 'Notifications' },
+    { title: 'Privacy' }
+  ]
 });
-```
 
-### cacheSize (iOS)
-
-```javascript
-// Number of views to pre-render offscreen
-$.myList.cacheSize = 3;  // Default
+table.addEventListener('click', (e) => Ti.API.info(`row ${e.index}`));
 ```
 
-## 15. Debugging
-
-### Common issues
+That directness is useful for a short fixed list. Prefer template-based
+`ListView` for long lists. Avoid treating the TableView model as a guarantee
+that native rows are never reused: the released
+[TableViewRow API](https://titaniumsdk.com/docs/sdk/13.4.1/Titanium.UI.TableViewRow)
+documents structural row classes for Android rendering performance.
 
-Problem: Jerky scrolling Solution: Remove `Ti.UI.SIZE` from templates
+The event is `click`, not `itemclick`.
 
-Problem: Data changes not visible Solution: Use `updateItemAt()` instead of modifying views
+![Two boxed screenshots labelled iOS and Android, side by side, each showing the same five-item list. On iOS the section header Modules is grey text on the window background above the first row. On Android it is white text on a filled grey bar spanning the width of the list.](https://titaniumsdk.com/docs/guides/list-view.png)
 
-Problem: Event not firing on template element Solution: Check `bindId` in event handler
+## Next
 
-Problem: Wrong item updated Solution: Use `e.section.getItemAt(e.itemIndex)` not a global reference
+[Icons and launch screens](icons-and-splash-screens.md) is what the
+app looks like before it opens.