Feature - Container Queries #16846

emmauss · 2024-08-28T14:03:49Z

What does the pull request do?

Container Queries allows styles to be activated for control based on the size of an ancestor, which acts as a container. This feature is similar to css's container queries.
A container can be defined by setting the ContainerType property. ContainerType is an enum with the following values.

public enum ContainerType
{
    /// <summary>
    /// The container will not be queries for any container size queries.
    /// </summary>
    Normal,

    /// <summary>
    /// The can be queried for container size queries for width.
    /// </summary>
    Width,

    /// <summary>
    /// The can be queried for container size queries for height.
    /// </summary>
    Height,

    /// <summary>
    /// The can be queried for container size queries for both width and height.
    /// </summary>
    WidthAndHeight
}

Currently only ContentControl and Border support acting as a container. To add container behavior for custom controls that do not implement these two controls, implement the Avalonia.Styling.IContainer interface.

    public interface IContainer
    {
        /// <summary>
        /// Gets or sets the <see cref="Avalonia.Layout.ContainerType"/> of the container.
        /// </summary>
        ContainerType ContainerType { get; set; }

        /// <summary>
        /// The name of the container.
        /// </summary>
        string? ContainerName { get; set; }

        /// <summary>
        /// The <see cref="VisualQueryProvider"/> of the container. This provides size information for the container query.
        /// </summary>
        VisualQueryProvider QueryProvider { get; }
    }

Queries are treated as selectors for the container, and are evaluated when the container size changes. Take the following use case

<Styles>
  <Style Selector="Border.b">
    <Setter Property="Background" Value="Red" />
    <Setter Property="Width" Value="200"/>
  </Style>
  <ContainerQuery Query="min-width:400">
    <Style Selector="Border.b">
      <Setter Property="Width" Value="400"/>
    </Style>
  </ContainerQuery>
</Styles>

<Grid ColumnDefinitions="*,200">
  <ContentControl Container="Width">
    <StackPanel>
      <Border Classes="b"/>
    </StackPanel>
  </ContentControl>
  <Button Grid.Column="1"/>
</Grid>

When ContentControl size changes, it triggers a reevaluation of any ContainerQuery attached to it. If the ContentControl's width is at least 400px, the styles in the Query are activated and the Border.b style is applied to any child that matches that selector.
Supported queries include;

min-width
max-width
width
min-height
max-height
height

A container query can specify which container to attach to by setting the Container property. The container will also need it's ContainerName property to be set.

<Styles>
  <Style Selector="Border.b">
    <Setter Property="Background" Value="Red" />
    <Setter Property="Width" Value="200"/>
  </Style>
  <ContainerQuery Query="min-width:400">
    <Style Selector="Border.b">
      <Setter Property="Width" Value="400"/>
    </Style>
  </ContainerQuery>

  <ContainerQuery Container="C1" ="min-width:400">
    <Style Selector="Border.b">
      <Setter Property="Width" Value="700"/>
    </Style>
  </ContainerQuery>
</Styles>

<Grid ColumnDefinitions="*,200">
  <ContentControl ContainerType="Width" ContainerName="C1">
    <StackPanel>
      <Border Classes="b"/> <!-- Should be 700px if 1st Grid column is >=400px instead of 400px -->
    </StackPanel>
  </ContentControl>
  <Button Grid.Column="1"/>
</Grid>

Only the ContainerQuery matching the C1 container name will be evaluated.

Layout

Container queries activates styles based on the size of a visual. The styles applied can change the size of the container, so the container size should remain constant during the whole layout pass.
At the beginning of the Measure pass, the size constraints of the container, i.e. the maximum size the container can be with respect to it's set Width,Height, Min and Max dimension are sent for evaluation before children are measured.
Measure proceeds as normal, with DesiredSize set according to the follow after children are measured.

If a dimension(Width or Height) is queried, and the value is Infinity, the respective measured dimension is used in the DesiredSize
If the dimension is not Infinity, the constraint dimension is used in the DesiredSize.

