View Markup Language (VML) Specification - WinUI3

Version 1.0-alpha.1 (WinUI 3 / XAML)

1. Overview

View Markup Language (VML) is a markup language derived from SGML, designed to represent a XAML-based UI for unidirectional, server-driven rendering on the WinUI 3 platform. It is designed to be a subset of XAML concepts, making it highly idiomatic for Windows developers.

Specification Note 1.1: Scope The VML specification is concerned exclusively with the structure and rendering of UI elements. It is a unidirectional standard (server-to-client). Mechanisms for handling user interactions, events, and data binding ({Binding}, {x:Bind}) are explicitly outside the scope of this document.

2. Document Headers and Type

2.1 HTTP Headers

When serving VML documents for WinUI 3:

Request Headers:

ACCEPT: application/winui3

Response Headers:

CONTENT-TYPE: application/winui3

2.1.1 Targets

If you want to target a specific device family you can use content-type parameters:

ACCEPT: application/winui3+vml; target=xbox

The server should respond with an XBox-specific template or optionall fallback to a general WinUI3 one.

2.2 Document Type Declaration

VML documents for WinUI 3 must begin with a doctype declaration.

<!doctype winui3>

3. Document Structure and Namespaces

VML documents require a root <vml> tag, which contains the <body>. The root tag can also contain namespace declarations for custom controls.

<vml xmlns:local="using:MyProject.Controls">
    <body>
        <Button Content="Standard Button" />
        <local:MyCustomControl />
    </body>
</vml>

Specification Note 3.1: Namespace Logic A client implementation must support a Control Registry. A tag with no prefix is first checked against the registry for standard controls. If not found, it is assumed to belong to the local namespace.

4. Element Conversion Rules

4.1 Properties to Attributes

All configurable properties of a WinUI 3 control are represented as direct attributes on the corresponding VML element.

<TextBlock Text="Hello" FontSize="24" FontWeight="Bold" />

4.2 Attached Properties

Attached properties are specified using the standard XAML dot-syntax.

<Button Content="Cell (1,0)" Grid.Row="1" Grid.Column="0" />

4.3 Content Properties

VML adopts the XAML model for content. Child elements without a special tag are assigned to their parent's default content property. Non-default content properties are specified using the <Parent.Property> syntax.

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
    </Grid.RowDefinitions>
</Grid>

5. The `attr` Helper

Specification Note 5.1: Not Implemented for WinUI 3 The attr helper is not implemented in the WinUI 3 adaptation of VML. This feature is tied to the modifier-based styling systems of SwiftUI and Jetpack Compose. As WinUI 3 uses direct property assignment instead of a chainable modifier system, the attr helper is not applicable.

6. Stylesheets and Resource References

The concept of stylesheets is implemented by referencing Style objects from a XAML ResourceDictionary. This is accomplished using markup extensions.

<Button Content="Styled Button" Style="{StaticResource PrimaryButtonStyle}" />
<TextBlock Text="Themed Text" Foreground="{ThemeResource SystemAccentColorBrush}" />

Specification Note 6.1: Markup Extensions Client parsers must support {StaticResource ...} and {ThemeResource ...}. An attribute value enclosed in {...} must be processed as a markup extension and not as a literal string. The Class attribute used in other VML adaptations is not used for WinUI 3.

7. WinUI 3 to VML Conversion Examples

Specification Note 7.1: Not Implemented This section is reserved for platform-specific conversion examples. For the WinUI 3 adaptation, all primary conversion rules are fully defined in the preceding sections and are not broken out into a separate section.

8. Validation Rules

Elements must be properly nested and closed.
All attribute values must be properly encoded.
VML clients must implement a Control Registry.
The attr helper and Class attribute must not be used.
Attribute values containing { and } must be parsed as Markup Extensions.
Attached properties must be specified using the <DefiningType.Property> attribute syntax.
Non-default content properties must be specified using the <Parent.Property> element syntax.

9. File Format

File extension: .vml
Encoding: UTF-8

bcardarella/vml-winui3.md