v11 How-To Guides - Requesting suggestions

[MikeCodesDotNET]

As we prepare for the release of Avalonia v11, we're keen to strengthen our documentation, especially regarding how-to guides. Guides are problem-oriented and take the reader through the steps required to solve a real-world problem. Each guide will come with a completed project to clone and explore at your leisure.

We're looking for suggestions on what content you'd like to see. We've currently got the following items on our to-do list:

• How to display an image from a ViewModel.
• How to use Google fonts.
• How to use native menus.
• How to display a list of data.
• How to modify a bound value (converters).
• How to use platform features.
• How to open and save files
• How to show a dialog.
• How to copy and paste.
• How to drag and drop.
• How to add a splash screen.
• How to customise a button's hover.
• How to deploy to RaspberryPi.
• How to package a macOS application.
• How to use the datagrid.
• How to create a navigation control.
• How to get screen resolution.
• How to show context menus.
• How to color a single word in a TextBlock.
• How to change the color theme.
• How to use SVG images.

[workgroupengineering]

But first you need to implement a mechanism similar to readthedocs which allows you to manage different versions (0.9.x, 0.10.x, 11.x) of the documentation.

[MikeCodesDotNET]

We're in the process of doing that. Do you have any suggestions relevant to the question?

[workgroupengineering]

Sorry, the tone of your answer, my inteo is not that. My suggestion was just that because at the moment the documentation is confusing because there are several mixed versions. I'm glad this issue gets resolved soon.

[MikeCodesDotNET]

You can see a proof of concept of the new docs portal. It's nowhere near complete but it was spun up just to explore.

[cirrusone]

Can I suggest -> How to implement a column filter on the datagrid.

Additionally, v11.docs.avaloniaui are really difficult to find from the standard docs docs.avaloniaui. It would be good to have a direct link to v11 on the standard docs.

[MikeCodesDotNET]

The v11 docs are a work in progress. The plan is to migrate all our docs to a new system allowing us to have versioned and multi-lingual docs within a single site. I've been exploring using Docusaurus and you can see a proof of concept here.

[BAndysc]

I know there are examples for this, but I think a guide How to render 3D graphics in Avalonia using DirectX/OpenGl/Vulkan/Metal would be useful as this is a common question that people used to ask in the past.

[maxkatz6]

I think some of more complex scenarios should be covered by the Avalonia.Samples repo and not guides. But yes, it should be covered somewhere.

[amerkoleci]

I know there are examples for this, but I think a guide How to render 3D graphics in Avalonia using DirectX/OpenGl/Vulkan/Metal would be useful as this is a common question that people used to ask in the future.

I second this! As engine developer I miss how can I use Avalonia as my game engine editor

[MikeCodesDotNET]

As Max has said, this is probably outside the scope of a guide due to its complexity.

[rabbitism]

As CJK user, embedding and using fonts is always painful, especially in wasm project. Could be nice to have a guide guarantee to work.

[nicola36631]

Some release oriented How To would be really useful:

• How to package an app for release on [Windows | MacOS | Linux | Android | iOS]
• How to patch an app with updates

[danipen]

How to setup the project for native AOT build.

[alexeid1337]

• How to embed a web browser window at least for desktops (think like cross-platform WebView. Right now only Cef.Net supports that for both Windows and Linux)
• How to use SkiaSharp for rendering on a canvas like component

[MikeCodesDotNET]

WebBrowser is probably outside the scope as it’d be a 3rd party dependancy, but I do agree having some guides on Skia would be useful.

[MetacodeX7]

Even if there's a 3rd party dependency, if that's something users will want to do, it would be good to have a how-to guide about it. Even if the guide only lists the various 3rd party options and some advice, without giving sample code.

When I started using Avalonia, I needed to render Html but it wasn't clear what was the right way to do it, what were the options, and whether Avalonia did or did not have something that works for this. I spent a lot of time investigating and trying things to figure it out, which as an Avalonia beginner was a long and wasteful process. A simple how-to guide would have saved me a lot of headaches.

