ListView

2026-09-20Loading rating…

1. Feature Description

RemoteListView is a vertically scrolling list component, corresponding to ViewType.VERTICAL_LIST_VIEW. It renders list items (ListItemData) in a data-driven way with 3 built-in predefined item types (plain text, icon + title, icon + two-line text). It supports full replacement, single insert/remove/update, divider configuration, a click switch, and a click event. It fits setting entries, file lists, status checklists, etc.

Create it via RemoteViewHelper.createListView(), then mount it with addToRoot():

val listView = helper.createListView()
listView.setWidth(300)
listView.setHeight(400)
listView.addToRoot()

Key Concepts

  • Data model ListItemData: build items via 3 static factory methods:

    • ListItemData.text(itemId, title): plain text
    • ListItemData.iconText(itemId, iconFileName, title): icon + title
    • ListItemData.iconTwoLine(itemId, iconFileName, title, subtitle): icon + two-line text

    Here itemId is the unique item identifier (used to distinguish items in the click callback), and iconFileName is the file name of an icon already uploaded to Pilot.

  • Item count limit: at most RemoteListView.MAX_ITEM_COUNT (100) items; setItems throws IllegalArgumentException if exceeded.

2. Common Properties

The following properties are set via the corresponding setXxx() methods. Unless noted otherwise, if the component is already mounted, call syncToRemote() after changing a property to make it take effect on Pilot.

Size & Layout (inherited from RemoteViewProvider)

MethodParamsDescription
setWidthIntWidth (dp); special values RemoteView.MATCH_PARENT(-1) / WRAP_CONTENT(-2)
setHeightIntHeight (dp); same special values. A bounded height is required for scrolling
setMinSizeminWidth: Int, minHeight: IntMinimum size (dp)
setPaddingleft, top, right, bottom: IntPadding (dp)
setVisibilityVisibilityTypeVisibility: VISIBLE / INVISIBLE / GONE
setAlphaFloatOpacity, 0.0 – 1.0
setEnabledBooleanWhether enabled

Background & Shape (inherited from RemoteViewProvider)

MethodParamsDescription
setBackgroundIntSolid background color (ARGB Int)
setBackgroundShapeShapeDescriptorBackground shape: fill / stroke / corner radius

List Properties

MethodParamsDescription
addToRootparams: WidgetLayoutParam?Mount the list to the root layout (optional layout params)
setItemsList<ListItemData>Set the full list data, up to 100 items; returns OperationResult
insertItemposition: Int, item: ListItemDataInsert one item at a position; returns OperationResult
removeItemposition: IntRemove one item at a position; returns OperationResult
updateItemposition: Int, item: ListItemDataUpdate one item at a position (full replacement); returns OperationResult
setDividerConfigDividerConfigDivider configuration; returns OperationResult
setItemClickEnabledBooleanWhether item click is enabled; returns OperationResult

DividerConfig constructor parameters:

ParamTypeDescription
heightIntDivider height (dp)
colorStringDivider color, "#RRGGBB" or "#AARRGGBB" (e.g. "#33FFFFFF")
paddingLeftIntLeft indent (dp)
paddingRightIntRight indent (dp)
showLastDividerBooleanWhether to show the divider below the last item

Events

MethodDescription
setOnItemClickListenerItem click callback with params (position: Int, itemId: String). The callback runs on the Binder thread pool; switch to the main thread yourself for UI/business updates

3. Tips

  1. At most 100 items. Passing more than MAX_ITEM_COUNT (100) items to setItems throws IllegalArgumentException. For large data, paginate or trim yourself instead of loading everything at once.
  2. The click callback is not on the main thread. The setOnItemClickListener callback runs on the AIDL Binder thread pool. To update your app's own View or do main-thread work, switch back with Handler(Looper.getMainLooper()).post { ... }.
  3. Icons must be uploaded to Pilot first. ListItemData's iconFileName references a file already present on Pilot. Always upload it via helper.pushImageFile(path, callback) and call setItems only after success, otherwise the server cannot find the icon.
  4. updateItem is a full replacement, not a partial update — the new ListItemData fully overwrites the old data at that position, and unset fields fall back to defaults.
  5. Divider color uses a string, unlike component colors. Colors in DividerConfig and ListItemData are "#RRGGBB" / "#AARRGGBB" strings, whereas common properties like setBackground use an ARGB Int. Do not mix them.
  6. A bounded height is required for scrolling. Give setHeight a fixed value (e.g. 400dp) so content scrolls inside the list when it overflows; otherwise the list keeps growing.
  7. Call syncToRemote() after changing a mounted component's properties. Data methods like setItems / insertItem already push to Pilot directly, so no extra syncToRemote() is needed for them.

4. Sample Code

In each group below, the code sample is on the left and the corresponding Pilot-side rendered preview is on the right.

01 Basic List (three item types)

// Create and mount the list
val listView = helper.createListView().apply {
    setWidth(300); setHeight(400)
}
listView.addToRoot()

// Three predefined item types (icon files must be uploaded via pushImageFile first)
listView.setItems(listOf(
    // Plain text
    ListItemData.text("item_1", "Plain text item 1"),
    ListItemData.text("item_2", "Plain text item 2"),
    // Icon + title
    ListItemData.iconText("item_ok", "check.png", "Success"),
    ListItemData.iconText("item_fail", "close.png", "Failure"),
    // Icon + two-line text
    ListItemData.iconTwoLine("item_photo", "photo.png", "Photo B.jpg", "5.1 MB"),
    ListItemData.iconTwoLine("item_video", "video.png", "Video C.mp4", "128 MB")
))

02 Data Operations (insert / remove / update)

// Build the initial list first
val listView = helper.createListView().apply {
    setWidth(300); setHeight(400)
}
listView.addToRoot()
listView.setItems(listOf(
    ListItemData.text("id_a", "List item A"),
    ListItemData.text("id_b", "List item B"),
    ListItemData.text("id_c", "List item C")
))

// Insert: insert one item at position 1
listView.insertItem(1, ListItemData.text("id_new", "Newly inserted"))

// Update: fully replace position 0 (unset fields fall back to defaults)
listView.updateItem(0, ListItemData.iconText("id_a", "star.png", "List item A (updated)"))

// Remove: remove the last item
listView.removeItem(3)

// The return value can be used to check the operation result
val result = listView.removeItem(0)
if (result != OperationResult.SUCCESS) {
    // Handle failure (e.g. position out of range)
}

03 Divider & Click

val listView = helper.createListView().apply {
    setWidth(300); setHeight(400)
}
listView.addToRoot()

// Divider: 1dp high, semi-transparent white, 56dp left indent, no divider after the last item
listView.setDividerConfig(
    DividerConfig(1, "#33FFFFFF", 56, 0, false)
)

listView.setItems(listOf(
    ListItemData.iconText("wifi", "wifi.png", "Wi-Fi"),
    ListItemData.iconText("bt", "bt.png", "Bluetooth"),
    ListItemData.iconText("about", "info.png", "About device")
))

// Enable clicking
listView.setItemClickEnabled(true)

// The click callback runs on the Binder thread; switch to the main thread for UI updates
listView.setOnItemClickListener { position, itemId ->
    Handler(Looper.getMainLooper()).post {
        // Handle the click on the main thread, e.g. navigate by itemId
        // toast("Clicked $itemId @$position")
    }
}

See the official Sample open-pilot-plugin-sample drawing/ListViewDrawer.ktopen in new window for a full runnable example.

Last Updated: