Draggable Settings Control Example

components/SettingsControls/samples/Dependencies.props

@@ -9,23 +9,27 @@
     For UWP / WinAppSDK / Uno packages, place the package references here.
 -->
 <Project>
+    <ItemGroup>
+        <PackageReference Include="CommunityToolkit.Mvvm" Version="8.4.0"/>
+    </ItemGroup>
+
     <!-- WinUI 2 / UWP -->
     <ItemGroup Condition="'$(IsUwp)' == 'true'">
-        <!-- <PackageReference Include="Microsoft.Toolkit.Uwp.UI.Controls.Primitives" Version="7.1.2"/> -->
+        <PackageReference Include="Microsoft.Xaml.Behaviors.Uwp.Managed" Version="3.0.0"/>
     </ItemGroup>
 
     <!-- WinUI 2 / Uno -->
     <ItemGroup Condition="'$(IsUno)' == 'true' AND '$(WinUIMajorVersion)' == '2'">
-        <!-- <PackageReference Include="Uno.Microsoft.Toolkit.Uwp.UI.Controls.Primitives" Version="7.1.11"/> -->
+        <PackageReference Include="Uno.Microsoft.Xaml.Behaviors.Interactivity" Version="3.0.3"/>
     </ItemGroup>
 
     <!-- WinUI 3 / WinAppSdk -->
-    <ItemGroup Condition="'$(IsWinAppSdk)' == 'true'">
-        <!-- <PackageReference Include="CommunityToolkit.WinUI.UI.Controls.Primitives" Version="7.1.2"/> -->
+    <ItemGroup Condition="'$(IsWinAppSdk)' == 'true'">      
+         <PackageReference Include="Microsoft.Xaml.Behaviors.WinUI.Managed" Version="3.0.0"/>
     </ItemGroup>
 
     <!-- WinUI 3 / Uno -->
     <ItemGroup Condition="'$(IsUno)' == 'true' AND '$(WinUIMajorVersion)' == '3'">
-        <!-- <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls.Primitives" Version="7.1.100-dev.15.g12261e2626"/> -->
+         <PackageReference Include="Uno.Microsoft.Xaml.Behaviors.Interactivity.WinUI" Version="3.0.3"/>
     </ItemGroup>
 </Project>

components/SettingsControls/samples/SettingsCard.md

@@ -20,3 +20,9 @@ You can set the `Header`, `Description`, `HeaderIcon` and `Content` properties t
 SettingsCard can also be turned into a button, by setting the `IsClickEnabled` property. This can be useful whenever you want your settings component to navigate to a detail page or open an external link. You can set a custom icon by setting the `ActionIcon`, or hiding it completely by setting the `IsActionIconVisible` to `false`.
 
 > [!SAMPLE ClickableSettingsCardSample]
+
+### Settings page example
+
+The following sample provides a typical design page, following the correct Windows 11 design specifications for things like spacing, section headers and animations.
+
+> [!SAMPLE SettingsPageExample]

components/SettingsControls/samples/SettingsControls.Samples.csproj

@@ -3,6 +3,7 @@
 
   <PropertyGroup>
     <ToolkitComponentName>SettingsControls</ToolkitComponentName>
+    <LangVersion>preview</LangVersion>
   </PropertyGroup>
 
   <!-- Sets this up as a toolkit component's sample project -->

components/SettingsControls/samples/SettingsExpander.md