[MikeCodesDotNET]

My concern would be that it dramatically increases the work required for the team. We have limited resources and probably don't want to use them to create docs for community / 3rd party projects. We'd have a far better impact by limiting the scope of work and focusing on creating better docs for Avalonia UI.

[MetacodeX7]

You don't need to create the docs for community and 3rd party projects - you just need to mention their existence and where their own docs are. New users don't know whether something should be done by Avalonia tech or 3rd party tech. They don't necessarily need a full code sample - they just need to be pointed in the right direction.

If the how-to the user needs doesn't exist, this will either translate into a user that gives up, or a user that asks a question on telegram or Github, as I did . In the latter case, a member of the Avalonia team still took the time to write an answer. The only difference is that it wasn't directly in the documentation, and the answer won't be updated if the situation changes.

[Antix-Development]

My concern would be that it dramatically increases the work required for the team. We have limited resources and probably don't want to use them to create docs for community / 3rd party projects. We'd have a far better impact by limiting the scope of work and focusing on creating better docs for Avalonia UI.

Now that GetGeometry has been exposed it's possible to do more things with FormattedText such as draw outlined text with relative ease, which is what I was using the SKCanvas code to accomplish before.

[curvedspace]

I would like to see a how-to on creating a basic desktop CRUD application with a Sqlite database (add, update, delete records with a datagrid or list view for the records).

[aldelaro5]

Non exhaustive list cause I just went through a bunch of problems myself in my current project:

