Skip to main content

BlockFormatting Struct

Definition​

Namespace:Avalonia.Controls.Documents.TextModel.Formatting
Assembly:Avalonia.Controls.Documents
Package:Avalonia.Controls.Documents

Block-level layout formatting snapshot. Value type for zero-reference safety. All data is stored as primitive types to ensure thread-safety.

public struct BlockFormatting

Inheritance: ValueType -> BlockFormatting

Implements: IEquatable<BlockFormatting>

Remarks​

Contains only block-specific layout properties (alignment, spacing, indentation, margins, borders, tabs). Shared element-level properties (font, color, background) are stored in Avalonia.Controls.Documents.TextModel.Formatting.TextElementFormatting on the Avalonia.Controls.Documents.Serialization.Snapshot.SnapshotNode base class.

Only relevant for block-level nodes (Paragraph, Section, List, etc.). For inline nodes, this will be default/zeroed.

Properties use device-independent pixels and semantic enums to match Avalonia property system conventions.

Format-agnostic: Contains only primitive values. Format-specific details (RTF border styles, shading patterns, etc.) are stored in format-specific metadata (e.g., RtfMetadata).

Adding a field? It does not flow anywhere by itself. Several consumers rebuild or filter this struct field by field, and each of them silently drops a field it does not know about (record equality keeps compiling, no test fails until the specific feature is exercised). A new field must be threaded through every one of these:

  • Capture: DocumentSnapshot.CaptureBlockFormatting (and CaptureListItemFormatting / CaptureTableCellFormatting / CaptureTableRowFormatting when the field applies to them) - reads the live element, IsSet-gated. A field the element cannot hold is lost the moment the node realizes, so it needs a property on Block (and ListItem) as well.
  • Apply: ElementFormattingApplier.ApplyBlockFormatting (and variants) - applies or clears the live element property.
  • DOCX: DocxMappings.FromParagraphProperties (direct read), DocxStyleResolver.ResolvedParaProps + ExtractParaProps + Merge (style chain), DocxMappings.FromResolvedParaProps (style-to-formatting), DocxMappings.MergeBlockFormatting (direct-over-style, rebuilds the struct), the has-any-formatting gates in DocxReader and DocxReader.Lists, DocxWriter.Lists.MergeListParagraphBlockFormatting (list-paragraph write, rebuilds the struct), and DocxMappings.ToParagraphProperties (write).
  • RTF: RtfReader.CreateParagraphFormatting (read) and both writer paths in RtfWriter (metadata-based and semantic-model).
  • Any exporter consuming the field (the PDF layout composer).

PageBreakBefore is the precedent: it was dropped by the DOCX merge and gate until both were taught about it. When adding a field, grep for a neighboring field (e.g. TabStopPositions) and mirror every hit.

Methods​

NameDescription
Equals (2 overloads)No summary available.
GetHashCodeNo summary available.
ToStringNo summary available.

Equals overloads​

Equals Method​

public bool Equals(Avalonia.Controls.Documents.TextModel.Formatting.BlockFormatting other)
Parameters​

other Avalonia.Controls.Documents.TextModel.Formatting.BlockFormatting

Returns​

bool

Equals Method​

public bool Equals(object obj)
Parameters​

obj object

Returns​

bool

GetHashCode Method​

public int GetHashCode()

Returns​

int

ToString Method​

public string ToString()

Returns​

string

Properties​

