avaloniaui / avalonia-docs Goto Github PK

Coming from WPF's App.Current.Shutdown() it is not immediately obvious what the analog is for Avalonia. After reading about Lifetimes, it makes sense why things are not as simple as WPF but still left me wondering "okay, so how do I quit the desktop app?"

Going the classic MVVM route I was essentially trying to map a "Quit" MenuItem to shutdown the application and do any user prompting ceremony.

The first step was learning that the IClassicDesktopStyleApplicationLifetime interface (try saying that 5 times fast) is where the expected Shutdown() (or TryShutdown()) method lives. But how would I access this from my MainWindowViewModel?

The solution I came up with was to inject that lifetime into the VM and rework the startup code a bit:

App.axaml.cs:

public override void OnFrameworkInitializationCompleted()
{
    if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
    {
        desktop.MainWindow = new MainWindow { DataContext = new MainWindowViewModel(desktop) };
        // Kinda gross, maybe pass (exitCode) => desktop.Shutdown(exitCode) instead?
    }

    base.OnFrameworkInitializationCompleted();
}

MainWindowViewModel.cs:

public sealed class MainWindowViewModel : ReactiveObject
{
    // Maybe store an Action<int> requestQuit instead?
    private readonly IClassicDesktopStyleApplicationLifetime _lifetime;
    
    private string _windowTitle = App.AppName;

    public string WindowTitle
    {
        get => _windowTitle;
        set => this.RaiseAndSetIfChanged(ref _windowTitle, value);
    }

    public MainWindowViewModel(IClassicDesktopStyleApplicationLifetime lifetime)
    {
        _lifetime = lifetime;
    }

    public void OnQuitRequested() => _lifetime.Shutdown();
}

MainWindow.axaml:

...
<MenuItem Header="_Quit" HotKey="Ctrl+Q" Command="{ReflectionBinding OnQuitRequested}"/>
...

This works great and "feels" the most clean approach. I didn't love needing the entire lifetime interface stored by the VM, so maybe passing an Action<int> requestQuit that calls lifetime.Shutdown(exitCode) instead could be more de-coupled approach.

Anyways, it would be nice if something like this could be documented as it seems fairly elementary in the context of desktop applications.

E.g.

• How to set ItemsControl.ItemsPanel using a FuncTemplate<T>
• How to create a control template from code

More and more people are interested in avalonia web programming, can you explain how avalonia uses signalR to communicate with the server? Thank you!

Original Issue: AvaloniaUI/Avalonia#11935

We need to update the Supported Platforms to include the following:

• iOS
• Android
• Web Assembly

How to use

• SolidColorBrush
• LinearGradientBrush
  ...

"I've had a quick look through the new documentation for version 11.0.0, but it doesn't seem to cover much on how to implement and use the INotifyPropertyChanged interface."

https://twitter.com/ekralmusic/status/1673997667171463176

There is no info about Avalonia Notifications (except namespace section).
It's simple to use and i could add several Pages in Tutorials (?) section:

• Avalonia Notifications
  • Notification usage (with default WindowNotificationManager reference)
  • Styling Notifications

Stay-Up-To-Date > Whats-New

https://docs.avaloniaui.net/docs/controls/progressbar#customizing-the-progress-text

this page mentions you can customize the progress bar text. the version on the top says 0.10.x , but it seems this feature was added later and is not in a current 0.10.x release? is it planned for a 0.10.x release or will it only be in 11.x?

Hi, I will be glad to see separated Deployment section in documentation what will explain how to deploy finall app to final systems.

The avalonia web page https://docs.avaloniaui.net/docs/distribution-publishing/macos recommends nuget package Dotnet-Bundle for building MacOS app. However this no longer works and the developer says they can't support this tool and is seeking other contributers (see egramtel/dotnet-bundle#16 (comment))

Can you please update the avalonia docs to remove this recommendation or suggest a functional alternative?

https://zealous-desert-09e073403.3.azurestaticapps.net/docs/next/deployment/macOS