• In general, the biggest issue that I seen throughout the docs is the docs assumes I am an experienced wpf developers, but I only did some wpf work years and years ago. We talking simple things like I was looking through the radio button page and I couldn't figure out if it could work with an enum/int or not until I did a lot more digging than I should to figure out that no, I would want booleans for each of the buttons. If I had more experience in wpf, I would know this, but because I don't, I have to dig very deeply to find out.
• Avalonia behaviors is in general badly documented to the point that I had to check the source code p deeply to figure things out. My case happens to be related to the drag and drop thing which is listed, but I noticed it's mostly because behaviors expects me to know how they worked in wpf, but I never actually used them, I was trying to learn them in context of Avalonia.
• The role of styled/direct properties aren't really made clear in the context of view only code reuse. Let's say I want to have a usercontrol, but that takes in params and that once it's handled to that usercontrol, it has everything it needs to do its view only job. I took forever to figure out how you are supposed to do it and even got answers in the telegram about a completely different usecase that wasn't relevant in what I was doing (people answered as if I was trying to create my own control, but that's not what I wanted: I just wanted to reuse a part of a view, not make my own controls). This has everything to do with the fact I never really used them when I did wpf btw.
• For wasm, it is not clear what are the limitations of it. I originally thought that you couldn't access files because I read that you can't access the filesystem, but in digging further (which none of this was documented so I had to google a lot here), I found it's not completely true and that you can actually open files through the same dialog style than in desktop. That being said, it turns out saving wasn't the case for firefox (which is being addressed rn), but finding that out was almost a deal breaker originally. In general, these limitations should be better documented so I know what to expect.
• DataGrid. Simply in general, that control badly needs love in how it's explained. I was trying to reuse template columns and I ended up finding a way to do it, but finding how was WAY harder than it should have been because the docs explains the most standard verbose syntax that you would see in wpf, but if I have a bunch of similar datagris, I would want to abstract parts of it out and you CAN do it, but it is not clear WHAT I COULD DO. For example, you can't bind the columns list directly, but you can add/remove them after the fact with different display index which I ended up doing after a bit. This actually joins with the idea of direct properties not being explained that well because I ended up making use of them heavily here. Also, might as well point it out: I noticed some strange styling behavior on the columns headers that I couldn't figure out with the dev tools and the docs didn't really help me (the header would take blank space it really shouldn't).

Those I would say were my biggest pain points. I just think that the current approach of the docs is aimed at experienced wpf devs moving to avalonia rather than being completely new to this concept despite the fact the docs ALSO does have pages about this angle. While it is nice to see this, I feel it's not enough for me to go from beginner in avalonia to intermediate where it feels like a huge difficulty spike because of the docs.

As for howto suggestion: making wrappers around models that do not implement change notifications. This is something I wanted to do for reasons, but searching online, I see not only many others ran into this need, but I also saw how lacking the explanations for this usecase are everywhere. Even wpf articles, I took a bit to find out the optimal way to do this. I think it's something avalonia could do well in documenting, bonus points if it involves collection which I made my own abstraction to make it work, but it took a while to get there.

[robloo]

I couldn't figure out if it could work with an enum/int or not until I did a lot more digging than I should to figure out that no, I would want booleans for each of the buttons. If I had more experience in wpf, I would know this, but because I don't, I have to dig very deeply to find out.

The ColorPicker uses RadioButton with an enum. To do this, the standard method from WPF using a converter is used. I added the converter to Avalonia itself though so everyone can use it going forward: https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.Controls/Converters/EnumToBoolConverter.cs.

Avalonia behaviors is in general badly documented

I believe most are following UWP behaviors which are well documented on Microsoft's websites.

The role of styled/direct properties aren't really made clear in the context

Yes, I plan to add documents for that myself if it isn't further clarified by someone else. This was heavily discussed here: #9944. Basically, only use DirectProperty for read-only or calculated properties right now. Also for animation due to performance. There are other special cases but you probably won't run into them.

[aldelaro5]

For the radio button, well that's new to me, but again, same issue where it's the kind of stuff that is common enough, I would expect to see in the radio button page. This is because while bools can work for maybe <= 3 choices, it doesn't scale well so someone will eventually run into this.

About the properties, it's not necessarily the differences between styled and direct that was the problem, it's rather the usecase being not well explained. While the docs explains what it allows me to do (pass values to the view by attributes), it doesn't explain how you can use this to pass bound values to a subview. I think this is better explained by an example: https://github.com/aldelaro5/Bug-Fables-Save-Editor/blob/main/BugFablesSaveEditor/BugFablesSaveEditor.Core/Views/ViewModelCollectionView.axaml

This view binds a couple of stuff to its code behind, those are the properties I put. This allows me to have any view display it as a subview, but while also passing the bindings so it goes vm -> master view -> properties of the sub view -> sub view.

So in this case, I am not making a "control", I am making a reusable view with many controls inside of it. The problem I had is the way you did the binding like this, this took me a very long while to figure out because the docs wasn't really explaining how this is doable, but the samples that explains you about the properties talks about making controls.

This might be solved by another sample or a guide, but it definitively should have something.

EDIT: oh btw, for avalonia behaviors, I personally don't think it's a good idea to simply link to microsoft's docs. I say this because these mostly applies to wpf apps, but since then, practices changed a lot. This is actually related to my issue where because I tend to get more yields out of looking up wpf docs than avalonia, I have to be more careful because the docs I find are much older and might not be optimal today. I think there might be merit to adapt the docs on this.

[jack775544]

How to create a navigation control.

I would love for this to not just cover the visual side, but also handling the routing as well. I know there is a ticket for version 11 for page based navigation routing and would like to have some firm examples to follow if that makes it into the release. My current application that I am developing is using the ReactiveUI routed view host, but if you are not already invested into ReactiveUI then there isn't really any guidance on what to do.

One other thing that I would really love to see is some more explicit documentation on lifecycle methods of controls. One problem that I have faced in the past was manipulating the position of a control based off of its parents height. I ended up using Loaded but I couldn't find any documentation on why that was the right choice. Something like a diagram of the control lifecycle (something like this for React) would be great for helping out with these situations. I guess extending on from that, having some docs on what the difference between the logical and visual trees are and how they relate to controls as well would be great.

[Mrxx99]

How to create a single instance application (and bring existing MainWindow to front)

[dbriard]

Good idea, I did not look into it yet, and I am not sure what I use with WPF is cross platform.

[robloo]

Main UI topics not covered:

1. Localization. This is a big one and has been discussed a few different places. Basically you currently write your own markup extension and then generate the translation strings from the resource files using VocaDb.ResXFileCodeGenerator. Visual Studio plug-ins are very important here as well: ResXManager. I think this is the best workflow so far.

Since Avalonia is a UI framework only there are several things not covered that cross-platform app developers will need. These will keep coming up so it might be best to devote a section to them as well.

1. How to handle in-app purchases. You are going to need to recommend an third party library like .NET MAUI does. There is another discussion on that here: In app purchase controls / library for mac app store / windows app store? #9636.
2. Persistent settings: perhaps link to some of the third party libraries that can do cross-platform settings.
3. I would also show how to pull in MAUI essentials for the current platforms it supports

I also just updated the XAML framework comparison: https://github.com/robloo/PublicDocs/blob/master/XAMLFrameworkComparison.md You might want to review for areas that should be documented in a guide to fill in gaps/explain differences with .NET MAUI or Uno Platform.

[nielsbosma]

I'd appreciate a detailed guid for porting from v10 to v11.

[Len42]

Yes, please! I just tried updating my project from 0.10.19 to 11.0.0-preview7. I was able to figure out a few things but I can't get my ListBoxes to work.

[timunie]

@Len42 just to unblock you:

1. have you looked into the breaking changes wiki?
2. have you seen that if you want to bind items, you need to bind to ItemSource now? The reasoning behind this is that only this change unlocked new possibilities for us that Items could not do, unfortunately.

[Len42]

Thanks, I missed that. Do I just have to change the property name in the xaml or does it work differently? (This is why a porting guide would be helpful!)

[timunie]

Just change the name in the XAML. However, I fully I agree we need a porting guide once 11.0 is shipped. But normally you can't do it for every preview release.

[Mbucari]

The biggest changes I needed to make was migrating to the new StorageProvider to open and save files.

[kyuranger]

How to rewrite the control template of a control? It is very important for a new comer.

[lukaszossowski]

A guide that talks about the purpose and use of control themes, control templates, overriding them, etc would be appreciated, I think this may be a source of confusion for many new users, especially if they are not already very well acquainted with WPF.

[robloo]

The WPF docs don't help a lot here either as this is one place Avalonia has a lot of differences -- usually for the better.

[Antix-Development]

Reorder some documents to be in better order, for example the "Basics" section should be way up near the top. "Layout" should also be higher, and "Styling" maybe after "Controls".

It would be great to be able to download the docs so they can be accessed offline. I know there's a PDF export but it doesn't seem to contain any contents so it's rather hard to find anything in there.

Some better explanation of "DependencyProperty". I was trying to follow a WPF tutorial on Routed Events and then had to give up because Avalonia does it differently and I couldn't figure out what to substitute and where.

Please note, I'm a total noob at Avalonia and never touched WPF, so maybe my suggestions are dumb.

[timunie]

Please note, I'm a total noob at Avalonia and never touched WPF, so maybe my suggestions are dumb.

No, the opposite is correct. Folks who don't know anything yet are giving us the best feedback you can have. You are only a beginner once. And if you write docs as an experienced developer, you don't always know what topics to cover. So thank you very much 👍

[Antix-Development]

You're welcome. I guess I arrived at Avalonia at the right time then, I'm so green my boots still hurt my feet 👯‍♂️

[timahrentlov]

• How to add and control fonts
• A little background on how the c# [!] property syntax is implemented so you don’t go “huh?”

[MikeCodesDotNET]

1. Yep, agreed, and it's on the list :)
2. I'm not sure what you mean. Do you mean negating binding values?

[timahrentlov]

ad 2. Exactly. That was my initial thought too ☺️Take a look at https://v11.docs.avaloniaui.net/guides/binding-from-code where you find a few examples. It’s used other places too. I suppose it is a source generated feature that allows for a special way to bind properties together in code ?

[MikeCodesDotNET]

Thanks for clarifying :)

[timahrentlov]

Btw, looove the GetObservable and the underlying reactive pinnings. I did not know before I read this.

[Antix-Development]

• Slider documentation

The Slider basically has no documentation, just links to the API page and it's source code.

As a new user I found it terribly confusing trying to figure out how to get a sliders value as it is changing because the slider does not logically have a ValueChanged event like most other controls that support input (and most other frameworks or whatever that have a slider control). Instead I had to google and eventually found 10080 which contained a code snippet that I eventually used.

So having some solid documentation on the sliders arcane inner workings would be great :)

