FROG Standard Tree Widgets

Normative baseline for standardized tree control and tree indicator widget classes
FROG — Free Open Graphical Language

Navigation

Classes Defined Here

frog.widgets.tree_control
frog.widgets.tree_indicator

Overview

The Tree family defines standardized widgets for finite hierarchical node structures in FROG. It provides a public tree value model, node identity model, expansion model, selection model, viewport model, optional editing and drag posture, checkbox posture, icon posture, and stable public part model.

A Tree widget is suitable for hierarchical data display, project navigation, configuration trees, object browsers, inspection trees, hierarchical results, file-like navigation, and structured runtime UI selection.

The intrinsic Tree baseline is not a filesystem API, database browser, object-reflection API, scene graph, or IDE-private navigator. Those integrations may use the Tree family, but they remain downstream from the widget class law.

Common Family Posture

family: hierarchical selection / navigation widget family
primary value: present
value type: frog.tree
public value-facing surface: yes
object-style access surface: yes
primary value mirror property: value
common label property: label.text
common caption property: caption.text
common visibility property: interaction.visible

The family separates:

value — the class-owned tree payload,
nodes.* — node data, identity, children, and display posture,
selection.* — selected node posture,
expansion.* — expanded / collapsed node posture,
viewport.* — visible scroll window and indentation posture,
editing.* — optional node editing posture,
check.* — optional checkbox or check-state posture,
drag.* and drop.* — optional drag/drop posture,
realization-private row pools, renderer caches, virtualized node handles, host-native tree handles, and IDE-private node objects.

`frog.widgets.tree_control`

Class identity

class_id: frog.widgets.tree_control
family: tree_widget
compatible role: control

Primary value posture

primary value: present
value type: frog.tree
natural value participation: yes
user-mutable: yes where editing, selection, expansion, or check-state surfaces are exposed
diagram-mutable: yes
mirrored property: value

A tree control may allow node selection, expansion/collapse, editing labels, reordering nodes, toggling check state, and drag/drop when those capabilities are enabled by the active class posture or profile. The intrinsic class does not require every host to support full drag/drop or virtualized editing.

`frog.widgets.tree_indicator`

Class identity

class_id: frog.widgets.tree_indicator
family: tree_widget
compatible role: indicator

Primary value posture

primary value: present
value type: frog.tree
natural value participation: yes
user-mutable: no for tree value in the standard portable posture
diagram-mutable: yes
mirrored property: value

A tree indicator is display-oriented. It may still support viewport changes, node expansion for inspection, and selection readout when those interactions do not mutate the tree value.

Tree Value Model

The canonical portable tree value is a structured finite hierarchy. The baseline recognizes:

Field	Meaning	Baseline status
`nodes`	Node table or recursive node list.	required
`root_ids`	Top-level node identifiers.	required when nodes are flat-indexed
`selected_node_ids`	Optional current selection mirror.	optional
`expanded_node_ids`	Optional expansion mirror.	optional
`metadata`	Optional tree-level metadata.	optional

Node model

Each node may expose:

nodes[].id — stable node identifier,
nodes[].parent_id — optional parent identifier,
nodes[].children or nodes[].child_ids,
nodes[].label,
nodes[].value,
nodes[].icon,
nodes[].depth where derived or declared,
nodes[].path,
nodes[].expanded,
nodes[].selectable,
nodes[].editable,
nodes[].checked when check state is exposed,
nodes[].visible,
nodes[].metadata.

Node identity

Node identity SHOULD be stable when the tree participates in selection, expansion, check state, or editing. Selection and expansion SHOULD be expressed by node id or node path, not by host-private row handles.

Node paths

A node path is a stable public path-like address through the hierarchy. Path syntax is realization-independent. It may be represented as an array of node ids or as a canonicalized path string where allowed by the active profile.

Selection Model

selection.mode — none, single_node, multi_node, or range
selection.selected_node_ids
selection.active_node_id
selection.active_column_id
selection.active_cell_id
selection.anchor_node_id
selection.selected_paths

