The RDForms document
An RDForms document holds one form as a constrained XAML dialect: XML whose elements are the form's components, named for their classes, and whose attributes are the properties they set. FormXaml reads a document into the model and writes the model as a document.
In a project, a form is two files of one base name in one folder: its code, Form1.rdform, which keeps its Attribute VB_* lines, and its document, Form1.xaml. FormXamlDocumentReader reads the document for the platform, which declares the form's controls to its code.
<Form FormatVersion="1" Name="Form1" Caption="Orders" Width="320" Height="240" xmlns="https://rubberduckvba.ca/schemas/rdforms">
<Form.Font>
<Font Name="Tahoma" Size="8.25" />
</Form.Font>
<Frame Name="Frame1" Caption="Ship by" Left="8" Top="8" Width="160" Height="80">
<OptionButton Name="optShip" Index="0" Caption="&Air" Value="True" Left="8" Top="16" Width="120" Height="20" />
<OptionButton Name="optShip" Index="1" Caption="&Sea" Left="8" Top="40" Width="120" Height="20" />
</Frame>
<ListBox Name="lstItems" Left="176" Top="8" Width="134" Height="80">
<ListBox.List>
<Item Text="Alpha" ItemData="1" />
<Item Text="Beta" ItemData="20" ItemIcon="R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" />
</ListBox.List>
</ListBox>
<CommandButton Name="cmdOK" Caption="OK" Left="232" Top="192" Width="81" Height="33" />
</Form>
Elements
Every element is in the namespace https://rubberduckvba.ca/schemas/rdforms.
| Element | Is | Holds |
|---|---|---|
Form, MDIForm, UserControl, PropertyPage |
The root: the form itself. Only the root has FormatVersion. |
The form's components, and its property elements. |
A control class, such as CommandButton or Frame |
A component of that class of ComponentClasses. |
The components placed in it, where its class is a container, and its property elements. |
Menu |
A menu item. | Its submenu's items. |
UnmodelledComponent |
A component the model does not have, such as an ActiveX control, kept as text: its TypeName, its Name, and its text as the element's content. |
Text. |
A component that its parent cannot hold, such as a control written in a CommandButton, is placed in the nearest enclosing component that can.
Attributes
| Attribute | Value |
|---|---|
FormatVersion |
The format's version, on the root: 1. |
Name |
The component's name. Every component has one. |
Index |
The component's index in its control array, from 0 to 32767. |
A property, such as Caption |
The value of a property the component's class has, compared without regard to case. A property the component does not set is left out, and has its class's default. |
| Value type | Written as | Example |
|---|---|---|
| String | The text. | Caption="&OK" |
| Boolean | True or False. |
Enabled="False" |
Boolean or Null, a ToggleButton's Value |
True, False or Null. |
Value="Null" |
| Number | Invariant digits, with . for decimals. |
Left="120", Size="8.25" |
| Enumeration | The member's name; a number is read too. | BorderStyle="FixedSingle" |
| Colour | A system colour by its name, or #RRGGBB. |
BackColor="ButtonFace", ForeColor="#1234AB" |
| Picture | The bytes of its file, in base64. | Picture="iVBORw0KGgo..." |
Positions and sizes are as in the model: a control's Left, Top, Width and Height in pixels (1/96 inch) whatever its container's ScaleMode, and a Line's ends in its container's scale.
Property elements
A property element is named for its component's element and the property, such as ListBox.List.
| Element | Holds |
|---|---|
<Class>.Font |
One Font element: Name and Size, and where they differ from the default, Weight (400 normal, 700 bold), Italic, Underline, Strikethrough and Charset. |
<Class>.List |
One Item for each item of a ListBox or ComboBox: its Text, and its ItemData and ItemIcon where it has them. An item with no ItemData has 0, and one with no ItemIcon has none. |
<Class>.Tabs |
One Tab for each tab of a TabStrip: its Name and Caption, and its ToolTipText, Enabled, Visible and Tag where they differ from a tab's default. A TabStrip with no Tabs element has the two default tabs, and an empty one has none. |
<Root>.ControlLibraries |
One ControlLibrary for each control library the form lists: its Id, Version and FileName. |
<Class>.UnmodelledProperties |
One UnmodelledProperty for each property the model does not have: its Name and Text. |
<Class>.<Property> |
Any other property's value as text, such as a caption of several lines. |
What a document cannot hold
A document is read as data. It holds no code and names no handlers, and only the elements above are read: an Avalonia or WPF element, a markup extension, an x:Class or any other code-behind is not part of the format. The code behind a form handles its events by name, as in VB.
Reading
FormXaml.Read reads a document's text, and ReadFile a file. A read does not throw on what a document holds: it keeps what the model cannot hold as text, and reports it in FormXamlRead.Diagnostics.
| Diagnostic | Severity | What the reader does |
|---|---|---|
MalformedDocument |
Error | No form: the document is not well-formed XML, declares a DTD, or is longer than 67,108,864 characters. |
NotAForm |
Error | No form: the root element is not a root class in the format's namespace. |
NamelessComponent |
Warning (Error for the root) | The component is kept as an UnmodelledComponent. |
NestingTooDeep |
Warning | A component nested deeper than 2,500 (the root included) is kept as an UnmodelledComponent, with its contents. |
MisplacedComponent |
Warning | The component is placed in the nearest enclosing component that can hold it. |
UnknownProperty |
Warning | The value is kept as an UnmodelledProperty. |
InvalidValue |
Warning | The value is kept as an UnmodelledProperty: one its property's type cannot hold, a picture that is not base64 or is larger than 16 MiB, or an Index outside 0 to 32767. |
NewerFormatVersion |
Information | The document is read anyway. |
UnmodelledElement |
Information | An element the format does not have in its place is kept as an UnmodelledComponent, with its XML as its text. |
A document's own XML is read safely: a DTD is refused, and nothing outside the document is read.
Writing
FormXaml.Write returns a form's document, indented; WriteFile writes it to a file as UTF-8 with an XML declaration. A document written and read again holds the same form, except for the ItemData and ItemIcon values past a list's last item, which are not written. Line breaks and tabs in a string are written so that they are read back as they were. A character XML 1.0 does not allow, such as a NUL, is written as a character reference, which Read reads back and another XML reader may refuse.
Versions
The format's version is 1. A document of a later version is read anyway, with a NewerFormatVersion report, and what this version does not know is reported as it is met.
Implementation
| Type | Role |
|---|---|
FormXaml |
Reads and writes documents. |
FormXamlRead |
The form a read returns, its format version, and its diagnostics. |
FormXamlDiagnostic |
One thing a read reports: its kind, severity, line and message. |
ACCUEIL • HOME | BIENVENUE • WELCOME | DÉMARRER • GET STARTED | IMPORTER • IMPORT | CONTROLS | FORMAT | 🌐 rubberduckvba.ca