diff --git a/components/SettingsControls/samples/Dependencies.props b/components/SettingsControls/samples/Dependencies.props index e622e1df..20f3c819 100644 --- a/components/SettingsControls/samples/Dependencies.props +++ b/components/SettingsControls/samples/Dependencies.props @@ -9,23 +9,27 @@ For UWP / WinAppSDK / Uno packages, place the package references here. --> + + + + - + - + - - + + - + diff --git a/components/SettingsControls/samples/SettingsCard.md b/components/SettingsControls/samples/SettingsCard.md index 667bc703..214810db 100644 --- a/components/SettingsControls/samples/SettingsCard.md +++ b/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] diff --git a/components/SettingsControls/samples/SettingsControls.Samples.csproj b/components/SettingsControls/samples/SettingsControls.Samples.csproj index 188a0f4d..de0e51d9 100644 --- a/components/SettingsControls/samples/SettingsControls.Samples.csproj +++ b/components/SettingsControls/samples/SettingsControls.Samples.csproj @@ -3,6 +3,7 @@ SettingsControls + preview diff --git a/components/SettingsControls/samples/SettingsExpander.md b/components/SettingsControls/samples/SettingsExpander.md index 3fd0566d..fca3f465 100644 --- a/components/SettingsControls/samples/SettingsExpander.md +++ b/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. diff --git a/components/SettingsControls/samples/SettingsExpanderDragHandleSample.xaml b/components/SettingsControls/samples/SettingsExpanderDragHandleSample.xaml new file mode 100644 index 00000000..297fd13d --- /dev/null +++ b/components/SettingsControls/samples/SettingsExpanderDragHandleSample.xaml @@ -0,0 +1,92 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/components/SettingsControls/samples/SettingsExpanderDragHandleSample.xaml.cs b/components/SettingsControls/samples/SettingsExpanderDragHandleSample.xaml.cs new file mode 100644 index 00000000..4d4724c7 --- /dev/null +++ b/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 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; +} + diff --git a/components/SettingsControls/samples/SettingsExpanderSample.xaml b/components/SettingsControls/samples/SettingsExpanderSample.xaml index 7c96fb97..e7de36b2 100644 --- a/components/SettingsControls/samples/SettingsExpanderSample.xaml +++ b/components/SettingsControls/samples/SettingsExpanderSample.xaml @@ -1,20 +1,20 @@ - + - + Option 1 @@ -22,22 +22,22 @@ Option 3 - - + +