Skip to content

Button.md

Latest commit

 

History

History
390 lines (308 loc) · 13.5 KB

Button.md

File metadata and controls

390 lines (308 loc) · 13.5 KB

FROG logo

FROG Standard Button Widget

Normative baseline for the standardized button control widget class
FROG — Free Open Graphical Language

Navigation

Contents

1. Overview

This document defines the intrinsic standardized baseline for the button widget in FROG. The button is a command-oriented control with a boolean state, explicit mechanical-action behavior, event observation, and realization-driven visual state support.

The intrinsic button baseline is not merely a decorative clickable rectangle and is not equivalent to a generic boolean control. It owns button-specific timing and interaction semantics while remaining compatible with the shared widget model.

2. Class Defined Here

  • frog.widgets.button

3. Button Class versus Realization

The button class owns state meaning, mechanical action, properties, methods, events, parts, and legal access through frog.ui.*. The realization owns shape, skin, SVG resources, state-specific visual resources, part bindings, anchors, transitions, and host-specific rendering.

A state-specific SVG override does not create a new button class. A new class is justified only when the public contract changes.

4. Label, Caption, and State Text Posture

label.*
    - structural / logical widget name surface

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

state_text.*
    - optional text displayed inside the button face
      and optionally varied by button state
  • label.text names the object for tooling, references, diagram readability, accessibility, and debugging.
  • caption.text is the external front-panel caption shown near the button.
  • state_text.false_text and state_text.true_text are the internal button-face strings.

5. Mechanical Action Model

The button exposes the following canonical property: 

behavior.mechanical_action

The standard values are:

  • switch_when_pressed
  • switch_when_released
  • switch_until_released
  • latch_when_pressed
  • latch_when_released
  • latch_until_released
Mechanical action Value event Button value after user release Latch reset rule
switch_when_pressed Toggle the stored boolean value on the press edge. The toggled value remains stored. Not applicable.
switch_when_released Toggle the stored boolean value on the release edge. The toggled value remains stored. Not applicable.
switch_until_released Publish true while pressed and false on release. false. Not applicable.
latch_when_pressed Publish true on the press edge. Latched until natural value consumption resets it. Reset after the executable diagram consumes the natural value path.
latch_when_released Publish true on the release edge. Latched until natural value consumption resets it. Reset after the executable diagram consumes the natural value path.
latch_until_released Show the pressed state while held, then publish true on release. Latched until natural value consumption resets it. Reset after the executable diagram consumes the natural value path.

For latch modes, the reset condition MUST be explicit. The portable baseline defines the reset trigger as consumption through the natural button value path when that path is present in the executable diagram. A mere object-style property read of value SHOULD NOT by itself reset the latch unless a later profile or runtime-family contract explicitly publishes that behavior. Runtimes MUST NOT accept a mechanical action unless the corresponding event timing, stored value behavior, UI snapshot behavior, and reset behavior are implemented and validated for that runtime family.

6. Public Visual Part Model

  • root
  • label
  • caption
  • frame
  • face
  • state_face
  • state_text
  • focus_ring

Default SVG realizations SHOULD publish stable anchors for external text placement, internal state text placement, and host input overlays. The rectangular default realization publishes label.anchor, caption.anchor, state_text.center, and face.bounds. Host overlays for input handling MAY align to face.bounds, but they MUST NOT replace the SVG-owned visible button skin.

7. Standard Property Surface

7.1 State

  • value : bool

7.2 Label and caption

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

7.3 Internal state text

  • state_text.visible : bool
  • state_text.lock_in_center : bool
  • state_text.multiple_strings : bool
  • state_text.false_text : string
  • state_text.true_text : string
  • state_text.hover_false_text : string when exposed
  • state_text.hover_true_text : string when exposed
  • state_text.style.*

7.4 Interaction and behavior

  • interaction.visible : bool
  • interaction.enabled : bool
  • interaction.focusable : bool
  • interaction.focused : bool
  • interaction.hovered : bool
  • interaction.pressed : bool
  • behavior.mechanical_action : enum
  • behavior.latch_reset_policy : enum

7.5 Style and realization

  • style.frame.*
  • style.face.*
  • style.state_face.*
  • style.focus_ring.*
  • style.disabled.opacity : number
  • realization.family : string
  • realization.variant : string
  • realization.skin_id : string

8. frog.widgets.button

8.1 Class identity

  • class_id: frog.widgets.button
  • family: button_widget
  • compatible role: control

8.2 Value posture

  • primary value: present
  • value type: bool
  • natural value participation: optional and mechanical-action-dependent
  • mirrored property: value

8.3 Standard methods

  • focus()
  • press()
  • release()
  • activate()
  • click()
  • set_true()
  • set_false()
  • toggle()
  • reset_to_default()

8.4 Standard events

  • pressed
  • released
  • clicked
  • value_changed
  • hover_entered
  • hover_left
  • focus_gained
  • focus_lost

9. Default SVG Realization Posture

The default realization SHOULD support a parameterized rectangular SVG template, state-dependent color application, caption and internal state-text rendering, a single visible rectangular face with configurable border, optional frame / state-face surfaces for advanced realizations, and focus ring display.

The Default Button SVG template is the reusable visual grammar for examples and runtimes. Example sources may provide instance-level values, labels, layout, bindings, and style overrides, but they should reference the Default realization package and its published SVG assets instead of duplicating local button skins. 

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

10. State Resource Override Posture

The default button realization may be driven by one parameterized template SVG and may also publish optional state-specific SVG overrides.

The initial state-specific override names are:

  • false
  • true
  • hover_false
  • hover_true
  • transition_false_to_true
  • transition_true_to_false

Additional visual states such as pressed_false, pressed_true, disabled_false, disabled_true, focused_false, and focused_true may be represented by parameter binding or later explicit override assets.

11. Diagram Interaction Posture

The button supports object-style property access through frog.ui.property_read and frog.ui.property_write, method invocation through frog.ui.method_invoke, event observation through frog.ui.event_observe, and widget reference targeting through widget_reference.

When the button participates through a natural value path, that value path is mechanical-action-aware and may be relevant to latch reset. Object-style reads of value remain distinct from natural value consumption.

12. Validation Expectations

Validators SHOULD diagnose unknown mechanical actions, illegal value access for the selected button posture, unsupported state-resource overrides, attempts to use realization-only SVG layers as public class members, and attempts to make a skin or state asset redefine class semantics.

13. Summary

The standardized button defines the intrinsic command-oriented action widget of the FROG baseline:

  • frog.widgets.button

The button is a stateful command control with explicit mechanical-action behavior, event posture, internal state text, shared label / caption convention, and default SVG realization support with optional state-specific overrides.