Table of Contents

Class FormXaml

Namespace
RDCore.Forms.Xaml
Assembly
RDCore.Forms.dll

Reads and writes RDForms documents: a form as a constrained XAML dialect, with the classes of ComponentClasses as its elements.

public static class FormXaml
Inheritance
FormXaml
Inherited Members

Remarks

The root element is the form's root component, such as a Form, in the Namespace namespace, with a FormatVersion attribute. Each component is an element named for its class, with its Name, its Index in a control array, and each property it sets as an attribute; a component placed in another is a child element of it. A font is a property element, such as Label.Font, and so are a list's items, a root's control libraries, and the properties the model does not have. Only the elements of the format are read: no other XAML element, markup extension or code-behind.

A read never throws on what a document holds. It keeps what the model cannot hold as text, as an UnmodelledProperty or an UnmodelledComponent, and reports it in Diagnostics. A DTD is refused, nothing outside the document is read, and a document is read up to MaxDocumentCharacters characters and MaxNestingDepth components deep.

Fields

FormatVersion

The format version this library writes, and the latest it reads: 1. A document of a later version is read anyway.

public const int FormatVersion = 1

Field Value

int

MaxDocumentCharacters

The most characters a document is read to: 67,108,864. A larger document holds no form.

public const int MaxDocumentCharacters = 67108864

Field Value

int

MaxNestingDepth

How deep the components of a document are read, the root's included: 2,500. A component nested deeper is kept as an UnmodelledComponent, its own contents included.

public const int MaxNestingDepth = 2500

Field Value

int

Namespace

The XML namespace of the format's elements.

public const string Namespace = "https://rubberduckvba.ca/schemas/rdforms"

Field Value

string

Methods

NameRangesOf(string, string)

Finds where a document's text names a component: the value of the Name attribute of each component of that name, such as the ranges a rename of a control replaces.

public static IReadOnlyList<FormXamlNameRange> NameRangesOf(string document, string name)

Parameters

document string

The document's text.

name string

The component's name, matched ignoring case.

Returns

IReadOnlyList<FormXamlNameRange>

The ranges, in the document's order: one for each component of the form that Read(string) reads with that name, the root and menu items included, and each element of a control array, which all have the array's name. None where the document holds no form.

Remarks

A range covers the attribute's value as the text writes it, between its quotes, character references included. A name kept as text is not found: a component the model cannot hold (an UnmodelledComponent), a property kept as an UnmodelledProperty, a tab of a TabStrip, or a comment.

Exceptions

ArgumentNullException

document or name is null.

Read(string)

Reads a document's text.

public static FormXamlRead Read(string document)

Parameters

document string

The document's text.

Returns

FormXamlRead

The form, and what the read reports.

Exceptions

ArgumentNullException

document is null.

ReadFile(string)

Reads a document from a file, its encoding as its XML declaration states, UTF-8 where it states none.

public static FormXamlRead ReadFile(string path)

Parameters

path string

The file's path.

Returns

FormXamlRead

The form, and what the read reports.

Exceptions

ArgumentNullException

path is null.

ArgumentException

path is empty, or holds a NUL.

IOException

The file cannot be read.

UnauthorizedAccessException

The file cannot be accessed.

Write(FormDefinition)

Writes a form as a document.

public static string Write(FormDefinition form)

Parameters

form FormDefinition

The form.

Returns

string

The document's text, indented, with no XML declaration.

Remarks

Only the properties a component sets are written; the others keep their class's default when the document is read. A list's ItemData and ItemIcon are written for its items, and a value past its last item is not written.

A string that holds a character XML 1.0 does not allow, such as a NUL, is written with that character as a character reference, which Read(string) reads back; another XML reader may refuse it.

Exceptions

ArgumentNullException

form is null.

WriteFile(FormDefinition, string)

Writes a form as a document in a file, encoded as UTF-8 with an XML declaration, replacing the file where it exists.

public static void WriteFile(FormDefinition form, string path)

Parameters

form FormDefinition

The form.

path string

The file's path.

Remarks

What is written is what Write(FormDefinition) writes.

Exceptions

ArgumentNullException

form or path is null.

ArgumentException

path is empty, or holds a NUL.

IOException

The file cannot be written.

UnauthorizedAccessException

The file cannot be accessed.