Merge branch 'main' into main

Author: jindongjie

docs/guides/platforms/windows/host-avalonia-controls-in-winforms.md

@@ -0,0 +1,54 @@
+---
+id: host-avalonia-controls-in-winforms
+title: Host Avalonia controls in Windows Forms
+---
+
+# Host Avalonia controls in Windows Forms
+
+Avalonia controls can be hosted in Windows Forms applications. This enables a step-by-step migration of existing Windows Forms applications to Avalonia.
+
+## Overview
+
+An exemplary Windows Forms application with Avalonia controls requires at least two projects:
+
+1. `YourApp` Cross platform library where you put your Avalonia controls 
+2. `YourApp.WinForms` Your existing Windows Forms application
+3. `YourApp.Desktop` (optional) Executable Avalonia application, required only for the Visual Studio Avalonia designer
+
+As Windows Forms is only supported on Microsoft Windows, adding Avalonia controls to your app will not make it cross platform.
+
+## Step-by-step instructions
+
+These instruction assume that you use Visual Studio 2022 with the Avalonia extension.
+You can adjust the steps and leave out the `YourApp.Desktop` project if you are using VS Code or Rider.
+
+1. Create both Avalonia projects
+   - In Visual Studio add a new project to your solution
+   - Choose _Avalonia C# Project_
+   - Select at least _Desktop_ as target platforms
+   - Click _Create_
+   - You should now have a `YourApp` and a `YourApp.Desktop` project in your solution
+2. Add references to your existing Windows Forms project
+   - A package reference to `Avalonia.Desktop`
+   - A package reference to `Avalonia.Win32.Interoperability`
+   - A project reference to `YourApp.csproj`
+3. Add the following lines in your `Program.cs` before you call `Application.Run()`
+```cs
+AppBuilder.Configure<App>()
+    .UsePlatformDetect()
+    .SetupWithoutStarting();
+```
+4. Add an `WinFormsAvaloniaControlHost` control from the Toolbox
+5. Add the following line to your form's constructor after `InitializeComponent()`
+```cs
+winFormsAvaloniaControlHost1.Content = new MainView { DataContext = new MainViewModel() };
+```
+
+Now you should see Avalonia's default main view _Welcome to Avalonia_ in your Windows Forms application.
+
+:::info
+You cannot use ReactiveUI for your Windows Forms and Avalonia controls at the same time.
+
+If you want to use it for Avalonia you must register ReactiveUI at the `AppBuilder` with `.UseReactiveUI()` in `Program.cs`.
+Do not include a reference to `ReactiveUI.WinForms` otherwise interactions will not work (see [#16478](https://github.com/AvaloniaUI/Avalonia/discussions/16478)).
+:::

docs/guides/styles-and-resources/resources.md

@@ -108,6 +108,10 @@ To add a resource dictionary file, follow this procedure:
 -  Type the file name you want to use.
 -  Click **Add**.
 
+:::note
+After the resource file is created you have to correctly include it into your application. See [Include and Merge Resources](#include-and-merge-resources) section.
+:::
+
 You can now add the resources you want to define in the position indicated. It looks like this:
 
 ```xml
@@ -173,6 +177,22 @@ Here the border control is using the resource with the key 'Warning'. This is de
 
 Resources can be included from a resource dictionary file, and merged with the resources defined in another file (even if there are not any).
 
+<img src="/img/gitbook-import/assets/image (1) (4).png" alt=""/>
+
+In case, if you would like to merge resource dictionary on the whole application level, you have to declare a resource dictionary in the in the **Application.Resources** section of application XAML **App.axaml** file, like this
+
+```xml
+<Application.Resources>
+  <ResourceDictionary>
+    <ResourceDictionary.MergedDictionaries>
+      <MergeResourceInclude Source="/Assets/AppResources.axaml" />
+    </ResourceDictionary.MergedDictionaries>
+  </ResourceDictionary>
+</Application.Resources>
+```
+
+You can also merge resource dictionary to declare merged resources to be specific to a style.
+
 <img src="/img/gitbook-import/assets/image (1) (3).png" alt=""/>
 
 This means that you can implement styles in one file, and use resources defined in another. This keeps your styling consistent, and your application solution well organised and easy to maintain.
@@ -189,7 +209,7 @@ To include the resources dictionary from a file in a styles file, add the follow
   </Styles.Resources>
 ```
 
-In the above example, the resources file `AppResources.axaml` is located in the `/Assets` project folder. You can then define the styles using the resources, for example:
+In the above examples, the resources file `AppResources.axaml` is located in the `/Assets` project folder. You can then define the styles using the resources, for example:
 
 ```xml
 <Style Selector="Button.btn-info">

sidebars.js

@@ -380,6 +380,13 @@ const sidebars = {
                 'guides/platforms/ios/build-and-run-your-application-on-a-simulator',
               ],
             },
+            {
+              'type': 'category',
+              'label': 'Windows',
+              'items': [
+                'guides/platforms/windows/host-avalonia-controls-in-winforms',
+              ],
+            },
             {
               'type': 'category',
               'label': 'Raspberry PI',