ModernWPF Documentation

ModernWPF periodically synchronizes its resource values and control templates with the official Microsoft WPF Fluent theme. This ensures that ModernWPF applications maintain visual parity with the official platform while preserving backward compatibility for older target frameworks (like net462).

Key behaviors to note:

• Target Framework Differences: On net10.0-windows7.0, ModernWPF uses official templates via FluentControlsResources. On older frameworks (net462, net8.0-windows7.0), it uses backported templates that mimic the official look.
• Resource Aliases: ModernWPF often uses its own resource aliases (e.g., ButtonBackground instead of official WPF Fluent keys) to maintain a stable public API surface, even when the underlying values are synced from the official source.
• Intentional Differences: Some values (like TextControlThemeMinWidth or specific CornerRadius implementations) are intentionally kept different from the official WPF Fluent to prevent layout breaks in existing ModernWPF applications.

ModernWpf uses the official WPF Fluent ScrollBar style as the source for the stock System.Windows.Controls.Primitives.ScrollBar template. This ensures that the ScrollBar in ModernWpf applications behaves identically to the official WPF Fluent implementation.

Key Behaviors

• DefaultStyle: The DefaultScrollBarStyle follows the official WPF Fluent setter surface, including Margin=0, Padding=0, SnapsToDevicePixels=True, and OverridesDefaultStyle=True.
• Orientation: Orientation selection uses official WPF Fluent triggers:
  • Horizontal: Sets Height=12 and uses HorizontalScrollBarTemplate.
  • Vertical: Sets Width=12 and uses VerticalScrollBarTemplate.
• Template Parts: The templates utilize official WPF Fluent parts: PART_Border, line-button, PART_Track, page-button, and thumb shape.
• Compatibility: For older target frameworks, System.Runtime namespace references are mapped to mscorlib, and Border.CornerRadius is mapped to maintain the 4px thumb radius via the existing ModernWpf backport bridge.

ModernWPF maps the ResizeGrip control to the standard WPF System.Windows.Controls.Primitives.ResizeGrip. The styling in ModernWPF is designed to match the official WPF Fluent design language.

Key characteristics of the ModernWPF ResizeGrip include:

• Glyph-based Template: Uses a plain WPF TextBlock with a glyph instead of the older tiled Path or DrawingBrush drawings.
• Property Alignment: The following properties are aligned with official WPF Fluent values:
  • ResizeGripMinHeight
  • ResizeGripMinWidth
  • ResizeGripIconSize
  • ResizeGripIconGlyph
• Template Resources: The template utilizes SymbolThemeFontFamily, ResizeGripIconGlyph, ResizeGripIconSize, and ResizeGripForeground.
• Theme Aliases: ResizeGripForeground is provided via theme resource aliases:
  • Light/Dark Themes: Points to ControlStrongFillColorDefaultBrush.
  • High Contrast Theme: Points to SystemColorButtonTextColorBrush.

The ModernWpf WrapPanel is a source-backed WPF port of the official WinUI 3 implementation. It is not a legacy WPF approximation but follows the WinUI 3 row-building and layout algorithms.

Key characteristics include:

• Public Surface: Matches WinUI 3 IDL, including Padding, ItemSpacing, LineSpacing, Orientation, and ItemsStretch (with WrapPanelItemsStretch.None or Last).
• Layout Behavior:
  • Measure: Children are measured with padded available size. Collapsed children are skipped without adding spacing. Row height is determined by the maximum child cross size.
  • Arrange: Implements a source cache rule where rows are refreshed only when the arranged primary-axis size is smaller than the measured desired size. This preserves row breaks when a parent expands in width.
• Automation: Relies on the standard platform panel/child automation tree rather than a custom automation peer.

ModernWPF has updated its ListBox, ListView, and GridView styles to match the official WPF Fluent source templates. This ensures visual parity with the official Microsoft Fluent design for WPF while maintaining compatibility with older targets.

Key Implementation Details

• Templates: ListBox.xaml, ListBoxItem.xaml, GridView.xaml, ListView.xaml, and ListViewItem.xaml now use official stock WPF Fluent templates.
• Resource Management: The official split dictionaries are merged via ModernWpf\StockControlsResources.xaml to provide a single public entry point for stock controls.
• Converters: Instead of using the official WPF Fluent.Controls.ViewIsGridViewConverter, ModernWPF uses its own ModernWpf.Controls.Primitives.IsGridViewConverter to maintain compatibility.
• Theming: Official resource brush definitions are mapped to ModernWPF aliases in ThemeResources\Light.xaml, Dark.xaml, and HighContrast.xaml to integrate with the existing ModernWPF theme model.

The LayoutPanel in ModernWpf is a source-backed WPF port of the WinUI 3 LayoutPanel control. It provides a layout surface that follows the WinUI 3 algorithm for measuring and arranging children.

Key Features

• Public Surface: Supports Layout, BorderBrush, BorderThickness, Padding, and CornerRadius.
• Layout Logic: Available/final size is reduced by padding and border thickness (clamped to zero), then delegated to the specified Layout. If no layout is present, it applies the size as a single fill rectangle to every child.
• Layout Replacement: When the Layout property is changed, the old layout is detached, the new layout is initialized and hooked, and the panel invalidates its measure.
• Chrome Rendering: Uses LayoutChromeHelper to render equivalent border and corner radius effects in WPF.
• Clipping: Rounded layout clipping and hit testing are implemented using WPF Geometry and HitTestCore.
• Children Access: Provides a lightweight IReadOnlyList<UIElement> wrapper over the UIElementCollection to mimic WinUI's Children().GetView() behavior.

ModernWPF implements a WPF-based substitution for the WinUI ThemeShadow compositor. While not a literal port of the WinUI compositor, it achieves parity by deriving shadow properties—such as depth, blur, offset, inset, hollow-center behavior, and light/dark opacity constants—directly from WinUI source code and MockDComp visual-tree masters.

Key technical differences to note:

• Rendering Engine: ModernWPF uses a software-rendered ThemeShadowChrome substitute instead of the WinUI compositor's UIElement.Shadow visuals.
• Corner Radius: ModernWPF uses a direct CornerRadius mask, whereas WinUI uses an adjusted NineGridBrush with insets and independent X/Y radii.
• Opacity: ModernWPF applies child opacity to a private shadow host to match WinUI behavior.
• Geometry: Shadow geometry is validated against WinUI MockDComp masters to ensure the WPF renderer's bitmap size and content offsets match WinUI's expected output for various scenarios (e.g., basic drop shadows, dynamic corner radii, and windowed popups).

ModernWPF provides a set of specialized WPF adapters designed to replicate WinUI 3 layout and composition behaviors within a WPF environment. These adapters ensure that layout properties like spacing, rounded corners, and content transitions behave identically to WinUI 3.

Key adapters include:

• BorderEx: Handles rounded corner painting and background sizing (outer vs. inner edge).
• GridEx: Adds RowSpacing and ColumnSpacing support to the standard WPF Grid, including support for negative spacing and multi-track spans.
• StackPanelEx: Implements WinUI-style spacing (only between visible children) and exposes snap-point contracts for scrolling.
• ContentPresenterEx: The preferred surface for text and chrome. It forwards properties like CharacterSpacing, IsTextScaleFactorEnabled, TextWrapping, LineHeight, and MaxLines to the underlying text element.
• ContentControlEx: Manages content transitions, specifically mapping NavigationThemeTransition to the WPF NavigationAnimation engine.