UI Layout Definition Format

Version: 1.2
Documentation Version: 1.2
Author: Dalibor Votruba
URL: 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.

Overview
What's New in v1.2
Core Concepts
Document Structure
View Definitions
Pattern Definitions
Wireframe Inheritance
Window Definitions
External Includes
Window Includes (NEW)
Validation System
Examples
Best Practices
Platform Support
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

Window Includes Support
- Separate window definitions into external files
- Improved organization for large applications
- Better team collaboration capabilities
Enhanced Schema Validation
- More comprehensive XSD schema
- Better error reporting and validation
- Support for all platform-specific controls
Expanded Platform Support
- Full Avalonia UI control library
- Enhanced WinForms control definitions
- Web and mobile control patterns
Advanced View Features
- Enhanced communication patterns
- Workflow support for process-driven views
- Module view organization
- Main navigation integration
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 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

<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

<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

<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

<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

<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

<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

<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

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

Validation Includes

<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

<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 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

<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:

<!-- 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

Window Includes: Organize windows in separate files
Enhanced Schema: Better validation and error reporting
Extended Platform Support: More control libraries
Advanced View Features: Workflows, modules, communication

Migration Steps

Update Schema Reference: Change version to "1.2"
Optional: Reorganize Windows: Move windows to separate files
Optional: Add Platform Controls: Include platform-specific patterns
Optional: Enhance Views: Add communication, workflows, modules
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.

readme.md 18 KB Histórico Em bruto