99 lines
5.4 KiB
Markdown
99 lines
5.4 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common/Interface/TSRAIRGo/INavigationButtonInfo.cs
|
||
- Common/DTS.Common/Interface/TSRAIRGo/ArmStateMachineStates.cs
|
||
generated_at: "2026-04-16T02:58:05.648513+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "4d4fb80c3a1cb6b2"
|
||
---
|
||
|
||
# TSRAIRGo
|
||
|
||
## Documentation: `INavigationButtonInfo` Interface and `ArmStateMachineStates` Enum
|
||
|
||
---
|
||
|
||
### 1. Purpose
|
||
This module defines core data structures for UI state representation in the TSRAIRGo application. Specifically, the `INavigationButtonInfo` interface standardizes how navigation buttons are modeled—enabling consistent binding and control of button properties (e.g., text, tooltip, enabled state) across the UI layer. The `ArmStateMachineStates` enum captures the discrete operational states of the arm subsystem’s finite state machine (FSM), providing a typed, descriptive representation of arm lifecycle stages (e.g., disarmed, recording, faulted). Together, they support UI responsiveness to arm state changes and button state management.
|
||
|
||
---
|
||
|
||
### 2. Public Interface
|
||
|
||
#### `INavigationButtonInfo` interface
|
||
Defined in `DTS.Common.Interface.TSRAIRGo.INavigationButtonInfo`
|
||
- **`NavigationButtonId Id { get; }`**
|
||
Read-only identifier for the button. Used to uniquely reference the button in logic or event handling.
|
||
- **`string Text { get; set; }`**
|
||
Read-write display text shown on the button.
|
||
- **`string Tooltip { get; set; }`**
|
||
Read-write tooltip text shown on hover (or equivalent UI affordance).
|
||
- **`bool Enabled { get; set; }`**
|
||
Read-write flag indicating whether the button is interactive (i.e., not disabled).
|
||
- **`bool ShowBorder { get; set; }`**
|
||
Read-write flag controlling visual rendering—specifically, whether the button should display a border.
|
||
|
||
#### `ArmStateMachineStates.States` enum
|
||
Defined in `DTS.Common.Enums.TSRAIRGo.ArmStateMachineStates.States`
|
||
- **`CheckingArmState`**
|
||
Initial state verifying arm readiness.
|
||
- **`Disarmed`**
|
||
Arm is inactive and safe.
|
||
- **`IDLE`**
|
||
Arm is armed but not actively recording.
|
||
- **`PreparingForArming`**
|
||
Pre-flight checks and setup before arming.
|
||
- **`ClearingFlash`**
|
||
Flash memory is being cleared (e.g., prior to recording).
|
||
- **`WaitingForTrigger`**
|
||
Armed and ready, awaiting external trigger.
|
||
- **`Recording`**
|
||
Data acquisition is in progress.
|
||
- **`PostTestProcessing`**
|
||
Post-recording cleanup or analysis.
|
||
- **`CheckingForData`**
|
||
Verifying data integrity or availability post-test.
|
||
- **`GettingEventInfo`**
|
||
Retrieving event metadata (e.g., timestamps, annotations).
|
||
- **`ReadyForDownload`**
|
||
Data is ready for export/download.
|
||
- **`Faulted`**
|
||
An unrecoverable error has occurred; arm is non-operational.
|
||
|
||
> **Note**: Each enum value is annotated with a `[Description]` attribute (from `System.ComponentModel`) containing a human-readable label.
|
||
|
||
---
|
||
|
||
### 3. Invariants
|
||
- **`Id` is immutable**: Once instantiated, the `Id` property cannot be modified (read-only).
|
||
- **`Text`, `Tooltip`, `Enabled`, and `ShowBorder` are mutable**: All other properties are read-write, implying consumers may update them dynamically (e.g., in response to state changes).
|
||
- **`Enabled` and `ShowBorder` are boolean flags**: No validation beyond `true`/`false`; no semantic constraints (e.g., `ShowBorder = true` does not imply `Enabled = true`).
|
||
- **`ArmStateMachineStates.States` values are exhaustive and mutually exclusive**: The FSM is assumed to be in exactly one state at a time, though the interface does not enforce this.
|
||
|
||
---
|
||
|
||
### 4. Dependencies
|
||
|
||
#### This module depends on:
|
||
- `DTS.Common.Enums.TSRAIRGo.NavigationButtonId` (referenced in `INavigationButtonInfo.Id` but *not provided in source*).
|
||
- `System.ComponentModel` (for `[Description]` attribute usage in `ArmStateMachineStates`).
|
||
|
||
#### This module is depended upon by:
|
||
- UI components or view models that consume `INavigationButtonInfo` to render navigation controls.
|
||
- State machine logic that maps `ArmStateMachineStates` to UI updates (e.g., enabling/disabling buttons based on current arm state).
|
||
- Serialization/deserialization logic (e.g., for persisting button states or state transitions).
|
||
|
||
> **Note**: The `NavigationButtonId` type is referenced but not defined in the provided sources. Its definition is required to fully understand `INavigationButtonInfo`.
|
||
|
||
---
|
||
|
||
### 5. Gotchas
|
||
- **`NavigationButtonId` is undefined here**: Its type (e.g., `enum`, `struct`, `class`) and possible values are unknown from the provided sources. This is critical for interpreting `Id` semantics.
|
||
- **`ArmStateMachineStates.States` is nested**: The enum is declared inside a class (`ArmStateMachineStates`), not as a top-level type. Consumers must reference it as `ArmStateMachineStates.States`.
|
||
- **No validation on `Text`/`Tooltip`**: Empty strings or null values are permitted unless enforced elsewhere (e.g., in UI binding or view logic).
|
||
- **`ShowBorder` semantics are ambiguous**: Its purpose (e.g., visual styling, accessibility, theming) is not documented; behavior may vary by UI framework.
|
||
- **No state transition guarantees**: The enum describes states but does not define valid transitions or timing constraints.
|
||
- **`[Description]` attributes are metadata-only**: They do not affect runtime behavior unless explicitly consumed (e.g., via reflection for localization or logging).
|
||
|
||
None identified beyond the above. |