Skip to content

Table.md

Latest commit

 

History

History
483 lines (385 loc) · 15.2 KB

Table.md

File metadata and controls

483 lines (385 loc) · 15.2 KB

FROG logo

FROG Standard Table Widgets

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

Navigation

Classes Defined Here

  • frog.widgets.table_control
  • frog.widgets.table_indicator

Overview

The Table family defines standardized widgets for flat row-and-column tabular data in FROG. It provides a public value model, column schema, row identity posture, selection model, viewport model, editing posture, sorting and filtering posture, and stable public part model.

A Table widget is not merely a decorative grid. It is a structured data widget suitable for measurement tables, parameter grids, logs, tabular inspection output, editable tabular inputs, and structured front-panel displays.

The intrinsic Table baseline intentionally remains flat. Tree tables, hierarchical tables, pivot tables, spreadsheets with formula languages, database views, and virtualized host-grid engines are downstream profiles or host realizations unless explicitly standardized elsewhere.

Common Family Posture

  • family: structured tabular data widget family
  • primary value: present
  • value type: frog.table
  • 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 table payload,
  • columns.* — column schema and headers,
  • rows.* — row identity and row-count posture,
  • cells.* — cell-level access and edit surfaces,
  • selection.* — current table selection,
  • viewport.* — visible scroll window,
  • sort.* and filter.* — optional presentation / view postures,
  • realization-private row pools, cell renderers, virtualization caches, host handles, and editing controls.

frog.widgets.table_control

Class identity

  • class_id: frog.widgets.table_control
  • family: table_widget
  • compatible role: control

Primary value posture

  • primary value: present
  • value type: frog.table
  • natural value participation: yes
  • user-mutable: yes when editing is enabled
  • diagram-mutable: yes
  • mirrored property: value

A table control may allow cell editing, row selection, column selection, resizing, scrolling, sorting, and copy/paste-like host interactions when those surfaces are exposed by the active posture. The intrinsic class does not require every host to implement spreadsheet-grade editing.

frog.widgets.table_indicator

Class identity

  • class_id: frog.widgets.table_indicator
  • family: table_widget
  • compatible role: indicator

Primary value posture

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

A table indicator is display-oriented. It may still support viewport changes, selection readout, copy selection, sorting view changes, or inspection gestures when those do not mutate the table value.

Table Value Model

The canonical portable table value is a structured object:

Field Meaning Baseline status
columnsColumn schema list.required
rowsRow records or row vectors.required
cellsOptional explicit cell matrix representation.optional alternative
row_idsStable row identifiers when exposed.optional
metadataOptional table-level metadata.optional

Column model

Each column may expose:

  • columns[].id
  • columns[].header
  • columns[].type
  • columns[].width
  • columns[].alignment
  • columns[].format
  • columns[].editable
  • columns[].visible

Cell model

Each cell value belongs to one row and one column. Portable cell values may contain scalar values such as booleans, strings, numeric values, enum values, paths, timestamps, or profile-supported scalar payloads. A cell may also carry optional presentation metadata such as format, alignment, validation state, or read-only state when exposed by the active profile.

Row model

Rows may be represented as arrays indexed by column order or as objects keyed by column id. When row_ids are present, selection and editing surfaces SHOULD preserve those ids across sorting and filtering.

Selection Model

The Table family supports bounded table selection.

  • selection.mode — none, cell, row, column, range, or multi_range
  • selection.active_cell
  • selection.anchor_cell
  • selection.ranges
  • selection.selected_rows
  • selection.selected_columns

Selection is distinct from value. Changing selection does not mutate table data unless a method or edit operation explicitly mutates table data.

Editing Model

  • editing.enabled
  • editing.active_cell
  • editing.commit_policy — on_enter, on_focus_lost, explicit
  • editing.validation_policy
  • editing.pending_value

Editing is legal for frog.widgets.table_control when enabled. Editing table data through a table indicator is not part of the portable intrinsic posture.

Viewport, Sort, and Filter Model

Viewport

  • viewport.row_offset
  • viewport.column_offset
  • viewport.visible_rows
  • viewport.visible_columns
  • viewport.row_height
  • viewport.default_column_width