https://zealous-desert-09e073403.3.azurestaticapps.net/docs/next/guides/platforms/macos-packaging

Describe the bug
The documentation has entries for SplitButton and ToggleSplitButton, however in the XAML and in C# there's no Avalonia.Controls.SplitButton or ToggleSplitButton classes

To Reproduce

1. Create Empty Project
2. Try to add a SplitButton to the layout
3. Compiler complains

Expected behavior
The SplitButton should be restored, or the respective documentation removed

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: Windows
• Version 0.10.18

Additional context

Outside of Visual Studio or Rider environment, the docs just imply to
Alternatively you can install the Android command line tools from here and give a link to AndroidDeveloper.
https://docs.avaloniaui.net/tutorials/developing-for-mobile/android/setting-up-your-developer-environment-for-android

Downloading the AndroidSDK that way does not setup Xamarin.Android.Tooling.targets to have AndroidSdkDirectory and JavaSdkDirectory properties configured for the correct path.
As a result an error is thrown while compiling

This documentation update should cover users' questions from these issues: AvaloniaUI/Avalonia#6692 and AvaloniaUI/Avalonia#3100

Basics > User-Interface > File-Dialogs

People may want to define custom accents at runtime. Let's add docs about how to achieve this in v11.

Related: AvaloniaUI/Avalonia#11953

I've started to do a more detailed look at porting a UWP/WinUI app over to Avalonia and think a detailed guide would be useful (several apply to WPF as well). Below I'll collect the things I've found so far in the hopes of adding a dedicated page to the docs eventually.

XAML

• Switch to xmlns="https://github.com/avaloniaui
• Add x:CompileBindings="True" where possible (it is supported in most cases now)
• Replace all ThemeResource usages with DynamicResource
• Remove any <ResourceDictionary.ThemeDictionaries> Light/Dark/HighContrast dictionaries. Avalonia does not conceptually support this yet and will use a different pattern when this functionality is added. For now, resource dictionaries for dark/light should be manually loaded.
• Remove unsupported properties from XAML
  • Remove any UpdateSourceTrigger usage which was common in WPF/WinUI TextBoxes. See AvaloniaUI/Avalonia#3754
  • Spacing is missing in both Grid and StackPanel
  • Remove any Style property usage. This usually requires switching to the Theme property with a new ControlTheme or use style classes.
  • Remove BorderBrush, Background and BorderThickness property usage from Grid. Place the Grid inside a Border which has these properties like what was done in WPF. UWP/WinUI did this to flatten the visual tree for performance but it never made a lot of sense as Grid was just layout and should have no visual style.
  • Remove ComboBox.SelectionChangedTrigger="Committed" which isn't supported in Avalonia
  • More tricky, ComboBox doesn't have DisplayMemberPath, SelectedValue and SelectedValuePath: AvaloniaUI/Avalonia#4718. This requires some changes to view models to work-around and possibly switching types. More recently DisplayMemberBinding was added to replace DisplayMemberPath: AvaloniaUI/Avalonia#8922
• Switch from Visibility to IsVisible. This is one of the more involved changes and requires not only renames and property setter updates, but also converter and view model changes.
• Switch Style to ControlTheme in the cases of default control template styles
• Switch Style to using selectors and classes when not changing control templates
• Replace any control usage not in Avalonia. Note that effort was made in the 11.0 release to close the control gap with WinUI and Avalonia now includes several controls such as SplitButton, ToggleSplitButton, DropDownButton, ColorPicker etc. out of the box.
  • For those controls still not in Avalonia (ContentDialog, etc.) It is best to use FluentAvalonia to add back most of the missing controls when porting from UWP/WinUI
  • FontIcon -> Fluent Avalonia's FontIcon
  • ListView -> ListBox
  • etc...