Selection is distinct from tree value. Changing selection does not mutate node payloads unless an explicit edit or method mutates tree data. When a tabular Tree surface exposes columns, selection.active_column_id and selection.active_cell_id may identify the currently focused cell while selection.active_node_id remains the selected node used by ordinary node-selection dataflow.

Expansion Model

expansion.expanded_node_ids
expansion.collapsed_node_ids
expansion.auto_expand_on_search
expansion.default_state — expanded or collapsed

Expansion is a view posture. It does not mutate the underlying hierarchy unless explicitly treated as part of the value by a profile or program.

Check State Model

Tree widgets may expose node check states when useful for configuration trees or multi-selection workflows.

check.enabled
check.mode — none, boolean, or tri_state
check.checked_node_ids
check.indeterminate_node_ids
nodes[].checked

Tri-state check behavior is optional and belongs to the Tree check surface. It does not redefine scalar boolean widgets.

Viewport and Search Model

viewport.node_offset
viewport.visible_node_count
viewport.row_height
viewport.indent_width
viewport.horizontal_offset

search.query
search.matches
search.active_match
filter.expression
filter.visible_node_count

Search and filtering are view postures unless explicitly modeled as value transformations elsewhere.

Editing and Drag/Drop Model

editing.enabled
editing.active_node_id
editing.pending_label
editing.commit_policy

drag.enabled
drag.active_node_ids
drop.enabled
drop.target_node_id
drop.position — before, inside, or after

Drag/drop is optional. Hosts that do not support portable drag/drop may still support selection and expansion.

Standard Properties

Common properties

value
label.text
label.visible
caption.text
caption.visible
interaction.visible
interaction.enabled

Tree properties

nodes.count
nodes.root_ids
nodes.children
nodes.label
nodes.value
nodes.icon
nodes.path
nodes.depth
nodes.visible

Display properties

display.column_headers_visible
display.column_headers_fixed
display.row_headers_visible
display.vertical_scrollbar_visible
display.horizontal_scrollbar_visible
display.vertical_lines_visible
display.horizontal_lines_visible
display.hierarchy_lines_visible
display.symbols_visible
display.expand_contract_symbols_visible
display.checkboxes_visible

Scrollbar style properties

style.scrollbar.track_fill_color
style.scrollbar.border_color
style.scrollbar.border_width
style.scrollbar.thumb_fill_color
style.scrollbar.vertical_thumb_width_percent
style.scrollbar.vertical_thumb_bleed
style.scrollbar.horizontal_thumb_height_percent

Tree affordance style properties

Tree item symbols, expand/collapse controls, and optional checkbox surfaces are separate visual affordances. A realization or runtime host must not drive them from one shared style bucket because doing so makes an item icon look like a button, or a button look like ordinary decoration.

style.node_icon_slot.fill_color
style.node_icon_slot.icon_fill_color
style.node_icon_slot.border_color
style.node_icon_slot.border_width
style.node_icon_slot.size
style.node_icon_slot.margin_right
style.expander.fill_color
style.expander.hover_fill_color
style.expander.text_color
style.expander.border_color
style.expander.border_width
style.expander.size
style.expander.font_size
style.expander.glyph_size
style.expander.glyph_stroke_width
style.expander.frame_visible
style.expander.margin_right
style.checkbox.fill_color
style.checkbox.checked_fill_color
style.checkbox.check_color
style.checkbox.border_color
style.checkbox.border_width
style.checkbox.size
style.checkbox.font_size
style.checkbox.margin_right

Interaction properties

selection.*
expansion.*
check.*
viewport.*
search.*
filter.*
editing.*
drag.*
drop.*

Standard Methods

focus()
clear_selection()
set_selection(selection)
select_node(node_id)
select_path(path)
expand_node(node_id)
collapse_node(node_id)
toggle_node(node_id)
expand_all()
collapse_all()
scroll_to_node(node_id)
scroll_to_path(path)
set_node_label(node_id, label)
set_node_value(node_id, value)
append_child(parent_id, node)
insert_before(reference_node_id, node)
remove_node(node_id)
move_node(node_id, target_parent_id, position)
set_checked(node_id, checked)
find_nodes(query)
clear_filter()