Sorting

  • sort.enabled
  • sort.keys
  • sort.direction — ascending or descending

Filtering

  • filter.enabled
  • filter.expression
  • filter.visible_row_count

Sorting and filtering are view postures unless explicitly exposed as value transformations by another operation.

Standard Properties

Common properties

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

Table structure properties

  • rows.count
  • columns.count
  • columns.headers
  • columns.schema
  • cells.value
  • cells.format
  • cells.read_only

Visible item properties

Table realizations expose LabVIEW-like visible-item posture as source-owned properties. The runtime may render host overlays, scroll tracks, headers, index displays, and selection faces, but it must consume these properties and the published Default Table parts instead of baking a table shell into runtime code.

  • display.index_display_visible
  • display.vertical_scrollbar_visible
  • display.horizontal_scrollbar_visible
  • display.row_headers_visible
  • display.column_headers_visible
  • display.vertical_lines_visible
  • display.horizontal_lines_visible
  • display.symbols_visible

Row and column header text maps to rows[].label and columns[].label. Selection color maps to style.selection_face.*. The active cell maps to selection.active_cell.*. Scrollbar colors, borders, and thumb geometry map to style.scrollbar.*.

Interaction properties

  • selection.*
  • interaction.selection_scrolling_enabled
  • headers.editable
  • columns.separators_movable
  • rows.autosize_height
  • input.multi_line_enabled
  • scrolling.smooth_enabled
  • editing.*
  • viewport.*
  • sort.*
  • filter.*

If a runtime does not yet implement an advanced operation such as editable headers, moveable separators, or multi-line editing, it must report the limitation explicitly. It must not silently replace the source-owned property model with hardcoded runtime behavior.

Standard Methods

  • focus()
  • clear_selection()
  • set_selection(selection)
  • select_cell(row, column)
  • select_row(row)
  • select_column(column)
  • scroll_to(row, column)
  • scroll_to_row(row)
  • scroll_to_column(column)
  • set_cell_value(row, column, value)
  • get_cell_value(row, column)
  • insert_row(index, row)
  • remove_row(index)
  • append_row(row)
  • clear_rows()
  • resize_column(column, width)
  • sort_by(column, direction)
  • clear_sort()
  • apply_filter(filter)
  • clear_filter()

Standard Events

  • value_changed
  • cell_value_changed
  • selection_changed
  • viewport_changed
  • sort_changed
  • filter_changed
  • row_inserted
  • row_removed
  • column_resized
  • edit_started
  • edit_committed
  • edit_cancelled
  • cell_clicked
  • header_clicked
  • focus_gained
  • focus_lost

Public Parts

  • root
  • label
  • caption
  • frame
  • header_region
  • column_header_region
  • row_header_region
  • grid_region
  • body_region
  • row
  • cell
  • active_cell
  • selection_face
  • edit_overlay
  • sort_indicator
  • resize_handle
  • vertical_scrollbar
  • horizontal_scrollbar
  • focus_ring

Rows, cells, and selection faces are public part categories. Realization-private row pools, recycled cell renderers, virtualization caches, host-grid handles, or editor controls are not semantic storage.

Diagram Interaction Posture

The Table 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 table dataflow should prefer widget_value. Object-style access should be used for selection, viewport, editing, sorting, filtering, and cell-level interaction.

Validation Expectations

Validators SHOULD diagnose at least:

  • non-table value payloads,
  • inconsistent row and column dimensions,
  • column schema entries without stable identifiers,
  • cell values incompatible with declared column type,
  • selection ranges outside table bounds,
  • invalid active cell,
  • invalid viewport offset or visible window size,
  • duplicate column identifiers,
  • unsupported edit operations on indicators,
  • attempts to treat realization-only row handles, cell renderers, virtualized row caches, or host-native grid handles as public semantic storage.

Summary

The Table family provides the standard portable flat tabular data baseline of FROG:

  • frog.widgets.table_control
  • frog.widgets.table_indicator

It covers table value, schema, rows, cells, selection, viewport, editing, sorting, filtering, and a stable part model while keeping host-native virtualization and renderer internals downstream from class law.