Skip to content

Numeric.md

Latest commit

 

History

History
495 lines (389 loc) · 17 KB

Numeric.md

File metadata and controls

495 lines (389 loc) · 17 KB

FROG logo

FROG Standard Numeric Widgets

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

Navigation

Contents

1. Overview

This document defines the intrinsic standardized baseline for numeric widgets in FROG.

The numeric family provides the standard widget surfaces used for numeric entry and numeric display. It is richer than the boolean and string families because a numeric widget naturally combines scalar value semantics, representation selection, data-entry limits, formatting, radix presentation, optional unit labels, and optional increment/decrement interaction.

The standard numeric family is defined as a real object surface with:

  • a primary numeric value posture,
  • a portable representation model,
  • a portable data-entry model,
  • a portable display-format model,
  • a minimal but real method surface,
  • a minimal but real event surface,
  • a stable public part model for realization targeting.

The design is intentionally analogous to mature graphical environments such as LabVIEW, while modernizing the public contract and preserving strict separation between class law, realization assets, runtime interpretation, and IDE tooling.

2. Classes Defined Here

  • frog.widgets.numeric_control
  • frog.widgets.numeric_indicator

Both classes share one numeric family posture. The control is user-editable in the portable baseline. The indicator is display-oriented and receives its value from diagram/runtime publication.

3. Numeric Class versus Realization

A numeric class is not the same thing as a host numeric text box, a spinbox, a fixed-point editor, a runtime-private field, or a SVG picture containing a number.

The class owns:

  • the numeric value surface,
  • the control-versus-indicator distinction,
  • the representation model,
  • the data-entry model,
  • the display-format model,
  • the public property inventory,
  • the public method inventory,
  • the public event inventory,
  • the public part model.

The realization owns:

  • the visible text box or numeric face geometry,
  • increment/decrement button embodiment,
  • radix badge placement,
  • unit-label placement,
  • SVG assets or host-native drawing resources,
  • state maps,
  • style application,
  • skin and variant selection.

A spinbox-like realization, a compact numeric indicator, or a radix-badge style does not automatically create a new numeric class. A distinct standardized class should be introduced only when the public contract itself changes.

4. Label, Caption, and Value Text Posture

The numeric family follows the shared FROG label/caption convention and adds a numeric-specific value-text surface. 

label.*
    - structural / logical widget name surface

caption.*
    - front-panel presentation caption shown near the numeric widget

value / text_value
    - semantic numeric value and its rendered text surface
  • label.text names the object for tooling, references, diagram readability, accessibility, and debugging.
  • caption.text is the external front-panel caption shown near the numeric widget.
  • value is the semantic numeric value.
  • text_value is the rendered value text part owned by realization but fed by the class-owned value.

5. Common Family Posture

  • family: scalar numeric widget family
  • primary value: present
  • value kind: numeric scalar
  • primary value mirror property: value
  • natural value participation: yes
  • object-style access surface: yes
  • structural label surface: label.*
  • front-panel caption surface: caption.*
  • representation surface: representation.*
  • data-entry surface: data_entry.*
  • display-format surface: display.*
  • unit-label surface: unit_label.*
  • interaction surface: interaction.*
  • portable style surface: style.*
  • portable realization-selection surface: realization.*

6. Numeric Representation Model

The canonical property is: 

representation.kind

The standard representation kinds are:

  • int8, int16, int32, int64
  • uint8, uint16, uint32, uint64
  • float32, float64
  • decimal64, decimal128
  • fixed_point_signed, fixed_point_unsigned
  • complex64, complex128

IDEs may expose aliases such as I32, DBL, SGL, or FXP. Those aliases are ergonomic presentation names. The canonical class law should preserve explicit representation identifiers.

When the active representation is fixed-point, the following additional members are relevant:

  • representation.encoding — signed or unsigned
  • representation.word_length_bits
  • representation.integer_word_length_bits
  • representation.include_overflow_status

7. Public Visual Part Model

  • root
  • label
  • caption
  • frame
  • value_face
  • text_value
  • spinner when present
  • increment_up when present
  • increment_down when present
  • radix_badge when present
  • unit_label when present
  • focus_ring when present

8. Standard Property Surface

8.1 Value and representation

  • value : numeric
  • representation.kind : enum
  • representation.encoding : enum when applicable
  • representation.word_length_bits : u32 when applicable
  • representation.integer_word_length_bits : u32 when applicable
  • representation.include_overflow_status : bool when applicable

