WCT documentation update v8.1.240328-rc

.openpublishing.redirection.json

@@ -9,6 +9,86 @@
       "source_path": "mvvm/index.md",
       "redirect_url": "/mvvm/introduction",
       "redirect_document_id": true
+    },
+    {
+      "source_path_from_root": "/docs/windows/Animations/Animations.md",
+      "redirect_url": "/windows/animations",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/Animations/AnimationSet.md",
+      "redirect_url": "/windows/behaviors/animationset",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/Behaviors/Behaviors.md",
+      "redirect_url": "/windows/behaviors",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/CameraPreview/CameraPreview.md",
+      "redirect_url": "/windows/camerapreview",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/Converters/Converters.md",
+      "redirect_url": "/windows/converters",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/DeveloperTools/DeveloperTools.md",
+      "redirect_url": "/windows/developertools",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/ImageCropper/ImageCropper.md",
+      "redirect_url": "/windows/imagecropper",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/LayoutTransformControl/LayoutTransformControl.md",
+      "redirect_url": "/windows/layouttransformcontrol",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/MetadataControl/MetadataControl.md",
+      "redirect_url": "/windows/metadatacontrol",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/Primitives/StaggeredSamples.md",
+      "redirect_url": "/windows/primitives/staggeredlayout",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/RadialGauge/RadialGauge.md",
+      "redirect_url": "/windows/radialgauge",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/RangeSelector/RangeSelector.md",
+      "redirect_url": "/windows/rangeselector",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/RichSuggestBox/RichSuggestBox.md",
+      "redirect_url": "/windows/richsuggestbox",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/Segmented/Segmented.md",
+      "redirect_url": "/windows/segmented",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/TokenizingTextBox/TokenizingTextBox.md",
+      "redirect_url": "/windows/tokenizingtextbox",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/docs/windows/Triggers/Triggers.md",
+      "redirect_url": "/windows/triggers",
+      "redirect_document_id": false
     }
   ]
 }

docs/windows/Animations/Animations.md → docs/windows/Animations/index.md

@@ -55,3 +55,5 @@ Here is an example that shows how different animations can be attached to a UI e
 :::code language="xaml" source="~/../code-windows/components/Animations/samples/AnimationsImplicitSample.xaml":::
 
 :::code language="csharp" source="~/../code-windows/components/Animations/samples/AnimationsImplicitSample.xaml.cs":::
+
+

docs/windows/Animations/AnimationSet.md → docs/windows/Behaviors/AnimationSet.md

@@ -158,7 +158,9 @@ This makes it possible to also not having to name the target UI element, to regi
 
 :::code language="xaml" source="~/../code-windows/components/Behaviors/samples/InvokeActionsSample.xaml":::
 
-:::code language="csharp" source="~/../code-windows/components/Behaviors/samples/InvokeActionsSample.xaml.cs"::::::code language="xaml" source="~/../code-windows/components/Behaviors/samples/StartAnimationActivitySample.xaml":::
+:::code language="csharp" source="~/../code-windows/components/Behaviors/samples/InvokeActionsSample.xaml.cs":::
+
+:::code language="xaml" source="~/../code-windows/components/Behaviors/samples/StartAnimationActivitySample.xaml":::
 
 :::code language="csharp" source="~/../code-windows/components/Behaviors/samples/StartAnimationActivitySample.xaml.cs":::
 