• Switch to new DataTemplateSelector pattern https://github.com/AvaloniaUI/Avalonia.Samples/tree/main/src/Avalonia.Samples/DataTemplates/IDataTemplateSample
• Any behaviors will require switching to using the Avalonia.Xaml.Behaviors package https://github.com/wieslawsoltes/AvaloniaBehaviors. This is largely compatible and was designed to follow UWP from the start.
• Any AcrylicBrush usage must be removed. Avalonia currently supports an experimental acrylic material but it is usable only on Border.Material property so is conceptually different. Note that the entire window can still simulate acrylic/mica using different methodology TransparencyLevelHint="AcrylicBlur".
• Avalonia doesn't support x:Uid='key' resource localization. For localized apps, this creates another very involved change. The recommended approach is to create a localization/translation markup extension and consume .resx files by the extension. See: AvaloniaUI/Avalonia#8741 (comment)
• [Also Code] Avalonia controls do not have any header or header template properties. Usage of these properties common in UWP/WinUI must be removed. In Avalonia, create a new HeaderedContentControl as required for this or just separate out the headers into TextBlocks. Avalonia, like WPF, is a cleaner design as it avoids duplicate properties and bloat in many controls.
• ListBox does not support grouping like ListView does in WinUI. This means Linq IGrouping cannot be used nor CollectionViewSource or ListView.GroupStyle. To work-around this custom ListBoxItems must be created with different data templates.

Code-Behind

• All occurrences of .ActualHeight and .ActualWidth must be changed to .Bounds.Height and .Bounds.Width
• Change all event handler signatures to use new event args types. These are sporadic and its best to follow IDE error information.
• Convert property types
  • UIElement to object? or IControl? for content properties
  • FrameworkElement to Control
  • Brush Background/BorderBrush to IBrush?
