Add a basic, standalone xaml-free Hello World example to the docs

[tseguine]

According to the FAQ it is possible to use Avalonia without xaml, but I could find almost zero information in the official documentation for how to accomplish this. Maybe I just didn't find it, but it seems like if it exists it is well hidden.

It is really frustrating from a user perspective when the only introductory way of "Getting Started" in the docs is "Hey, install this visual studio extension and download this entire project that does 1000 things you don't want or need."

I understand it is more or less the intended way of using the framework, but I don't think it is too out of line to somewhere document the 3 liner to get a basic window to display:

Application app = Application.Current ?? AppBuilder.Configure<Application>().UsePlatformDetect().SetupWithoutStarting().Instance;
app.Styles.Add(new DefaultTheme());
app.Run(new Window() { Title = "Avalonia Basic Example", Content = "Hello Avalonia!" });

As someone with no prior Avalonia, WPF, or Winforms experience it took me several hours to figure out just those three lines. And I somehow think I am not the only person whose use case fits this way of using the library better than the xaml path.

[kekekeks]

The relevant docs about using Avalonia without XAML are here: https://docs.avaloniaui.net/docs/data-binding/binding-from-code

Those don't include basic stuff like constructing an object graph since we assume that you know what are you doing.

[alexzandros]

Being rude does not make you right.

[tseguine]

None of that stuff is actually pertinent or in any way helpful to the basic task of starting an application and creating a window. i.e. The first thing anyone would actually want to do with the library

[tseguine]

I also think you misunderstood my gripe: WPF which this API is apparently based on does not have this documentation issue. The architecture is slightly different so it makes sense that it is simpler, but in WPF it is both:

• Obvious enough to figure out in 5 seconds without any documentation whatsoever by a simple glance at the class names.
• Is actually documented anyway in an easily discoverable location in the docs.

It is a FAQ. That means you know this is something people have asked how to do. And even coming from WPF it wouldn't exactly be obvious how to do it in Avalonia.

I am merely suggesting giving an answer in the FAQ that is actually useful to someone who is actually trying to do the frequently asked thing.

My steps:

• Do the obvious thing, that would have actually worked in WPF.
• Fail because the platform layer is not initialized.
• Search for how to instantiate the platform layer.
• Find literally nothing except for some obscure posts on github where someone with the same issue getting the fairly unhelpful comment from you "You need to follow the framework initialization procedure, see project templates for examples." (you literally could have told them how to do what they were trying to do with less typed characters than what you actually told thim)
• Finally found a real actual answer that isn't "hey: download this example project. "
• No error, but window is inexplicably blank.
• Search for a reason
• find nothing
• actually download the template in frustration
• that works even though it is doing almost the exact same thing as I am line for line except loading xaml files.
• Go back to the example that was actually helpful
• Figure out you have to manually load the default theme for anything to actually display whatsoever.

Every single step is in my opinion reasonable and logical. I have used several different GUI libraries in several different languages in over 20 years of programming. And it has literally never in my life (even when I was entirely new to programming and a literal child) taken me more than 15 minutes to get the goddamn hello world application running without 5 files and over 100 lines of code.

Rant over. It is a usability issue. Period. Fix it or don't. At least if someone else has the same problem as me now, they will find this post instead of your unhelpful attitude of "we assume that you know what are you doing." GTFO with that bull.

[grokys]

Hi sorry about that, we're trying our best but we're trying as hard as we can. We don't have a team the size of some of the frameworks you may be used to using, currently and so documentation can be lacking for some use-cases (particularly if you're trying to avoid XAML). We'll try to add something to the docs about this.

[sn4k3]

I have used several different GUI libraries in several different languages in over 20 years of programming...

I only have used WinForms before, it took me few days to adapt and learn the framework but almost all questions and troubles were solved by look at documentation, which is not perfect but is enough to start, more when you have that such experience...

If you use Visual Studio with Avalonia extension, it's easy as create new project and select Avalonia. It will create a empty "Hello World" app for you with all requirements and things setup for you, no different from create a WinForm project.
Also look here: https://docs.avaloniaui.net/docs/getting-started to see step by step how to work with Avalonia.

