Skip to content

Chart.md

Latest commit

 

History

History
454 lines (370 loc) · 14.8 KB

Chart.md

File metadata and controls

454 lines (370 loc) · 14.8 KB

FROG logo

FROG Standard Waveform Chart Widget

Composite-object baseline for the standardized waveform chart widget class
FROG — Free Open Graphical Language

Navigation

Classes Defined Here

  • frog.widgets.waveform_chart

Overview

The Waveform Chart family defines the standardized indicator-oriented chart widget used for time-ordered numeric samples, retained history, multiple plots, axes, scale labels, legends, cursors, scrollbars, palette tools, and lightweight plot-image overlays.

A waveform chart is a composite front-panel object. It is not merely a rectangle containing a curve, and it is not a full graphing framework. It is the portable FROG baseline for streaming or appended numeric history visualization.

The intrinsic baseline is intentionally narrower than a full graph family. XY graphs, intensity graphs, mixed-signal graphs, polar plots, histograms, annotations frameworks, plugin renderers, and domain-specific plotting systems belong to later classes, profiles, or host integrations.

Class Identity

  • class_id: frog.widgets.waveform_chart
  • family: waveform_chart_widget
  • compatible role: indicator

Primary Value Posture

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

A waveform chart may allow user-originated viewport, cursor, palette, and scrollbar changes. Those interactions do not mutate the retained sample history unless an explicit method or data operation does so.

Chart Class versus Realization

The chart class owns the public value model, history model, plot model, scale model, legend/cursor/palette/scrollbar surfaces, methods, events, and public parts.

The realization owns the drawing strategy: SVG template, host-native plot surface, canvas, GPU surface, polyline rasterization, tick rendering, legend layout, palette layout, cursor drawing, plot-image layer composition, and host-specific optimization.

Composite Object Model

frog.widgets.waveform_chart
├── value
├── history.*
├── samples.*
├── timebase.*
├── plot_area.*
├── plots.*
├── scales.x.*
├── scales.y.*
├── legends.plot.*
├── legends.scale.*
├── legends.cursor.*
├── palette.*
├── scrollbars.x.*
├── scrollbars.y.*
├── cursors.*
├── plot_images.*
├── annotations.*
├── thresholds.*
├── interaction.*
├── style.*
└── realization.*

The sub-object model gives the chart a property-node and method-node posture similar in spirit to mature graphical systems, while keeping the portable core bounded.

Value, Samples, and Timebase Model

Value payload kinds

The portable chart value may carry one of these payload postures:

  • single_sample — one numeric value appended to the active plot,
  • sample_array — multiple samples appended to the active plot,
  • multi_plot_sample — one sample per plot,
  • multi_plot_arrays — multiple samples per plot,
  • waveform — numeric samples plus timing metadata,
  • history_replace — explicit history replacement payload.

Sample model

  • samples.value_type — i32, u32, f32, f64, or profile-supported numeric type
  • samples.nan_policy — preserve, gap, or reject
  • samples.timestamp_policy — implicit_index, dt_t0, or explicit_x
  • samples.order — append_order for the intrinsic baseline

Timebase model

  • timebase.mode — sample_index, relative_time, or absolute_time
  • timebase.t0
  • timebase.dt
  • timebase.unit
  • timebase.sample_rate

History Model

  • history.data
  • history.capacity
  • history.length
  • history.update_mode — append, replace_history, or rolling_window
  • history.retention_policy — drop_oldest, reject_when_full, or grow_until_capacity
  • history.clear_on_start
  • history.visible_window

Retained history is chart-owned display state. It is not an unbounded data logger. Data logging belongs to another library or runtime integration.

Plot Model

  • plots.count
  • plots.active_index
  • plots[].id
  • plots[].name
  • plots[].visible
  • plots[].color
  • plots[].line_style
  • plots[].line_width
  • plots[].point_style
  • plots[].point_size
  • plots[].interpolation — none, linear, step_left, or step_right
  • plots[].fill_to
  • plots[].x_scale_index
  • plots[].y_scale_index

Scale and Grid Model

X scales

  • scales.x.active_index
  • scales.x[].name
  • scales.x[].visible
  • scales.x[].label.text
  • scales.x[].label.visible
  • scales.x[].autoscale
  • scales.x[].minimum
  • scales.x[].maximum
  • scales.x[].log
  • scales.x[].inverted
  • scales.x[].offset
  • scales.x[].multiplier
  • scales.x[].tick.major.visible
  • scales.x[].tick.minor.visible
  • scales.x[].grid.major.visible
  • scales.x[].grid.minor.visible

