UI Layout Definition Draw Tool — Implementation Proposal

Version: 0.1.0 Platform: Android (APK), native C++ compiled with Clang in Termux Target Spec: UI Layout Definition Format v1.6

1. Project Overview

A lightweight Android application for visually designing UI layouts conforming to the ui-layout-def XML specification (v1.6). The tool enables selecting a control set, drawing wireframes by placing controls from a toolbox, creating windows with slot overrides, editing control properties, and saving/loading/validating XML files against the XSD schemas.

The app is built entirely in C++ using the Android NDK toolchain available in Termux, with no Java/Kotlin layer — pure NativeActivity + OpenGL ES or Skia for rendering.

2. Architecture

2.1 High-Level Component Diagram

┌─────────────────────────────────────────────────────┐
│                    Android APK                       │
│  ┌───────────────────────────────────────────────┐  │
│  │              NativeActivity (C++)              │  │
│  │  ┌─────────┐ ┌──────────┐ ┌───────────────┐  │  │
│  │  │ UI Core │ │ Renderer │ │ Input Handler │  │  │
│  │  │ (ImGui) │ │(GLES 2.0)│ │ (touch/keys)  │  │  │
│  │  └────┬────┘ └─────┬────┘ └───────┬───────┘  │  │
│  │       │            │              │           │  │
│  │  ┌────▼────────────▼──────────────▼───────┐   │  │
│  │  │           Application Core             │   │  │
│  │  │  ┌────────────┐  ┌──────────────────┐  │   │  │
│  │  │  │  Document   │  │  Control         │  │   │  │
│  │  │  │  Model      │  │  Registry        │  │   │  │
│  │  │  │  (DOM tree) │  │  (parsed XMLs)   │  │   │  │
│  │  │  └──────┬─────┘  └────────┬─────────┘  │   │  │
│  │  │         │                 │             │   │  │
│  │  │  ┌──────▼─────────────────▼──────────┐  │   │  │
│  │  │  │         XML Engine                │  │   │  │
│  │  │  │  ┌──────────┐  ┌──────────────┐   │  │   │  │
│  │  │  │  │ pugixml  │  │ libxml2 XSD  │   │  │   │  │
│  │  │  │  │ (R/W)    │  │ (validation) │   │  │   │  │
│  │  │  │  └──────────┘  └──────────────┘   │  │   │  │
│  │  │  └───────────────────────────────────┘  │   │  │
│  │  └─────────────────────────────────────────┘   │  │
│  └───────────────────────────────────────────────┘  │
│                  ┌───────────────┐                   │
│                  │  File System  │                   │
│                  │  (storage)    │                   │
│                  └───────────────┘                   │
└─────────────────────────────────────────────────────┘

2.2 Key Technology Choices

Component	Library	Rationale
UI Framework	Dear ImGui (docking branch)	Immediate-mode GUI, trivial to embed in NativeActivity, excellent for toolbox/property panels, zero Java dependency
Rendering	OpenGL ES 2.0 via EGL	Universal Android support, ImGui has a backend for it
XML Parsing/Writing	pugixml	Header-only C++, lightweight, DOM-based — perfect fit for ui-layout-def tree manipulation
XSD Validation	libxml2	The only practical C library with XSD schema validation; available in Termux (`pkg install libxml2`)
Touch/Input	android_native_app_glue	Standard NDK input handling for NativeActivity
Build System	CMake + NDK via Termux	`pkg install android-ndk cmake` in Termux
File Dialogs	Custom ImGui panel	Browsing `/sdcard/` for open/save since there's no native file picker in NativeActivity

2.3 Why Not SDL2 / Other Frameworks?

SDL2 is an option but adds an unnecessary abstraction layer. NativeActivity + android_native_app_glue + ImGui is more direct, smaller APK, and gives full control over the GL context lifecycle. If future versions need audio or gamepad input, SDL2 can be introduced later.

3. Data Model

3.1 Control Registry

On startup, the app parses the control definition XML files (abstract-controls.xml, avalonia-controls.xml, winform-controls.xml, webawesome-controls.xml) using pugixml. Each parsed control becomes an entry in a ControlRegistry:

struct ControlDef {
    std::string name;           // "TextBox", "Panel", "wa-button"
    std::string type;           // "input", "container", "display"
    std::string category;       // "basic", "avalonia-input", etc.
    std::string inherits;       // "CommonControl"
    std::string platform;       // "basic", "avalonia", "web"
    std::string description;
    bool is_container;
    std::vector<std::string> allowed_parents;
    std::vector<std::string> allowed_children;
    std::vector<AttributeDef> attributes;
    std::vector<EventDef> events;
};

