Browsers¶
Browser Engine
Import¶
import "_IVLS/std-library/nodes/components/browsers.ksp"Node: Stl.Browsers.Template¶
Uses: Init, Reload, FirstLoad
Overview¶
Browser Engine
Filterable, tag-driven browser component for building sound and preset selection UIs.
Manages a sorted item list, a bitmask-based tag filter, a scrollbar, and a focused
item index. Exposes override hooks for rendering entries, playing previews, loading
items, and restoring fallback state. Requires a companion Stl.Scrollbar.Template node
wired to the same #name# namespace.
LIBRARY: Stl.Browsers.Template
Key concepts:
- Items are addressed by integer index into #name#.sorted_items.
- Tags are individual bits in Mask objects; the active filter is #name#.currentFilter.
- Fallback state captures a filter + item so the user can cancel a selection.
- All UI rendering delegates to #name#.ui.hooks.* override functions.
API¶
Nodes¶
| Name | Description |
|---|---|
node Stl.Browsers.Template(#name#, #max_items#, #num_tags#, #num_entries#) (Template) |
Parameterized browser node template; instantiate once per browser with a unique ... |
Defines¶
| Name | Description |
|---|---|
define #name#.num_filtered_results |
Legacy alias for #name#.current_items.count. |
define #name#.options.always_available_tags |
Legacy alias for #name#.options.alwaysAvailableTags. |
define #name#.options.default_filter |
Legacy alias for #name#.options.defaultFilter. |
define STL.UI_CALLBACKS += #name#.cb.tag, ... |
Registers the browser's five UI callback slots with the global STL.UI_CALLBACKS ... |
Functions¶
| Name | Description |
|---|---|
#name#.current_to_fallback() |
Saves the current filter and focused item as the browser's fallback state. |
#name#.fallback() |
Restores the browser filter and focused item to the last saved fallback state. |
#name#.fallback_sound_only() |
Reloads only the fallback item without restoring the filter state. |
#name#.get_filter(part) -> return |
Returns a single 32-bit part of the current filter mask for persistence or inspe... |
#name#.hooks.fallback_load(generic_id, fallback_item, fallback_filter) |
Default fallback-load hook. |
#name#.jump_to_focused_item(item) |
Scrolls the browser to bring the given item into view and marks it as focused. |
#name#.process_filter() |
Rebuilds the filtered item list and refreshes all tag, scrollbar, and entry UI. |
#name#.refresh(item) |
Refreshes the browser to show the given item, updating the filter to accommodate... |
#name#.reingest_tags() |
Reads the UI tag button states into the filter and reprocesses the full browser ... |
#name#.reset_filter() |
Restores the browser filter to the configured default and reprocesses the item l... |
#name#.scrollbar.response(index) |
Scrollbar response override. |
#name#.select_entry(entry, is_dbl_click, key_modifiers) |
Handles a browser entry selection, optionally loading or previewing the item. |
#name#.set_fallback(generic_id, item, filter_mask) |
Stores a filter snapshot and item index as the browser's cancellation restore po... |
#name#.set_filter(filter) |
Applies a new filter mask to the browser and refreshes the display. |
#name#.set_filter_to_item(item) |
Sets the focused item and updates the filter to include it. |
#name#.ui.entry_list.refresh() |
Refreshes the visible browser entry list from the current scrollbar position. |
#name#.ui.filter_to_tag_btns() |
Syncs the UI tag buttons to match the current filter state. |
#name#.ui.refresh_tag_buttons() |
Updates each tag button's visual state to reflect the cached filter parts. |
#name#.ui.tag_btns_to_filter() |
Writes the current UI tag button states back into the active filter mask. |
uicb.#name#.cb.abort(ui_id, n) |
UI callback for the abort/cancel button; stops any active preview and restores t... |
uicb.#name#.cb.entry(ui_id, n) |
UI callback for browser entry selection events. |
uicb.#name#.cb.next_item(ui_id, n) |
UI callback for the next-item button. |
uicb.#name#.cb.prev_item(ui_id, n) |
UI callback for the previous-item button. |
uicb.#name#.cb.tag(ui_id, n) |
UI callback for tag button events. |
Task Functions¶
| Name | Description |
|---|---|
#name#.jump_focus_by() |
Shifts focus by the given step count within the filtered list, wrapping at bound... |
Nodes¶
node Stl.Browsers.Template(#name#, #max_items#, #num_tags#, #num_entries#)¶
Callbacks: Init, Reload, FirstLoad
Parameterized browser node template; instantiate once per browser with a unique #name# namespace.
| Parameter | Description |
|---|---|
#name# |
namespace prefix for all generated functions, callbacks, and hooks |
#max_items# |
item capacity |
#num_tags# |
tag count |
#num_entries# |
visible row count |
Defines¶
define #name#.num_filtered_results¶
Legacy alias for #name#.current_items.count. Prefer the canonical name in new code.
define #name#.options.always_available_tags¶
Legacy alias for #name#.options.alwaysAvailableTags. Prefer the camelCase name in new code.
define #name#.options.default_filter¶
Legacy alias for #name#.options.defaultFilter. Prefer the camelCase name in new code.
define STL.UI_CALLBACKS += #name#.cb.tag, ...¶
Registers the browser's five UI callback slots with the global STL.UI_CALLBACKS list.
Functions¶
#name#.current_to_fallback()¶
Saves the current filter and focused item as the browser's fallback state.
#name#.fallback()¶
Restores the browser filter and focused item to the last saved fallback state.
#name#.fallback_sound_only()¶
Reloads only the fallback item without restoring the filter state.
#name#.get_filter(part) -> return¶
Returns a single 32-bit part of the current filter mask for persistence or inspection.
| Parameter | Type | Description |
|---|---|---|
part |
integer | index of the Mask object's 32-bit part to read |
Returns: return — The 32-bit value of the specified filter mask part
#name#.hooks.fallback_load(generic_id, fallback_item, fallback_filter)¶
Default fallback-load hook. Loads fallback_item when it is valid and fallback_filter references a live Mask. Override per product to restore full browser state alongside the item load.
| Parameter | Type | Description |
|---|---|---|
generic_id |
integer | product-defined identifier for the cached state |
fallback_item |
integer | item index to restore |
fallback_filter |
integer | Mask object id representing the filter to restore |
#name#.jump_to_focused_item(item)¶
Scrolls the browser to bring the given item into view and marks it as focused.
| Parameter | Type | Description |
|---|---|---|
item |
integer | the item index to scroll to and focus |
#name#.process_filter()¶
Rebuilds the filtered item list and refreshes all tag, scrollbar, and entry UI.
#name#.refresh(item)¶
Refreshes the browser to show the given item, updating the filter to accommodate it.
| Parameter | Type | Description |
|---|---|---|
item |
integer | item index to focus; must be stored via the save hook to persist across reloads |
#name#.reingest_tags()¶
Reads the UI tag button states into the filter and reprocesses the full browser display.
#name#.reset_filter()¶
Restores the browser filter to the configured default and reprocesses the item list.
#name#.scrollbar.response(index)¶
Scrollbar response override. Refreshes the entry list whenever the scrollbar index changes.
| Parameter | Type | Description |
|---|---|---|
index |
integer | new scrollbar position (ignored; entry list reads it directly) |
#name#.select_entry(entry, is_dbl_click, key_modifiers)¶
Handles a browser entry selection, optionally loading or previewing the item.
| Parameter | Type | Description |
|---|---|---|
entry |
integer | index in the browser entry list |
is_dbl_click |
integer | TRUE or FALSE if the selection was a double-click event |
key_modifiers |
integer | a bitmask of keyboard modifiers held at the moment of browser entry being clicked on |
#name#.set_fallback(generic_id, item, filter_mask)¶
Stores a filter snapshot and item index as the browser's cancellation restore point.
Preconditions: The filter mask must adhere to the mutex logic of the project or bugs will occur.
| Parameter | Type | Description |
|---|---|---|
generic_id |
integer | product-defined identifier for the cached state |
item |
integer | the item to which we want to fall back to |
filter_mask |
integer | the Mask object containing the filter state to restore |
#name#.set_filter(filter)¶
Applies a new filter mask to the browser and refreshes the display.
Preconditions: The new filter must adhere to the mutex logic of the project or bugs will occur.
| Parameter | Type | Description |
|---|---|---|
filter |
integer | the Mask object id representing the desired tag selection |
#name#.set_filter_to_item(item)¶
Sets the focused item and updates the filter to include it.
| Parameter | Type | Description |
|---|---|---|
item |
integer | item index to focus; use a negative value to apply the default filter without changing focus |
#name#.ui.entry_list.refresh()¶
Refreshes the visible browser entry list from the current scrollbar position.
#name#.ui.filter_to_tag_btns()¶
Syncs the UI tag buttons to match the current filter state.
#name#.ui.refresh_tag_buttons()¶
Updates each tag button's visual state to reflect the cached filter parts.
#name#.ui.tag_btns_to_filter()¶
Writes the current UI tag button states back into the active filter mask.
uicb.#name#.cb.abort(ui_id, n)¶
UI callback for the abort/cancel button; stops any active preview and restores the fallback state.
| Parameter | Type | Description |
|---|---|---|
ui_id |
integer | ID of the abort button control |
n |
integer | button value (unused) |
uicb.#name#.cb.entry(ui_id, n)¶
UI callback for browser entry selection events.
| Parameter | Type | Description |
|---|---|---|
ui_id |
integer | ID of the entry list control |
n |
integer | index of the entry that was clicked |
uicb.#name#.cb.next_item(ui_id, n)¶
UI callback for the next-item button. Moves focus one step forward in the filtered list.
| Parameter | Type | Description |
|---|---|---|
ui_id |
integer | ID of the next-item button control |
n |
integer | button value (unused) |
uicb.#name#.cb.prev_item(ui_id, n)¶
UI callback for the previous-item button. Moves focus one step backward in the filtered list.
| Parameter | Type | Description |
|---|---|---|
ui_id |
integer | ID of the previous-item button control |
n |
integer | button value (unused) |
uicb.#name#.cb.tag(ui_id, n)¶
UI callback for tag button events. Notifies the tag-select hook and reingests the active tag set into the browser filter.
| Parameter | Type | Description |
|---|---|---|
ui_id |
integer | ID of the tag button control |
n |
integer | index of the tag button that was activated |
Task Functions¶
#name#.jump_focus_by()¶
Shifts focus by the given step count within the filtered list, wrapping at boundaries.
Example¶
// TODO: Add usage example