8.2 Label, caption, and unit label

  • label.visible : bool
  • label.text : string
  • label.style.*
  • caption.visible : bool
  • caption.text : string
  • caption.placement : enum
  • caption.padding : length
  • caption.style.*
  • unit_label.visible : bool
  • unit_label.text : string
  • unit_label.style.*

8.3 Interaction

  • interaction.visible : bool
  • interaction.enabled : bool
  • interaction.read_only : bool
  • interaction.focusable : bool
  • interaction.focused : bool

8.4 Data entry

  • data_entry.minimum : numeric
  • data_entry.maximum : numeric
  • data_entry.increment_step : numeric
  • data_entry.coerce_on_commit : bool
  • data_entry.response_to_out_of_range : enum — reject, coerce, warn, or allow_with_status

8.5 Display format

  • display.format_kind : enum — default, decimal, scientific, engineering, hex, binary, octal, or custom
  • display.format_string : string
  • display.precision_digits : u32
  • display.radix_visible : bool
  • display.increment_buttons_visible : bool
  • display.text_width_chars : u32

8.6 Key bindings

  • key_binding.focus : string when exposed
  • key_binding.increment : string when exposed
  • key_binding.decrement : string when exposed

8.7 Style and realization

  • style.frame.*
  • style.value_face.*
  • style.text_value.*
  • style.spinner.*
  • style.focus_ring.*
  • style.disabled.opacity : number
  • realization.family : string
  • realization.variant : string
  • realization.skin_id : string

9. frog.widgets.numeric_control

9.1 Class identity

  • class_id: frog.widgets.numeric_control
  • family: numeric_widget
  • compatible role: control

9.2 Standard methods

  • focus()
  • select_text()
  • set_value(number)
  • increment()
  • decrement()
  • clamp_to_limits()
  • format_value()
  • parse_and_commit(text)
  • reset_to_default()

9.3 Standard events

  • value_changed
  • value_committed
  • edit_started
  • edit_committed
  • out_of_range
  • increment_pressed
  • decrement_pressed
  • focus_gained
  • focus_lost

10. frog.widgets.numeric_indicator

10.1 Class identity

  • class_id: frog.widgets.numeric_indicator
  • family: numeric_widget
  • compatible role: indicator

10.2 Standard methods

  • focus() when supported by the host
  • format_value()
  • reset_to_default_style()

10.3 Standard events

  • value_rendered
  • focus_gained
  • focus_lost

11. Default SVG Realization Posture

The default numeric realization SHOULD support a rectangular SVG template with:

  • a value face,
  • dynamic value text,
  • optional increment/decrement buttons,
  • optional radix badge,
  • optional unit label,
  • label and caption surfaces,
  • focus-ring posture.

12. Diagram Interaction Posture

The numeric family 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.

13. Behavior Expectations

  • numeric controls accept user-originated editing only when enabled and not read-only,
  • increment and decrement use data_entry.increment_step,
  • commits respect data_entry.response_to_out_of_range,
  • formatting follows display.*,
  • representation changes must preserve or explicitly convert numeric meaning according to the active validation posture.

14. Compatibility with Example 05 Flat Surface

Example 05 was intentionally frozen as an executable corridor and uses a bounded flat numeric surface for its acceptance path. That frozen surface should not be silently rewritten by the general numeric baseline.

The compatibility mapping is:

  • label maps to caption.text or label.text depending on the host compatibility mode.
  • visible maps to interaction.visible.
  • enabled maps to interaction.enabled.
  • foreground_color maps to a compatible text or foreground style surface in the runtime-family corridor.

New numeric work should use the canonical hierarchical surface defined here. The frozen Example 05 runtime-family acceptance path may continue to preserve its existing compatibility surface.

15. Validation Expectations

Validators SHOULD diagnose at least:

  • non-numeric values on numeric widgets,
  • unknown representation kinds,
  • fixed-point members used without a fixed-point representation kind,
  • minimum greater than maximum,
  • non-positive increment steps for increment/decrement posture,
  • out-of-range values where the configured response forbids them,
  • unsupported public members,
  • attempts to treat realization-only spinner internals as public class members.

16. Summary

The numeric widget family defines the intrinsic standardized numeric baseline of FROG:

  • frog.widgets.numeric_control
  • frog.widgets.numeric_indicator

It standardizes numeric value, representation, data-entry limits, display format, optional unit and radix surfaces, optional increment/decrement interaction, and a realization-ready public part model while preserving the class-versus-realization boundary.