struct AttributeDef {
    std::string name;
    std::string type;       // "string", "int", "bool", "enum"
    std::string default_val;
    bool required;
    int min, max;
    std::string values;     // comma-separated enum values
};

class ControlRegistry {
    std::unordered_map<std::string, ControlDef> controls_;
    // Grouped by control set for toolbox display
    std::map<std::string, std::vector<std::string>> by_category_;
public:
    void load_control_set(const std::string& xml_path);
    const ControlDef* find(const std::string& name) const;
    void resolve_inheritance();  // flatten inherited attributes
};

The registry resolves inherits chains so each ControlDef has the full merged attribute list from CommonControl down to the specific control.

3.2 Document Model

The working document is an in-memory tree mirroring the ui-layout-def XML structure:

// Represents a placed control instance on the canvas
struct ControlInstance {
    std::string id;             // unique within document
    std::string control_name;   // reference to ControlDef
    float x, y, w, h;          // canvas position/size
    std::map<std::string, std::string> properties;  // attribute overrides
    std::vector<ControlInstance*> children;
    ControlInstance* parent;
};

// A wireframe definition
struct WireframeDef {
    std::string name;
    std::string type;
    std::vector<SlotDef> slots;    // named regions
    ControlInstance* root_layout;  // the template tree
};

// A window definition
struct WindowDef {
    std::string name;
    std::string title;
    std::string wireframe_ref;     // optional wireframe name
    std::string view_ref;          // optional view name
    std::string target_platform;
    // Either template (free-form) or slot-overrides
    ControlInstance* template_root;
    std::map<std::string, ControlInstance*> slot_overrides;
};

// Root document
struct Document {
    std::string version = "1.6";
    std::string target_platform = "basic";
    std::vector<std::string> pattern_includes;
    std::vector<WireframeDef> wireframes;
    std::vector<WindowDef> windows;
    // views, validation-rules stored as raw pugixml nodes
    // (v0.1 focuses on patterns+windows)
    pugi::xml_document raw_doc;  // for round-tripping unsupported sections
    std::string file_path;
    bool modified = false;
};

3.3 Round-Trip XML Fidelity

Sections the tool doesn't visually edit (views, validation-rules, state-management, etc.) are preserved as raw XML nodes via pugixml's DOM. When saving, the tool:

Serializes patterns (from registry selection)
Serializes wireframes (from canvas)
Serializes windows (from canvas)
Preserves untouched sections verbatim

This guarantees no data loss when editing files created by hand or other tools.

4. Feature Implementation

4.1 Feature 1 — Create New UI Definition (Control Set Selection)

Flow:

User taps "New" → modal dialog presents control set options:
- Abstract only (basic controls)
- Abstract + WinForms
- Abstract + Avalonia
- Abstract + Web Awesome
- Custom combination (multi-select)
User selects target platform (basic, winforms, avalonia, web, mixed)
App creates a new Document with appropriate <pattern-include> entries
Control registry loads/filters to the selected sets
Toolbox panel populates with available controls grouped by category

Control set files bundled in APK assets:

File	Control Set
`abstract-controls.xml`	Always loaded — base controls
`winform-controls.xml`	WinForms-specific controls
`avalonia-controls.xml`	Avalonia-specific controls
`webawesome-controls.xml`	Web Awesome components

The XSD schemas are also bundled for validation.

4.2 Feature 2 — Wireframe Drawing (Canvas + Toolbox)

Canvas:

OpenGL ES 2.0 rendered surface, ImGui draw-list overlay
Pan (two-finger drag) and zoom (pinch) with transform matrix
Grid snap (configurable: 4px, 8px, 16px, 32px)
Each control renders as a labeled rectangle with type icon
Container controls show dotted border and accept children via drag-drop
Selection: tap to select, long-press for context menu
Multi-select via lasso or Shift+tap (with external keyboard)

Toolbox panel (left sidebar, collapsible):

Accordion-style categories: Display, Input, Container, List, Navigation, etc.
Each entry shows control name + small icon
Tap a toolbox item → enters "placement mode" → tap canvas to place
Alternative: drag from toolbox to canvas (if touch precision allows)

Wireframe creation:

User defines a wireframe via menu: "New Wireframe" → name + type
Places container controls (Panel, SplitPanel, TabControl) as layout skeleton
Marks named slots within containers (right-click → "Mark as Slot" → enter slot name)
Slot regions render with distinct dashed border + slot label

Rendering style for v0.1:

