Skip to content

Boolean.md

Latest commit

 

History

History
465 lines (357 loc) · 17.2 KB

Boolean.md

File metadata and controls

465 lines (357 loc) · 17.2 KB

FROG logo

FROG Standard Boolean Widgets

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

Navigation

Contents

1. Overview

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

The boolean family provides the standard widget surfaces used for true/false interaction and true/false display. It is intentionally small, portable, inspectable, and strong enough to serve as part of the reusable front-panel baseline.

The intrinsic boolean baseline is strictly true/false. It does not standardize a tri-state boolean model in the intrinsic core.

This file defines the boolean class law. It does not make a particular SVG asset, host toolkit, runtime implementation, or IDE editor operation the semantic owner of the widget.

2. Classes Defined Here

  • frog.widgets.boolean_control
  • frog.widgets.boolean_indicator

3. Boolean Class versus Realization

A boolean class is not the same thing as its visible embodiment.

The class owns the boolean value meaning, the control-versus-indicator distinction, the public property inventory, the public method inventory, the public event inventory, the public part model, and the legality of object-style access through frog.ui.*.

The realization owns rectangular, circular, checkbox-like, switch-like, toggle-like, LED-like, or other visual embodiment choices, SVG assets or host-native drawing resources, part-to-visual bindings, state-to-visual mappings, text placement and anchoring, skin resources, and compatible visual variants.

A different shape does not automatically create a different boolean class. A rectangular boolean and a circular boolean remain frog.widgets.boolean_control or frog.widgets.boolean_indicator as long as their public contract remains the same.

The rectangular Boolean realization is a Boolean value-control / value-indicator skin. It MUST NOT be treated as the standardized Button command widget; Button command behavior is defined separately by frog.widgets.button.

4. Label, Caption, and State Text Posture

The boolean family follows the shared FROG label/caption convention and adds a boolean-specific internal state text surface. 

label.*
    - structural / logical widget name surface

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

state_text.*
    - optional text displayed inside the boolean face for true/false values

This distinction prevents ambiguity between the text naming the widget, the user-facing caption, and the text displayed as part of the true/false embodiment.

5. Common Family Posture

  • family: scalar boolean widget family
  • primary value: present
  • value type: bool
  • primary value mirror property: value
  • natural value participation: yes
  • object-style access surface: yes
  • structural label surface: label.*
  • front-panel caption surface: caption.*
  • internal state text surface: state_text.*
  • interaction surface: interaction.*
  • portable style surface: style.*
  • portable realization-selection surface: realization.*

The boolean family follows these architectural rules:

  • value is class-owned semantic boolean data.
  • label.text is class-owned logical widget-name text.
  • caption.text is class-owned front-panel display caption text.
  • state_text.true_text and state_text.false_text are optional state text surfaces, not the semantic source of the boolean value.
  • outer_face and inner_face are stable public visual parts, not runtime-private decorations.

6. Public Visual Part Model

  • root — root widget surface and hit-test container,
  • label — structural label surface when displayed by tooling or host,
  • caption — front-panel user-facing caption surface,
  • outer_face — outside boolean visual structure, frame, or body,
  • inner_face — inside boolean state surface or state marker,
  • state_text — optional internal true/false text surface,
  • focus_ring — optional focus visualization surface,
  • frame — optional outer frame surface when a realization separates frame from outer face.

7. Standard Property Surface

7.1 Semantic value properties

  • value : bool — primary boolean value.

7.2 Structural label properties

  • label.visible : bool
  • label.text : string
  • label.style.text_color : frog.color.rgba8
  • label.style.font_family : string
  • label.style.font_size : length
  • label.style.font_weight : enum
  • label.style.font_style : enum
  • label.style.text_decoration : enum

7.3 Caption properties

  • caption.visible : bool
  • caption.text : string
  • caption.placement : enum — preferred caption placement such as top, bottom, left, or right.
  • caption.padding : length
  • caption.style.text_color : frog.color.rgba8
  • caption.style.font_family : string
  • caption.style.font_size : length
  • caption.style.font_weight : enum
  • caption.style.font_style : enum
  • caption.style.text_decoration : enum
  • caption.style.text_alignment : enum

7.4 Internal state-text properties

  • state_text.visible : bool
  • state_text.true_text : string
  • state_text.false_text : string
  • state_text.placement : enum
  • state_text.style.text_color.true : frog.color.rgba8
  • state_text.style.text_color.false : frog.color.rgba8
  • state_text.style.font_family : string
  • state_text.style.font_size : length
  • state_text.style.font_weight : enum
  • state_text.style.font_style : enum
  • state_text.style.text_decoration : enum
  • state_text.style.text_alignment : enum