• All ItemsControls such as ListBox and ComboBox require a collection to be created and then set to the Items property. The Items property cannot be used directly like in WPF/UWP/WinUI which separates it from ItemsSource. When not using pure MVVM with these collections in view models this requires changing the code to build collections directly.
• Resource lookup has changed. Code such as (Brush)Application.Current.Resources["key"]; generally doesn't work as it won't search the full resources (AvaloniaUI/Avalonia#6021). An extension method as described in the issue is generally the easiest fix but this still requires changing all usages in code.

Other

• Drag/Drop is heavily reworked coming from UWP/WinUI. However, Avalonia uses a pattern similar to WPF (but you must specially add handlers to the routed events as these are not exposed as CLR events).
• Tooltips also behave much more like WPF which requires changes coming over from UWP/WinUI.
• The most changed code is probably Visibility -> IsVisible. This shows up everywhere.
• Avalonia has a lot of non-mutable types such as brushes and colors that are mutable in WPF/UWP/WinUI. That requires changing code in some places.
• When porting over existing code Rider is almost mandatory. Visual Studio and the Avalonia plug-ins do not provide detailed enough error information to locate XAML issues in a reasonable way. Avalonia's name generator also is all-or-nothing so finding issues is very difficult in Visual Studio. However, Rider shows you right away any problems in your XAML code.
• Avalonia requires parameterless constructors in custom controls / views. That is not true in WinUI which can work with optional parameters (where all are optional).

Note: I might complete a base version of this for my own public docs repository. We'll see. Just collecting things here for now.

I am new to Avalonia, but quite experienced with WPF and develop using Rider on macOS.

While developing my UI, I wanted to support the native menu bar at the top of the screen. Going through the documentation, I could not find anything about this. Looking in the Controls section I found NativeMenu but it is not clear how it works.

Then I found an older Github issue that mentions NativeMenuBar but that's not in the docs. Ultimately, I searched the entire repo for this and found an integration test example that uses it in XAML.

Using that I got it to work, but it shows Avalonia Application as in the macOS menu bar instead of my window title. Still not sure how/where to change that.

It would be really nice to update the docs with how to use NativeMenuBar and NativeMenu for cross-platform UIs.

Mega-list by @maxkatz6:

From https://github.com/AvaloniaUI/Documentation/issues/399

Must be added before 11.0 release:

• ControlTheme documentation, comparison with 0.10 styling. Also would require updating Troubleshooting page. @grokys : #22
• ThemeDictionaries + ThemeVariants (can be mostly copy pasted from the AvaloniaUI/Avalonia#8166) @maxkatz6
• Fluent and Simple theme documentation. Fluent page must include details about palettes.
• Add proper TopLevel documentation as a separated page (and add links to it from service pages)
• OnPlatform markup extension @maxkatz6
• TextBlock Inlines @Gillibald #324
• AvaloniaUI/Documentation#27
• Update CompiledBindings page, as most of old issues were solved and it's possible to enable them globally now
• Update supported platforms page. Make sure macOS min supported version fully supports Metal API, as we plan to switch to Metal mid 11.x.
• New controls documentation pages (ColorPicker, DrowDownButton...)
• Effects API AvaloniaUI/Avalonia#11014 (+ not sure if box shadow was documented before)
• Document RenderOptions (especially since we have different defaults now) https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Base/Media/RenderOptions.cs#L7
• https://github.com/AvaloniaUI/Documentation/issues/438

Nice to have

• GPU low level interop (see AvaloniaUI/Avalonia#10014) @kekekeks
• Move breaking changes page from the Avalonia repo wiki to the documentation page. Format it properly.
• New events interaction gestures like BackRequested, Holding, pinch.
• Automation APIs
• Documentation on custom markup extension (including new OptionsMarkupExtensions)
• Runtime XAML parsing API which was improved in the 11.0
• Notes about System.Reactive removal?
• #48
• #58
• AvaloniaUI/Avalonia#6960

Won't be added:

• Composition related documentation. It's not considered stable atm, and might have heavy changes during the 11.x timeline.

Something from the 0.10 that really should be documented. Note, there are a lot more missing documentation pages, but I want to mention here major Avalonia features that get lots of questions about.:

• Control lifecycle (was changed in the 11.0 with Loaded/Unloaded events)
• NativeControlHost
• Headless API

Existing Documents

• avalonia-docs/docs/stay-up-to-date/whats-new.md

  Line 6 in 9c5df73

  TODO: What's new in Avalonia 11

• avalonia-docs/docs/basics/user-interface/controls/creating-controls/tutorial.md

  Line 4 in 9c5df73

  ---

• avalonia-docs/docs/basics/user-interface/file-dialogs.md

  Line 4 in 9c5df73

  ---

• avalonia-docs/docs/tutorials/music-store-app/index.md

  Line 14 in 9c5df73

  This is a more advanced tutorial. The 'To Do List App' is a recommended prerequisite if you have limited experience with the MVVM pattern. Read about the 'To Do List App' tutorial [here](../todo-list-app/). 

• avalonia-docs/docs/basics/user-interface/adding-interactivity.md

  Line 4 in 9c5df73

  ---

Issues from Old Docs Repo

Issues in old repro marked with "Content request":

https://github.com/AvaloniaUI/Documentation/issues?q=is%3Aopen+is%3Aissue+label%3A%22content+request%22

It's easy to misunderstand what is Avalonia's role on mobile and look for various packaging related documentation pages.
When in fact Avalonia does not do any packaging, so all the signing, icon related, dependencies questions should be redirected to the official Microsoft tooling.

For example, "How to add icon to Avalonia iOS app" should redirect users to the https://learn.microsoft.com/en-us/xamarin/ios/app-fundamentals/images-icons/app-icons?tabs=macos page ("How to add icon to .NET iOS app").

Short explanation of how exactly Avalonia works on top of mobile/wasm .NET runtime would be helpful as well.

https://realfavicongenerator.net/favicon_checker?protocol=https&site=docs.avaloniaui.net%2F

I will add soon

It will be nice to have documentation of control lifecycle, explaining the order of methods executed, when elements are attached to trees, or templates are applied to control.

Describe the bug
It does not build. I installed nuget "Avalonia.Themes.Fluent"
<FluentTheme Mode="Light"/>

Expected behavior
Very simple app, should be running. If I remove the xml line from App.axaml, the app will run having no background window or anything.

Desktop (please complete the following information):

• OS: Windows 11

https://docs.avaloniaui.net/docs/next/tutorials/music-store-app/creating-a-modern-looking-window
Need to update information about ThemeVariant. There’s old version with Mode=“”. Should be RequestedThemeVariant

Add docs after AvaloniaUI/Avalonia#7838 is merged

Discussed in AvaloniaUI/Avalonia#8300

Sample and docs

I see often questeions about how to use the OpenGL control. So I think we need to add docs about this control.

The page on the <Grid> control (source) makes no mention of the SharedSizeGroup property on RowDefinition and ColumnDefinition. The related Grid.IsSharedSizeScope is missing as well.

This page should be edited to include a sample <Grid> based <ItemsRepeater> example. For my case, it's to have a bit more control over the layout and look of the <DataGrid> control. So I use something like this:

public class TestModel
{
    public string ColumnA { get; }
    public string ColumnB { get; }
    public string ColumnC { get; }
    public string ColumnD { get; }

    public TestModel(string a, string b, string c, string d)
    {
        ColumnA = a;
        ColumnB = b;
        ColumnC = c;
        ColumnD = d;
    }
}

<StackPanel
    Grid.IsSharedSizeScope="True"
    Orientation="Vertical"
    Spacing="6">
    <Grid>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="Auto" SharedSizeGroup="a" />
            <ColumnDefinition Width="Auto" SharedSizeGroup="b" />
            <ColumnDefinition Width="Auto" SharedSizeGroup="c" />
            <ColumnDefinition Width="*" SharedSizeGroup="d" />
        </Grid.ColumnDefinitions>
        <TextBlock Grid.Column="0" FontSize="14" FontWeight="Bold" Margin="6" Text="Column A" />
        <TextBlock Grid.Column="1" FontSize="14" FontWeight="Bold" Margin="6" Text="Column B" />
        <TextBlock Grid.Column="2" FontSize="14" FontWeight="Bold" Margin="6" Text="Column C" />
        <TextBlock Grid.Column="3" FontSize="14" FontWeight="Bold" Margin="6" Text="Column D" />
    </Grid>
    <ItemsRepeater Items="{CompiledBinding TestEntries}">
        <ItemsRepeater.ItemTemplate>
            <DataTemplate DataType="models:TestModel">
                <Grid>
                    <Grid.ColumnDefinitions>
                        <ColumnDefinition Width="Auto" SharedSizeGroup="a" />
                        <ColumnDefinition Width="Auto" SharedSizeGroup="b" />
                        <ColumnDefinition Width="Auto" SharedSizeGroup="c" />
                        <ColumnDefinition Width="*" SharedSizeGroup="d" />
                    </Grid.ColumnDefinitions>
                    <TextBlock Grid.Column="0" Margin="6" Text="{CompiledBinding ColumnA}" />
                    <TextBlock Grid.Column="1" Margin="6" Text="{CompiledBinding ColumnB}" />
                    <TextBlock Grid.Column="2" Margin="6" Text="{CompiledBinding ColumnC}" />
                    <TextBlock Grid.Column="3" Margin="6" Text="{CompiledBinding ColumnD}" />
                </Grid>
            </DataTemplate>
        </ItemsRepeater.ItemTemplate>
    </ItemsRepeater>
</StackPanel>

This example shows how one can share column widths between different <Grid> controls[a], but the wrapping <StackPanel> and <Grid> could possibly be removed for a simpler example.

Should also mention that the names don't matter, as long as they're unique for each unique column width desired.

[a]: Yes, the <ItemsRepeater> generates multiple <Grid> controls (one for each row), but it's not entirely clear to beginners that that's happening. This example makes the sharing of widths more clear. Without it, one might be confused why they'd need the SharedGroupSize property.

Missing migratotion custom ItemsControl AvaloniaUI/Avalonia#9677

Certain important things are documented in the Wiki and not in the Avalonia documentation. So one has to dig really deep to get into that separate documentation.

I think this page should be in the main documentation.
Configuring X11 per monitor DPI

Sample project:
Archive.zip

Discussed in AvaloniaUI/Avalonia#11950

public static int Main(string[] args)
{
    var builder = BuildAvaloniaApp();
    if (args.Contains("--drm"))
    {
        SilenceConsole();
        return builder.StartLinuxDrm(args);
    }
    return builder.StartWithClassicDesktopLifetime(args);
}

The current documentation of the RadioButton is very bare bones and does not explain how to use it/has no examples/does not show how to property bind to the value.

Labels : [content request]

It would be really useful to have some clear examples that focus on the "Provider" Architectural Pattern with dependency injection that focuses on native APIs; RFID support might be a really good candidate.

Windows, Linux, MacOS and Android should support it nicely but iOS might not.

That could be a great opportunity on how to handle platforms that do not support a specific functionality.

The Custom Flyout sample has a few issues.

• CreatePresenter no longer exists on FlyoutBase (it is part of PopupFlyoutBase)
• [!Image.SourceProperty] = this[!ImageProperty]: this line doesn't compile. Image is both a class property and type. The compiler picks the property instead of the Image type.
• The title is "How to Create a Custom Panel" instead of Flyout

following PR AvaloniaUI/Documentation#368 we should add also some docs about how to enable validation for custom controls.

• Add a property with validation enabled
• Inside the ControlTemplate wrap the control inside the validation control

There's basically no documentation about mouse and touch events, and there's a decent bit of nuance that's not necessarily obvious.

One big example is capture. When is capture gained? When is it lost? What happens if the control which has captured the pointer has is moved/deactived/hidden while the mousebutton is still down? I don't want to deal with missing button release events.

Another use case is finding out what control is beneath the pointer when the button is released. In my case, I want a Visual Studio like docking control, so I'm handing over a control to a different part of the visual and logical trees on mouse release, provided the mouse is over a valid target.

The problem is that DragDrop is severely inadequate for this sort of use. I can of course serialize a reference into a string and back again, and use reflection to validate types, but this is a horrible kludge, and I don't particularly want my app leaking object references or other odd side effects if the user happens to drag something meant for internal use off to another program or over a textbox or something. However, to my knowledge, there just isn't a better way to do it.

from our chat:

Tim, [19.08.2022 11:43]
the question is, is Item the only supported syntax?

Tim, [19.08.2022 11:43]
or is Item[theKey] also working?

Tim, [19.08.2022 11:44]
And is MyOtherIndexedProperty.Item working?

So I can start to add Chinese docs.

There is a page (3 pages) in the documentation about opening dialogs here. It's a very complicated approach.

I just published HanumanInstitute.MvvmDialogs which makes this kind of operation super simple. I think the documentation should be updated to include this much simpler approach. With at least a link; the library's usage is well-documented already.

"And I think the navigation is mentioned only in Samples & Tutorials and it looks like the navigation remained the same as in the previous version."

https://twitter.com/ekralmusic/status/1673997844762558465

I think it might be a good idea to change the current 'Deployment / Publishing' section to 'Platforms', which then sub-sections for each supported platform. We can then have the deployment docs and other platform-specific info within these sub-sections.

I imagine a structure something like:

• Platforms
  • Windows
    • Publishing / Deployment
      • Ad-Hoc
      • Microsoft Store
    • Supported Versions
  • macOS
    • Publishing / Deployment
      • Ad-Hoc
      • App Store
    • Supported Versions
  • Linux
    • Publishing / Deployment
    • Supported Distros

Basics > User-Interface > Adding-Interactivity

List here the places where the docs are out of date:

• https://github.com/AvaloniaUI/avalonia-docs/pull/12/files/1590a705b11d146c33b76e4e26081610331401fa#diff-76675fb01d0eb84021b48a1e55651fe32159fb9c5909ff02ca057626364bca05: <FluentTheme Mode="Dark"/>

It is necessary to add information about UniformGrid to the page https://docs.avaloniaui.net/docs/layout/panels-overview