About your title question, once by random I found an library or sample that spawn a window from code without any xaml and extra files, since I was not looking for it I forgot where I saw that or the name, but then it's possible...

Someone here could give you an anwser to obtain that, but your atitude isn't the best and may lead to people skip on you.
Ok documentation aren't complete and far from perfect, but look what this team did for the community of C# and desktop applications, for free and open-source! So far you don't have any C# alternative to multi-platform that behaves like Avalonia. Even MAUI is "far" and will not follow the same principle as Avalonia.
You could have just ask your question and then fork and update docs. Learn, share and retribute what others give to you.

[tseguine]

@sn4k3

Someone here could give you an anwser to obtain that, but your atitude isn't the best

My attitude was completely normal until someone told me "we assume you know what you are doing" when I came with a reasonable gripe. Following precisely the tone that I was approached with.

And at this point I basically already figured it out myself. My point was that I shouldn't have had to do that for something so basic.

[MikeCodesDotNET]

Hi @tseguine

I'm sorry that you've found several challenges with starting development with Avalonia, and I appreciate you taking the time to let us know.

We're aware that our documentation has gaps, and it's something we're keen to resolve. Our docs have been written from the perspective that developers will be writing their apps using XAML, reflecting how most of our community uses Avalonia.

Given our open-source nature, the most helpful thing you could do for us (other than contribute some docs) would be to create issues in the documentation repository to let us know of missing content.

Lastly, if the docs haven't helped, I suggest asking in our telegram community chat. That chat has hundreds of active Avalonia developers with a wealth of experience who can help.

[tseguine]

@MikeCodesDotNET

Are the docs also in github, and are you open to pull requests? If so (and I find time: using this is for a personal project not work) I might try to write something up.

[MikeCodesDotNET]

https://github.com/AvaloniaUI/Documentation

[timunie]

Hey @tseguine ,

Yes the docs are open source and PR are welcome. Additionally we have Avalonia.Samples which is also open source and should grow over time.

You can reach out to me via gitter or telegram and we can prepare a hello world sample together, which can then be linked to the docs.

Welcome to Avalonia and happy coding
Tim

[kkukshtel]

As a note I also ran into this exact issue — I read on the first page of the documentation that you could use it without XAML and then searched everywhere for literally any documentation on how to do it and the only thing I found was this Github issue. It's been more than two years since this was first reported, is there a canonical C# code-only example?

[thevortexcloud]

There is now a dedicated library to make it easier with some small examples : https://github.com/AvaloniaUI/Avalonia.Markup.Declarative

[tseguine]

I actually didn't intend to leave this hanging. I figured out how to do what I set out to do, and I was going to make a PR on the docs, but never got around to it because of life. It actually isn't that hard, there are just more gotchas than one would suspect.

If you want as minimal as it gets, then the three lines I posted in my original post basically do it. What djeikyb posted just recently is more or less what I original used (I dunno if it was that exact code but it was similar) as a working example to figure out what the minimal example is.

You are still going to run into small problems instantiating widgets programmatically, because the docs only really describe how to do it with xaml. But what I did was find what widgets I want to use using the docs, then look at the constructors and methods for those classes in my IDE.

In case it helps, Microsoft's documentation for WPF is pretty helpful actually when trying to figure out the widgets. You have to cross check some stuff though.

[djeikyb]

Fwiw @Dareka826 published a really helpful example here: https://github.com/Dareka826/Avalonia_no_XAML/blob/master/Program.cs

using Avalonia;
using Avalonia.Controls;

class MainClass {
    public static void Main(string[] args) {
        AppBuilder
            .Configure<Application>()
            .UsePlatformDetect()
            .Start(AppMain, args);
    }