@@ -26,6 +26,29 @@ You can easily override certain properties to create custom experiences. For ins
 
 NOTE: Due to [a bug](https://github.com/microsoft/microsoft-ui-xaml/issues/3842) related to the `ItemsRepeater` used in `SettingsExpander`, there might be visual glitches whenever the `SettingsExpander` expands and a `MaxWidth` is set on a parent `StackPanel`. As a workaround, the `StackPanel` (that has the `MaxWidth` set) can be wrapped in a `Grid` to overcome this issue. See the `SettingsPageExample` for snippet.
 
+### Dragging Settings Cards
+
+You may use a list of `SettingsCard` or `SettingsExpander` to represent configurable items within a tool. The order of these may be something you want to track.
+
+In this case there is a conflict between the interactions with the settings card and the drag and drop interactions of a parent containing `ListView`, for instance.
+
+Therefore, it is recommended to use the drag-handle type UI approach for this scenario in having a dedicated space for re-ordering manipulation vs. interaction with the Settings control.
+
+You can see how to do this with `SettingsExpander` in the example below, however it equally works with a collection of `SettingsCard` as the main data template component as well.
+
+> [!SAMPLE SettingsExpanderDragHandleSample]
+
+The main important pieces of this example are:
+
+1. Enabling the three drag properties on the `ListView`: `CanDragItems`, `CanReorderItems`, and `AllowDrop`.
+2. Setting `SelectionMode` to `None` to prevent selection and the selection indicator from appearing.
+3. Using a simple UIElement to act as a drag handle, the pass-through of the mouse on this element to `ListView` allows the normal drag experience to work uninterrupted.
+4. Modifying the `Margin` and `Padding` values of the `ItemContainerStyle` to align cards how we want within the ListView.
+5. Overriding the `ListViewItemBackgroundPointerOver` resource to prevent the hover effect across the entire list item, the Settings Controls already have an effect here on hover.
+6. Optionally, add a behavior to highlight the drag region when the pointer is over it.
+
+Note: If controls within the dragged SettingsCard/Expander state are not bound, they will be reset upon drop in some cases. E.g. a ToggleSwitch. It is best to ensure you have bound your control's states to your data model.
+
 ### Settings page example
 
 The following sample provides a typical design page, following the correct Windows 11 design specifications for things like spacing, section headers and animations.

components/SettingsControls/samples/SettingsExpanderDragHandleSample.xaml

@@ -0,0 +1,92 @@
+<Page x:Class="SettingsControlsExperiment.Samples.SettingsExpanderDragHandleSample"
+      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+      xmlns:Interactivity="using:Microsoft.Xaml.Interactivity"
+      xmlns:controls="using:CommunityToolkit.WinUI.Controls"
+      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+      xmlns:local="using:SettingsControlsExperiment.Samples"
+      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+      mc:Ignorable="d">
+
+    <!--
+        Enabled the List view to drag its items and reorder them around,
+        plus need SelectionMode None so the indicator doesn't appear when clicking on the drag region
+    -->
+    <ListView AllowDrop="True"
+              CanDragItems="True"
+              CanReorderItems="True"
+              ItemsSource="{x:Bind MyDataSet}"
+              SelectionMode="None">
+        <ListView.ItemTemplate>
+            <DataTemplate x:DataType="local:ExpandedCardInfo">
+                <Grid>
+                    <Grid.ColumnDefinitions>
+                        <ColumnDefinition Width="Auto" />
+                        <ColumnDefinition Width="*" />
+                    </Grid.ColumnDefinitions>
+                    <!--  Provide a custom area that can be manipulated by the user, this could be before or after the card.  -->
+                    <Border Width="36"
+                            Height="75"
+                            Margin="1,1,1,1"
+                            VerticalAlignment="Top"
+                            Background="Transparent"
+                            CornerRadius="{ThemeResource ControlCornerRadius}">
+                        <TextBlock HorizontalAlignment="Center"
+                                   VerticalAlignment="Center"
+                                   FontFamily="Segoe UI Symbol"
+                                   FontSize="20"
+                                   Foreground="{ThemeResource TextFillColorSecondaryBrush}"
+                                   Text="&#x283F;" />
+                        <!--  Use Behaviors to hover on pointer  -->
+                        <Interactivity:Interaction.Behaviors>
+                            <Interactivity:EventTriggerBehavior EventName="PointerEntered">
+                                <Interactivity:ChangePropertyAction PropertyName="Background">
+                                    <Interactivity:ChangePropertyAction.Value>
+                                        <SolidColorBrush Color="{ThemeResource ControlFillColorDefault}" />
+                                    </Interactivity:ChangePropertyAction.Value>
+                                </Interactivity:ChangePropertyAction>
+                            </Interactivity:EventTriggerBehavior>
+                            <Interactivity:EventTriggerBehavior EventName="PointerExited">
+                                <Interactivity:ChangePropertyAction PropertyName="Background">
+                                    <Interactivity:ChangePropertyAction.Value>
+                                        <SolidColorBrush Color="Transparent" />
+                                    </Interactivity:ChangePropertyAction.Value>
+                                </Interactivity:ChangePropertyAction>
+                            </Interactivity:EventTriggerBehavior>
+                        </Interactivity:Interaction.Behaviors>
+                    </Border>
+                    <!--  Standard Settings Expander (could also just be a Card)  -->
+                    <controls:SettingsExpander Grid.Column="1"
+                                               Description="{x:Bind Info}"
+                                               Header="{x:Bind Name}"
+                                               IsExpanded="{x:Bind IsExpanded, Mode=TwoWay}">
+
+                        <ToggleSwitch IsOn="{x:Bind IsExpanded, Mode=TwoWay}"
+                                      OffContent="Off"
+                                      OnContent="On" />
+
+                        <controls:SettingsExpander.Items>
+                            <controls:SettingsCard Header="{x:Bind LinkDescription}">
+                                <HyperlinkButton Content="{x:Bind Url}"
+                                                 NavigateUri="{x:Bind Url}" />
+                            </controls:SettingsCard>
+                        </controls:SettingsExpander.Items>
+                    </controls:SettingsExpander>
+                </Grid>
+            </DataTemplate>
+        </ListView.ItemTemplate>
+        <!--  Customize Size of Item Container from ListView  -->
+        <ListView.ItemContainerStyle>
+            <Style BasedOn="{StaticResource DefaultListViewItemStyle}"
+                   TargetType="ListViewItem">
+                <Setter Property="Margin" Value="0" />
+                <Setter Property="Padding" Value="4" />
+            </Style>
+        </ListView.ItemContainerStyle>
+        <!--  Hides the overall highlight from the ListView Container  -->
+        <ListView.Resources>
+            <SolidColorBrush x:Key="ListViewItemBackgroundPointerOver"
+                             Color="Transparent" />
+        </ListView.Resources>
+    </ListView>
+</Page>

components/SettingsControls/samples/SettingsExpanderDragHandleSample.xaml.cs

@@ -0,0 +1,56 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using CommunityToolkit.Mvvm.ComponentModel;
+
+namespace SettingsControlsExperiment.Samples;
+
+[ToolkitSample(id: nameof(SettingsExpanderDragHandleSample), "SettingsExpanderDragHandle", description: "The SettingsCard/SettingsExpander can be within a collection itself which can be re-ordered.")]
+public sealed partial class SettingsExpanderDragHandleSample : Page
+{
+
+    public ObservableCollection<ExpandedCardInfo> MyDataSet = new() {
+        new()
+        {
+            Name = "First Item",
+            Info = "More about first item.",
+            LinkDescription = "Click the link for more on first item.",
+            Url = "https://microsoft.com/",
+        },
+        new()
+        {
+            Name = "Second Item",
+            Info = "More about second item.",
+            LinkDescription = "Click the link for more on second item.",
+            Url = "https://xbox.com/",
+        },
+        new()
+        {
+            Name = "Third Item",
+            Info = "More about third item.",
+            LinkDescription = "Click the link for more on third item.",
+            Url = "https://toolkitlabs.dev/",
+        },
+    };
+
+    public SettingsExpanderDragHandleSample()
+    {
+        this.InitializeComponent();
+    }
+}
+
+public partial class ExpandedCardInfo : ObservableObject
+{
+    public string? Name { get; set; }
+
+    public string? Info { get; set; }
+
+    public string? LinkDescription { get; set; }
+
+    public string? Url { get; set; }
+
+    [ObservableProperty]
+    public partial bool IsExpanded { get; set; } = false;
+}
+

components/SettingsControls/samples/SettingsExpanderSample.xaml

@@ -1,43 +1,43 @@
-<!--  Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE file in the project root for more information.  -->
+<!--  Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE file in the project root for more information.  -->
 <Page x:Class="SettingsControlsExperiment.Samples.SettingsExpanderSample"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+      xmlns:controls="using:CommunityToolkit.WinUI.Controls"
       xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
-      xmlns:local="using:CommunityToolkit.WinUI.Controls"
       xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
       xmlns:ui="using:CommunityToolkit.WinUI"
       mc:Ignorable="d">
 
-    <local:SettingsExpander x:Name="settingsCard"
-                            VerticalAlignment="Top"
-                            Description="The SettingsExpander has the same properties as a Card, and you can set SettingsCard as part of the Items collection."
-                            Header="SettingsExpander"
-                            HeaderIcon="{ui:FontIcon Glyph=&#xE91B;}"
-                            IsEnabled="{x:Bind IsCardEnabled, Mode=OneWay}"
-                            IsExpanded="{x:Bind IsCardExpanded, Mode=OneWay}">
+    <controls:SettingsExpander x:Name="settingsCard"
+                               VerticalAlignment="Top"
+                               Description="The SettingsExpander has the same properties as a Card, and you can set SettingsCard as part of the Items collection."
+                               Header="SettingsExpander"
+                               HeaderIcon="{ui:FontIcon Glyph=&#xE91B;}"
+                               IsEnabled="{x:Bind IsCardEnabled, Mode=OneWay}"
+                               IsExpanded="{x:Bind IsCardExpanded, Mode=OneWay}">
         <!--  TODO: This should be TwoWay bound but throws compile error in Uno.  -->
         <ComboBox SelectedIndex="0">
             <ComboBoxItem>Option 1</ComboBoxItem>
             <ComboBoxItem>Option 2</ComboBoxItem>
             <ComboBoxItem>Option 3</ComboBoxItem>
         </ComboBox>
 
-        <local:SettingsExpander.Items>
-            <local:SettingsCard Header="A basic SettingsCard within an SettingsExpander">
+        <controls:SettingsExpander.Items>
+            <controls:SettingsCard Header="A basic SettingsCard within an SettingsExpander">
                 <Button Content="Button" />
-            </local:SettingsCard>
-            <local:SettingsCard Description="SettingsCard within an Expander can be made clickable too!"
-                                Header="This item can be clicked"
-                                IsClickEnabled="True" />
+            </controls:SettingsCard>
+            <controls:SettingsCard Description="SettingsCard within an Expander can be made clickable too!"
+                                   Header="This item can be clicked"
+                                   IsClickEnabled="True" />
 
-            <local:SettingsCard ContentAlignment="Left">
+            <controls:SettingsCard ContentAlignment="Left">
                 <CheckBox Content="Here the ContentAlignment is set to Left. This is great for e.g. CheckBoxes or RadioButtons." />
-            </local:SettingsCard>
+            </controls:SettingsCard>
 
-            <local:SettingsCard HorizontalContentAlignment="Left"
-                                ContentAlignment="Vertical"
-                                Description="You can also align your content vertically. Make sure to set the HorizontalAlignment to Left when you do!"
-                                Header="Vertically aligned">
+            <controls:SettingsCard HorizontalContentAlignment="Left"
+                                   ContentAlignment="Vertical"
+                                   Description="You can also align your content vertically. Make sure to set the HorizontalAlignment to Left when you do!"
+                                   Header="Vertically aligned">
                 <GridView SelectedIndex="1">
                     <GridViewItem>
                         <Border Width="64"
@@ -64,13 +64,13 @@
                                 CornerRadius="4" />
                     </GridViewItem>
                 </GridView>
-            </local:SettingsCard>
-            <local:SettingsCard Description="You can override the Left indention of a SettingsCard by overriding the SettingsCardLeftIndention"
-                                Header="Customization">
-                <local:SettingsCard.Resources>
+            </controls:SettingsCard>
+            <controls:SettingsCard Description="You can override the Left indention of a SettingsCard by overriding the SettingsCardLeftIndention"
+                                   Header="Customization">
+                <controls:SettingsCard.Resources>
                     <x:Double x:Key="SettingsCardLeftIndention">40</x:Double>
-                </local:SettingsCard.Resources>
-            </local:SettingsCard>
-        </local:SettingsExpander.Items>
-    </local:SettingsExpander>
+                </controls:SettingsCard.Resources>
+            </controls:SettingsCard>
+        </controls:SettingsExpander.Items>
+    </controls:SettingsExpander>
 </Page>