main

Author: sharpchen

docs/document/Skill/Avalonia/docs/1. Fundamentals/2. XAML Essentials.md

@@ -1,26 +1,5 @@
 # XAML Essentials
 
-Each tag in XAML file is of `AvaloniaObject`, it can be of `Control` or something else but inherits from `AvaloniaObject`.
-
-::: code-group
-
-```xml [App.axaml]
-<!-- Application is AvaloniaObject but not a Control --> <!-- [!code highlight] -->
-<Application xmlns="https://github.com/avaloniaui"
-             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
-             x:Class="MyApp.App"
-             xmlns:local="using:MyApp"
-             RequestedThemeVariant="Default">
-    <Application.DataTemplates>
-        <local:ViewLocator/>
-    </Application.DataTemplates>
-    <Application.Styles>
-        <FluentTheme />
-    </Application.Styles>
-</Application>
-```
-:::
-
 ## XAML Namespace
 
 XAML namespace was a feature inherited from xml, it allows to import namespaces at any level of element, and all of its child elements within the scope can access the namespace.
@@ -64,14 +43,22 @@ Each child element within the scope can access it.
 - `x:DataType`: the `DataContext`(aka ViewModel in MVVM) for current control.
 - `x:Name`: name of the instance of control within the code-behind class.
     - XAML compiler would generate an instance by that name for your code-behind class.
-    - avalonia has a `StyledElement.Name` property available, which is an equivalence of `x:Name`
-- `x:Static`: accessor for **static members in assembly**
+    - avalonia has a `StyledElement.NameProperty` available, which is an equivalence of `x:Name`
+- `x:Type`: accessor for types, can be used as a **markup extension**. It's the equivalent of using the `typeof` operator.
+```xml
+ <Window.DataTemplates>
+    <DataTemplate DataType="{x:Type local:Student}">
+        <!-- ... -->
+    </DataTemplate>
+ </Window.DataTemplates>
+```
+- `x:Static`: accessor for **static members in assembly**, can be used as a **markup extension**.
 ```xml
  <Window.Resources>
      <SolidColorBrush Color="{x:Static Colors.Aqua}"></SolidColorBrush> <!-- [!code highlight] -->
  </Window.Resources>
 ```
-- `x:Key`: similar to `x:Name` but for static identifier in resource dictionary
+- `x:Key`: similar to `x:Name` but for static identifier in resource **dictionary**
 
 ::: code-group
 ```xml [XAML]

docs/document/Skill/Avalonia/docs/1. Fundamentals/Avalonia Types.md

@@ -1,21 +1,12 @@
 # Avalonia Types
 
-One should know about avalonia types before learning XAML, each tag in XAML constructs a instance from corresponding type.
-XAML also has some implicit bindings for special types with certain properties, such as `ContentControl.Content` and `ItemsControl.Items`.
-There's two critical base classes in avalonia：
-- `AvaloniaObject`: a type containing a bunch of `AvaloniaProperty`
-    - all components/controls are of `AvaloniaObject`, such as `Window`, `Button`.
-- `AvaloniaProperty`: how avalonia defined a **shared property metadata** for property **owners**
-    - `StyledProperty`: property definition supports styling overriding and inheritance
-    - `DirectProperty`: simple property for storing plain data
-
 ## AvaloniaObject
 
 All controls are derived from `AvaloniaObject` class.
 There's some special and critical control base class you may encounter when using avalonia.
 - `StyledElement`: a minimal useable control base which starts styling support, most of controls became applicable after this class
-- `ContentControl`: control for storing singular content
-- `ItemsControl`: control for storing multiple items
+- `ContentControl`: control for presenting singular content
+- `ItemsControl`: control for presenting multiple items
 - `UserControl`: TODO
 - `TemplatedControl`: TODO
 
@@ -91,8 +82,8 @@ public class AvaloniaObject : IAvaloniaObjectDebug, INotifyPropertyChanged {
 ### Direct Property
 
 `DirectProperty` is a minimal property type registered for **plain data**, ideal for **indicators** of a control, such as `Button.IsPressed` or a **statistic** such as `ItemsControl.ItemCount` or even an **collection**.
-Unlike `StyledProperty` which stores backing values in `ValueStore`, `DirectProperty` simply requires a true **backing field** within the class.
-`SetAndRaise` will raise `AvaloniaObject.PropertyChanged` event **when the new value is different than old one.**
+Unlike `StyledProperty` which stores backing values in `ValueStore`, `DirectProperty` simply requires a dedicated **backing field** within the class.
+`AvaloniaObject.SetAndRaise` will raise `AvaloniaObject.PropertyChanged` event **when the new value is different than the old.**
 
 ```cs
 public static readonly DirectProperty<Button, bool> IsPressedProperty =
