Skip to content

Tree.md

Latest commit

 

History

History
189 lines (153 loc) · 8.24 KB

Tree.md

File metadata and controls

189 lines (153 loc) · 8.24 KB

FROG logo

Tree Widget Example Reference

Current Tree control and Tree indicator proof surface
FROG - Free Open Graphical Language

Scope

The stabilized Tree slice is Examples/24_tree_node_selection_roundtrip. It proves a frog.widgets.tree_control command surface driving a read-only frog.widgets.tree_indicator through a native manifest-backed selected-node value and an explicit frog.tree.records diagram dataflow. 

system_tree.value.selected_node_value
  -> native u16 proof kernel
  -> published_tree.value.selected_node_value
  -> public selected_node_value

system_tree.nodes.*
  -> frog.tree.records dataflow
  -> published_tree.nodes.*
  -> public published_tree_records

This page is a practical example note, not the normative Tree class law. The normative class surface remains Libraries/Widgets/Tree.md, and the Default realization surface remains Libraries/Realizations/Default/Tree.md.

FROG-Owned Instance Data

The .frog source owns the diagram and all front-panel instance data:

  • Examples/24_tree_node_selection_roundtrip/main.frog
  • Tree control instance: system_tree, frog.widgets.tree_control
  • Tree indicator instance: published_tree, frog.widgets.tree_indicator
  • node ids, tags, labels, hierarchy, numeric values, check posture, item icon enum values, and editable attributes
  • column ids, labels, value references, widths, visibility, and editability
  • selection state: selected node id, selected column id, selected cell id, and selected numeric node value
  • expansion state, scroll offsets, visible item posture, row height, header height, indentation, and layout
  • instance-level style for labels, headers, rows, active cells, selection, scrollbars, item icon slots, expanders, and optional checkboxes

The Tree example deliberately contains more rows and columns than the visible viewport so both vertical and horizontal scrollbar behavior can be inspected.

Published Parts And Configurable Properties

Surface Current source properties Runtime obligation
Tree body style.node_region.*, viewport.*, display.* Render the body through the Default Tree node_region part and source-owned viewport posture.
Rows and cells nodes.*, columns.*, style.node_row.*, style.active_cell.* Use source-owned node and column records; do not hardcode row labels, values, widths, or selection behavior.
Expand/collapse control expansion.*, style.expander.* Expose one plus/minus control per expandable parent node; keep the glyph centered and independent from item icons.
Item icon slot nodes.icon, style.node_icon_slot.* Resolve item symbols through the .wfrog item-symbol registry and consume Default SVG assets.
Optional checkbox nodes.checked, display.checkboxes_visible, style.checkbox.* Keep checkbox styling separate from expanders and item icons.
Scrollbars viewport.*, display.*scrollbar_visible, style.scrollbar.* Keep vertical and horizontal scrollbar tracks and thumbs configurable, centered, and aligned to published SVG parts.

The Default Tree SVG shell publishes static geometry parts. Dynamic row, cell, selection, expander, checkbox, icon, edit, and scrollbar overlays are host-rendered from source-owned data and the Default realization contract.

WFROG-Owned Realization Data

The example package is: 

Examples/24_tree_node_selection_roundtrip/ui/tree_panel.wfrog

It owns only realization references, asset references, item-symbol registry entries, and host capability declarations.

  • Default Tree package: Libraries/Realizations/Default/tree.default.wfrog
  • Tree shell SVG: Libraries/Realizations/Default/assets/tree/templates/tree_shell.svg
  • Item symbol SVG assets: assets/tree/item_symbols/check.svg, folder_closed.svg, folder_open.svg, document.svg, and leaf.svg
  • Example asset ids consumed by runtimes: tree_shell_svg and tree_item_symbol_*

Runtime Expectations

  • The runtime consumes .frog node, column, selection, expansion, viewport, and style records.
  • The runtime resolves the Tree shell and item-symbol SVG assets from .wfrog; no runtime-private icon drawings are valid.
  • Changing selection or expansion patches front-panel state only. It does not execute the diagram.
  • Editable Tree cells preserve command-side edits until Execute.
  • Execute consumes the current source-modeled state, runs the manifest-backed native selected-node kernel, and publishes the declared Tree records flow.
  • The Tree indicator remains read-only for value edits, but may allow viewport, expansion, and selection inspection when those interactions do not mutate the public tree payload.
  • The runtime must reject fallback markers that replace the Tree with a hardcoded HTML-only shell.

Native Kernel Posture

  • native manifest: Implementations/Reference/LLVM/examples/24_tree_node_selection_roundtrip/native_kernel_manifest.json
  • native ABI: frog_u16_to_result_status_outptr
  • lowering unit: Examples/24_tree_node_selection_roundtrip/main.lowering.json
  • The native proof kernel handles the selected numeric node value. The full Tree record payload is carried by declared diagram dataflow, not by hidden UI synchronization.
  • Example 24 is accepted at the same C++/Python/Rust private-runtime source level; this does not claim generalized runtime completeness beyond the validated slice.

Resizable Host Posture

The Default Tree shell is SVG-backed and uses a viewBox, so a conforming IDE or runtime host can scale the widget without bitmap pixelation. Scaling is not automatic layout correctness by itself: the host must recompute overlays for rows, cells, scrollbars, expanders, checkboxes, item icons, labels, and edit surfaces from the published SVG parts and the source-owned layout/style properties.

The current browser host uses CSS pixel coordinates as a concrete inspection surface. Another host, such as a Qt, native desktop, or GPU-backed host, may render the same Tree if it preserves the .frog instance model, .wfrog asset resolution, Default SVG part contract, and public property/method/event behavior.

Validation Notes

  • The Tree must be manually inspected in the browser host before acceptance.
  • Vertical and horizontal scrollbars must be smooth, aligned, centered, and configurable.
  • Every selectable cell must show a uniform selection border width.
  • Labels must be visually separated from the widget body and aligned with the source-owned layout.
  • Item icons must remain static display enum values; expanding or collapsing a node must not mutate the item icon.
  • There must be no duplicated example-local Tree SVG skin when the Default Tree realization exists.