Simple rectangles with rounded corners
Control type name rendered inside
Container nesting shown by indentation/border hierarchy
Color-coding by control type (blue=input, green=display, gray=container, orange=list)

4.3 Feature 3 — Window Creation (Wireframe Overrides + Standalone)

Two modes:

A) Window with wireframe reference:

User creates window → selects an existing wireframe
Canvas shows the wireframe layout with slot regions highlighted
User drags controls into slot regions → creates <slot-overrides>
Non-slot areas are read-only (inherited from wireframe)
Slot content is freely editable

B) Standalone window (no wireframe):

User creates window → skips wireframe selection
Blank canvas → builds layout from scratch using <template> mode
Can reference a <structure> pattern or build free-form

Window list panel (right sidebar):

Tree view: Document → Wireframes → Windows
Shows wireframe→window relationships
Double-click to open a window on the canvas
Multiple windows can be open as tabs

4.4 Feature 4 — Property Editor

When a control is selected on the canvas, the Properties panel shows:

Identity section: name (editable), control type (read-only), category
Layout section: x, y, width, height, dock, anchor, margin, padding
Appearance section: background-color, foreground-color, font-*, visible, enabled
Type-specific section: attributes from the ControlDef (e.g., max-length for TextBox, paging-enabled for Gallery)
Data binding section: data-source, binding properties
Raw XML: advanced toggle to see/edit raw XML attributes

Property editors by attribute type:

string → text input
int → numeric input with min/max clamp and slider
bool → checkbox
enum → dropdown (populated from values attribute)
color → color picker widget (ImGui has one built-in)

Validation feedback: red highlight on properties that fail constraints (min/max, required).

4.5 Feature 5 — Save to XML File

Serialization pipeline:

Document model → pugixml DOM tree → formatted XML string → file

Build <ui-layout-def> root with version, schema-version, target-platform attributes
Build <patterns> with <pattern-include> elements for selected control sets
For each wireframe → build <wireframe> with <template> containing the layout tree
For each window:
- If wireframe-based → <window wireframe="..."> with <slot-overrides>
- If standalone → <window> with <template> content
Preserve raw sections (views, validation-rules) from original load
Save to user-specified path (default: /sdcard/Documents/ui-layout/)

File naming: {document-name}.xml with .xml extension enforced.

Auto-save: optional, every 60 seconds to ~/.uidef-autosave/.

4.6 Feature 6 — Open Existing XML File

Loading pipeline:

File → pugixml parse → Document model population → Canvas render

Parse XML with pugixml
Read root attributes (version, platform, schema-version)
Load <pattern-include> entries → resolve control registry
Parse <wireframe> elements → build wireframe canvas objects
Parse <window> elements → build window canvas objects with control instances
Sections not visually editable → store as raw DOM nodes
Handle parse errors gracefully with error dialog listing issues

Version compatibility: warn if schema-version != "1.6" but attempt to load anyway.

4.7 Feature 7 — XSD Validation

Using libxml2 for schema validation:

#include <libxml/xmlschemastypes.h>

bool validate_against_schema(const std::string& xml_path,
                             const std::string& xsd_path) {
    xmlSchemaParserCtxtPtr parser_ctx =
        xmlSchemaNewParserCtxt(xsd_path.c_str());
    xmlSchemaPtr schema = xmlSchemaParse(parser_ctx);
    xmlSchemaValidCtxtPtr valid_ctx =
        xmlSchemaNewValidCtxt(schema);

    // Collect errors via callback
    xmlSchemaSetValidErrors(valid_ctx, error_cb, warning_cb, &errors);

    int ret = xmlSchemaValidateFile(valid_ctx, xml_path.c_str(), 0);

    // cleanup...
    return ret == 0;
}

Validation workflow:

User taps "Validate" toolbar button
App serializes current document to temp file
Runs libxml2 validation against ui-layout-def.xsd (which imports all sub-schemas)
Results displayed in a scrollable error/warning panel at bottom
Tapping an error highlights the relevant control on canvas
Errors categorized: Schema errors, Constraint violations, Warnings

Bundled XSD files:

Schema	Purpose
`ui-layout-def.xsd`	Root document structure
`ui-layout-patterns.xsd`	Controls, structures, wireframes
`ui-layout-views.xsd`	View definitions
`ui-layout-validation.xsd`	Validation rules, profiles
`ui-layout-basic-controls.xsd`	Basic control types
`ui-layout-winforms-controls.xsd`	WinForms controls
`ui-layout-avalonia-controls.xsd`	Avalonia controls
`ui-layout-webawesome-controls.xsd`	Web Awesome controls