NameDescription
BorderBrushArgbPacked ARGB value for border brush. Null means not explicitly set or no border.
BorderThicknessBorder thickness in device-independent pixels. Null means not explicitly set or no border.
ColumnSpanNumber of grid columns the cell spans (maps to Avalonia.Controls.Documents.TableCell.ColumnSpan and Word's w:gridSpan). Only meaningful for table cells; null (treated as a span of 1) for other blocks and un-merged cells.
CornerRadiusCorner radius of the block border in device-independent pixels. Null means not explicitly set (square corners).
DefaultDefault formatting with no explicit values set.
FlowDirectionFlow direction (LeftToRight or RightToLeft). Null means not explicitly set.
KeepTogetherAvoids splitting the block across pages in paginated output; a block taller than one page still splits. Maps to RTF \keep and Word's w:keepLines; null means not explicitly set (off). The continuous on-screen flow ignores it.
KeepWithNextKeeps the block's end on the same page as the start of the following block in paginated output. Maps to RTF \keepn and Word's w:keepNext; null means not explicitly set (off). The continuous on-screen flow ignores it.
LineHeightLine height in device-independent pixels. Null means not explicitly set.
MarginMargin in device-independent pixels. Null means not explicitly set.
MinHeightMinimum height in device-independent pixels. Only meaningful for table rows (maps to Avalonia.Controls.Documents.TableRow.Height and Word's w:trHeight); null for other blocks.
PaddingPadding in device-independent pixels. Null means not explicitly set.
PageBreakBeforeStarts a new page before this block in paginated output (print/PDF). Maps to RTF \pagebb and Word's w:pageBreakBefore; null means no explicit break. The continuous on-screen flow ignores it.
RowSpanNumber of grid rows the cell spans (maps to Avalonia.Controls.Documents.TableCell.RowSpan and Word's w:vMerge). Only meaningful for table cells; null (treated as a span of 1) for other blocks and un-merged cells.
TabStopPositionsTab stop positions in device-independent pixels. Default or empty means no custom tab stops defined.
TextAlignmentText alignment (Left, Right, Center, Justify).
TextIndentFirst-line text indent in device-independent pixels. Negative values create hanging indents. Null means not explicitly set.
VerticalAlignmentVertical alignment of content within the block's height. Only meaningful for table cells (maps to Avalonia.Controls.Documents.TableCell.VerticalAlignment and Word's w:vAlign); null for other blocks.
WidowControlWidow/orphan control for paginated output: at least two lines of the paragraph stay and at least two lines move at a page break. Maps to RTF \widctlpar/\nowidctlpar and Word's w:widowControl; null means not explicitly set and resolves to ON (Word's default).

BorderBrushArgb Property​

Packed ARGB value for border brush. Null means not explicitly set or no border.

public Nullable<uint> BorderBrushArgb { get; set; }

Remarks​

When all border sides have the same color, stored here. Per-side colors require Avalonia.Controls.Documents.BlockDecorationInfo via Avalonia.Controls.Documents.Block.BlockDecorationInfoProperty.

BorderThickness Property​

Border thickness in device-independent pixels. Null means not explicitly set or no border.

public Nullable<Avalonia.Thickness> BorderThickness { get; set; }

ColumnSpan Property​

Number of grid columns the cell spans (maps to Avalonia.Controls.Documents.TableCell.ColumnSpan and Word's w:gridSpan). Only meaningful for table cells; null (treated as a span of 1) for other blocks and un-merged cells.

public Nullable<int> ColumnSpan { get; set; }

CornerRadius Property​

Corner radius of the block border in device-independent pixels. Null means not explicitly set (square corners).

public Nullable<Avalonia.CornerRadius> CornerRadius { get; set; }

Remarks​

No file format carries it: it is an authoring and rendering property, and it is here so a clone, an undo of a structural edit, and a snapshot round trip keep it.

Default Property​

Default formatting with no explicit values set.

public Avalonia.Controls.Documents.TextModel.Formatting.BlockFormatting Default { get; set; }

FlowDirection Property​

Flow direction (LeftToRight or RightToLeft). Null means not explicitly set.

public Nullable<Avalonia.Media.FlowDirection> FlowDirection { get; set; }

KeepTogether Property​

Avoids splitting the block across pages in paginated output; a block taller than one page still splits. Maps to RTF \keep and Word's w:keepLines; null means not explicitly set (off). The continuous on-screen flow ignores it.

public Nullable<bool> KeepTogether { get; set; }

KeepWithNext Property​

Keeps the block's end on the same page as the start of the following block in paginated output. Maps to RTF \keepn and Word's w:keepNext; null means not explicitly set (off). The continuous on-screen flow ignores it.

public Nullable<bool> KeepWithNext { get; set; }

LineHeight Property​

Line height in device-independent pixels. Null means not explicitly set.

public Nullable<double> LineHeight { get; set; }

Remarks​

Interpretation depends on format-specific metadata. Without metadata, treated as Auto. For RTF round-trip, see RtfMetadata.LineSpacingTwips and LineSpacingRule.

Margin Property​

Margin in device-independent pixels. Null means not explicitly set.

public Nullable<Avalonia.Thickness> Margin { get; set; }

MinHeight Property​

Minimum height in device-independent pixels. Only meaningful for table rows (maps to Avalonia.Controls.Documents.TableRow.Height and Word's w:trHeight); null for other blocks.

public Nullable<double> MinHeight { get; set; }

Padding Property​

Padding in device-independent pixels. Null means not explicitly set.

public Nullable<Avalonia.Thickness> Padding { get; set; }

Remarks​

Populated from RTF border spacing (\brsp).

PageBreakBefore Property​

Starts a new page before this block in paginated output (print/PDF). Maps to RTF \pagebb and Word's w:pageBreakBefore; null means no explicit break. The continuous on-screen flow ignores it.

public Nullable<bool> PageBreakBefore { get; set; }

RowSpan Property​

Number of grid rows the cell spans (maps to Avalonia.Controls.Documents.TableCell.RowSpan and Word's w:vMerge). Only meaningful for table cells; null (treated as a span of 1) for other blocks and un-merged cells.

public Nullable<int> RowSpan { get; set; }

TabStopPositions Property​

Tab stop positions in device-independent pixels. Default or empty means no custom tab stops defined.

public double[] TabStopPositions { get; set; }

Remarks​

Format-agnostic: contains only positions. Format-specific details (alignment, leader styles) are stored in format metadata. The array is immutable, so the value a background serializer reads cannot move under it.

TextAlignment Property​

Text alignment (Left, Right, Center, Justify).

public Nullable<Avalonia.Media.TextAlignment> TextAlignment { get; set; }

TextIndent Property​

First-line text indent in device-independent pixels. Negative values create hanging indents. Null means not explicitly set.

public Nullable<double> TextIndent { get; set; }

VerticalAlignment Property​

Vertical alignment of content within the block's height. Only meaningful for table cells (maps to Avalonia.Controls.Documents.TableCell.VerticalAlignment and Word's w:vAlign); null for other blocks.

public Nullable<Avalonia.Layout.VerticalAlignment> VerticalAlignment { get; set; }

WidowControl Property​

Widow/orphan control for paginated output: at least two lines of the paragraph stay and at least two lines move at a page break. Maps to RTF \widctlpar/\nowidctlpar and Word's w:widowControl; null means not explicitly set and resolves to ON (Word's default).

public Nullable<bool> WidowControl { get; set; }

On this page