ListPanel
File: Rhapsodist/Widgets/ListPanel.js · Namespace: ListPanel.
Overview
Creates a scrollable, interactive list.
Built with a ScriptedViewport plus an inner panel sized to fit all items, with hover/selection highlighting, per-row icons, multi-select, keyboard navigation, and automatic scroll to keep the selection visible.
Selection and keyboard behaviour
With allowMultiSelect on: shift-click for range select, ctrl/cmd-click to toggle one row, and clicking the sole selected row again to deselect it (only if allowNoSelect is also set).
Keyboard: ctrl+A/cmd+A selects all, escape deselects, page up/page down jump to the first/last item, and the cursor keys move one item at a time (wrapping at either end). Might not work in all hosts.
The viewport’s component ID is derived from the parent panel’s ID (its "pnl" prefix becomes "vpt"), useful to know if you need to reference it directly, though create() already exposes it on data.viewport.
Usage
const pnlMyList = ListPanel.create("pnlMyListContainer", ["Item A", "Item B", "Item C"], { rowHeight: 30, allowMultiSelect: true });
Options
| Option | Description | Default |
|---|---|---|
saveInPreset | Whether the list’s selection is saved in the preset. | false |
rowHeight | Height of each row. | 35 |
margin | Space around the inner panel inside the viewport. | 5 |
icons | Per-row Phosphor icon codepoints. | [] |
allowMultiSelect | Enables shift/ctrl-click range and toggle selection. | false |
allowNoSelect | Allows deselecting the sole selected row when multi-select is on. | false |
border | Padding around the viewport. | 0 |
scrollBarThickness | Width of the viewport’s scrollbar. | 10 |
useCustomPaintRoutine | Skips the built-in paint routine, so a caller can supply its own while keeping selection/scrolling/keyboard behaviour. This is how ArticulationList uses it. | false |
Look and Feel
Override the paint routine:
pnlMyList.setPaintRoutine(function(g) {
var items = this.data.items;
// Custom rendering
});
Public API
create() returns the parent panel; the helpers below take that panel as their first argument.
| Function | Description | Returns |
|---|---|---|
create(parentPanelId: string, items: Array, options: JSON) | Returns the parent panel, with viewport and listPanel set on its data object for attaching further callbacks. Prints an error if parentPanelId doesn’t exist. | object |
setItems(panel: ScriptObject, items: Array) | Replaces the item list and resizes. | — |
resize(panel: ScriptObject) | Recomputes height from the current item count. | — |
setIcons(panel: ScriptObject, icons: Array) | Replaces the row icons array. | — |
setAllowMultiSelect(panel: ScriptObject, value: number) | Toggles allowMultiSelect. | — |
selectAll(panel: ScriptObject) / deselectAll(panel: ScriptObject) | No-ops unless allowMultiSelect is on; deselectAll leaves the current value selected unless allowNoSelect is also set. | — |
updateViewportPosition(panel: ScriptObject) | Scrolls so the selected row is visible. | — |
Internal Reference
| Function | Description | Returns |
|---|---|---|
createViewport(parent: ScriptObject, options: JSON) | Creates or reuses the underlying ScriptedViewport (ID derived from the parent panel’s ID) and applies its size/scrollbar properties. | ScriptObject |
paintRoutine() | Default paint routine: draws each row’s background, selection highlight, icon, and label. Applied automatically unless useCustomPaintRoutine is set. | — |
mouseCallback() | Handles hover/click hit-testing and single/multi-select selection logic. | — |
keyPressCallback() | Handles ctrl+A/cmd+A, escape, page up/page down, and cursor-key navigation. | — |