Skip to content

Commit 9cdba90

Browse files
claudeclaude
committed
Add standalone UI test harness for RmlUi development
Create comprehensive testing infrastructure for RmlUi UI development without requiring full SpringBoard backend. Enables rapid iteration and testing of UI components in isolation. Test Harness (scen_edit/view_rmlui/test/ui_test_harness.lua): - Mocks Spring.RmlUi API for testing without BAR Engine - Creates mock controllers (project, team, status) - Simulates user interactions (clicks, form input) - Automated test scenarios - Export mock data for inspection Mock Data (scen_edit/view_rmlui/test/mock_data.lua): - Realistic test data (projects, maps, teams, units, triggers) - Mock team/project/status controllers - Heightmap generation - Command history - Status messages Documentation (scen_edit/view_rmlui/test/README.md): - Usage examples - Test scenario documentation - Mock controller API reference - Contribution guidelines - Troubleshooting guide Benefits: - Rapid UI development without full game - Isolated component testing - Reproducible test scenarios - No backend dependencies for basic testing - Foundation for CI/CD integration Usage: SB.Include("scen_edit/view_rmlui/test/ui_test_harness.lua") RunUITests() Status: Foundation complete, ready for expanded test coverage Note: Directory naming (view_rmlui) will be cleaned up in next commit
1 parent 27dc6df commit 9cdba90

19 files changed

+3024
-0
lines changed