@@ -106,9 +97,60 @@ public bool IsPressed {
 }
 ```
 
+> [!IMPORTANT]
+> It doesn't mean that a plain data can only be of `DirectProperty`, it can be a `StyledProperty` depending on its role, `Layoutable.HeightProperty` for example is a `StyledProperty`.
+
 ### Attached Property
 
-TODO: what is that?
+`AttachedProperty` is a static property presentation that, it **does not require instance member as backing source**(like what `StyledProperty` and `DirectProperty` required) but two **conventional static getter/setter** methods to be invoked on runtime.
+
+Besides `TOwner` and `TValue`, `AttachedProperty` has an extra type parameter
+
+- `THost`: which kind of type the property can attach to
+
+Static `Design` class is one of the great examples of attached property, what you have bind for `Design.DataContext` is exactly a property attached to your current control(`MainWindow` for example)
+You would notice that `AttachedProperty` would require two **static** methods with conventional name, those methods would be invoked by runtime by their special name.
+And the property value would be **still managed by `AvaloniaObject.GetValue` and `AvaloniaObject.SetValue`**, meaning that it has **same mechanism** as `StyledProperty`(the `ValueStore` was involved).
+
+::: code-group
+
+
+```cs [Design.DataContext]
+public static readonly AttachedProperty<object> DataContextProperty = AvaloniaProperty
+    .RegisterAttached<Control, object>("DataContext", typeof(Design));
+
+public static void SetDataContext(Control host, object value) {
+    host.SetValue(DataContextProperty, value); // [!code highlight]
+}
+
+public static object GetDataContext(Control host) {
+    return host.GetValue(DataContextProperty); // [!code highlight]
+}
+```
+
+```xml [Attach DataContext for Control]
+<Window xmlns="https://github.com/avaloniaui"
+        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+        xmlns:vm="using:MyAva.ViewModels"
+        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+        mc:Ignorable="d" d:DesignWidth="800" d:DesignHeight="450"
+        x:Class="MyAva.Views.MainWindow"
+        x:DataType="vm:MainWindowViewModel"
+        Icon="/Assets/avalonia-logo.ico"
+        Title="MyAva">
+
+    <Design.DataContext> <!-- [!code focus] -->
+        <vm:MainWindowViewModel /> <!-- [!code focus] -->
+    </Design.DataContext> <!-- [!code focus] -->
+</Window>
+```
+:::
+
+> [!IMPORTANT]
+> Yes, XAML compiler would recognize the attached property and properly set the value at runtime.
+> Even though it was written in an instance construction syntax.
+
 
 ### Reuse Property Definition
 
@@ -161,11 +203,50 @@ public IBinding this[IndexerDescriptor binding] {
 }
 ```
 
-## Data Context
+## StyledElement.DataContext
 
 `StyledElement.DataContext` is **the instance of view model** which allows you to access(or even mutate) the state of view model within a control(code-behind).
 Avalonia **searches upward hierarchically** for `DataContext` property until top level element, meaning that controls can share context with children.
 
