# UI Layout Definition Format

**Version:** 1.2  
**Documentation Version:** 1.2  
**Author:** Dalibor Votruba  
**URL:** [quadarax.com/ui-layout-def](https://quadarax.com/ui-layout-def)

A comprehensive XML-based format for describing user interface layouts with inheritance, pattern definitions, view organization, external includes, and platform-specific extensions. This format enables cross-platform UI generation with strict validation and modular component libraries.

## Table of Contents

- [Overview](#overview)
- [What's New in v1.2](#whats-new-in-v12)
- [Core Concepts](#core-concepts)
- [Document Structure](#document-structure)
- [View Definitions](#view-definitions)
- [Pattern Definitions](#pattern-definitions)
- [Wireframe Inheritance](#wireframe-inheritance)
- [Window Definitions](#window-definitions)
- [External Includes](#external-includes)
- [Window Includes (NEW)](#window-includes-new)
- [Validation System](#validation-system)
- [Examples](#examples)
- [Best Practices](#best-practices)
- [Platform Support](#platform-support)
- [Migration Guide](#migration-guide)

## Overview

The UI Layout Definition Format provides a standardized way to define user interfaces that can be translated to various platforms (Windows Forms, WPF, Avalonia, Qt, Web, Mobile). It emphasizes:

- **View-Based Organization**: Logical grouping of related UI components by business function
- **Separation of Concerns**: Pattern definitions separate from usage
- **Inheritance**: Base wireframes and views with specific overrides
- **External Includes**: Modular design with external pattern, view, validation, and window files
- **Validation**: Strict constraints ensure consistent, valid UIs
- **Cross-Platform**: Platform-specific control libraries
- **MVVM Support**: Direct mapping to view models and business logic

## What's New in v1.2

### Major Enhancements

1. **Window Includes Support**
   - Separate window definitions into external files
   - Improved organization for large applications
   - Better team collaboration capabilities

2. **Enhanced Schema Validation**
   - More comprehensive XSD schema
   - Better error reporting and validation
   - Support for all platform-specific controls

3. **Expanded Platform Support**
   - Full Avalonia UI control library
   - Enhanced WinForms control definitions
   - Web and mobile control patterns

4. **Advanced View Features**
   - Enhanced communication patterns
   - Workflow support for process-driven views
   - Module view organization
   - Main navigation integration

5. **Improved Control Library**
   - Abstract control definitions
   - Better inheritance patterns
   - Platform-specific specializations

### Breaking Changes from v1.1

- Enhanced schema validation may require updates to existing documents
- Some control attributes have been refined for better platform compatibility
- Window include structure requires specific file organization

## Core Concepts

### 1. View-First Design
Views represent logical business functions (ProductView, OrderView) that group related windows and define shared data context and behaviors.

### 2. Patterns-First Design
All controls and structures must be defined in the `<patterns>` section before use in windows.

### 3. External Includes
Modular design allows splitting definitions across multiple files:
- Pattern includes for control libraries
- View includes for business logic organization
- Validation includes for rule sets
- Window includes for UI definitions

### 4. Inheritance Hierarchy
- Views can inherit from other views
- Controls can inherit from other controls
- Windows can inherit from wireframe layouts
- Attributes can be overridden at any level

### 5. Slot-Based Composition
Wireframes use slots as placeholders that windows can fill with specific content.

### 6. Constraint Validation
Comprehensive validation rules ensure UI consistency and platform compliance.

## Document Structure

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ui-layout-def xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="ui-layout-definition ui-layout-def.xsd"
               version="1.2">
  
  <!-- Optional: Validation rules with external includes -->
  <validation-rules>
    <validation-include src="..." important="true/false" />
    <rule name="...">...</rule>
  </validation-rules>
  
  <!-- Required: Pattern definitions with external includes -->
  <patterns>
    <pattern-include src="..." important="true/false" />
    <control name="...">...</control>
    <structure name="...">...</structure>
    <wireframe name="...">...</wireframe>
  </patterns>
  
  <!-- View definitions with external includes -->
  <views>
    <view-include src="..." important="true/false" />
    <view name="..." type="..." category="..." inherits="...">...</view>
  </views>
  
  <!-- NEW: Window includes -->
  <window-includes>
    <window-include src="..." important="true/false" />
  </window-includes>
  
  <!-- Window definitions (can be in external files) -->
  <window name="..." title="..." wireframe="..." view="...">
    <!-- Window content -->
  </window>
  
</ui-layout-def>
```

## View Definitions

### View Concept

Views are logical containers that group related windows, dialogs, and UI components that work together for a specific business function. They provide:

- **Logical Organization**: Group UI components by business purpose
- **Data Context**: Shared state management within the view
- **Navigation**: Centralized navigation logic
- **Dependencies**: Clear relationships between views
- **Code Generation**: Generate view classes with proper structure

### Basic View Structure

```xml
<view name="ProductView" type="business-entity" category="core" inherits="BaseEntityView">
  <description>Product management functionality</description>
  
  <!-- View metadata for code generation -->
  <metadata>
    <model-class>Product</model-class>
    <view-model-class>ProductViewModel</view-model-class>
    <controller-class>ProductController</controller-class>
    <permissions>product.read,product.write</permissions>
  </metadata>
  
  <!-- View dependencies -->
  <dependencies>
    <view-ref name="CategoryView" relationship="lookup" required="false" />
    <shared-component name="FileUploadComponent" required="true" />
  </dependencies>
  
  <!-- Shared data context -->
  <data-context>
    <property name="currentProduct" type="Product" scope="view" />
    <property name="productList" type="ProductList" scope="view" />
  </data-context>
  
  <!-- Window associations -->
  <windows>
    <window-ref name="ProductListWindow" role="main" default="true" />
    <window-ref name="ProductEditDialog" role="editor" modal="true" />
  </windows>
  
  <!-- View-level navigation -->
  <navigation>
    <action name="show-list" target="ProductListWindow" />
    <action name="edit-product" target="ProductEditDialog" context="currentProduct" />
  </navigation>
  
  <!-- Communication patterns -->
  <communication>
    <publishes>
      <event name="product-saved" data="product-id" />
    </publishes>
    <subscribes>
      <event name="category-changed" source="CategoryView" handler="refresh-list" />
    </subscribes>
  </communication>
</view>
```

### View Types and Categories

**View Types:**
- `business-entity` - Product, Order, Customer management
- `process-flow` - OrderProcessing, Checkout workflows
- `dashboard` - MainDashboard, ReportsView
- `utility` - Settings, UserPreferences
- `wizard` - Setup wizards, guided processes
- `composite` - Views composed of multiple sub-views
- `module` - Application modules containing multiple views
- `base` - Base views for inheritance

**Categories:**
- `core` - Essential business functionality
- `admin` - Administrative functions
- `reporting` - Reports and analytics
- `system` - System-level functionality
- `framework` - Base views for inheritance
- `business` - Business-specific functionality

### Advanced View Features

#### Workflow Support
```xml
<view name="OrderProcessingView" type="process-flow" category="core">
  <workflow>
    <step name="order-entry" window="OrderEntryWindow" next="payment" />
    <step name="payment" window="PaymentWindow" next="confirmation" previous="order-entry" />
    <step name="confirmation" window="ConfirmationWindow" previous="payment" />
  </workflow>
</view>
```

#### Module Organization
```xml
<view name="ECommerceModule" type="module" category="business">
  <module-views>
    <view-ref name="ProductView" />
    <view-ref name="OrderView" />
    <view-ref name="CustomerView" />
  </module-views>
  
  <main-navigation>
    <nav-item text="Products" view="ProductView" action="show-list" />
    <nav-item text="Orders" view="OrderView" action="show-list" />
    <nav-item text="Customers" view="CustomerView" action="show-list" />
  </main-navigation>
</view>
```

## Pattern Definitions

### Control Definition

```xml
<control name="Button" type="action" category="basic">
  <constraints>
    <allowed-parents>Panel,FormField</allowed-parents>
    <allowed-children>none</allowed-children>
    <container>false</container>
  </constraints>
  
  <attributes>
    <attribute name="text" type="string" default="Button" required="true" />
    <attribute name="enabled" type="bool" default="true" />
    <attribute name="style" type="enum" values="normal,primary,danger" default="normal" />
  </attributes>
  
  <behavior>
    <event name="click" required="true" />
  </behavior>
</control>
```

### Platform-Specific Controls

The format supports platform-specific control libraries:

#### Avalonia Controls
```xml
<control name="AvaloniaButton" type="action" category="avalonia-specific" inherits="Button">
  <attributes>
    <attribute name="click-mode" type="enum" values="Release,Press,Hover" default="Release" />
    <attribute name="is-default" type="bool" default="false" />
    <attribute name="command" type="string" default="" />
  </attributes>
</control>
```

#### WinForms Controls
```xml
<control name="DataGridView" type="data" category="winforms-data">
  <constraints>
    <allowed-parents>Panel,GroupBox,TabPage,Form</allowed-parents>
    <requires-structure>columns</requires-structure>
  </constraints>
  
  <attributes>
    <attribute name="allowusertoaddrows" type="bool" default="true" />
    <attribute name="selectionmode" type="enum" values="CellSelect,FullRowSelect" default="RowHeaderSelect" />
  </attributes>
</control>
```

## External Includes

### Pattern Includes

```xml
<patterns>
  <pattern-include src="abstract-controls.xml" important="true" />
  <pattern-include src="winform-controls.xml" important="true" />
  <pattern-include src="avalonia-controls.xml" important="false" />
  <pattern-include src="web-controls.xml" important="false" />
  <!-- Local pattern definitions -->
</patterns>
```

### View Includes

```xml
<views>
  <view-include src="business-views.xml" important="true" />
  <view-include src="admin-views.xml" important="false" />
  <!-- Local view definitions -->
</views>
```

### Validation Includes

```xml
<validation-rules>
  <validation-include src="base-validation.xml" important="true" />
  <validation-include src="view-validation.xml" important="true" />
  <validation-include src="accessibility-rules.xml" important="false" />
  <!-- Local validation rules -->
</validation-rules>
```

## Window Includes (NEW)

Version 1.2 introduces the ability to organize windows in separate files for better project structure and team collaboration.

### Main Document Structure
```xml
<ui-layout-def version="1.2">
  <patterns>
    <!-- Pattern definitions -->
  </patterns>
  
  <views>
    <!-- View definitions -->
  </views>
  
  <window-includes>
    <window-include src="main-windows.xml" important="true" />
    <window-include src="dialog-windows.xml" important="true" />
    <window-include src="admin-windows.xml" important="false" />
  </window-includes>
</ui-layout-def>
```

### Window Include File (main-windows.xml)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<windows xmlns="ui-layout-definition">
  
  <window name="MainWindow" title="Main Application" view="MainView">
    <!-- Window definition -->
  </window>
  
  <window name="ProductListWindow" title="Products" view="ProductView">
    <!-- Window definition -->
  </window>
  
</windows>
```

### Include Processing Rules

- **important="true"**: Must be found and loaded, build fails if missing
- **important="false"**: Optional, warnings only if missing
- Includes are processed in order before local definitions
- Local definitions can override included definitions
- Naming conflicts resolved by last-loaded-wins principle

## Validation System

### Enhanced Validation Rules

```xml
<validation-rules>
  <!-- View-specific validation -->
  <rule name="view-window-association">
    <description>All windows must be associated with a view</description>
    <constraint>Every window must be referenced by at least one view</constraint>
  </rule>
  
  <rule name="view-dependency-validation">
    <description>View dependencies must be valid</description>
    <constraint>Referenced views in dependencies must be defined</constraint>
  </rule>
  
  <!-- Control validation -->
  <rule name="control-definition-required">
    <description>All controls used in windows must be defined in patterns</description>
    <constraint>Every control element must reference a defined pattern</constraint>
  </rule>
  
  <!-- Include validation -->
  <rule name="include-validation">
    <description>Important includes must be accessible</description>
    <constraint>Files marked important="true" must exist and be loadable</constraint>
  </rule>
</validation-rules>
```

## Examples

### Complete Application Structure

```
project/
├── main.xml                    # Main document with includes
├── patterns/
│   ├── abstract-controls.xml   # Base control definitions
│   ├── winform-controls.xml    # WinForms-specific controls
│   └── avalonia-controls.xml   # Avalonia-specific controls
├── views/
│   ├── business-views.xml      # Business entity views
│   └── admin-views.xml         # Administrative views
├── windows/
│   ├── main-windows.xml        # Primary application windows
│   ├── dialog-windows.xml      # Modal dialogs and popups
│   └── admin-windows.xml       # Administrative interfaces
└── validation/
    ├── base-validation.xml     # Core validation rules
    ├── view-validation.xml     # View-specific rules
    └── accessibility-rules.xml # Accessibility compliance
```

### Platform-Specific Builds

Generate different outputs for different platforms:

```xml
<!-- For WinForms -->
<pattern-include src="winform-controls.xml" important="true" />
<pattern-include src="avalonia-controls.xml" important="false" />

<!-- For Avalonia -->
<pattern-include src="avalonia-controls.xml" important="true" />
<pattern-include src="winform-controls.xml" important="false" />
```

## Best Practices

### 1. Project Organization
- Use external includes for better modularity
- Separate concerns: patterns, views, windows, validation
- Group related functionality in dedicated files
- Use consistent naming conventions

### 2. View Design Patterns
- **Single Responsibility**: Each view should handle one business concept
- **Dependency Injection**: Use view dependencies rather than tight coupling
- **Data Context**: Define clear data scopes (view, shared, global)
- **Navigation**: Centralize navigation logic within views

### 3. Include Management
- Mark critical includes as `important="true"`
- Document include dependencies
- Use version control for include files
- Test with missing optional includes

### 4. Platform Compatibility
- Define abstract controls for common functionality
- Use platform-specific includes for specialized features
- Test on all target platforms
- Maintain compatibility matrices

### 5. Code Generation Strategy
- Map views to view model classes
- Generate navigation methods
- Create dependency injection configuration
- Generate view factory classes

## Platform Support

### Enhanced Platform Integration

**Windows Forms / WPF**
- Complete control library support
- Generate view classes with proper MVVM binding
- Create dependency injection containers
- Generate navigation services

**Avalonia UI**
- Full Avalonia control set
- Cross-platform compatibility
- Modern UI patterns and styling
- MVVM architecture support

**Qt / KDE**
- Qt widget system integration
- KDE desktop integration patterns
- Cross-platform Qt navigation

**Web / HTML**
- Generate MVC views or React components
- Support for SPA routing
- Progressive web app patterns
- Responsive design support

**Mobile**
- Platform-specific view controllers
- Mobile navigation patterns
- Responsive view layouts
- Touch-optimized interactions

## Migration Guide

### From Version 1.1 to 1.2

#### Backward Compatibility
Version 1.2 maintains full backward compatibility with 1.1 documents. Existing documents will work without modification.

#### New Features Available
1. **Window Includes**: Organize windows in separate files
2. **Enhanced Schema**: Better validation and error reporting
3. **Extended Platform Support**: More control libraries
4. **Advanced View Features**: Workflows, modules, communication

#### Migration Steps
1. **Update Schema Reference**: Change version to "1.2"
2. **Optional: Reorganize Windows**: Move windows to separate files
3. **Optional: Add Platform Controls**: Include platform-specific patterns
4. **Optional: Enhance Views**: Add communication, workflows, modules
5. **Update Validation**: Add new validation rule includes

#### Gradual Migration
You can migrate gradually by:
- Keeping existing structure initially
- Adding new features incrementally
- Testing each enhancement
- Moving to external includes when beneficial

### Schema Updates
- Update XSD reference to ui-layout-def-1.2.xsd
- Enhanced validation will catch more potential issues
- Better error messages for debugging

---

*This format specification enables consistent, validated, cross-platform UI definitions with powerful view organization, external includes, inheritance, and modular design capabilities.*