Standard Events

value_changed
node_added
node_removed
node_moved
node_label_changed
node_value_changed
selection_changed
expansion_changed
node_expanded
node_collapsed
check_changed
viewport_changed
search_changed
filter_changed
edit_started
edit_committed
edit_cancelled
node_clicked
node_double_clicked
drag_started
drop_completed
focus_gained
focus_lost

Public Parts

root
label
caption
frame
node_region
column_headers
node_row
node_indent
node_connector
expander_face
checkbox_face
node_icon
node_label
active_node
active_cell
selection_face
edit_overlay
drag_feedback
drop_target
vertical_scrollbar
horizontal_scrollbar
focus_ring

Node rows, expanders, connectors, checkbox faces, icons, labels, and selection surfaces are public part categories. Tree node icons are source-owned enum/string values that must resolve through realization-published item-symbol assets when display.symbols_visible is enabled; a host must not invent fallback icon artwork. The item icon is static per node. Expand/collapse state is rendered only through expander_face and style.expander.*, not by mutating the node icon. The item icon slot, expand/collapse face, and checkbox face have distinct style surfaces: style.node_icon_slot.*, style.expander.*, and style.checkbox.*. When a tabular Tree exposes cell focus, active_cell is the published cell-selection surface and its fill, border color, and border width remain source-owned style properties. Virtualized node renderers, host-native row handles, recycled item views, or IDE-private node references remain realization-private.

Diagram Interaction Posture

The Tree family supports:

natural value participation through widget_value,
property access through frog.ui.property_read and frog.ui.property_write,
method invocation where legal,
event observation where legal.

Ordinary tree dataflow should prefer widget_value. Object-style access should be used for selection, expansion, check state, node editing, viewport, search, filter, or drag/drop interaction.

Validation Expectations

Validators SHOULD diagnose at least:

non-tree value payloads,
duplicate node identifiers,
missing root nodes,
parent-child cycles,
children that reference unknown node ids,
selection ids outside the tree,
expansion ids outside the tree,
check-state ids outside the tree,
invalid node paths,
invalid viewport offsets,
unsupported edit or drag/drop operations on indicators,
attempts to treat realization-only row handles, virtualized node handles, host-native tree handles, or IDE-private node objects as public semantic storage.

Summary

The Tree family provides the standard portable finite hierarchical data baseline of FROG:

frog.widgets.tree_control
frog.widgets.tree_indicator

It covers node identity, hierarchy, selection, expansion, optional check state, viewport, editing, drag/drop posture, and a stable part model while keeping host-native virtualization and renderer internals downstream from class law.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FROG Standard Tree Widgets

Navigation

Classes Defined Here

Overview

Common Family Posture

`frog.widgets.tree_control`

Class identity

Primary value posture

`frog.widgets.tree_indicator`

Class identity

Primary value posture

Tree Value Model

Node model

Node identity

Node paths

Selection Model

Expansion Model

Check State Model

Viewport and Search Model

Editing and Drag/Drop Model

Standard Properties

Common properties

Tree properties

Display properties

Scrollbar style properties

Tree affordance style properties

Interaction properties

Standard Methods

Standard Events

Public Parts

Diagram Interaction Posture

Validation Expectations

Summary

FilesExpand file tree

Tree.md

Latest commit

History

Tree.md

File metadata and controls

FROG Standard Tree Widgets

Navigation

Classes Defined Here

Overview

Common Family Posture

frog.widgets.tree_control

Class identity

Primary value posture

frog.widgets.tree_indicator

Class identity

Primary value posture

Tree Value Model

Node model

Node identity

Node paths

Selection Model

Expansion Model

Check State Model

Viewport and Search Model

Editing and Drag/Drop Model

Standard Properties

Common properties

Tree properties

Display properties

Scrollbar style properties

Tree affordance style properties

Interaction properties

Standard Methods

Standard Events

Public Parts

Diagram Interaction Posture

Validation Expectations

Summary

`frog.widgets.tree_control`

`frog.widgets.tree_indicator`