    public static void AppMain(Application app, string[] args) {
        // Application needs a theme to render window content
        app.Styles.Add(new Avalonia.Themes.Simple.SimpleTheme());
        app.RequestedThemeVariant = Avalonia.Styling.ThemeVariant.Default; // Default, Dark, Light

        // Create window
        var win = new Window();
        win.Title = "Avalonia no XAML";
        win.Width = 800;
        win.Height = 600;

        var text = new Label();
        win.Content = text;

        text.Content = "Hello from C#!";
        text.HorizontalAlignment = Avalonia.Layout.HorizontalAlignment.Center;
        text.VerticalAlignment = Avalonia.Layout.VerticalAlignment.Center;
        text.FontSize = 72;

        win.Show();
        app.Run(win);
    }
}

[tseguine]

I think I based my code on this example originally (or something very similar to it). The issue I was trying to solve is that I needed to use it in a scenario that didn't really make sense to have an AppMain function. Specifically I was only using it for a transient splash screen in one code path, and a simple dialog in another. In any case I wanted as little code as necessary. I think my splash screen ended up being shorter and clearer than this example code.

The reason why I originally went on a rant, is that the docs seem to imply everywhere that this library is mostly Windows.Forms compatible.

And in windows forms I could have done what I wanted (at least in terms of shortest path to hello world) more or less with the single line. It's been a while, but If I remember correctly, you just new Window() and then call show on it. Which is I think the first thing anyone would think to do.

My issue was that going from the obvious thing to code that actually works was way bigger of an ordeal than seemed necessary.

[djeikyb]

Makes sense. I came to this issue trying to draw a grid in the code behind instead of xaml. I prolly won't ship this implementation, but it's an interesting practice problem.

It was incredibly clarifying to understand (or relearn? I feel like I knew this and just forgot) that in the code behind of a control, after calling InitializeComponent(), you can set the content property like this.Content = grid to whatever you want. Setting it to a control like Grid or StackPanel is interesting because they let you add multiple children.

Not sure how to work all this into a doc, but here's the code version of the previous paragraph:

// avalonia version 11.0.11
using Avalonia.Controls;

namespace Example;

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();

        var grid = new Grid();
        grid.ShowGridLines = true;
        grid.ColumnDefinitions.Add(new ColumnDefinition { Width = new GridLength(1, GridUnitType.Star) });
        grid.ColumnDefinitions.Add(new ColumnDefinition { Width = new GridLength(1, GridUnitType.Star) });

        var text1 = SomeLabel();
        var text2 = SomeLabel();

        Grid.SetColumn(text1, 0);
        Grid.SetColumn(text2, 1);

        grid.Children.Add(text1);
        grid.Children.Add(text2);

        this.Content = grid;
    }

    private static int _i = 0;
    private static Label SomeLabel()
    {
        var text = new Label();
        text.Content = $"halooooo {_i++}";
        text.HorizontalAlignment = Avalonia.Layout.HorizontalAlignment.Center;
        text.VerticalAlignment = Avalonia.Layout.VerticalAlignment.Center;
        text.FontSize = 72;
        return text;
    }
}

[tseguine]

In case it helps, Microsoft's documentation for WPF is pretty helpful actually when trying to figure out the widgets. You have to cross check some stuff though.

[stevemonaco]

You can simplify the ColumnDefinitions if you don't mind possibly taking a runtime exception if you mess up the syntax:

grid.ColumnDefinitions = ColumnDefinitions.Parse("*, *");

Either way, if the main goal is to have a minimal crossplatform window, then you're probably better off using GLFW .NET bindings or such. The time and effort spent creating XAML wasn't for the purpose of having people learn more things. As such, no-XAML approaches aren't really represented in the docs though that's equally because of time priorities.

[stevensrmiller]

I've written a set of no-XAML examples for those who are interested. There's a recommended order for helping to learn how they work, with comments in the code (the comments assume the reader is following the recommended order, so they don't repeat what's been said before).

I've looked at Avalonia.Declarative.Markup, but haven't been able to understand it yet. If anyone knows of documentation on that, please post a link or let me know. It does look promising.

My repo of no-XAML examples is at my GitHub page

[bmitc]

