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
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
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
Namespace
The XML namespace of the format's elements.
public const string Namespace = "https://rubberduckvba.ca/schemas/rdforms"
Field Value
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
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
documentornameis null.
Read(string)
Reads a document's text.
public static FormXamlRead Read(string document)
Parameters
documentstringThe document's text.
Returns
- FormXamlRead
The form, and what the read reports.
Exceptions
- ArgumentNullException
documentis 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
pathstringThe file's path.
Returns
- FormXamlRead
The form, and what the read reports.
Exceptions
- ArgumentNullException
pathis null.- ArgumentException
pathis 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
formFormDefinitionThe 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
formis 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
formFormDefinitionThe form.
pathstringThe file's path.
Remarks
What is written is what Write(FormDefinition) writes.
Exceptions
- ArgumentNullException
formorpathis null.- ArgumentException
pathis empty, or holds a NUL.- IOException
The file cannot be written.
- UnauthorizedAccessException
The file cannot be accessed.