[jack775544]

I have felt this one as well. Ended going to the WPF Slider docs to try and work out what the different properties were.

[MikeCodesDotNET]

We can make a guide for sliders. I’m guessing you’re not using MVVM?

The new (WIP) docs do include slider info: https://v11.docs.avaloniaui.net/reference/controls/detailed-reference/slider

[Antix-Development]

No I'm not using MVVM. For my next Avalonia project I'll give MVVM another try as I'm becoming more comfortable with Avalonia.

[rabbitism]

As discussed in tg, we should have a documentation page for control lifecycle.
Please see https://github.com/AvaloniaUI/Documentation/issues/347

[RobinsonWM]

These two might be part of "How to use platform features," but I ran into two issues building a cross-platform app that I put together quick solutions for, and I thought it might be nice if the Avalonia docs could recommend more tried and true solutions:

• For a desktop app, it would be nice to have shortcut keys use Ctrl on Windows and Linux but Meta on Mac (e.g. Ctrl+S on Windows/Linux but ⌘S on Mac.) I wanted it to respect the platform whether I was running on Desktop or Browser.
  • I came up with a solution using AvaloniaLocator.Current.GetService<PlatformHotkeyConfiguration>() and iterating all the Buttons, MenuItems, and InputGestures in a parent control to fix them up. It used [JSImport] to discover the OS when running browser. It worked, but I would like to know if there is a more "recommended" solution to this common problem.