5. UI Layout of the App Itself

┌──────────────────────────────────────┐
│ Toolbar: [☰] [New][Open][Save][✓Val] │
├──────────────────────────────────────┤
│                                      │
│         Canvas                       │
│         (wireframe/window            │
│          drawing area)               │
│                                      │
│    ┌──────────────────┐              │
│    │  Panel            │             │
│    │  ┌──────────────┐ │             │
│    │  │  TextBox      │ │             │
│    │  └──────────────┘ │             │
│    │  ┌──────────────┐ │             │
│    │  │  Button       │ │             │
│    │  └──────────────┘ │             │
│    └──────────────────┘              │
│                                      │
├──────────────────────────────────────┤
│  Doc Tree / Validation (collapsible) │
│  ▸ Wireframes                        │
│    ▸ MainLayout (3 slots)            │
│  ▸ Windows                           │
│    ▸ ProductListWindow               │
└──────────────────────────────────────┘

 ◄ Swipe from left        Swipe from right ►
┌────────────┐            ┌────────────────┐
│  Toolbox   │            │  Properties    │
│            │            │                │
│ [Label]    │            │ Name: ________ │
│ [TextBox]  │            │ X: ___  Y: ___ │
│ [Button]   │            │ W: ___  H: ___ │
│ [Panel]    │            │ dock: [none ▾] │
│ [SplitPnl] │            │ enabled: [☑]   │
│ [TabCtrl]  │            │ visible: [☑]   │
│ [ListBox]  │            │                │
│ [DataGrid] │            │ --- Type ---   │
│ [Tree]     │            │ maxLen: [255]  │
│  ...       │            │ placeholder: _ │
└────────────┘            └────────────────┘

Portrait layout behavior:

Canvas occupies the full width, maximizing vertical drawing space
Toolbox slides in from the left edge (swipe or hamburger menu)
Properties panel slides in from the right edge (swipe or tap selected control)
Bottom panel (document tree / validation output) is collapsible with a drag handle
Toolbar stays fixed at the top

6. Build System & Toolchain

6.1 Termux Setup

# Install required packages
pkg install clang cmake make ndk-sysroot android-ndk
pkg install libxml2 git

# Clone project
mkdir -p ~/uidef-tool && cd ~/uidef-tool

# External dependencies (header-only or source-included)
# pugixml: single header+source, copy into project
# imgui: clone docking branch
# imgui backends: imgui_impl_opengl3 + imgui_impl_android

6.2 CMake Structure

uidef-tool/
├── CMakeLists.txt
├── src/
│   ├── main.cpp                  # NativeActivity entry point
│   ├── app.h / app.cpp           # Application lifecycle
│   ├── canvas/
│   │   ├── canvas.h / .cpp       # Drawing surface + transform
│   │   ├── grid.h / .cpp         # Snap grid rendering
│   │   └── selection.h / .cpp    # Selection + multi-select
│   ├── model/
│   │   ├── document.h / .cpp     # Document root
│   │   ├── control_instance.h    # Placed control
│   │   ├── wireframe_def.h       # Wireframe
│   │   ├── window_def.h          # Window
│   │   └── control_registry.h    # Registry
│   ├── xml/
│   │   ├── xml_reader.h / .cpp   # Load from XML (pugixml)
│   │   ├── xml_writer.h / .cpp   # Save to XML (pugixml)
│   │   └── xsd_validator.h / .cpp# Validate (libxml2)
│   ├── ui/
│   │   ├── toolbox.h / .cpp      # Toolbox panel
│   │   ├── properties.h / .cpp   # Property editor
│   │   ├── doc_tree.h / .cpp     # Document tree panel
│   │   ├── toolbar.h / .cpp      # Top toolbar
│   │   ├── file_dialog.h / .cpp  # Open/save file browser
│   │   └── validation_panel.h    # Validation results
│   └── util/
│       ├── undo_redo.h / .cpp    # Undo/redo stack
│       └── platform.h / .cpp     # Android-specific helpers
├── assets/                        # Bundled into APK
│   ├── schemas/                   # All .xsd files
│   ├── controls/                  # Control definition .xml files
│   └── fonts/                     # ImGui font (e.g. Roboto)
├── third_party/
│   ├── pugixml/
│   ├── imgui/                     # docking branch
│   └── imgui_backends/
└── android/
    └── AndroidManifest.xml

6.3 Build & Package

# Configure
cmake -B build \
  -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-26 \
  -DCMAKE_BUILD_TYPE=Release

