ListView
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 textListItemData.iconText(itemId, iconFileName, title): icon + titleListItemData.iconTwoLine(itemId, iconFileName, title, subtitle): icon + two-line text
Here
itemIdis the unique item identifier (used to distinguish items in the click callback), andiconFileNameis the file name of an icon already uploaded to Pilot.Item count limit: at most
RemoteListView.MAX_ITEM_COUNT(100) items;setItemsthrowsIllegalArgumentExceptionif 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)
| Method | Params | Description |
|---|---|---|
setWidth | Int | Width (dp); special values RemoteView.MATCH_PARENT(-1) / WRAP_CONTENT(-2) |
setHeight | Int | Height (dp); same special values. A bounded height is required for scrolling |
setMinSize | minWidth: Int, minHeight: Int | Minimum size (dp) |
setPadding | left, top, right, bottom: Int | Padding (dp) |
setVisibility | VisibilityType | Visibility: VISIBLE / INVISIBLE / GONE |
setAlpha | Float | Opacity, 0.0 – 1.0 |
setEnabled | Boolean | Whether enabled |
Background & Shape (inherited from RemoteViewProvider)
| Method | Params | Description |
|---|---|---|
setBackground | Int | Solid background color (ARGB Int) |
setBackgroundShape | ShapeDescriptor | Background shape: fill / stroke / corner radius |
List Properties
| Method | Params | Description |
|---|---|---|
addToRoot | params: WidgetLayoutParam? | Mount the list to the root layout (optional layout params) |
setItems | List<ListItemData> | Set the full list data, up to 100 items; returns OperationResult |
insertItem | position: Int, item: ListItemData | Insert one item at a position; returns OperationResult |
removeItem | position: Int | Remove one item at a position; returns OperationResult |
updateItem | position: Int, item: ListItemData | Update one item at a position (full replacement); returns OperationResult |
setDividerConfig | DividerConfig | Divider configuration; returns OperationResult |
setItemClickEnabled | Boolean | Whether item click is enabled; returns OperationResult |
DividerConfig constructor parameters:
| Param | Type | Description |
|---|---|---|
height | Int | Divider height (dp) |
color | String | Divider color, "#RRGGBB" or "#AARRGGBB" (e.g. "#33FFFFFF") |
paddingLeft | Int | Left indent (dp) |
paddingRight | Int | Right indent (dp) |
showLastDivider | Boolean | Whether to show the divider below the last item |
Events
| Method | Description |
|---|---|
setOnItemClickListener | Item 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
- At most 100 items. Passing more than
MAX_ITEM_COUNT(100) items tosetItemsthrowsIllegalArgumentException. For large data, paginate or trim yourself instead of loading everything at once. - The click callback is not on the main thread. The
setOnItemClickListenercallback runs on the AIDL Binder thread pool. To update your app's own View or do main-thread work, switch back withHandler(Looper.getMainLooper()).post { ... }. - Icons must be uploaded to Pilot first.
ListItemData'siconFileNamereferences a file already present on Pilot. Always upload it viahelper.pushImageFile(path, callback)and callsetItemsonly after success, otherwise the server cannot find the icon. updateItemis a full replacement, not a partial update — the newListItemDatafully overwrites the old data at that position, and unset fields fall back to defaults.- Divider color uses a string, unlike component colors. Colors in
DividerConfigandListItemDataare"#RRGGBB"/"#AARRGGBB"strings, whereas common properties likesetBackgrounduse an ARGB Int. Do not mix them. - A bounded height is required for scrolling. Give
setHeighta fixed value (e.g. 400dp) so content scrolls inside the list when it overflows; otherwise the list keeps growing. - Call
syncToRemote()after changing a mounted component's properties. Data methods likesetItems/insertItemalready push to Pilot directly, so no extrasyncToRemote()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-sampledrawing/ListViewDrawer.kt for a full runnable example.