• My desktop app had some modal dialog boxes, which obviously did not work in Browser. I ended up using a suggestion from https://stackoverflow.com/questions/62194012/avalonia-ui-pop-up-overlay and building some infrastructure around it to use a modal on Desktop or overlay in Browser, but again it would be nice to know if I hobbled together unfortunate code or if there is a more recommended solution.
  • It also took me a bit of digging to grasp the concept of View, Window, and TopLevel, and how those applied when running in a Browser

[Maruhl]

I would like to see a guide app that you can "just" download and see it live. With integrated code/Xaml viewer etc. Maybe you could combine it with the "Avalonia Control Gallery". Because until today you can't just test the app without going to the Microsoft Store.

At the end of the day, it's all about taking beginners by the hand and helping them learn how to do it all. Of course, there must also be in-depth documentation. But for this, the entry hurdle must first be kept small.

[dbriard]

From the issues I has when discovering Avalonia few weeks ago, I am thinking about:

1. What are the WASM limitations for people that never work on web, and how to deal with them, such as the single thread limitation, until Avalonia allow to use multithread compilation flag. Also explain that AOT is so much faster than debug/release. We may think it is too slow if you do not spend time to compile with AOT.
2. For the Google fonts guide, how could we use them in WASM without embedding them in ressources. Ideally a sample with a font combo box that download then on demand.
3. How to use custom draw operations with Skia. That's new to WPF developer and that open a lot of possibilities.
4. How to use OpenGL. For instance, how to create a control that draw a 3d object/scene in Avalonia, with transparent background if possible.
5. How to save app settings on all supported platforms.
6. How to deal with app suspension/restoration (when you reboot with the app still running).
7. More info how to make Avalonia app to launch on MacOS, for non Mac users. I tried and it do not worked. May be a tool to package and create additional files needed.
8. The limitations of each platforms, i.e file picking
9. A guide about storage files and bookmark, I didn't figure out what bookmark was at first...
10. May be a guide about best practices and optimisation pitfall? For example my first Avalonia app was a scrollviewer with a 24 mpxl image, and it was mega slow!! (2 fps may be). Big disappointement, hopefully I searched and discover that it was because Avalonia do not reserve enough GPU memory for the image (a single image!) and I had to add something in the app project to increase the default value. Then it was super fast and smooth. As WPF developer I never had to think about that and I never run into that performance issue... So yes this last point almost made me to give up and never look again to Avalonia...