# Build
cmake --build build -j$(nproc)

# Package APK (using aapt2 + apksigner from build-tools)
# Script provided in android/build-apk.sh

7. Milestone Plan

Milestone 1 — Skeleton (weeks 1–2)

NativeActivity + OpenGL ES + ImGui rendering loop
Basic toolbar, empty canvas with pan/zoom
ImGui docking layout (toolbox, canvas, properties, bottom panel)

Milestone 2 — Control Registry + Toolbox (weeks 3–4)

Parse abstract-controls.xml with pugixml
Populate toolbox from registry
Control set selection dialog (new document flow)

Milestone 3 — Canvas Drawing (weeks 5–7)

Place controls on canvas from toolbox
Drag to move, resize handles
Container nesting (parent-child relationships)
Grid snap
Selection + multi-select
Undo/redo

Milestone 4 — Property Editor (week 8)

Display selected control's attributes
Editable fields by type (text, int, bool, enum, color)
Constraint validation (min/max, required)
Layout properties (x, y, w, h, dock, anchor)

Milestone 5 — Wireframes & Windows (weeks 9–11)

Wireframe definition: create, name, template editing
Slot marking within wireframes
Window creation: wireframe-based with slot overrides
Window creation: standalone with template
Document tree panel with window/wireframe hierarchy

Milestone 6 — XML I/O (weeks 12–13)

Save document to .xml (serialization with pugixml)
Open existing .xml files (deserialization)
File browser dialog
Round-trip preservation of non-visual sections
Auto-save

Milestone 7 — XSD Validation (week 14)

Integrate libxml2 schema validation
Validation results panel with error navigation
Error-to-canvas-element mapping

Milestone 8 — Polish & Package (weeks 15–16)

APK packaging script
Touch input refinement (long-press, gestures)
Performance optimization (large documents)
Responsive layout for phones vs tablets
Testing with sample documents

8. Risks & Mitigations

Risk	Impact	Mitigation
libxml2 XSD validation may not handle all schema features (imports, complex types)	Validation incomplete	Test early with all bundled XSDs; fallback to partial validation reporting
Touch precision for small controls	Poor UX on phones	Configurable zoom + snap grid; "precision mode" toggle; portrait orientation maximizes canvas width
ImGui text input on Android soft keyboard	Keyboard may not work well	Use ImGui's Android backend which handles IME; test early
Large documents (100+ controls)	Performance	Use ImGui viewport culling; lazy render off-screen controls
APK signing in Termux	Can't install	Use `apksigner` from Android SDK build-tools; document setup
NDK version compatibility	Build failures	Pin NDK version in CMakeLists.txt; document tested versions

9. Future Versions (Post 0.1)

v0.2: View definitions editor (state management, accessibility, performance sections); Gallery box-template visual editor
v0.3: Live preview — render actual platform-like controls instead of rectangles
v0.4: External includes resolution — load <pattern-include src="..."> from external files
v0.5: Multi-file project support — manage a collection of includes + main file
v0.6: Code generation — emit platform-specific code (XAML, HTML, WinForms designer)
v1.0: Collaboration — share/import control libraries; theming preview

10. Dependencies Summary

Dependency	Version	License	Size	Purpose
Dear ImGui	1.91+ (docking)	MIT	~400KB src	UI framework
pugixml	1.14+	MIT	~300KB src	XML DOM read/write
libxml2	2.12+	MIT	~5MB .so	XSD validation
Android NDK	r26+	Apache 2.0	(system)	Toolchain
Roboto Font	—	Apache 2.0	~150KB	UI font

Total estimated APK size: ~8–12 MB (Release, arm64-v8a only).

11. Open Questions

Gallery control editor — The Gallery box-template with visual element placement is complex. Should v0.1 support visual editing of <box-template> or defer to raw XML editing? Decision: Deferred to v0.2.0. In v0.1.0 the Gallery renders as a compact block on canvas; box-template content is not visually editable.
Web Awesome controls — These have HTML-specific semantics (slots via <div slot="..."> pattern). How should the canvas represent HTML slot semantics? Decision: Show as named regions similar to wireframe slots; HTML-specific attributes editable in property editor.
Undo granularity — Should undo be per-action (move, resize, property change) or group related actions? Decision: Per-action with optional grouping for drag sequences.
Portrait orientation Decision: Portrait orientation. Toolbox and properties become slide-in drawers from left/right edges; canvas gets maximum vertical space. Bottom panel remains collapsible.

0-proposal-of-impl.md 26 KB Permalink History Raw