@@ -203,3 +205,4 @@ Here is an example of how the new `PipelineVisualFactory` type can be combined w
 ```
 
 Here we are setting the `IsAnimatable` property for the effects we want to animate after creating the brush. This is necessary because Win2D/Composition effects do not support animation by default, and additional setup is required when creating a Composition brush to enable this functionality. Effects in a pipeline are not just all configured as being animatable by default both in order to reduce the overhead, and because there is a limit on the number of effects that can be animated in a single brush. Making this more advanced functionality opt-in for users ensures that it will still be possible to animate effects even within very large pipelines, without incurring into issues due to this limit.
+

docs/windows/Behaviors/HeaderBehaviors.md

@@ -41,7 +41,9 @@ The QuickReturnHeaderBehavior causes the element in the scrolling collection to
 
 :::code language="xaml" source="~/../code-windows/components/Behaviors/samples/Headers/QuickReturnHeaderBehaviorSample.xaml":::
 
-:::code language="csharp" source="~/../code-windows/components/Behaviors/samples/Headers/QuickReturnHeaderBehaviorSample.xaml.cs":::It can also be used to have content quickly re-appear in any `ScrollViewer`:
+:::code language="csharp" source="~/../code-windows/components/Behaviors/samples/Headers/QuickReturnHeaderBehaviorSample.xaml.cs":::
+
+It can also be used to have content quickly re-appear in any `ScrollViewer`:
 
 :::code language="xaml" source="~/../code-windows/components/Behaviors/samples/Headers/QuickReturnScrollViewerSample.xaml":::
 
@@ -53,8 +55,12 @@ The StickyHeaderBehavior causes the element in the scrolling collection to stay
 
 :::code language="xaml" source="~/../code-windows/components/Behaviors/samples/Headers/StickyHeaderBehaviorSample.xaml":::
 
-:::code language="csharp" source="~/../code-windows/components/Behaviors/samples/Headers/StickyHeaderBehaviorSample.xaml.cs":::Or similarly, it can be used with a `HeaderedItemsControl` to maintain context at the top:
+:::code language="csharp" source="~/../code-windows/components/Behaviors/samples/Headers/StickyHeaderBehaviorSample.xaml.cs":::
+
+Or similarly, it can be used with a `HeaderedItemsControl` to maintain context at the top:
 
 :::code language="xaml" source="~/../code-windows/components/Behaviors/samples/Headers/StickyHeaderItemsControlSample.xaml":::
 
 :::code language="csharp" source="~/../code-windows/components/Behaviors/samples/Headers/StickyHeaderItemsControlSample.xaml.cs":::
+
+

docs/windows/Behaviors/StackedNotificationsBehavior.md

@@ -81,3 +81,5 @@ This example shows sending simple text based notifications that will appear only
 :::code language="xaml" source="~/../code-windows/components/Behaviors/samples/Notifications/StackedNotificationsBehaviorToolkitSample.xaml":::
 
 :::code language="csharp" source="~/../code-windows/components/Behaviors/samples/Notifications/StackedNotificationsBehaviorToolkitSample.xaml.cs":::
+
+

docs/windows/Behaviors/Behaviors.md → docs/windows/Behaviors/index.md

@@ -49,7 +49,9 @@ Of the given targets, this behavior sets the focus on the first control which ac
 A control only receives focus if it is enabled and loaded into the visual tree:
 :::code language="xaml" source="~/../code-windows/components/Behaviors/samples/FocusBehaviorButtonSample.xaml":::
 
-:::code language="csharp" source="~/../code-windows/components/Behaviors/samples/FocusBehaviorButtonSample.xaml.cs":::Empty lists do not receive focus:
+:::code language="csharp" source="~/../code-windows/components/Behaviors/samples/FocusBehaviorButtonSample.xaml.cs":::
+
+Empty lists do not receive focus:
 :::code language="xaml" source="~/../code-windows/components/Behaviors/samples/FocusBehaviorListSample.xaml":::
 
 :::code language="csharp" source="~/../code-windows/components/Behaviors/samples/FocusBehaviorListSample.xaml.cs":::
@@ -61,3 +63,5 @@ This behavior allows you to define a Uri in XAML, similar to a `Hyperlink` or `H
 :::code language="xaml" source="~/../code-windows/components/Behaviors/samples/NavigateToUriActionSample.xaml":::
 
 :::code language="csharp" source="~/../code-windows/components/Behaviors/samples/NavigateToUriActionSample.xaml.cs":::
+
+

docs/windows/Collections/AdvancedCollectionView.md

@@ -2,7 +2,7 @@
 title: AdvancedCollectionView
 author: nmetulev
 description: The AdvancedCollectionView is a collection view implementation that support filtering, sorting and incremental loading. It's meant to be used in a viewmodel.
-keywords: AdvancedCollectionView, data, sorting, filtering
+keywords: AdvancedCollectionView, data, sorting, filtering, Collections
 dev_langs:
   - csharp
 category: Helpers

docs/windows/Collections/IncrementalLoadingCollection.md

@@ -2,7 +2,7 @@
 title: IncrementalLoadingCollection
 author: nmetulev
 description: The IncrementalLoadingCollection helpers greatly simplify the definition and usage of collections whose items can be loaded incrementally only when needed by the view (such as a ScrollViewer).
-keywords: IncrementalLoadingCollection, Control, Data, Incremental, Loading
+keywords: IncrementalLoadingCollection, Control, Data, Incremental, Loading, Collections
 dev_langs:
   - csharp
 category: Helpers
