AxDa.XamlDocConverter.Abstractions 1.0.4

WPF Flow Document Converter Abstractions Overview

This Abstractions package provides base classes to be used by high performance converters converting WPF Flow Document XAML to alternative serialization formats and vice versa.

Usage

This package is automatically included as a dependency of one of the two main packages, AxDa.XamlDocConverter.Html and AxDa.XamlDocConverter.Markdown. Typically, the Abstractions package is not explicitly installed as it only contains abstract base classes with no public interface.

Creating Your Own WPF Flow Document Converters

You can create your own XAML Flow Document text language converters based on AxDa.XamlDocConverter.Abstractions.XamlDocConverterBase and use the methods and properties of the base class to convert elements of other text description languages to XAML Flow Document format.

Abstractions Support for WPF Flow Documents

The WPF flow document feature is designed to optimize text viewing and readability. Rather than being set to one predefined layout, flow documents dynamically adjust and reflow their content based on run-time variables such as window size, device resolution, and optional user preferences. This is true for other flow document layout languages, too, like HTML or Markdown.

However, WPF Flow Documents do not support some features common to other document layout engines.For example, heading, horizontal rule or quote block classes are missing from the System.Windows.Documents namespace.

To be able to convert these elements from another text description language to WPF XAML, and vice versa, classes derived from the XamlDocConverterBase class assume a set of conventions for identifying XAML flow document elements as heading, horizontal rule, quotation block or code.

• Heading

  A Paragraph element is identified as a heading element if the following conditions are met:

  1. The font size matches one of the font sizes defined in the HeadingSizes array property in XamlDocConverterOptions.

  Example

  Assuming that the font size array in XamlDocConverterOptions.HeadingSizes is equal to [24, 20, 18, 16, 15, 14, 13], then

  <Paragraph FontSize="24">
    <Run>This is heading level 1</Run>
  </Paragraph>
  <Paragraph FontSize="20">
    <Run>This is heading level 2</Run>
  </Paragraph>
  <Paragraph FontSize="18">
    <Run>This is heading level 3</Run>
  </Paragraph>
  <Paragraph FontSize="16">
    <Run>This is heading level 4</Run>
  </Paragraph>
  

  On the other hand, to have a paragraph with a specific font size not being recognized as a heading, set the paragraph's font size to any value other than the values defined in XamlDocConverterOptions.HeadingSizes.

  Example

  <Paragraph FontSize="24.001">
    <Run>This is not a heading</Run>
  </Paragraph>
  

• Horizontal Rule

  A Section element is identified as a horizontal rule element if the following conditions are met:

  1. It contains no child element
  2. It contains no text
  3. It has a top border – and only a border at the top – defined with the BorderBrush and BorderThickness properties set
  4. The thickness of the top border corresponds to the HorizontalLineThickness property defined in XamlDocConverterOptions. All other border thickness values must be 0.

  Example

  <Section BorderThickness="0, 3, 0 ,0" BorderBrush="Silver"></Section>
  

• Quote Block

  A Section element is identified as a quote block element if the following conditions are met:

  1. It has a left border – and only a border on the left side – defined with the BorderBrush and BorderThickness properties set
  2. The left border thickness corresponds to the BlockQuoteLineThickness property defined in XamlDocConverterOptions. All other border thickness values must be 0.

  Example

  <Section BorderThickness="3, 0, 0 ,0" BorderBrush="Silver">
    <Paragraph>
      <Run>“This is the truth”.</Run>
    </Paragraph>
  </Section>
  

• Code Block

  A Section element is identified as a code block element if the following conditions are met:

  1. It is assigned a font family name that matches the font family name defined in the MonospaceFontName property of the XamlDocConverterOptions object.
  2. Optionally, a computer language acronym has been assigned to the Tag attribute.

  Example

  <Section FontFamily="Courier New" xml:space="preserve" Tag="c#">
    <Paragraph>
      <Run><![CDATA[int = 1;
  
  return i;]]></Run>
    </Paragraph>
  </Section>
  

• Inline Code

  A Run or Span element is identified as an inline code element if the following conditions are met:

  1. It is assigned a font family name that matches the font family name defined in the MonospaceFontName property of the XamlDocConverterOptions object.

  Example

  <Paragraph>
    <Run>The value is </Run>
    <Run FontFamily="Courier New" xml:space="preserve">true</Run>
    <Run>.</Run>
  </Paragraph>
  

Conversion Options Overview

To customize the conversion behavior, derive your Options class from the XamlDocConverterOptions base class. It can then be used by your XamlDocConverterBase-derived class during the conversion process.

XamlDocConverterOptions Properties

<dl> <dt>HeadingSizes</dt> <dd>

Collection of XAML font sizes used to identify a Paragraph element so that it is interpreted as the corresponding heading level in the target format.

The default values are: [24, 20, 18, 16, 15, 14, 13].</dd>

<dt>MonospaceFontName</dt> <dd>

Font name used to identify Paragraph, Run or Span elements so thy are interpreted as elements containing code snippets in the target format.

The default font family name is "Courier New".</dd>

<dt>BlockQuoteLineThickness</dt> <dd>

Left side border thickness used to identify a block quote.

The default value is 3.</dd>

<dt>BlockQuoteLineColor</dt> <dd>

Left border Color used for displaying a block quote.

The default value is Colors.Silver.</dd>

<dt>HorizontalLineThickness</dt> <dd>

Top border thickness used to identify a horizontal rule.

The default value is 3.</dd>

<dt>HorizontalLineColor</dt> <dd>

Top border Color used for displaying a horizontal rule.

The default value is Colors.Silver.</dd>

<dt>EnforceWSPreserve</dt> <dd>

Enables or disables a conversion option that adds the XML attribute xml:space=preserve to the root element of an input document and to the root element of the generated XAML output document.

The default value is true.

A peculiarity of the WPF parser requires the xml:space=preserve XML attribute in the root element. If this attribute is not present in the XML root element, the WPF renderer may not display words with the expected word break.

However, this requirement typically results in the resulting XML being output as a single, long line. For troubleshooting purposes, you can set this property to false. The resulting XML will then be output with normal indentation. However, the result will not be WPF-compatible if this property is set to false.</dd> </dl>

Feedback, Sponsorship and Contact

You may reach me on axeldahmen.de or LinkedIn