For an example, in the use case above the ContentControl queries for Width, so if the Width evaluated is PositiveInfinity, the measured width of its content will be used as the DesiredSize.Width. If it 700px, the DesiredSize.Width will be 700. The DesireSize.Height will be the height measure from the children in both cases.

This is a partial rewrite of #7938

What is the current behavior?

What is the updated/expected behavior with this PR?

How was the solution implemented (if it's not obvious)?

Checklist

Added unit tests (if possible)?
Added XML documentation to any related classes?
Consider submitting a PR to https://github.com/AvaloniaUI/avalonia-docs with user documentation

Breaking changes

Obsoletions / Deprecations

Fixed issues

Fixes #16949

avaloniaui-bot · 2024-08-28T14:27:57Z

You can test this PR using the following package version. 11.2.999-cibuild0051541-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

avaloniaui-bot · 2024-08-29T16:00:54Z

You can test this PR using the following package version. 11.2.999-cibuild0051554-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

avaloniaui-bot · 2024-08-29T16:59:17Z

You can test this PR using the following package version. 11.2.999-cibuild0051558-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

grokys · 2024-08-29T17:00:12Z

Currently only ContentControl and Border support acting as a container.

Should probably be Decorator (base class of Border)?

grokys · 2024-08-29T17:02:55Z

The container will also need it's ContainerName property to be set.

Names are unique in a name scope. Are ContainerNames intended to be unique in any scope? Feels a little inconsistent having non-unique names. Maybe ContainerClass might be more consistent?

Thinking more about it: if that's the case then can we just use the existing Classes?

emmauss · 2024-08-29T17:31:37Z

The container will also need it's ContainerName property to be set.

Names are unique in a name scope. Are ContainerNames intended to be unique in any scope? Feels a little inconsistent having non-unique names. Maybe ContainerClass might be more consistent?

Thinking more about it: if that's the case then can we just use the existing Classes?

Names aren't unique in css. They probably couldn't use Class as it will conflict with their existing Class concept. An element can have multiple classes, but only 1 name, but multiple elements can have the same name
We can't use existing Classes because there could be inconsistencies in matching which container is most suitable to query, especially if there are multiple container queries with different names but pointing to the same container. It would be best to make the user to specify which container to match for any query they write.

emmauss · 2024-08-29T17:33:17Z

Currently only ContentControl and Border support acting as a container.

Should probably be Decorator (base class of Border)?

That would be the better class to implement it for.

avaloniaui-bot · 2024-08-29T18:03:57Z

You can test this PR using the following package version. 11.2.999-cibuild0051562-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

robloo · 2024-08-31T14:21:19Z

I really like to see functionality expanding in this area. We had lots of related conversations with the media query branch and this brings several ideas together nicely. However, I don't think we should follow CSS this closely here. Let me explain.

Firstly we should note that this functionality (a subset) was implemented in WinUI using AdaptiveTriggers. The idea behind AdaptiveTriggers was fairly powerful -- if UWP at the time worked like WPF's Triggers this would have been nearly perfect. Avalonia doesn't have style triggers. I've originally lamented that as I think they are pretty simple to use in several cases. However, style selectors with pseudoclasses and property matching have proven pretty good for this as well covering the vast majority of use cases a trigger would have otherwise handled. So all is well on that front but we obviously can't use AdaptiveTrigger.

My instinct at this point is simply to extend the selector syntax to handle visual tree navigation. I.e. We need a syntax that can query another control's properties in the tree. We already have precedence for this: The nth-child selector works this way. The item itself doesn't have enough information to know whether the style should be applied -- but it's container parent does. Because some prior art exists here I have to think it can be generalized without a major performance impact.

Some other points:

It would be great if we supported percentages (finally!)
It would be great if this didn't have a string name. I realize that's like SharedSizeGroups but here it limits us. We should just have a target-type control IMO that can be any control in the tree. All controls have size/bounds/sizechanged.
ContainerType doesn't make a lot of sense. You deviated quite a bit from CSS for no reason as far as I can tell. This is only for size changes anyway so basically should only have Normal and Size.

Bringing all this together, why isn't it possible to have a syntax like the following in Selectors themselves:

<Style Selector="TextBlock:parent-min-width:300">
<Style Selector="TextBlock:parent-min-width:50%">

or

<Style Selector="TextBlock:parent-min-width:300(#ParentControlNameInTree)">

These are not fully developed ideas but hopefully it gets my point across. The style selector syntax itself is certainly debatable.

thevortexcloud · 2024-08-31T14:42:42Z

I.e. We need a syntax that can query another control's properties in the tree.

I could be wrong/misunderstanding you, but is that not what this is?

https://docs.avaloniaui.net/docs/reference/styles/style-selector-syntax#by-property-match

emmauss · 2024-08-31T17:19:41Z

I really like to see functionality expanding in this area. We had lots of related conversations with the media query branch and this brings several ideas together nicely. However, I don't think we should follow CSS this closely here. Let me explain.

Firstly we should note that this functionality (a subset) was implemented in WinUI using AdaptiveTriggers. The idea behind AdaptiveTriggers was fairly powerful -- if UWP at the time worked like WPF's Triggers this would have been nearly perfect. Avalonia doesn't have style triggers. I've originally lamented that as I think they are pretty simple to use in several cases. However, style selectors with pseudoclasses and property matching have proven pretty good for this as well covering the vast majority of use cases a trigger would have otherwise handled. So all is well on that front but we obviously can't use AdaptiveTrigger.

My instinct at this point is simply to extend the selector syntax to handle visual tree navigation. I.e. We need a syntax that can query another control's properties in the tree. We already have precedence for this: The nth-child selector works this way. The item itself doesn't have enough information to know whether the style should be applied -- but it's container parent does. Because some prior art exists here I have to think it can be generalized without a major performance impact.

Some other points:
1. It would be great if we supported percentages (finally!)

2. It would be great if this didn't have a string name. I realize that's like SharedSizeGroups but here it limits us. We should just have a target-type control IMO that can be any control in the tree. All controls have size/bounds/sizechanged.

3. ContainerType doesn't make a lot of sense. You deviated quite a bit from CSS for no reason as far as I can tell. This is only for size changes anyway so basically should only have Normal and Size.
Bringing all this together, why isn't it possible to have a syntax like the following in Selectors themselves:

<Style Selector="TextBlock:parent-min-width:300"> <Style Selector="TextBlock:parent-min-width:50%">

or

<Style Selector="TextBlock:parent-min-width:300(#ParentControlNameInTree)">

These are not fully developed ideas but hopefully it gets my point across. The style selector syntax itself is certainly debatable.

Percentages are values for setters, not queries. Though out of scope of this PR, it is a useful feature, as only Grids have an equivalent. I don't see how it's possible to query if a control is a percentage of its available size giving that a control only knows its available size on Measure, and the size it will actually take on Arrange. By that point, it's too late to activate size styles for children.
The Name is optional. If Name isn't specified, it matches the nearest container in its ancestors.
Css actually has 3 types, Normal, Size and InlineSize. We have no concepts of inline in Avalonia, so the separate Width and Height types were made to account for that.

I'm not sure of how the selector idea would work in the current style system. The desired size of all controls are stored in properties that aren't AvaloniaProperties, i.e. DesireSize. It can't trigger any notification for style activators to work. To make it work would mean creating and subscribing to a size event for every control that could potentially be queried for size in a specific selector.
In a chat app, TextBlock:parent-min-width:300 will subscribe to the card border of every message, and not the scrollviewer.

robloo · 2024-08-31T22:18:25Z

@thevortexcloud

I could be wrong/misunderstanding you, but is that not what this is?

Well, that is a bit different because it's only checking for property matches on the control itself -- NOT another control in the tree. nth-child does actually get information from elsewhere in the tree. However, you've given me a better idea for the concept and syntax.

@emmauss

I'm not sure of how the selector idea would work in the current style system.

Yes, this a clear place where not having Width/Height properties like WPF is an issue. I'll explain more. However, it might still be possible. Also note that I'm starting at a very high level and trying to design the best API first. Then implementation will need to be considered and design revised as needed. That's just the process I'm used to. I know you are quite a bit further along than I am on this issue though.

So keeping with my main points from above:

We should try to use a new selector syntax. This is cleaner -- especially in XAML -- to use. It doesn't introduce any new complexities from a user-standpoint.
We already have an example of a selector getting information from elsewhere in the tree: nth-child.

Here is the new syntax proposal:

Selector="TextBox[^.Width=300]" : We already support > for child and '^' for parent in selectors. This is a new sytax that allows using the direct visual parent to get the property value of the Width property... Yes Width doesn't exist in Avalonia so more later
Selector="TextBox[#ASpecificParentContainer.Width=300]" : Now we extend the syntax to support referencing a parent control (container) by name directly. Then we read the property values off it to see if the selector matches.
Because Width doesn't exist in Avalonia, but it's super useful in cases like this, it could be special cased. Behind the scenes it would use the Bounds.Width value. If that is not agreeable it would be possible to add new read-only ActualWidth and ActualHeight properties to expose this information in the current system. Now doing this during measure/arrange before rendering is an issue as you pointed out. But if we special case the meaning of 'Width' and 'Height' here behind the scenes we can use what is necessary as well (DesiredSize). I'm just thinking very high level for now though...
Selector="TextBox[#ASpecificParentContainer.Width=lt-300]" : I'm getting more creative here (perhaps too much). But to actually make this selector useful we need less-than/greater-than support (min-width and max-width above). This is something that will be extremely useful in a lot of places though. So it could theoretically be added as a lt- or gt- prefix on the value. =lt- is a little strange so I suppose some alternate could be possible removing the equal sign.

Edit: We could actually use concepts from https://github.com/levitali/CompiledBindings?tab=readme-ov-file#xbind-markup-extension. Eventually, that powerful of syntax would be useful all over the place. Here something like Selector="TextBox[#ASpecificParentContainer.Width is gt 200 and lt 300] would be extremely powerful. Conceptually it's similar to all the work C# pattern matching is doing these days.

This API is still a stretch but it has some clear benefits:

It's generalized. We can use ANY parent control (by name) and ANY property value on that parent control to match. It doesn't need to be a special container. This works for any existing selectors too besides size.
We get less-than and greater-than support for any numerical properties
Seems super easy to read compared to this PR but I'm of course biased.

In a chat app, TextBlock:parent-min-width:300 will subscribe to the card border of every message, and not the scrollviewer.

That was only an example above where the default would be the first parent. Specifying a parent control by name is probably more appropriate in usage.

emmauss · 2024-08-31T22:42:13Z

'Width' and 'Height' does exist in Avalonia. But it doesn' represent the laid out dimensions, which is the most important information for queries, of a control.

robloo · 2024-08-31T22:45:48Z

@emmauss As I said, I'm starting at a high level and designing the best API first. Implementation second. There are multiple options here:

Special case Width and Height as I said above. These would internally route to the necessary DesiredSize or other layout dimensions you need when the selector is being matched.
Use your interface ideas. Any control that implements IControlSize or something has implementation of Width and Height with the appropriate layout values. Then this selector (when it used Width or Height) would only be supported if the specified parent control implemented IControlSize (or whatever it's called). That's a hybrid design but is similar to what you are doing now.
I think ActualWidth and ActualHeight properties from WPF might work here as well.

thevortexcloud · 2024-09-01T03:02:44Z

Well, that is a bit different because it's only checking for property matches on the control itself -- NOT another control in the tree. nth-child does actually get information from elsewhere in the tree. However, you've given me a better idea for the concept and syntax.

But can't easily combine the two? EG

TextBlock[IsEnabled=True]:nth-child(2n+3)

That is how you typically do stuff in CSS. It does lead to some very verbose queries though.

I think ActualWidth and ActualHeight properties from WPF might work here as well.

Avalonia already sort of has this. It's just hidden under the Bounds property. Width/Height can be zero but Bounds contains the actual size on screen.

grokys · 2024-09-02T12:51:48Z

Selector="TextBox[#ASpecificParentContainer.Width is gt 200 and lt 300]

I really don't like this. I've been against putting arbitrary expressions in selectors quite a few times (e.g. people have asked for selectors that can query properties on the data context). These are the reasons:

It's hard to read. People will start putting complex expressions in here that will make your eyes bleed
It's bad for performance. These expressions are going to have to be parsed at startup and then evaluated on each layout pass, and property subscriptions put in place to monitor when the properties change
It's going to cause layout cycles where a selector creates a circular dependency on another

We already have a way to create layouts with complex logic: code-behind. I know people have some sort of dogmatic aversion to code-behind, but code is the place for such logic, not a DSL shoved into a syntax that was never intended to support it. People complain the Rx is hard to understand, but at least it's C# - here you have the equivalent but with a custom syntax and no debugging tools.

thevortexcloud · 2024-09-02T13:06:15Z

t's hard to read. People will start putting complex expressions in here that will make your eyes bleed

CSS has been slowly moving in that direction. It went from being a simple text file that describes visuals to being basically a very simplified specialised programming language. People however keep taking it further with things like preprocessors that add actual programming concepts like control statements. I can't say I am a fan of it.

In the context of XAML you are better off just using some sort of calculated property at that point.

robloo · 2024-09-02T14:22:56Z

Please keep in mind I'm approaching this from a different viewpoint. Rather than trying to integrate a completely new concept: Container Query. I'm trying to fit the functionality into what we already have.

As noted above, the core of this functionality is related to nth-child (parent properties used in selectors) and property value matching. It's a short extension from there to use ANY arbitrary parent control properties. The complexity is trying to find a syntax that works for the less-than and greater-than constraints as well as where do we get Width/Height from considering the deviations in Avalonia's design in this area.

I really don't like this... We already have a way to create layouts with complex logic: code-behind. I know people have some sort of dogmatic aversion to code-behind, but code is the place for such logic, not a DSL shoved into a syntax that was never intended to support it.

As one who probably puts too much in code-behind and never jumped on the 100% MVVM bandwagon I agree with you more than you think. However, a few points:

I could just as easily spin this around and say there are some with a dogmatic aversion to making XAML less static and more powerful ;) As a DSL we can define it to be whatever is most productive. It can certainly use upgrades in areas to extend functionality.
The core of this discussion -- changing style dynamically as size changes -- is going to be done in XAML regardless of the design. So no matter what syntax we are discussing here we are discussing things that we all agree go in the XAML layer.

It's hard to read. People will start putting complex expressions in here that will make your eyes bleed

If devs want to make their own eyes bleed they ALWAYS have that ability no matter what a framework does. I would never try to design around the least capable developer and reduce the feature set for everyone else. Besides, the person that ultimately would have to deal with such issues is... the developer or company that allows that in the first place. It doesn't affect anyone else. Whenever the person responsible is also the person accountable things have a way of working themselves out.

It's bad for performance. These expressions are going to have to be parsed at startup and then evaluated on each layout pass, and property subscriptions put in place to monitor when the properties change

Well, we don't actually need full expressions (I did say I might be getting too creative). However, the subset to support less-than and greater-than is little different in cost than what is required for container queries implemented another way.

I will say though simple arithmetic with CONSTANT values (as opposed to adding properties from multiple controls) will be much less of a performance concern. If we eventually supported binding to, as a contrived example, Height of one control and then added +10 to that value with a simple arithmetic expression there would be negligible performance impact and no more circular dependency than we already have.

Bringing this back on topic: Does anyone else see my viewpoint? Trying to integrate this functionality into selectors. We are already part of the way there with how selectors currently function.

I have no commitment to any specific selector syntax. I was just throwing out some ideas. I'm sure people have better ideas for syntax that could be more acceptable. Personally, I don't really like the ContainerQuery syntax specified above. I think it's overly specific when it should be better generalized and integrated with ideas we already have.

kekekeks · 2024-09-03T13:55:47Z

src/Avalonia.Base/Styling/IContainer.cs

+    /// <summary>
+    /// Defines the interface for a container
+    /// </summary>
+    public interface IContainer


I don't think this needs to be a public API at least yet

kekekeks · 2024-09-03T13:55:56Z

src/Avalonia.Base/Layout/Layoutable.cs

+
+                double width, height;
+
+                if (isContainer)


I believe that this logic should be bypassed for TopLevels and TopLevel should always implicitly be a SizeAndHeight container.

kekekeks · 2024-09-03T13:58:33Z

samples/ContainerDemo/ContainerDemo.csproj

@@ -0,0 +1,36 @@
+<Project Sdk="Microsoft.NET.Sdk">


Can we somehow fit this demo into ControlCatalog? I'd really prefer to not have yet another set of projects in the solution.

I understand that it does require a separate TopLevel and we only have one on mobile, but we can probably just switch the MainView on a button click or something.

kekekeks · 2024-09-03T13:59:02Z

src/Avalonia.Base/Platform/VisualQueryProvider.cs

+
+namespace Avalonia.Platform
+{
+    public class VisualQueryProvider


Shouldn't be public

kekekeks · 2024-09-03T14:00:20Z

src/Avalonia.Base/Styling/Container.cs

+    /// <summary>
+    /// Defines a container.
+    /// </summary>
+    public class Container : StyleBase


The name feels to be too generic and is likely to cause name clashes later. We already have IContainer that means a completely different thing.

kekekeks · 2024-09-03T14:02:06Z

src/Avalonia.Base/Styling/Query.cs

+    /// <summary>
+    /// A query in a <see cref="Container"/>.
+    /// </summary>
+    public abstract class Query


Again, naming feels to be too generic. Maybe StyleQuery?

kekekeks · 2024-09-03T14:06:12Z

src/Avalonia.Controls/Decorator.cs


 namespace Avalonia.Controls
 {
    /// <summary>
    /// Base class for controls which decorate a single child control.
    /// </summary>
-    public class Decorator : Control
+    public class Decorator : Control, IContainer


The choice to mark controls as possible containers seems to be rather arbitrary.

What was the logic behind choosing Decorator, ContentControl and ContentPresenter? Why do we have both ContentControl and ContentPresenter as containers?

Those are chosen because they are expected to have 1 child, and we can predict how it measures, thus makes more sense as containers. As for ContentControl and Presenter, that ContentPresenter should be the one container, so it is a mistake to make ControlControl one. I'll update it.
We could make all Controls be a potential container, but that won't make sense for controls that do not expect content, like Calendar and NumberUpDown

On second thought, even if a Control implements IContainer, it doesn't implicitly become a target for queries, as its ContainerType would be Normal. So ContentControl should be an IContainer. ContentPresenter is made to be an IContainer so allow users to make customer controls that can act as a container without implementing IContainer.

I don't think the implementation is generic enough as-is. I see no reason a container query can't target ANY control. We can already opt-out by default with type Normal.

Keep in mind that the design of XAML is nesting of controls. That means this should be opt-out rather than opt-in. IMO the controls where it just never makes sense should have a mechanism to disable the container query provided by Control base by overriding the type.

kekekeks · 2024-09-03T14:06:55Z

src/Avalonia.Controls/WindowBase.cs

@@ -284,6 +283,11 @@ protected override Size MeasureCore(Size availableSize)

            var constraint = LayoutHelper.ApplyLayoutConstraints(this, availableSize);

+            if (this is Styling.IContainer container)


Note that this condition is currently always true since WindowBase is a ContentControl

Also, why is it in WindowBase and not in TopLevel?

TopLevel doesn't have any special MeasureCore implemention, relying on the base implementation in Layoutable and the override in WindowBase

TopLevels should always act as Width+Height containers for satisfying media queries

TopLevels should never be affected by the new Measure logic in Layoutable

Manually setting ContainerType/ContainerName on a TopLevel is invalid and should trigger an exception

kekekeks · 2024-09-03T14:09:38Z

src/Avalonia.Base/Styling/Activators/ScreenActivator.cs

+            _argument = argument;
+        }
+
+        protected override bool EvaluateIsActive() => (CurrentContainer?.ContainerType == Layout.ContainerType.Width || CurrentContainer?.ContainerType == Layout.ContainerType.WidthAndHeight) 


What happens if container type changes at runtime?

It wouldn't evaluate as long as it isn't a container type that applies to the dimension.

robloo · 2024-09-05T17:28:25Z