Y scales

  • scales.y.active_index
  • scales.y[].name
  • scales.y[].visible
  • scales.y[].label.text
  • scales.y[].label.visible
  • scales.y[].autoscale
  • scales.y[].minimum
  • scales.y[].maximum
  • scales.y[].log
  • scales.y[].inverted
  • scales.y[].offset
  • scales.y[].multiplier
  • scales.y[].tick.major.visible
  • scales.y[].tick.minor.visible
  • scales.y[].grid.major.visible
  • scales.y[].grid.minor.visible

Cursor, Legend, Palette, and Scrollbar Model

Cursors

  • cursors.count
  • cursors.active_index
  • cursors[].id
  • cursors[].name
  • cursors[].visible
  • cursors[].color
  • cursors[].plot_index
  • cursors[].position.x
  • cursors[].position.y
  • cursors[].snap_mode — free, nearest_sample, or profile-supported mode
  • cursors[].dragging_mode

Legends

  • legends.plot.visible
  • legends.plot.position
  • legends.scale.visible
  • legends.scale.position
  • legends.cursor.visible
  • legends.cursor.position

Palette

  • palette.visible
  • palette.zoom_enabled
  • palette.pan_enabled
  • palette.selection_enabled
  • palette.autoscale_enabled

Scrollbars

  • scrollbars.x.visible
  • scrollbars.y.visible
  • scrollbars.x.position
  • scrollbars.y.position
  • scrollbars.x.value
  • scrollbars.y.value

Annotations, Thresholds, and Plot Image Layers

  • annotations.visible
  • annotations.items
  • thresholds.visible
  • thresholds.items
  • plot_images.back
  • plot_images.middle
  • plot_images.front

Annotations and thresholds are display overlays in the intrinsic baseline. They do not mutate sample history or plot semantics.

Public Part Model

  • root
  • label
  • caption
  • frame
  • plot_area
  • history_region
  • plot_layer
  • plot_polyline
  • plot_marker
  • grid
  • axis_tick
  • x_scale
  • y_scale
  • x_scale_label
  • y_scale_label
  • plot_legend
  • scale_legend
  • cursor_legend
  • graph_palette
  • x_scrollbar
  • y_scrollbar
  • cursor_layer
  • cursor_readout
  • plot_image_back
  • plot_image_middle
  • plot_image_front
  • annotation_layer
  • threshold_band
  • focus_ring

Standard Methods

  • append_sample(sample)
  • append_samples(samples)
  • append_waveform(waveform)
  • replace_history(samples)
  • clear_history()
  • set_history_capacity(capacity)
  • autoscale_x()
  • autoscale_y()
  • autoscale_all()
  • set_x_range(minimum, maximum)
  • set_y_range(minimum, maximum)
  • set_active_plot(index)
  • set_active_x_scale(index)
  • set_active_y_scale(index)
  • add_cursor(cursor)
  • remove_cursor(index)
  • move_cursor(index, position)
  • clear_cursors()
  • add_threshold(threshold)
  • clear_thresholds()
  • reset_to_default_style()
  • export_view() when supported
  • focus()

Standard Events

  • value_rendered
  • sample_appended
  • waveform_appended
  • history_replaced
  • history_cleared
  • history_capacity_changed
  • axis_range_changed
  • plot_visibility_changed
  • cursor_added
  • cursor_removed
  • cursor_moved
  • threshold_changed
  • palette_action
  • viewport_changed
  • focus_gained
  • focus_lost

Diagram Interaction Posture

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

Ordinary streaming updates should prefer widget_value or explicit append methods. Object-style access should be used for plots, scales, legends, palette, cursor, threshold, history, and viewport configuration.

Validation Expectations

Validators SHOULD diagnose at least:

  • non-numeric sample payloads,
  • invalid history capacity,
  • history length exceeding capacity,
  • invalid plot index,
  • invalid active scale index,
  • invalid cursor index,
  • invalid axis range,
  • invalid logarithmic scale ranges,
  • incompatible multi-plot sample shapes,
  • unsupported cursor snap modes,
  • unsupported threshold specifications,
  • attempts to treat realization-only drawing internals, canvas handles, GPU surfaces, or plot renderer handles as public class members.

Summary

frog.widgets.waveform_chart is the standard FROG baseline for time-ordered numeric history visualization. It covers streaming sample updates, retained history, multiple plots, axes, scale labels, legends, scrollbars, palette posture, optional cursors, annotations, thresholds, and plot-image layers while preserving the boundary between class law, realization, runtime, and host-native rendering.