7.5 Interaction properties

  • interaction.visible : bool
  • interaction.enabled : bool
  • interaction.focusable : bool
  • interaction.focused : bool
  • interaction.pressed : bool — readable transient pressed posture for controls when exposed.

7.6 Outer-face style properties

  • style.outer.fill_color.true : frog.color.rgba8
  • style.outer.fill_color.false : frog.color.rgba8
  • style.outer.border_color.true : frog.color.rgba8
  • style.outer.border_color.false : frog.color.rgba8
  • style.outer.border_width : length
  • style.outer.corner_radius : length
  • style.outer.opacity : number

7.7 Inner-face style properties

  • style.inner.visible.true : bool
  • style.inner.visible.false : bool
  • style.inner.fill_color.true : frog.color.rgba8
  • style.inner.fill_color.false : frog.color.rgba8
  • style.inner.border_color.true : frog.color.rgba8
  • style.inner.border_color.false : frog.color.rgba8
  • style.inner.border_width : length
  • style.inner.inset : length
  • style.inner.corner_radius : length
  • style.inner.opacity : number

7.8 Focus and disabled style properties

  • style.focus_ring.visible : bool
  • style.focus_ring.color : frog.color.rgba8
  • style.focus_ring.width : length
  • style.disabled.opacity : number

7.9 Realization-selection properties

  • realization.family : string
  • realization.variant : string — such as rectangular or circular.
  • realization.skin_id : string

8. frog.widgets.boolean_control

8.1 Class identity

  • class_id: frog.widgets.boolean_control
  • family: boolean_widget
  • compatible role: control

8.2 Primary value posture

  • primary value: present
  • value type: bool
  • natural value participation: yes
  • user-mutable: yes
  • diagram-mutable: yes
  • runtime-mutable: yes
  • mirrored property: value

8.3 Standard methods

  • focus()
  • toggle()
  • set_true()
  • set_false()
  • reset_to_default()

8.4 Standard events

  • value_changed
  • pressed
  • released
  • focus_gained
  • focus_lost

9. frog.widgets.boolean_indicator

9.1 Class identity

  • class_id: frog.widgets.boolean_indicator
  • family: boolean_widget
  • compatible role: indicator

9.2 Primary value posture

  • primary value: present
  • value type: bool
  • natural value participation: yes
  • user-mutable: no in the standard portable posture
  • diagram-mutable: yes
  • runtime-mutable: yes
  • mirrored property: value

9.3 Standard methods

  • focus() when supported by the host and active publication corridor.
  • reset_to_default() when default value or style defaults exist and the active publication corridor exposes them.

9.4 Standard events

  • value_rendered
  • focus_gained
  • focus_lost

10. Default SVG Realization Posture

The boolean family should have a default SVG-oriented realization posture. This does not mean that the SVG file owns boolean semantics. It means that a standard realization package may publish SVG-backed assets and part mappings that consume the public boolean property surface.

A default SVG realization SHOULD support resizing, structural label and caption placement, internal state-text rendering, state-dependent color application, configurable border widths, configurable fills, and focus ring display. 

widget property
    -> realization parameter
        -> SVG part/style application

11. Rectangular and Circular Realization Variants

The standard boolean class may be realized through rectangular and circular variants. These are realization variants, not separate widget classes.

  • realization.variant = rectangular
  • realization.variant = circular

Changing realization.variant changes embodiment, not class meaning.

12. Diagram Interaction Posture

The boolean 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 through frog.ui.event_observe where legal.

Typical legal object-style surfaces include value, label.*, caption.*, state_text.*, interaction.*, style.*, and realization.*.

13. Behavior Expectations

  • the primary value remains boolean,
  • boolean controls accept user-originated toggling only when enabled,
  • boolean value transitions may emit value_changed,
  • indicator realizations may emit value_rendered when their visible state is refreshed,
  • state text follows the current boolean value but does not define it.

14. Validation Expectations

Validators SHOULD diagnose non-boolean values, role/class mismatches, unsupported public members, illegal writes to indicator-only surfaces, attempts to treat realization-only internals as public class members, and attempts to use styling or realization selection to imply a distinct boolean class without explicit class publication.

15. Compatibility with Bounded Flat Slices

Some bounded executable slices may preserve older flat property names for stability. Those slice-local compatibility surfaces do not replace the canonical boolean widget law defined here.

Tools may support explicit compatibility mappings for frozen examples, but new boolean-facing widget work should use the hierarchical surface defined in this document.

16. Summary

The boolean widget family defines the intrinsic standardized true/false widget baseline of FROG:

  • frog.widgets.boolean_control
  • frog.widgets.boolean_indicator

The boolean family now follows the shared label / caption convention while preserving boolean-specific state_text for true/false text inside the state face.