mirror of
https://github.com/gui-cs/Terminal.Gui.git
synced 2025-12-30 01:38:01 +01:00
320 lines
16 KiB
Markdown
320 lines
16 KiB
Markdown
# Application.Run Terminology - Visual Guide
|
|
|
|
## The Two Problems
|
|
|
|
### Problem 1: RunState Sounds Like State Data
|
|
|
|
```
|
|
Current (Confusing):
|
|
┌─────────────────────────────────────┐
|
|
│ RunState rs = Begin(window); │ ← "State"? What state does it hold?
|
|
│ │
|
|
│ Application.RunLoop(rs); │
|
|
│ │
|
|
│ Application.End(rs); │
|
|
└─────────────────────────────────────┘
|
|
|
|
Users think: "What state information does RunState contain?"
|
|
Reality: It's a token/handle for the Begin/End pairing
|
|
|
|
|
|
Proposed (Clear):
|
|
┌─────────────────────────────────────┐
|
|
│ RunToken token = Begin(window); │ ✅ Clear: it's a token, not state
|
|
│ │
|
|
│ Application.RunLoop(token); │
|
|
│ │
|
|
│ Application.End(token); │
|
|
└─────────────────────────────────────┘
|
|
|
|
Users understand: "It's a token for the Begin/End pairing"
|
|
```
|
|
|
|
### Problem 2: EndAfterFirstIteration Confuses End() with Loop Control
|
|
|
|
```
|
|
Current (Confusing):
|
|
┌──────────────────────────────────────────┐
|
|
│ EndAfterFirstIteration = true; │ ← "End"? Like End() method?
|
|
│ │
|
|
│ RunState rs = Begin(window); │
|
|
│ │
|
|
│ RunLoop(rs); // Stops after 1 iteration│
|
|
│ │
|
|
│ End(rs); // This is "End" │
|
|
└──────────────────────────────────────────┘
|
|
|
|
Users think: "Does EndAfterFirstIteration call End()?"
|
|
Reality: It controls RunLoop() behavior, not End()
|
|
|
|
|
|
Proposed (Clear):
|
|
┌──────────────────────────────────────────┐
|
|
│ StopAfterFirstIteration = true; │ ✅ Clear: controls loop stopping
|
|
│ │
|
|
│ RunToken token = Begin(window); │
|
|
│ │
|
|
│ RunLoop(token); // Stops after 1 iter │
|
|
│ │
|
|
│ End(token); // Cleanup │
|
|
└──────────────────────────────────────────┘
|
|
|
|
Users understand: "Stop controls the loop, End cleans up"
|
|
```
|
|
|
|
## Understanding RunLoop vs RunIteration
|
|
|
|
**This distinction is valuable and should be preserved:**
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ RunLoop(token) │
|
|
│ │
|
|
│ Starts the driver's MainLoop │
|
|
│ Loops until stopped: │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────┐ │
|
|
│ │ while (toplevel.Running) │ │
|
|
│ │ { │ │
|
|
│ │ RunIteration(ref token); ←──────────┐ │ │
|
|
│ │ RunIteration(ref token); ←──────────┤ │ │
|
|
│ │ RunIteration(ref token); ←──────────┤ │ │
|
|
│ │ ... │ │ │
|
|
│ │ } │ │ │
|
|
│ └────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
│
|
|
│
|
|
┌─────────────▼───────────────┐
|
|
│ RunIteration(ref token) │
|
|
│ │
|
|
│ Processes ONE iteration: │
|
|
│ 1. Process driver events │
|
|
│ 2. Layout (if needed) │
|
|
│ 3. Draw (if needed) │
|
|
│ │
|
|
│ Returns immediately │
|
|
└─────────────────────────────┘
|
|
|
|
Key Insight:
|
|
- RunLoop = The LOOP itself (blocking, manages iterations)
|
|
- RunIteration = ONE iteration (immediate, processes events)
|
|
```
|
|
|
|
## Complete Lifecycle Visualization
|
|
|
|
```
|
|
Application.Run(window)
|
|
┌───────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ 1. Begin(window) → RunToken │
|
|
│ ┌─────────────────────────────────┐ │
|
|
│ │ • Initialize window │ │
|
|
│ │ • Layout views │ │
|
|
│ │ • Draw to screen │ │
|
|
│ └─────────────────────────────────┘ │
|
|
│ │
|
|
│ 2. RunLoop(token) │
|
|
│ ┌─────────────────────────────────┐ │
|
|
│ │ Start driver's MainLoop │ │
|
|
│ │ │ │
|
|
│ │ while (Running) { │ │
|
|
│ │ RunIteration(ref token) │ │
|
|
│ │ ├─ Process events │ │
|
|
│ │ ├─ Layout (if needed) │ │
|
|
│ │ └─ Draw (if needed) │ │
|
|
│ │ } │ │
|
|
│ │ │ │
|
|
│ │ Exits when: │ │
|
|
│ │ - RequestStop() called │ │
|
|
│ │ - StopAfterFirstIteration=true │ │
|
|
│ └─────────────────────────────────┘ │
|
|
│ │
|
|
│ 3. End(token) │
|
|
│ ┌─────────────────────────────────┐ │
|
|
│ │ • Cleanup window │ │
|
|
│ │ • Dispose token │ │
|
|
│ └─────────────────────────────────┘ │
|
|
│ │
|
|
└───────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Manual Control Pattern
|
|
|
|
When you need fine-grained control:
|
|
|
|
```
|
|
┌────────────────────────────────────────────┐
|
|
│ RunToken token = Begin(window); │
|
|
│ StopAfterFirstIteration = true; │ ✅ Clear: stop after one iter
|
|
│ │
|
|
│ while (!myCondition) │
|
|
│ { │
|
|
│ // Process one iteration │
|
|
│ RunIteration(ref token, first); │
|
|
│ first = false; │
|
|
│ │
|
|
│ // Your custom logic here │
|
|
│ DoCustomProcessing(); │
|
|
│ } │
|
|
│ │
|
|
│ End(token); │
|
|
└────────────────────────────────────────────┘
|
|
|
|
vs Old (Confusing):
|
|
|
|
┌────────────────────────────────────────────┐
|
|
│ RunState rs = Begin(window); │
|
|
│ EndAfterFirstIteration = true; │ ❌ Confusing: sounds like End()
|
|
│ │
|
|
│ while (!myCondition) │
|
|
│ { │
|
|
│ RunIteration(ref rs, first); │
|
|
│ first = false; │
|
|
│ DoCustomProcessing(); │
|
|
│ } │
|
|
│ │
|
|
│ End(rs); │
|
|
└────────────────────────────────────────────┘
|
|
```
|
|
|
|
## RequestStop Flow
|
|
|
|
```
|
|
User Action (e.g., Quit Key)
|
|
│
|
|
▼
|
|
┌────────────────────────┐
|
|
│ RequestStop(window) │ ✅ Keep: "Request" is clear
|
|
└────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────┐
|
|
│ window.Running=false │
|
|
└────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────┐
|
|
│ RunLoop exits │
|
|
└────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────┐
|
|
│ End() cleans up │
|
|
└────────────────────────┘
|
|
```
|
|
|
|
## What We're Keeping
|
|
|
|
```
|
|
✅ KEEP AS-IS:
|
|
|
|
Begin/End
|
|
┌──────────────────┐ ┌──────────────────┐
|
|
│ Begin(window) │ ... │ End(token) │
|
|
└──────────────────┘ └──────────────────┘
|
|
↑ ↑
|
|
│ │
|
|
Clear, concise Clear, concise
|
|
Not wordy Not wordy
|
|
|
|
|
|
RequestStop
|
|
┌─────────────────────┐
|
|
│ RequestStop() │
|
|
└─────────────────────┘
|
|
↑
|
|
│
|
|
"Request" appropriately
|
|
conveys non-blocking
|
|
|
|
|
|
RunLoop / RunIteration
|
|
┌─────────────────┐ ┌──────────────────┐
|
|
│ RunLoop() │ │ RunIteration() │
|
|
│ (the loop) │ │ (one iteration) │
|
|
└─────────────────┘ └──────────────────┘
|
|
↑ ↑
|
|
│ │
|
|
Distinction is important and valuable
|
|
```
|
|
|
|
## Side-by-Side Summary
|
|
|
|
```
|
|
╔═══════════════════════════════════╦═══════════════════════════════════╗
|
|
║ CURRENT ║ PROPOSED ║
|
|
╠═══════════════════════════════════╬═══════════════════════════════════╣
|
|
║ RunState rs = Begin(window); ║ RunToken token = Begin(window); ║
|
|
║ EndAfterFirstIteration = true; ║ StopAfterFirstIteration = true; ║
|
|
║ RunLoop(rs); ║ RunLoop(token); ║
|
|
║ End(rs); ║ End(token); ║
|
|
║ ║ ║
|
|
║ ❌ "State" misleading ║ ✅ "Token" clear ║
|
|
║ ❌ "End" confuses with End() ║ ✅ "Stop" aligns with RequestStop║
|
|
╚═══════════════════════════════════╩═══════════════════════════════════╝
|
|
```
|
|
|
|
## Terminology Mapping
|
|
|
|
```
|
|
CHANGE (2 names):
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
RunState → RunToken
|
|
EndAfterFirstIteration → StopAfterFirstIteration
|
|
|
|
|
|
KEEP UNCHANGED:
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
Begin → Begin ✅
|
|
End → End ✅
|
|
RequestStop → RequestStop ✅
|
|
RunLoop → RunLoop ✅
|
|
RunIteration → RunIteration ✅
|
|
Run → Run ✅
|
|
```
|
|
|
|
## Benefits Visualized
|
|
|
|
```
|
|
Before:
|
|
┌─────────────────────────────────────────┐
|
|
│ Users think: │
|
|
│ • "What state does RunState hold?" │
|
|
│ • "Does EndAfterFirstIteration call │
|
|
│ End()?" │
|
|
│ │
|
|
│ Result: Confusion, questions │
|
|
└─────────────────────────────────────────┘
|
|
|
|
After:
|
|
┌─────────────────────────────────────────┐
|
|
│ Users understand: │
|
|
│ • "RunToken is a token" │
|
|
│ • "StopAfterFirstIteration controls │
|
|
│ the loop" │
|
|
│ │
|
|
│ Result: Clear, self-documenting │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
## Summary
|
|
|
|
**2 Changes Only:**
|
|
- `RunState` → `RunToken` (clear it's a token)
|
|
- `EndAfterFirstIteration` → `StopAfterFirstIteration` (clear it controls loop)
|
|
|
|
**Everything Else Stays:**
|
|
- `Begin` / `End` - Clear and concise
|
|
- `RequestStop` - Appropriately non-blocking
|
|
- `RunLoop` / `RunIteration` - Valuable distinction
|
|
|
|
**Result:**
|
|
- ✅ Addresses confusion at the source
|
|
- ✅ Minimal disruption (2 names)
|
|
- ✅ Preserves what works well
|
|
- ✅ Respects maintainer feedback
|
|
|
|
See [TERMINOLOGY_PROPOSAL.md](TERMINOLOGY_PROPOSAL.md) for complete analysis.
|