FluentAvalonia Documentation

FluentAvalonia is a toolkit for Avalonia applications that provides a modern, fluent design inspired by WinUI. It allows developers to create cross-platform applications that maintain a high-quality, Windows-like aesthetic.

Important Notes:

• Deprecation Warning: The 1.x version of FluentAvalonia (compatible with Avalonia 0.10.x) is deprecated. Users should upgrade to Avalonia 11.0+ and FluentAvalonia 2.0+ for the latest features and support.
• Platform Support: Windows 7 and 8/8.1 are not officially supported. While the library might run on these versions, no support is provided for issues encountered there.
• Mobile/Web: The Control gallery versions for Android, iOS, and the browser are not actively maintained, though they are theoretically functional.

FAAppWindow is designed to provide a modern Windows window experience within an Avalonia application.

• Windows: It forces an extended window theme with a custom caption bar while preserving system effects like drop-shadows, borders, and DWM (Desktop Window Manager) effects.
• macOS/Linux: It does not intervene; the window behaves like a standard Avalonia Window.

On Windows, FAAppWindow replaces the system caption bar with a custom TitleBar consisting of a left-aligned icon (if provided) and title text.

By default, the TitleBar reserves the top space of the window, meaning your application content does not automatically extend into the title bar area. To customize the title bar or add extra items (like window controls or search bars), or to extend your content into the title bar area, you must follow specific implementation patterns (refer to the project's sample app for concrete code examples).

The XamlUICommand class allows you to define the user experience (UX) associated with a command in a single place. By defining a command as a resource (including its label, icon, shortcut, and description), you can reuse it across multiple controls. The controls will automatically inherit these UI properties, eliminating the need to redefine them for every instance.

Supported controls:

• CommandBarButton
• CommandBarToggleButton
• MenuFlyoutItem

Warning: Using hotkeys with XamlUICommand can cause crashes. If you need to use hotkeys, refer to the StandardUICommand documentation for workarounds to prevent application crashes.

The ContentDialog is rendered within the OverlayLayer of an existing window/TopLevel rather than using its own HWND or Top Level window.

Key Requirements & Behaviors:

• Lifecycle Compatibility: Because it doesn't use a separate window, it is compatible with non-desktop Application lifetimes.
• Dependency: You cannot launch a ContentDialog on its own; a TopLevel containing an OverlayLayer must be present.
• Concurrency: Unlike WinUI, there is no limit to the number of ContentDialog instances a single TopLevel/Window can display simultaneously. If multiple dialogs are launched, they will overlay each other. You are responsible for managing the state if you need to prevent overlapping dialogs.

Starting with FluentAvalonia v3 (compatible with Avalonia 12.0), FAAppWindow relies on Avalonia's native WindowDrawnDecorations API rather than using a custom WndProc to extend the client area.

Important constraints for v3 on Windows:

• You cannot manually change ExtendClientAreaToDecorationsHint.
• ExtendClientAreaTitleBarHeightHint has no effect.

If you encounter issues with window decoration, verify if they persist with a standard Avalonia extended window. If they do, the issue is likely an upstream Avalonia bug.

A StandardUICommand allows you to define the user experience (UX) of a command in one place and reuse it across multiple UI controls. It encapsulates the command's icon, label, keyboard shortcut (hotkey), and description.

Supported controls for StandardUICommand include:

• CommandBarButton
• CommandBarToggleButton
• MenuFlyoutItem

The TextCommandBarFlyout is a specialized flyout that automatically provides context-sensitive commands (like 'Copy') based on the state of the attached control. You do not need to manually specify commands; the flyout adapts its available actions based on clipboard state, text selection, and whether the control is a TextBox or a PasswordBox.

Note on limitations:

• Currently, formatting options like Bold, Italic, or Underline are not available due to Avalonia's rich text support limitations.
• It is the default ContextFlyout for TextBox in FluentAvalonia.

Ensure your Avalonia version matches the requirements for the specific version of FluentAvalonia you are using:

The NumberBox control uses a NumberFormatter property of type Func<double, string> to handle how values are displayed. Because .NET lacks some of the culture-aware formatters found in WinRT, this property allows you to provide a custom function to format the numeric value into a string.

When you provide a function, it receives the current double value and must return the formatted string to be displayed.

Constraints:

• NumberFormatter is NOT an AvaloniaProperty, so it does not support Data Binding.
• The returned string must represent a numeric value. You cannot include special formatting characters like % in the returned string.

The Playground allows you to type XAML markup into an edit box and load it into a UserControl container to see how it looks and behaves in real-time.

Key constraints and features:

• DataContext Bindings: DataContext bindings do not work in the Playground.
• Resource Lookups: Resource lookups are performed within the context of the Playground container, meaning the full FluentAvalonia (FA) theme is available for use.
• Theme Testing: You can use the theme switch button in the gallery to dynamically swap between light and dark modes to verify your markup's appearance in both.

For detailed guides, API documentation, and getting started instructions, visit the official documentation site:

FluentAvalonia Documentation

To see the controls in action and view practical code implementations, refer to the FAControlsGallery sample application included in the repository.