@@ -16,7 +16,9 @@ icon: Assets/IncrementalLoadingCollection.png
 
 :::code language="xaml" source="~/../code-windows/components/Collections/samples/IncrementalLoadingCollectionSample.xaml":::
 
-:::code language="csharp" source="~/../code-windows/components/Collections/samples/IncrementalLoadingCollectionSample.xaml.cs":::`IIncrementalSource` - An interface that represents a data source whose items can be loaded incrementally.
+:::code language="csharp" source="~/../code-windows/components/Collections/samples/IncrementalLoadingCollectionSample.xaml.cs":::
+
+`IIncrementalSource` - An interface that represents a data source whose items can be loaded incrementally.
 
 `IncrementalLoadingCollection` - An extension of [ObservableCollection](/dotnet/api/system.collections.objectmodel.observablecollection-1) such that its items are loaded only when needed.
 

docs/windows/ColorPicker/index.md

@@ -0,0 +1,30 @@
+---
+title: ColorPicker
+author: michael-hawker
+description: An extended color picker control that lets a user pick a color using a color spectrum, sliders, or text input.
+keywords: ColorPicker, Control, Layout
+dev_langs:
+  - csharp
+category: Controls
+subcategory: Input
+discussion-id: 0
+issue-id: 0
+icon: Assets/ColorPicker.png
+---
+
+# ColorPicker
+
+The [ColorPicker](/dotnet/api/microsoft.toolkit.uwp.ui.controls.colorpicker) control lets a user pick a color using a color spectrum, palette, sliders, or text input.
+
+:::code language="xaml" source="~/../code-windows/components/ColorPicker/samples/ColorPickerSample.xaml":::
+
+:::code language="csharp" source="~/../code-windows/components/ColorPicker/samples/ColorPickerSample.xaml.cs":::
+
+## ColorPickerButton
+The `ColorPickerButton` variant represents a `DropDownButton` variant which provides a preview of the selected color and allows a user to expand the drop-down to select a new color.
+
+:::code language="xaml" source="~/../code-windows/components/ColorPicker/samples/ColorPickerButtonSample.xaml":::
+
+:::code language="csharp" source="~/../code-windows/components/ColorPicker/samples/ColorPickerButtonSample.xaml.cs":::
+
+

docs/windows/Converters/Converters.md → docs/windows/Converters/index.md

@@ -96,7 +96,7 @@ Converts a source string from the App resources and returns its value, if found.
 
 ## StringFormatConverter
 
-This allows you to format a string property upon binding wrapping [string.Format](/dotnet/api/system.string.format?view=netstandard-2.0).  
+This allows you to format a string property upon binding wrapping [string.Format](/dotnet/api/system.string.format?view=netstandard-2.0&preserve-view=true).  
 It only allows for a single input value (the binding string), but can be formatted with the regular string.Format
 methods.
 
@@ -130,3 +130,5 @@ Converts a `Visibility` enumeration to a boolean value.
 :::code language="xaml" source="~/../code-windows/components/Converters/samples/VisibilityToBoolConverterSample.xaml":::
 
 :::code language="csharp" source="~/../code-windows/components/Converters/samples/VisibilityToBoolConverterSample.xaml.cs":::
+
+

docs/windows/DeveloperTools/DeveloperTools.md → docs/windows/DeveloperTools/index.md

@@ -38,3 +38,5 @@ FocusTracker will display the following information (when available) about the c
 :::code language="xaml" source="~/../code-windows/components/DeveloperTools/samples/FocusTrackerSample.xaml":::
 
 :::code language="csharp" source="~/../code-windows/components/DeveloperTools/samples/FocusTrackerSample.xaml.cs":::
+
+

docs/windows/Extensions/AttachedDropShadow.md

@@ -35,7 +35,9 @@ With the target element setup, you can simply attach a shadow to any number of o
 
 :::code language="xaml" source="~/../code-windows/components/Extensions/samples/Shadows/AttachedDropShadowBasicSample.xaml":::
 
-:::code language="csharp" source="~/../code-windows/components/Extensions/samples/Shadows/AttachedDropShadowBasicSample.xaml.cs":::> [!NOTE]
+:::code language="csharp" source="~/../code-windows/components/Extensions/samples/Shadows/AttachedDropShadowBasicSample.xaml.cs":::
+
+> [!NOTE]
 > If you need to scroll the element and its shadow, be sure to place your entire panel, including the sibling shadow target within the
 ScrollViewer.
 