+::: details definition
+
+```cs
+public class StyledElement : Animatable,
+    IDataContextProvider,
+    ILogical,
+    IThemeVariantHost,
+    IResourceHost2,
+    IStyleHost,
+    ISetLogicalParent,
+    ISetInheritanceParent,
+    ISupportInitialize,
+    INamed,
+    IAvaloniaListItemValidator<ILogical>,
+#pragma warning disable CS0618 // Type or member is obsolete
+    IStyleable
+#pragma warning restore CS0618 // Type or member is obsolete
+    {
+        /** ... **/
+        public static readonly StyledProperty<object?> DataContextProperty =
+            AvaloniaProperty.Register<StyledElement, object?>(
+                nameof(DataContext),
+                defaultValue: null,
+                inherits: true,
+                defaultBindingMode: BindingMode.OneWay,
+                validate: null,
+                coerce: null,
+                enableDataValidation: false,
+                notifying: DataContextNotifying);
+
+        public object? DataContext {
+            get { return GetValue(DataContextProperty); }
+            set { SetValue(DataContextProperty, value); }
+        }
+        /** ... **/
+    }
+```
+:::
+
 ```cs
 using Avalonia.Controls;
 using MyApp.ViewModels;
@@ -187,8 +268,7 @@ public partial class MainWindow : Window {
 
 Views beside `MainWindow`(which is the default window generated by avalonia project Template) needs explicit set for `DataContext`, because `MainWindow.DataContext` was assigned in `App.axaml.cs` so you don't need to worry about it.
 
-<details>
-<summary>App.axaml.cs</summary>
+::: details App.axaml.cs
 
 ```cs
 public override void OnFrameworkInitializationCompleted() {
@@ -203,7 +283,7 @@ public override void OnFrameworkInitializationCompleted() {
 }
 ```
 
-</details>
+:::
 
 ```cs
 namespace MyApp.Views;
@@ -225,16 +305,14 @@ You can create a dedicated view model class that inherits from a formal one, and
 public class MyDesignTimeViewModel: MyViewModel { // [!code highlight]
     public MyDesignTimeViewModel() {
         // properties are inherited from MyViewModel
-        ServerName = "John Price";
-        ServiceTitle = "Hair Cut and Beard Trim";
-        ServicePrice = (decimal)25.5;
-        ServiceDateTime = new DateTime(2023, 1, 3, 11, 15, 0);
-        Description = "Please allow 30 minutes.";
+        Name = "John Smith";
+        Age = 28;
+        Title = "Manager";
     }
 }
 ```
 
-Then you assign the mock view model class for `Design.DataContext`.
+Then you may specify the mock view model class for `Design.DataContext`.
 
 ```xml
 <UserControl
@@ -246,13 +324,146 @@ Then you assign the mock view model class for `Design.DataContext`.
     mc:Ignorable="d" d:DesignWidth="400" d:DesignHeight="250"
     x:Class="MyApp.Views.MyCustomView"
     xmlns:vm="using:MyApp.ViewModels"
-    x:DataType="vm:MyDesignTimeViewModel"> <!-- [!code highlight] -->
+    x:DataType="vm:MyDesignTimeViewModel"> <!-- [!code focus] -->
 
-   <Design.DataContext> <!-- [!code highlight] -->
-       <vm:MyDesignTimeViewModel/> <!-- [!code highlight] -->
-   </Design.DataContext> <!-- [!code highlight] -->
+   <Design.DataContext> <!-- [!code focus] -->
+       <vm:MyDesignTimeViewModel/> <!-- [!code focus] -->
+   </Design.DataContext> <!-- [!code focus] -->
 
 </UserControl>
 ```
 
-## Data Template
+## Template Types & Properties
+
+- Template Types:
+    - `ITemplate<TParam, TControl>`: the base template interface that requires implementer to know how to `Build`(instantiate) the template.
+        - `IDataTemplate`: inherits from `ITemplate<object?, Control?>`, requiring to know how to validate the `TParam` source using extra `Match` method.
+            - `DataTemplate`: for defining template for specific data type
+        - `IControlTemplate`: effectively `ITemplate<TemplatedControl, TemplateResult<Control>?>`
+            - `ControlTemplate`: common template type for `TemplatedControl.TemplateProperty`
+
+- Template Properties:
+    - `Control.DataTemplates`: a direct collection of `IDataTemplate`(not a `AvaloniaProperty`)
+        - provides a way to **present any type(such as a model) as a control**
+    - `TemplatedControl.TemplateProperty`: how a control was presented, you may override this property for controls to alter its default appearance
+    - `ContentControl.ContentTemplateProperty`: how `Content` was presented
+    - `ItemsControl.ItemTemplateProperty`:
+
+
+### IDataTemplate
+
+The common builtin presenter for displaying objects other than `AvaloniaObject` with certain format, implements `IDataTemplate`.
+A typical usage of `IDataTemplate` is `ViewLocator` which determines what kind of control can
+**Yes, controls are not specially treated by XAML compiler,** they were only allowed when you specify `.DataTemplates` for `Application` so that the application could load controls by the context object at runtime(**using reflection**).
+
+> [!NOTE]
+> If one were to compile ahead-of-time which could not use reflection, should use `CompiledBinding` markup and `DataTemplate.DataType` to inform XAML compiler explicitly.
+
+```xml
+<Application.DataTemplates>
+  <DataTemplate DataType="{x:Type local:Person}"> <!-- [!code focus] -->
+    <TextBlock>First Name:</TextBlock>
+    <TextBlock Text="{Binding FirstName}"/>
+    <TextBlock>Last Name:</TextBlock>
+    <TextBlock Text="{Binding LastName}"/>
+  </DataTemplate>
+</Application.DataTemplates>
+```
+
+- `Match(obj)`: determine whether current `DataContext` could embody using the given template.
+- `Build(obj)`: instantiate the template using current `DataContext`
+
+::: code-group
+```cs [ViewLocator]
+public class ViewLocator : IDataTemplate {
+    public Control? Build(object? datacontext) {
+        if (datacontext is null)
+            return null;
+
+        var name = datacontext.GetType().FullName!.Replace("ViewModel", "View", StringComparison.Ordinal);
+        var type = Type.GetType(name);
+
+        if (type != null) {
+            return (Control)Activator.CreateInstance(type)!;
+        }
+
+        return new TextBlock { Text = "Not Found: " + name };
+    }
+
+    public bool Match(object? datacontext) {
+        return datacontext is ViewModelBase;
+    }
+}
+```
+```xml [App.axaml]
+<Application xmlns="https://github.com/avaloniaui"
+             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+             x:Class="MyAva.App"
+             xmlns:local="using:MyAva"
+             RequestedThemeVariant="Default">
+             <!-- "Default" ThemeVariant follows system theme variant. "Dark" or "Light" are other available options. -->
+
+    <Application.DataTemplates> <!-- [!code focus] -->
+        <local:ViewLocator/> <!-- [!code focus] -->
+    </Application.DataTemplates> <!-- [!code focus] -->
+
+    <Application.Styles>
+        <FluentTheme />
+    </Application.Styles>
+</Application>
+```
+:::
+
+
+### ContentControl.ContentTemplate
+
+`ContentControl.ContentTemplate` is of type `IDataTemplate` that is commonly overridden by `DataTemplate`, the default **presentation of custom data formatting** type.
+The whole point of `DataTemplate` is to provide a way to format `ContentProperty` using given format.
+
+<!-- TODO: add example -->
+
+### ItemsControl.ItemTemplate
+
+Similar to `ContentControl.ContentTemplate` but for presenting items
+
+## ControlTemplate
+
+A common placeholder type to present how to re-structure a control's template looking(which you don't have access to modify the control's source definition).
+This is typically used to override `TemplatedControl.Template` and with `TemplateBinding` markup extension to read context from containing control.
+
+```xml
+<Setter Property="Template">
+  <ControlTemplate> <!-- [!code highlight] -->
+    <TextBlock Text="Templated Control" /> <!-- [!code highlight] -->
+  </ControlTemplate> <!-- [!code highlight] -->
+</Setter>
+```
+
+## Presenter Controls
+
+Presenter controls are control scaffold for representing certain content as a **wrapper** itself, so that it can bind **any source** of content from context within it.
+
+### ContentPresenter
+
+`ContentPresenter` is a type of placeholder for singular content. It's a lightweight element whose sole purpose is to **define a binding declaration** for displaying the content of a `ContentControl`
+So it's typically seen in declaration of `TemplatedControl.Template` and using with `TemplateBinding` markup extension to read context from containing control.
+
+```xml
+<ToggleButton.Template>
+  <ControlTemplate>
+    <Grid ColumnDefinitions="*,Auto">
+     <ContentPresenter <!-- [!code highlight] -->
+       Grid.Column="0" <!-- [!code highlight] -->
+       Content="{TemplateBinding Content}"> <!-- [!code ++] -->
+     </ContentPresenter> <!-- [!code highlight] -->
+   </Grid>
+  </ControlTemplate>
+</ToggleButton.Template>
+```
+
+### ItemsPresenter
+
+A place holder type presenting items specifically with `TemplateBinding`.
+
+Similar to `ContentControl.ContentTemplate` but for presenting items
+