‎scen_edit/view/view_rmlui/README.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# SpringBoard RmlUi UI System
2+
3+
This directory contains the RmlUi-based UI system for SpringBoard, which is intended to replace the legacy Chili-based UI framework.
4+
5+
## Overview
6+
7+
RmlUi is a modern, HTML/CSS-like UI library that provides better performance and more flexibility than the older Chili framework. This conversion focuses on dialog components as they are more self-contained and easier to migrate independently.
8+
9+
## Directory Structure
10+
11+
```
12+
view_rmlui/
13+
├── init.lua # Main initialization file
14+
├── rmlui_manager.lua # RmlUi context and document management
15+
├── dialog/ # Dialog Lua classes
16+
│ ├── rmlui_dialog.lua # Base dialog class
17+
│ ├── rmlui_file_dialog.lua # File browser dialog
18+
│ ├── rmlui_new_project_dialog.lua
19+
│ ├── rmlui_save_project_dialog.lua
20+
│ └── rmlui_open_project_dialog.lua
21+
├── rml/ # RML templates (markup)
22+
│ ├── base_dialog.rml
23+
│ ├── file_dialog.rml
24+
│ └── new_project_dialog.rml
25+
└── rcss/ # RCSS stylesheets (CSS-like)
26+
└── dialog.rcss
27+
```
28+
29+
## Architecture
30+
31+
### RmlUi Manager (`rmlui_manager.lua`)
32+
33+
The RmlUi Manager handles:
34+
- RmlUi context creation and initialization
35+
- Document loading and lifecycle management
36+
- Input event routing (mouse, keyboard)
37+
- Rendering coordination
38+
- Screen resize handling
39+
40+
Usage:
41+
```lua
42+
-- Initialize (done automatically on first use)
43+
SB.rmlui:Initialize()
44+
45+
-- Load and show a document
46+
local doc = SB.rmlui:LoadDocument("path/to/document.rml", true)
47+
48+
-- Close a document
49+
SB.rmlui:CloseDocument(doc)
50+
```
51+
52+
### Dialog Classes
53+
54+
#### `RmlUiDialog` (Base Class)
55+
56+
The base dialog class provides:
57+
- Document loading and setup
58+
- Event binding for OK/Cancel buttons
59+
- Error message display
60+
- Field value getters/setters
61+
- Keyboard shortcuts (ESC to close, Enter to confirm)
62+
- Lifecycle management (Show/Hide/Close/Dispose)
63+
64+
Key methods:
65+
- `Show()` - Display the dialog
66+
- `Close()` - Close the dialog
67+
- `ConfirmDialog()` - Override to implement validation logic
68+
- `SetupDocument()` - Override to customize dialog setup
69+
- `GetFieldValue(id)` - Get value from form field
70+
- `SetFieldValue(id, value)` - Set value of form field
71+
- `SetDialogError(msg)` - Display error message
72+
73+
#### Specific Dialog Implementations
74+
75+
**`RmlUiNewProjectDialog`**
76+
- Creates new SpringBoard projects
77+
- Allows blank map generation with custom dimensions
78+
- Validates project name uniqueness
79+
80+
**`RmlUiFileDialog`**
81+
- Base class for file browser dialogs
82+
- Displays file/directory listings
83+
- Supports file selection and filtering
84+
85+
**`RmlUiSaveProjectDialog`**
86+
- Extends FileDialog for saving projects
87+
- Validates project name
88+
89+
**`RmlUiOpenProjectDialog`**
90+
- Extends FileDialog for opening projects
91+
- Validates that selected path is a valid SpringBoard project
92+
93+
### RML Templates
94+
95+
RML (RmlUi Markup Language) files define the structure and layout of dialogs using HTML-like syntax:
96+
97+
```xml
98+
<rml>
99+
<head>
100+
<title>Dialog Title</title>
101+
<link type="text/rcss" href="../rcss/dialog.rcss"/>
102+
</head>
103+
<body>
104+
<div class="dialog-window">
105+
<div class="field-container">
106+
<span class="field-label">Label:</span>
107+
<input type="text" id="fieldId" />
108+
</div>
109+
<button id="ok-button">OK</button>
110+
</div>
111+
</body>
112+
</rml>
113+
```
114+
115+
### RCSS Stylesheets
116+
117+
RCSS (RmlUi CSS) files define styling using CSS-like syntax:
118+
119+
```css
120+
.dialog-window {
121+
background-color: #2a2a2a;
122+
border: 2dp #444444;
123+
padding: 10dp;
124+
}
125+
126+
button {
127+
padding: 8dp 20dp;
128+
background-color: #3a3a3a;
129+
}
130+
```
131+
132+
## Widget Integration
133+
134+
The `api_sb_rmlui.lua` widget provides:
135+
- RmlUi framework initialization
136+
- Drawing/rendering integration
137+
- Input event forwarding
138+
- Screen resize handling
139+
140+
Layer: -999 (draws before other widgets, similar to Chili)
141+
142+
## Engine Requirements
143+
144+
RmlUi requires the BAR (Beyond All Reason) Engine or Recoil Engine fork:
145+
- BAR Engine 105.1.1-2472-ga5aa45c or later
146+
- Standard Spring engine 104.x does NOT support RmlUi
147+
148+
To use RmlUi, launch SpringBoard with the "BAR Engine" option.
149+
150+
## Usage Example
151+
152+
```lua
153+
-- Create and show a new project dialog
154+
local dialog = RmlUiNewProjectDialog()
155+
dialog:Show()
156+
157+
-- With custom confirm callback
158+
local dialog = RmlUiSaveProjectDialog()
159+
dialog:setConfirmDialogCallback(function(path)
160+
-- Custom validation
161+
if not isValidPath(path) then
162+
return false, "Invalid path"
163+
end
164+
165+
-- Save logic here
166+
saveProject(path)
167+
return true
168+
end)
169+
dialog:Show()
170+
```
171+
172+
## Migration from Chili
173+
174+
### Key Differences
175+
176+
| Aspect | Chili | RmlUi |
177+
|--------|-------|-------|
178+
| **Markup** | Programmatic Lua | Declarative RML |
179+
| **Styling** | Lua skin tables | RCSS files |
180+
| **Layout** | Manual positioning | Flexbox/CSS layouts |
181+
| **Events** | Callback tables | Event listeners |
182+
| **Performance** | Lua-heavy | C++ rendering |
183+
184+
### Conversion Checklist
185+
186+
1. Create RML template for UI structure
187+
2. Create/update RCSS stylesheet for styling
188+
3. Create Lua class extending `RmlUiDialog`
189+
4. Implement `SetupDocument()` for initialization
190+
5. Implement `ConfirmDialog()` for validation
191+
6. Bind event listeners in `BindEvents()`
192+
7. Replace Chili dialog calls with RmlUi equivalents
193+
194+
## Current Status
195+
196+
**Completed:**
197+
- ✅ RmlUi Manager infrastructure
198+
- ✅ Base Dialog class
199+
- ✅ NewProjectDialog
200+
- ✅ FileDialog
201+
- ✅ SaveProjectDialog
202+
- ✅ OpenProjectDialog
203+
- ✅ Widget integration
204+
205+
**TODO:**
206+
- ⏳ Convert remaining dialogs
207+
- ⏳ Convert main UI panels
208+
- ⏳ Convert field editors
209+
- ⏳ Convert map editors
210+
- ⏳ Convert trigger system UI
211+
- ⏳ Full Chili replacement
212+
213+
## Testing
214+
215+
To test RmlUi dialogs:
216+
217+
1. Launch SpringBoard with BAR Engine
218+
2. The RmlUi widget should initialize automatically
219+
3. Dialog classes can be instantiated and shown:
220+
```lua
221+
local dlg = RmlUiNewProjectDialog()
222+
dlg:Show()
223+
```
224+
225+
## Known Limitations
226+
227+
1. **File Dialog**: File browser population is simplified and may need VFS integration improvements
228+
2. **Field Types**: Only basic input fields implemented; complex field types (color pickers, asset browsers) need conversion
229+
3. **AssetView**: The file browser component used in FileDialog needs full implementation
230+
4. **Styling**: RCSS styling may need refinement to match Chili appearance
231+
232+
## API Compatibility Notes
233+
234+
The RmlUi Lua API in Spring/Recoil may differ from standard RmlUi documentation. Current implementation assumes:
235+
236+
- `Spring.RmlUi.CreateContext(name, width, height)` - Create context
237+
- `context:LoadDocument(path)` - Load RML document
238+
- `document:Show()`, `document:Close()` - Document lifecycle
239+
- `document:GetElementById(id)` - Element access
240+
- `element.inner_rml` - Get/set element content
241+
- `element:SetProperty(name, value)` - Set CSS property
242+
- `element:AddEventListener(event, callback)` - Event binding
243+
244+
If actual API differs, adjust `rmlui_manager.lua` accordingly.
245+
246+
## Contributing
247+
248+
When converting additional UI components to RmlUi:
249+
250+
1. Follow existing naming conventions (RmlUi prefix)
251+
2. Place RML templates in `rml/`
252+
3. Place stylesheets in `rcss/`
253+
4. Place Lua classes in appropriate subdirectories
254+
5. Update `init.lua` to include new files
255+
6. Document changes in this README
256+
257+
## References
258+
259+
- [RmlUi Documentation](https://mikke89.github.io/RmlUiDoc/)
260+
- [Recoil Engine Documentation](https://beyond-all-reason.github.io/RecoilEngine/)
261+
- [Spring RTS Wiki](https://springrts.com/wiki/)

0 commit comments

Comments
 (0)