@@ -57,3 +59,5 @@ Or define your own definition within your style as we've done here:
 :::code language="xaml" source="~/../code-windows/components/Extensions/samples/Shadows/AttachedDropShadowStyleSample.xaml":::
 
 :::code language="csharp" source="~/../code-windows/components/Extensions/samples/Shadows/AttachedDropShadowStyleSample.xaml.cs":::
+
+

docs/windows/Extensions/DispatcherQueueExtensions.md

@@ -50,3 +50,36 @@ int someOtherValue = await dispatcherQueue.EnqueueAsync(async () =>
     return 42;
 });
 ```
+
+## Migrating from DispatcherHelper
+
+The [`CoreDispatcher`](/uwp/api/windows.ui.core.coredispatcher) is being deprecated (and it will no longer work with XAML Islands or WinUI 3) and should no longer be used, as it had a number of limitations. Specifically, it relied on the assumption that each window had its own UI thread tied to it, which is not always the case. The new `DispatcherQueue` instead can be used going forwards, and it requires some changes in code that was previously relying on `CoreDispatcher` and `DispatcherHelper`. Specifically, a background thread can no longer retrieve the `CoreDispatcher` by just accessing the dispatcher associated to the "main window" for the application, because this concept does not apply anymore. Instead, a `DispatcherQueue` instance needs to be retrieved on the UI thread and cached for later use in a background thread.
+
+If you were using `DispatcherHelper` on the UI thread, apply the following change (here we're using `Task.Run` to simulate some work being done in a background thread and accessing some UI component, and we're assuming for this example that there is a `TextBlock` control in our page called "MyTextBlock"):
+
+```csharp
+// Before
+Task.Run(() =>
+{
+    await DispatcherHelper.ExecuteOnUIThreadAsync(() =>
+    {
+        MyTextBlock.Text = "Hello from a background thread!";
+    });
+});
+
+// After
+DispatcherQueue dispatcherQueue = DispatcherQueue.GetForCurrentThread();
+
+Task.Run(() =>
+{
+    await dispatcherQueue.EnqueueAsync(() =>
+    {
+        MyTextBlock.Text = "Hello from a background thread!";
+    });
+});
+```
+
+## Examples
+
+You can find more examples in the [unit tests](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/UnitTests/UnitTests.UWP/Extensions/Test_DispatcherQueueExtensions.cs).
+

docs/windows/Extensions/FrameworkElementExtensions.md

@@ -76,7 +76,9 @@ Here is an example of how this can be used:
 
 :::code language="xaml" source="~/../code-windows/components/Extensions/samples/FrameworkElementAncestorSample.xaml":::
 
-:::code language="csharp" source="~/../code-windows/components/Extensions/samples/FrameworkElementAncestorSample.xaml.cs":::While this example is trivial, it shows you how to properly setup and bind to the parent element's property, in this case `Spacing`.
+:::code language="csharp" source="~/../code-windows/components/Extensions/samples/FrameworkElementAncestorSample.xaml.cs":::
+
+While this example is trivial, it shows you how to properly setup and bind to the parent element's property, in this case `Spacing`.
 
 ## Cursor
 

docs/windows/Extensions/ListViewExtensions.md

@@ -126,3 +126,5 @@ We can use this extension to make the selected item always centered:
 :::code language="xaml" source="~/../code-windows/components/Extensions/samples/ListViewExtensions/SmoothScrollIntoViewSample.xaml":::
 
 :::code language="csharp" source="~/../code-windows/components/Extensions/samples/ListViewExtensions/SmoothScrollIntoViewSample.xaml.cs":::
+
+

docs/windows/Extensions/ShadowAnimations.md

@@ -14,7 +14,7 @@ icon: Assets/ShadowAnimation.png
 
 # Shadow animations
 
-Either type of Attached Shadow can be easily animated using the Toolkit's [`AnimationSet`](../animations/AnimationSet.md) api. These provide an easy XAML based way to animate a wide variety of elements, including a variety of shadow properties. They can also be animated with any other composition animation technique in code-behind as well using either the `AnimationBuilder` or built-in composition animations.
+Either type of Attached Shadow can be easily animated using the Toolkit's [`AnimationSet`](../animations/AnimationSet.md) api. These provide an easy XAML based way to animate a wide variety of elements, including a variety of shadow properties. They can also be animated with any other composition animation technique in code-behind as well using either the [`AnimationBuilder`](../Behaviors/AnimationSet.md) or built-in composition animations.
 
 > **Platform APIs:** `BlurRadiusDropShadowAnimation`, `ColorDropShadowAnimation`, `OffsetDropShadowAnimation`, `OpacityDropShadowAnimation`