[dbriard]

After seeing QA live, a guide about how use compression for WASM app would be welcome top.

[zigzag312]

How to mutate visual tree depending on a state. Going beyond IsVisible property using DataTemplates and other things. Best practices, pros & cons of each method (like performance implications).

[cirrusone]

A more detailed tutorial on themes would be useful, such as

1. How to amend existing theme using <Style.Resources> and <Color x:Key="ThemeAccentColor">#777777</Color> etc.
2. How to change themes both at design time and runtime.
3. How to create a new theme from scratch so that it works across existing controls.
4. Font handling in themes.
5. An area for users to share themes with screenshots and resources to recreate theme.

[zigzag312]

For each XAML example in docs also show view markup in C# code version of an example (if you are serious about Avalonia.Markup.Declarative).

[xD0135]

I think it would be extremely useful to provide a detailed tutorial on how to develop an adaptive application for both Desktop and Mobile from a single codebase, including best practices, gotchas, accessing platform-specific APIS, and the publishing process for Mobile. I think having something similar to how Flutter does it would be extremely valuable to the Avalonia community.

[anose001]

I agree with this. This would be extremely helpful

[DmitryZhelnin]

One frequently asked question for desktop apps:

• How to exit the app with user confirmation

[cotti]

• Best/At-least-adequate practices to handle displaying a progress bar for an async/background thread operation
• General considerations for applications that load directly to the system tray, such as whether there's anything special to care about when handling it not having a MainWindow proper until something triggers one to be loaded (such as a tray menu item)

I'm not sure if it'd belong to the main docs, but some samples on Style/Event/DataTriggers (from Avalonia.Xaml.Behaviors) would be nice. Specifically, how and when Avalonia's style system can be leveraged to make some things that weren't as trivial on WPF more palatable with Avalonia.

[JohnKesko]

Reading through all the comments, here's my 2 cents to keep everything a bit more organized:
At the top of the documentation close to "get started" a section with:

1. Beginner (-Short background "What is WPF compared to Avalonia?" -How to get started? "Install for Win/Mac" -The first app: "ToDo-App" with no MVVM) Maybe link to a video or two if it's too much text to write.

2. Intermediate (-Moving on from a tightly coupled UI to introducing MVVM -Basic custom control)

3. Advanced (Here are some cool stuff you can do with Avalonia -CoolStuff1 -CoolStuff2 -CoolStuff3)

[robloo]

For point 2, MVU and projects without any XAML is increasingly popular for some scenarios. You can do things with less code by combing calculation and display logic. On the other hand MVVM forces separation of concerns and cleaner, more-maintainable code especially with larger projects/teams.

Software is cyclical but I think it's probably good to mention both patterns here and why a certain one should be used in some cases over the other.

[JohnKesko]

Software is cyclical but I think it's probably good to mention both patterns here and why a certain one should be used in some cases over the other.

Totally agree, valid point.

[TheMulhima]

Could there be a page on testing the UI of the app?