I get the sense from the developers that this is considered an advanced feature and not worth it to document. That is fine, but this feature is prominently advertised on the home page.

This is effectively my first foray into Avalonia. I am coming from Qt Quick with QML and Python as I would prefer building UIs with F# or at worst C# but not necessarily XAML. That this feature was advertised and F# was mentioned (!) on the homepage made me very excited and sold me immediately. However, I also found nothing in the documentation even alluding to this, which unsold me, as it makes me worry about its overall support, especially with third-party controls.

I would suggest that if it is not a priority to document this, then it would be best not to advertise it on the homepage.

[bmitc]

I'm hesitant to use that for the similar reasons alluded to above.

For example, how well is FuncUI supported? It's clearly a non-core solution. Will it work with third-party controls, like charts from Syncfusion or SciChart? Does it even support all of the functionality in Avalonia, such as drag and drop?

[stevensrmiller]

You could have a look at my no-XAML repo: https://github.com/stevensrmiller/AvaloniaWithoutXAML

I see you said you'd prefer F#, but you'd tolerate C#, which is what my examples all use. They're all pure Avalonia with no other product or library required (other than .NET itself, of course).

The Avalonia devs have spoken to the lack of documentation here and there. The short of it is that they are a small team working hard to pay their bills. The fact that this library is available as FOSS is kind of amazing. It's magnificently platform-agnostic. I use it to teach media coding to my university students, about have of whom use Windows and half use Mac. I have yet to run into a single issue arising from any differences between how Avalonia works on either.

Yes, the lack of documentation on the no-XAML approach is frustrating at times. But if one is persistent, a mix of looking at XAML for keywords, reading what doc there is, Googling, and looking at the Avalonia code itself will always get you though.

[MikeCodesDotNET]

I'm genuinely sorry that we don't have the non-XAML options documented. As @stevensrmiller mentioned, we're a small team doing our best to improve things.

Regarding documentation, two years ago, we invested a substantial sum (mid five-figures) in hiring someone on a short-term contract to improve our docs. While this did help improve things, we recognise we've got lots more to do. We funded this work through our commercial activities, as community donations didn't come close to covering the cost.

For over a year, we've asked our community for GitHub donations to help fund a part-time documentation writer. Currently, we receive about €400 monthly from our community of hundreds of thousands of developers. If every user donated just €1 a month, we'd have enough to grow our team from 11 to more than 70.

While I'd love for us to invest more in documentation, it's just not feasible to keep spending company funds on it when we need to focus on generating revenue (by building products and services). We're constantly trying to balance these priorities to keep our platform growing and sustainable.

[stevensrmiller]

This problem seems to plague the creators of lots of popular FOSS products. You become victims of your own success, with people expecting things without making contributions of their own. I really want to commend the Avalonia devs for not falling prey to the defense mechanisms a lot of others use in similar situations (i.e., becoming evasive; dismissing complaints as being evidence of ignorance; telling users they can fork off; simple whining). This library is one of the most mature, fulsome, useable FOSS products I've ever seen. It easily surpasses the usefulness and design quality of a lot of software that people pay for all the time. Somehow, the idea that the people who create such a thing expect also to make a living seems hard for the world to comprehend. FWIW, some of us do.

[ztl8702]

Just want to add a data point. I've been using Avalonia for a few months on a daily basis. I did not have WPF experience but it has been very smooth for me. Documentation has not been a big issue for me.

Whenever I am stuck, I almost always got unstuck by searching cs.github.com for examples or
asking ChatGPT. I rarely needed to raise an issue or ask in chat. I suspect there are a lot of silent happy users. :)

Documentation is nice. But the risk with writing documentation is that they are also a liability since they can get outdated. Nothing is free. The risk is small for users but for the team the opportunity cost could be huge. The proposition that better documentation necessarily will bring more users and therefore more revenue, is pretty hard to justify IMO.

I think the team is doing the right thing by NOT over-investing in onboarding documentation. That is for later in the adoption curve. I see that Avalonia is wisely avoiding chasing "majority adoption" too early. Keep it your way. 👍