diff --git a/docs/archive/windows/backgroundtaskhelper.md b/docs/archive/windows/backgroundtaskhelper.md new file mode 100644 index 00000000..4aeeb603 --- /dev/null +++ b/docs/archive/windows/backgroundtaskhelper.md @@ -0,0 +1,206 @@ +--- +title: Background Task Helper +author: nmetulev +description: The Background Task Helper helps users interact with background tasks in an easier manner. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Background Task Helper +dev_langs: + - csharp + - vb +--- + +# Background Task Helper (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [Background Task Helper](/dotnet/api/microsoft.toolkit.uwp.helpers.backgroundtaskhelper) helps users interact with background tasks in an easier manner. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Helpers?sample=BackgroundTaskHelper) + +## Syntax + +```csharp +using Microsoft.Toolkit.Uwp; + +BackgroundTaskRegistration registered = BackgroundTaskHelper.Register(typeof(BackgroundTaskClass), new TimeTrigger(15, true)); +BackgroundTaskRegistration registered = BackgroundTaskHelper.Register("TaskName", "TaskEntryPoint", new TimeTrigger(15, true)); +``` + +```vb +Imports Microsoft.Toolkit.Uwp + +Dim registered As BackgroundTaskRegistration = BackgroundTaskHelper.Register(GetType(BackgroundTaskClass), New TimeTrigger(15, True)) +Dim registered As BackgroundTaskRegistration = BackgroundTaskHelper.Register("TaskName", "TaskEntryPoint", New TimeTrigger(15, True)) +``` + +## Methods + +| Methods | Return Type | Description | +| -- | -- | -- | +| GetBackgroundTask(String) | [IBackgroundTaskRegistration](/uwp/api/Windows.ApplicationModel.Background.IBackgroundTaskRegistration) | Get the registered background task of the given type | +| GetBackgroundTask(Type) | IBackgroundTaskRegistration | Get the registered background task of the given type | +| IsBackgroundTaskRegistered(String) | bool | Check if a background task is registered | +| IsBackgroundTaskRegistered(Type) | bool | Check if a background task is registered | +| Register(String, IBackgroundTrigger, Boolean, Boolean, IBackgroundCondition[]) | [BackgroundTaskRegistration](/uwp/api/Windows.ApplicationModel.Background.BackgroundTaskRegistration) | Registers under the Single Process Model | +| Register(Type, IBackgroundTrigger, Boolean, Boolean, IBackgroundCondition[]) | BackgroundTaskRegistration | Register a background task with conditions | +| Register(String, String, IBackgroundTrigger, Boolean, Boolean, IBackgroundCondition[]) | BackgroundTaskRegistration | Register a background task with conditions | +| Unregister(String, Boolean) | void | Unregister a background task | +| Unregister(Type, Boolean) | void | Unregister a background task | +| Unregister(IBackgroundTaskRegistration, Boolean) | void | Unregister a background task | + +## Example + +### Using Multi-Process Model + +Using MPM (Multi-Process Model) is the classic way of using Background Task. + +To make it work, you will need : + +* To create Background Tasks in a Windows Runtime Component +* To register the Background Tasks in the package manifest (appxmanifest file) + +Once it is done, you can register your Background Tasks. + +```csharp +// Be sure to include the using at the top of the file: +using Microsoft.Toolkit.Uwp; +using Windows.ApplicationModel.Background; + +// Register a normal, separate process, background task +BackgroundTaskRegistration registered = BackgroundTaskHelper.Register("TaskName", "TaskEntryPoint", new TimeTrigger(15, true)); + +// This can also be written using the overload of Register with Type parameter. +BackgroundTaskRegistration registered = BackgroundTaskHelper.Register(typeof(BackgroundTaskClass), new TimeTrigger(15, true)); + +// With condition +BackgroundTaskRegistration registered = + BackgroundTaskHelper.Register(typeof(BackgroundTaskClass), + new TimeTrigger(15, true), + false, true, + new SystemCondition(SystemConditionType.InternetAvailable)); + +// 2 or more conditions +BackgroundTaskRegistration registered = + BackgroundTaskHelper.Register(typeof(BackgroundTaskClass), + new TimeTrigger(15, true), + false, true, + new SystemCondition(SystemConditionType.InternetAvailable), + new SystemCondition(SystemConditionType.UserPresent)); +``` + +```vb +' Be sure to include the Imports at the top of the file: +Imports Microsoft.Toolkit.Uwp +Imports Windows.ApplicationModel.Background + +' Register a normal, separate process, background task +Dim registered As BackgroundTaskRegistration = BackgroundTaskHelper.Register("TaskName", "TaskEntryPoint", New TimeTrigger(15, True)) + +' This can also be written using the overload of Register with Type parameter. +Dim registered As BackgroundTaskRegistration = BackgroundTaskHelper.Register(GetType(BackgroundTaskClass), New TimeTrigger(15, True)) + +' With condition +Dim registered As BackgroundTaskRegistration = BackgroundTaskHelper.Register(GetType(BackgroundTaskClass), + New TimeTrigger(15, True), + False, + True, + New SystemCondition(SystemConditionType.InternetAvailable)) + +' 2 or more conditions +Dim registered As BackgroundTaskRegistration = BackgroundTaskHelper.Register(GetType(BackgroundTaskClass), + New TimeTrigger(15, True), + False, + True, + New SystemCondition(SystemConditionType.InternetAvailable), + New SystemCondition(SystemConditionType.UserPresent)) +``` + +### Using Single-Process Model + +Using SPM (Single-Process Model) is the new and simple way of using Background Task. +It is required to target Anniversary Update (SDK 14393) or later. + +Using SPM, you can declare your Background Tasks inside your own project, no need to create a Windows Runtime Component. +Moreover, it is no longer required to register the Background Tasks in the package manifest (appxmanifest file). + +Once you have created the Background Task, you can register it by calling the `Register` method. + +```csharp +// Be sure to include the using at the top of the file: +using Microsoft.Toolkit.Uwp; +using Windows.ApplicationModel.Background; + +// Register a single process background task (Anniversary Update and later ONLY) +BackgroundTaskRegistration registered = BackgroundTaskHelper.Register("Name of the Background Task", new TimeTrigger(15, true)); +``` + +```vb +' Be sure to include the imports at the top of the file: +Imports Microsoft.Toolkit.Uwp +Imports Windows.ApplicationModel.Background + +' Register a single process background task (Anniversary Update and later ONLY) +Dim registered As BackgroundTaskRegistration = BackgroundTaskHelper.Register("Name of the Background Task", New TimeTrigger(15, True)) +``` + +The other difference between SPM and MPM is that in SPM, you have to handle your Background Tasks inside the `OnBackgroundActivated` event of `App.xaml.cs` class. +Here is an example of how to handle Background Tasks in SPM. + +```csharp +// Event fired when a Background Task is activated (in Single Process Model) +protected override void OnBackgroundActivated(BackgroundActivatedEventArgs args) +{ + base.OnBackgroundActivated(args); + + var deferral = args.TaskInstance.GetDeferral(); + + switch (args.TaskInstance.Task.Name) + { + case "Name of the Background Task": + new TestBackgroundTask().Run(args.TaskInstance); + break; + } + + deferral.Complete(); +} +``` + +```vb +Protected Overrides Sub OnBackgroundActivated(ByVal args As BackgroundActivatedEventArgs) + MyBase.OnBackgroundActivated(args) + + Dim deferral = args.TaskInstance.GetDeferral() + + Select Case args.TaskInstance.Task.Name + Case "Name of the Background Task" + New TestBackgroundTask().Run(args.TaskInstance) + End Select + + deferral.Complete() +End Sub +``` + +## Sample Project + +[Background Task Helper](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/BackgroundTaskHelper). You can [see this in action](uwpct://Helpers?sample=BackgroundTaskHelper) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +## API + +* [Background Task source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/BackgroundTaskHelper.cs) diff --git a/docs/archive/windows/bindablevalueholder.md b/docs/archive/windows/bindablevalueholder.md new file mode 100644 index 00000000..b3d143c2 --- /dev/null +++ b/docs/archive/windows/bindablevalueholder.md @@ -0,0 +1,76 @@ +--- +title: BindableValueHolder +author: nmetulev +description: The BindableValueHolder lets users change several objects' states at a time. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, BindableValueHolder +--- + +# BindableValueHolder (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) +- [GitHub issue #491](https://github.com/CommunityToolkit/Windows/issues/491) (Documentation mapping and porting) + +Original documentation follows below. + +--- + +The [BindableValueHolder](/dotnet/api/microsoft.toolkit.uwp.ui.helpers.bindablevalueholder) lets users change several objects' states at a time. + +## Syntax + +```xaml + +``` + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| Value | object | Gets or sets the held value | + +## Example + +You can use it to switch several object states by declaring it as a Resource (either in a page or control): + +```xaml + +``` + +and using it like that: + +```xaml + + + +``` + +and switching it like that: + +```xaml + + + + + + + + + +``` + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp.UI | +| NuGet package | [Microsoft.Toolkit.Uwp.UI](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI/) | + +## API + +* [BindableValueHolder source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI/Helpers/BindableValueHolder.cs) diff --git a/docs/archive/windows/bladeview.md b/docs/archive/windows/bladeview.md new file mode 100644 index 00000000..c48a7d3a --- /dev/null +++ b/docs/archive/windows/bladeview.md @@ -0,0 +1,125 @@ +--- +title: BladeView +author: nmetulev +description: The BladeView provides a container to host blades as extra detail pages in, for example, a master-detail scenario. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, BladeView, XAML Control, xaml +dev_langs: + - csharp + - vb +--- + +# BladeView (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [GitHub tracking issue for BladeView port](https://github.com/CommunityToolkit/Windows/issues/89) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [BladeView](/dotnet/api/microsoft.toolkit.uwp.ui.controls.bladeview) control provides a horizontal collection of [BladeItems](/dotnet/api/microsoft.toolkit.uwp.ui.controls.bladeitem) for drilling into detailed scenarios. The control is based on how the Azure Portal works. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=BladeView) + +## Syntax + +```xaml + + + + + + + + + + + +``` + +## Sample Output + +![BladeView animation](images/bladeview.gif) + +## Properties + +### BladeView Properties + +| Property | Type | Description | +|----------------------------|-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------| +| ActiveBlades | IList<[BladeItem](/dotnet/api/microsoft.toolkit.uwp.ui.controls.bladeitem)> | Description | +| AutoCollapseCountThreshold | int | Gets or sets a value indicating what the overflow amount should be to start auto collapsing blade items | +| BladeMode | [BladeMode](/dotnet/api/microsoft.toolkit.uwp.ui.controls.blademode) | Gets or sets a value indicating whether blade mode (ex: whether blades are full screen or not) | + +### BladeItem Properties + +| Property | Type | Description | +| -- | -- | -- | +| CloseButtonBackground | Brush | Gets or sets the background color of the default close button in the title bar | +| CloseButtonForeground | Brush | Gets or sets the foreground color of the close button | +| IsOpen | bool | Gets or sets a value indicating whether this blade is opened | +| Header | string | Gets or sets the content for the header | +| TitleBarBackground | Brush | Gets or sets the background color of the title bar | +| TitleBarVisibility | Visibility | Gets or sets the visibility of the title bar for this blade | + +## Events + +### BladeView Events + +| Events | Description | +| -- | -- | +| BladeClosed | Fires whenever a BladeItem is closed | +| BladeOpened | Fires whenever a BladeItem is opened | + +### BladeItem Events + +| Events | Description | +| -- | -- | +| VisibilityChanged | Fires when the blade is opened or closed | + +## Examples + +- If you want to use the BladeView for handling a flow of actions, you can use the `AutoCollapseCountThreshold` property to tell it to start auto collapsing BladeItems after a certain threshold count has been reached. This will also help keep a clean, uncluttered screen real estate. + + For example: if you set `AutoCollapseCountThreshold` to 3, the BladeView will start counting all BladeItems that are open in the BladeView and have their `TitleBarVisibility` property set to Visible. When the n+1 BladeItem, in our case the 4th one, is being added, the BladeView will auto collapse all n BladeItems except for the last one. All additional BladeItems that are added afterwards will trigger the same effect; collapse all BladeItems except for the last open one. + + *Sample Code* + + ```xaml + + + + + + + + ..... + ..... + + ``` + +## Sample Project + +[BladeView Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/BladeView). You can [see this in action](uwpct://Controls?sample=BladeView) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[BladeView XAML File](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Layout/BladeView/BladeView.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +- [BladeView source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Layout/BladeView) diff --git a/docs/archive/windows/bluetoothlehelper.md b/docs/archive/windows/bluetoothlehelper.md new file mode 100644 index 00000000..376f5754 --- /dev/null +++ b/docs/archive/windows/bluetoothlehelper.md @@ -0,0 +1,182 @@ +--- +title: BluetoothLEHelper +author: nmetulev +description: The BluetoothLEHelper class provides functionality to easily enumerate, connect to and interact with Bluetooth LE Peripherals. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, BluetoothLEHelper, bluetooth le, bluetooth +dev_langs: + - csharp + - vb +--- + +# BluetoothLEHelper (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The BluetoothLEHelper class provides functionality to easily enumerate, connect to and interact with Bluetooth LE Peripherals. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Helpers?sample=BluetoothLEHelper) + +## BluetoothLEHelper class + +### Properties + +| Property | Type | Description | +|---------------------------|---------------------------------------------------|-----------------------------------------------------------------------------| +| BluetoothLeDevices | ObservableCollection\ | Gets the list of available bluetooth devices | +| IsEnumerating | bool | Gets a value indicating whether app is currently enumerating | +| IsPeripheralRoleSupported | bool | Gets a value indicating whether peripheral mode is supported by this device | +| IsCentralRoleSupported | bool | Gets a value indicating whether central role is supported by this device | + +### Methods + +| Methods | Return Type | Description | +| -- | -- | -- | +| StartEnumeration() | void | Starts enumeration of bluetooth le devices | +| StopEnumeration() | void | Stops enumeration of bluetooth device | + +### Events + +| Events | Description | +| -- | -- | +| EnumerationCompleted | An event for when the enumeration is complete | + +## ObservableBluetoothLEDevice class + +### Properties + +| Property | Type | Description | +|--------------------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------| +| BluetoothAddressAsString | string | Gets the bluetooth address of this device as a string | +| BluetoothAddressAsUlong | ulong | Gets the bluetooth address of this device | +| BluetoothLEDevice | BluetoothLEDevice | Gets the base bluetooth device this class wraps | +| DeviceInfo | [DeviceInformation](/uwp/api/Windows.Devices.Enumeration.DeviceInformation) | Gets the device information for the device this class wraps | +| ErrorText | string | Gets the error text when connecting to this device fails | +| Glyph | BitmapImage | Gets or sets the glyph of this bluetooth device | +| IsConnected | bool | Gets a value indicating whether this device is connected | +| IsPaired | bool | Gets a value indicating whether this device is paired | +| Name | string | Gets the name of this device | +| RSSI | int | Gets the RSSI value of this device | +| Services | ObservableCollection\ | Gets the services this device supports | +| ServiceCount | int | Gets or sets the number of services this device has | + +### Methods + +| Methods | Return Type | Description | +| -- | -- | -- | +| ConnectAsync() | Task | ConnectAsync to this bluetooth device | +| DoInAppPairingAsync() | Task | Does the in application pairing | +| UpdateAsync(DeviceInformationUpdate) | Task | Updates this device's deviceInformation | +| ToString() | string | Overrides the ToString function to return the name of the device | + +## ObservableGattDeviceService + +### Properties + +| Property | Type | Description | +|-----------------|-----------------------------------------------------|----------------------------------------------| +| Characteristics | ObservableCollection\ | Gets all the characteristics of this service | +| Name | string | Gets the name of this service | +| UUID | string | Gets the UUID of this service | +| Service | GattDeviceService | Gets the service this class wraps | + +## ObservableGattCharacteristics + +### Properties + +| Property | Type | Description | +| -- | -- | -- | +| Characteristic | GattCharacteristic | Gets or sets the characteristic this class wraps | +| IsIndicateSet | bool | Gets a value indicating whether indicate is set | +| IsNotifySet | bool | Gets a value indicating whether notify is set | +| Parent | ObservableGattDeviceService | Gets or sets the parent service of this characteristic | +| Name | string | Gets or sets the name of this characteristic | +| UUID | string | Gets or sets the UUID of this characteristic | +| Value | string | Gets the value of this characteristic | +| DisplayType | DisplayTypes | Gets or sets how this characteristic's value should be displayed | + +### Methods + +| Methods | Return Type | Description | +|---------------------|--------------|---------------------------------------| +| ReadValueAsync() | Task\ | Reads the value of the Characteristic | +| SetIndicateAsync() | Task\ | Set's the indicate descriptor | +| StopIndicateAsync() | Task\ | Unset the indicate descriptor | +| SetNotifyAsync() | Task\ | Sets the notify characteristic | +| StopNotifyAsync() | Task\ | Unsets the notify descriptor | + +## Example + +```csharp +// Get a local copy of the context for easier reading +BluetoothLEHelper bluetoothLEHelper = BluetoothLEHelper.Context; + +// check if BluetoothLE APIs are available +if (BluetoothLEHelper.IsBluetoothLESupported) +{ + // Start the Enumeration + bluetoothLEHelper.StartEnumeration(); + + // At this point the user needs to select a device they want to connect to. This can be done by + // creating a ListView and binding the bluetoothLEHelper collection to it. Once a device is found, + // the Connect() method can be called to connect to the device and start interacting with its services + + // Connect to a device if your choice + ObservableBluetoothLEDevice device = bluetoothLEHelper.BluetoothLeDevices[]; + await device.ConnectAsync(); + + // At this point the device is connected and the Services property is populated. + + // See all the services + var services = device.Services; +} +``` + +```vb +' Get a local copy of the context for easier reading +Dim bluetoothLEHelper As BluetoothLEHelper = BluetoothLEHelper.Context + +' check if BluetoothLE APIs are available +If BluetoothLEHelper.IsBluetoothLESupported Then + ' Start the Enumeration + bluetoothLEHelper.StartEnumeration() + + ' At this point the user needs to select a device they want to connect to. This can be done by + ' creating a ListView and binding the bluetoothLEHelper collection to it. Once a device is found, + ' the Connect() method can be called to connect to the device and start interacting with its services + + ' Connect to a device if your choice + Dim device As ObservableBluetoothLEDevice = bluetoothLEHelper.BluetoothLeDevices() + Await device.ConnectAsync() + + ' At this point the device is connected and the Services property is populated. + + ' See all the services + Dim services = device.Services +End If +``` + +## Sample Project + +[BluetoothLE Helper Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/BluetoothLEHelper). You can [see this in action](uwpct://Helpers?sample=BluetoothLEHelper) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp.Connectivity | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +## API + +* [BluetoothLEHelper source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.Connectivity/BluetoothLEHelper) diff --git a/docs/archive/windows/canvaspathgeometry.md b/docs/archive/windows/canvaspathgeometry.md new file mode 100644 index 00000000..2529afd1 --- /dev/null +++ b/docs/archive/windows/canvaspathgeometry.md @@ -0,0 +1,226 @@ +--- +title: CanvasPathGeometry Drawing +author: ratishphilip +description: The CanvasPathGeometry class facilitates the drawing and manipulation of complex geometrical shapes. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Win2D, Win2D path mini language +dev_langs: + - csharp +--- + +# CanvasPathGeometry (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The `CanvasGeometry` class (in the `Microsoft.Graphics.Canvas.Geometry` namespace) facilitates the drawing and manipulation of complex geometrical shapes. These shapes can be outlined with a stroke and filled with a brush (which can be a solid color, a bitmap pattern, or a gradient). + +While the `CanvasGeometry` class provides various static methods to create predefined shapes like Circle, Ellipse, Rectangle, RoundedRectangle, the `CanvasPathBuilder` class provides several methods to create freeform CanvasGeometry objects. +Creation of a complex freeform geometric shape may involve invoking of several CanvasPathBuilder commands. For example, the following code shows how to create a triangle geometry using CanvasPathBuilder + +```cs +CanvasPathBuilder pathBuilder = new CanvasPathBuilder(device); +pathBuilder.BeginFigure(1, 1); +pathBuilder.AddLine(300, 300); +pathBuilder.AddLine(1, 300); +pathBuilder.EndFigure(CanvasFigureLoop.Closed); +CanvasGeometry triangleGeometry = CanvasGeometry.CreatePath(pathBuilder); +``` + +The [`CanvasPathGeometry`](/dotnet/api/microsoft.toolkit.uwp.ui.media.geometry.canvaspathgeometry) class provides several static methods that parse the [Win2D Mini Language](win2d-path-mini-language.md) and instantiate the complex geometries, color, brushes, strokes, and stroke styles. This class is available in the `Microsoft.Toolkit.Uwp.UI.Media.Geometry` namespace. + +> [!div class="nextstepaction"] +> [try it in the sample app](uwpct://Helpers?sample=CanvasPathGeometryPage) + +## Examples + +### Creating CanvasGeometry with CanvasPathGeometry + +The following APIs convert path data string to CanvasGeometry + +```cs +public static CanvasGeometry CreateGeometry(ICanvasResourceCreator resourceCreator, string pathData, StringBuilder logger = null); +public static CanvasGeometry CreateGeometry(string pathData, StringBuilder logger = null); +``` + +The **logger** parameter in this method is an option argument of type **StringBuilder** that can be used to obtain the **CanvasPathBuilder** commands in text format. It is mainly intended for information/debugging purposes only. + +### Creating Color + +#### From Hexadecimal Color String or High Dynamic Range Color String + +There are two APIs that convert the hexadecimal color string in **#RRGGBB** or **#AARRGGBB** format or the High Dynamic Range Color string in the **R G B A** format to the corresponding Color object. The '#' character is optional in Hexadecimal color string. R, G, B & A should have value in the range between 0 and 1, inclusive. + +```cs +public static Color CreateColor(string colorString); +public static bool TryCreateColor(string colorString , out Color color); +``` + +The first API will raise an **ArgumentException** if the argument is not in the correct format while the second API will attempt to convert the color string without raising an exception. + +Example + +```cs +var redColor = CanvasPathGeometry.CreateColor("#ff0000"); +CanvasPathGeometry.TryCreateColor("0000ff", out Color blueColor); + +try +{ + // throws ArgumentException + var invalidColor = CanvasPathGeometry.CreateColor("xyz"); +} +catch (ArgumentException) +{ + +} +``` + +#### From High Dynamic Range Color (Vector4) + +The following API Converts a **Vector4** High Dynamic Range Color to Color object. Negative components of the Vector4 will be sanitized by taking the absolute value of the component. The HDR Color components should have value in the range [0, 1]. If their value is more than 1, they will be clamped at 1. **Vector4** 's X, Y, Z, W components match to **Color**'s R, G, B, A components respectively. + +```cs +public static Color CreateColor(Vector4 hdrColor); +``` + +Example + +```cs +var hdrVector = new Vector4(1, 0, 0, 1); +// Red color +var redColor = CanvasPathGeometry.CreateColor(hdfVector); +``` + +### Creating ICanvasBrush + +The following API converts a brush data string to **ICanvasBrush** object + +```cs +public static ICanvasBrush CreateBrush(ICanvasResourceCreator resourceCreator, +string brushData); +``` + +Example + +```cs +// SolidColorBrush with 0.75 opacity +var solidRedBrush = CanvasPathGeometry.CreateBrush(device, "SC #FFFF0000 O 0.75"); +// LinearGradientBrush +var linearGradientBrush = CanvasPathGeometry.CreateBrush(device, “LG M 0 80 Z0 0 S 0.00 #ffee5124, 0.18 #fff05627, 0.26 #fff15b29, 0.6 #fff58535, 1.00 #fff9af41”); +``` + +### Creating CanvasStrokeStyle + +The following API converts a style data string to **CanvasStrokeStyle** object + +```cs +public static CanvasStrokeStyle CreateStrokeStyle(string styleData); +``` + +Example + +```cs +// CanvasStrokeStyle with custom dash style +var customStrokeStyle = CanvasPathGeometry.CreateStrokeStyle(“CSS CDS 2 2 0 2 1 3”); +``` + +### Creating ICanvasStroke + +**ICanvasStroke** is an interface to represent the Stroke which can be used to render an outline on a **CanvasGeometry**. **CanvasStroke** class implements this interface. + +```cs +public interface ICanvasStroke +{ + ICanvasBrush Brush { get; } + float Width { get; } + CanvasStrokeStyle Style { get; } + Matrix3x2 Transform { get; set; } +} + +public sealed class CanvasStroke : ICanvasStroke +{ + public ICanvasBrush Brush { get; } + public float Width { get; } + public CanvasStrokeStyle Style { get; } + public Matrix3x2 Transform { get; set; } + + public CanvasStroke(ICanvasBrush brush, float strokeWidth = 1f); + public CanvasStroke(ICanvasBrush brush, float strokeWidth, CanvasStrokeStyle strokeStyle); + public CanvasStroke(ICanvasResourceCreator device, Color strokeColor, float strokeWidth = 1f); + public CanvasStroke(ICanvasResourceCreator device, Color strokeColor, float strokeWidth, CanvasStrokeStyle strokeStyle); +} +``` + +The following API converts a stroke data string to **ICanvasStroke** object + +```cs +public static ICanvasStroke CreateStroke(ICanvasResourceCreator resourceCreator, string strokeData); +``` + +Example + +```cs +// A dashed stroke rendered with a LinearGradientBrush and a custom stroke style +var dashedStroke = CanvasPathGeometry.CreateStroke(device, “ST 4.5 LG M 0 0 Z80 80 S 0.00 #ffff0000, 0.5 #ff00ff00, 0.99 #ff0000ff CSS DS 2 Do 2 SC 1 EC 2 CDS 2 2 0 2 1 3”); +// A solid line stroke of thickness 2 having red color +var solidStroke = CanvasPathGeometry.CreateStroke(device, “ST 2 SC #ff0000”); +``` + +### Compositor Extension Methods + +Based on the above methods, the following extension methods for **Compositor** are now available + +```cs +public static CompositionPath CreatePath(this Compositor compositor, string pathData); +public static CompositionPathGeometry CreatePathGeometry(this Compositor compositor, string pathData); +public static CompositionSpriteShape CreateSpriteShape(this Compositor compositor, string pathData); +public static CompositionGeometricClip CreateGeometricClip(this Compositor compositor, CanvasGeometry geometry); +public static CompositionGeometricClip CreateGeometricClip(this Compositor compositor, string pathData); +``` + +### Creating a Squircle + +A [Squircle](https://en.wikipedia.org/wiki/Squircle) is an intermediate shape between a square and a circle. + +![Squircle Demo](images/squircle.gif) + +The following extension methods help to create a Squircle in Composition layer or using Win2D. + +```cs +// CanvasPathGeometry +public static CanvasGeometry CreateSquircle(ICanvasResourceCreator resourceCreator, float x, float y, float width, float height, float radiusX, float radiusY); +// CanvasPathBuilder extension method +public static void AddSquircleFigure(this CanvasPathBuilder pathBuilder, float x, float y, float width, float height, float radiusX, float radiusY); +// CanvasDrawingsession extension methods +public static void DrawSquircle(this CanvasDrawingSession session, float x, float y, float w, float h, float radiusX, float radiusY, ICanvasStroke stroke); +public static void DrawSquircle(this CanvasDrawingSession session, float x, float y, float w, float h, float radiusX, float radiusY, Vector2 offset, ICanvasStroke stroke); +public static void FillSquircle(this CanvasDrawingSession session, float x, float y, float w, float h, float radiusX, float radiusY, Color color); +public static void FillSquircle(this CanvasDrawingSession session, float x, float y, float w, float h, float radiusX, float radiusY, ICanvasBrush brush); +public static void FillSquircle(this CanvasDrawingSession session, float x, float y, float w, float h, float radiusX, float radiusY, Vector2 offset, Color color); +public static void FillSquircle(this CanvasDrawingSession session, float x, float y, float w, float h, float radiusX, float radiusY, Vector2 offset, ICanvasBrush brush); +``` + +## Sample Project + + + +[CanvasPathGeometry Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/CanvasPathGeometry/CanvasPathGeometryPage.xaml.cs). You can [see this in action](uwpct://Helpers?sample=CanvasPathGeometryPage) in [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, MinVersion or higher | +| ------------- | ------------------------------------------------------------------------------------------------ | +| Namespace | Microsoft.Toolkit.Uwp.UI.Media.Geometry | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Media](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Media/) | + +## API + +- [CanvasPathGeometry Source Code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Media/Geometry/CanvasPathGeometry.cs) diff --git a/docs/archive/windows/carousel.md b/docs/archive/windows/carousel.md new file mode 100644 index 00000000..19bff7a6 --- /dev/null +++ b/docs/archive/windows/carousel.md @@ -0,0 +1,101 @@ +--- +title: Carousel +author: nmetulev +description: The Carousel control inherits from ItemsControl, representing a nice and smooth carousel. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, carousel, xaml control, xaml +dev_langs: + - csharp + - vb +--- + +# Carousel (Archived) + +**Important Note:** This document has been archived in the Windows Community Toolkit. + +While the Carousel control is not included in WCT 8.x, there are plans to introduce a modern, improved version in Community Toolkit Labs. The existing implementation from 7.x was deprecated due to its age and limitations, particularly around infinite scrolling functionality. + +Community interest and contributions are welcome to help accelerate this effort. You can track progress and express interest in the GitHub discussions: + +- [Carousel discussion in Labs](https://github.com/CommunityToolkit/Labs-Windows/discussions/498) + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [Carousel](/dotnet/api/microsoft.toolkit.uwp.ui.controls.carousel) control provides a new control, inherited from the [ItemsControl](/uwp/api/Windows.UI.Xaml.Controls.ItemsControl), representing a nice and smooth carousel. +This control lets you specify a lot of properties for a flexible layouting. +The `Carousel` control works fine with mouse, touch, mouse and keyboard as well. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=Carousel) + +## Syntax + +```xaml + + + + + + + + + + + + + +``` + +## Sample Output + +![Carousel Overview](images/carousel-overview.gif) + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| EasingFunction | EasingFunctionBase | Gets or sets easing function to apply for each Transition | +| InvertPositive | bool | Gets or sets a value indicating whether the items rendered transformations should be opposite compared to the selected item If false, all the items (except the selected item) will have the exact same transformations If true, all the items where index > selected index will have an opposite tranformation (Rotation X Y and Z will be multiply by -1) | +| ItemDepth | int | Gets or sets depth of non Selected Index Items | +| ItemMargin | int | Gets or sets the item margin | +| ItemRotationX | double | Gets or sets rotation angle on X | +| ItemRotationY | double | Gets or sets rotation angle on Y | +| ItemRotationZ | double | Gets or sets rotation angle on Z | +| Orientation | Orientation | Gets or sets the Carousel orientation. Horizontal or Vertical | +| SelectedIndex | int | Gets or sets selected Index | +| SelectedItem | object | Gets or sets the selected Item | +| TransitionDuration | int | Gets or sets duration of the easing function animation in ms | + +## Events + +| Events | Description | +| -- | -- | +| SelectionChanged | Occurs when the selected item has changed | + +## Sample Project + +[Carousel Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Carousel). You can [see this in action](uwpct://Controls?sample=Carousel) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[Carousel XAML File](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Layout/Carousel/Carousel.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +* [Carousel source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Layout/Carousel) diff --git a/docs/archive/windows/datagrid-guidance/customize-autogenerated-columns.md b/docs/archive/windows/datagrid-guidance/customize-autogenerated-columns.md new file mode 100644 index 00000000..6b358f50 --- /dev/null +++ b/docs/archive/windows/datagrid-guidance/customize-autogenerated-columns.md @@ -0,0 +1,108 @@ +--- +title: How to - Customize Auto-Generated Columns in the DataGrid Control +author: harinikmsft +description: Guidance document that shows how to customize auto generated columns in the DataGrid control +keywords: windows 10, uwp, windows community toolkit, windows toolkit, DataGrid, xaml control, xaml, AutoGenerateColumns +--- + +# How to: Customize Auto-Generated Columns in the DataGrid Control (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component directly to 8.x, it's important to understand that: +- The WCT 7.x DataGrid is still usable alongside WCT 8.x components for existing projects. +- The DataGrid control has been deprecated in favor of the new DataTable component. + +For new development, we recommend using the DataTable component which offers improved functionality and is actively maintained. If you have specific needs that DataTable doesn't meet, please consider contributing to WCT Labs where component improvements are prototyped and incubated. + +For more information: +- [DataGrid discussion in Labs](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [DataGrid](../datagrid.md) control supports the option to automatically generate columns based on the collection data bound through the **ItemsSource** property. + +```xaml + + +``` + +You can modify the **DataGrid.Columns** collection at run time regardless of whether it contains generated columns. However, if you specify columns in XAML, you should set AutoGenerateColumns to false in order to avoid duplication. + +You can handle the DataGrid's **AutoGeneratingColumn** event to modify, replace, or cancel a column that is being generated. The AutoGeneratingColumn event occurs one time for each public, non-static property in the bound data type when the ItemsSource property is changed and the AutoGenerateColumns property is true. + +## To handle the AutoGeneratingColumn event + +1. Create an event handler for the DataGrid's **AutoGeneratingColumn** event. + + ```csharp + private void dataGrid1_AutoGeneratingColumn(object sender, DataGridAutoGeneratingColumnEventArgs e) + { + //... + } + ``` + +2. Add the event handler to the DataGrid instances events. + + ```xaml + + ``` + +## To modify a generated column + +In the AutoGeneratingColumn event handler, access the DataGridColumn properties by referencing the **DataGridAutoGeneratingColumnEventArgs.Column** property. + +```csharp +//Modify the header of the "Name" column +if (e.Column.Header.ToString() == "Name") +{ + e.Column.Header = "Task"; +} +``` + +## To replace a generated column + +1. In the AutoGeneratingColumn event handler, create a new **DataGridColumn**. + + ```csharp + //Replace the DueDate column with a custom template column. + if (e.PropertyName == "DueDate") + { + //Create a new template column. + var templateColumn = new DataGridTemplateColumn(); + templateColumn.Header = "Due Date"; + //... + } + ``` + +2. Replace the column from the **DataGridAutoGeneratingColumnEventArgs.Column** property with the new **DataGridColumn** instance. + + ```csharp + //Replace the auto-generated column with the templateColumn. + e.Column = templateColumn; + ``` + +## To cancel generation of a column + +Set the **Cancel** property to true. + +```csharp +//Cancel AutoGeneration of all boolean columns. +if (e.PropertyType == GetType(Boolean)) +{ + e.Cancel = True; +} +``` + +## See Also + +* [Add a DataGrid control to a page](datagrid-basics.md) +* [Customize the DataGrid control using styling and formatting options](styling-formatting-options.md) +* [Sizing options in the DataGrid control](sizing-options.md) +* [DataGrid Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid) diff --git a/docs/archive/windows/datagrid-guidance/datagrid-basics.md b/docs/archive/windows/datagrid-guidance/datagrid-basics.md new file mode 100644 index 00000000..6ef3d390 --- /dev/null +++ b/docs/archive/windows/datagrid-guidance/datagrid-basics.md @@ -0,0 +1,299 @@ +--- +title: How to - Add a DataGrid control to a page +author: harinikmsft +description: Guidance document that shows how to add a DataGrid control and display data in rows and columns +keywords: windows 10, uwp, windows community toolkit, windows toolkit, DataGrid, xaml control, xaml +--- + +# How to: Add a DataGrid control to a page (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component directly to 8.x, it's important to understand that: +- The WCT 7.x DataGrid is still usable alongside WCT 8.x components for existing projects. +- The DataGrid control has been deprecated in favor of the new DataTable component. + +For new development, we recommend using the DataTable component which offers improved functionality and is actively maintained. If you have specific needs that DataTable doesn't meet, please consider contributing to WCT Labs where component improvements are prototyped and incubated. + +For more information: +- [DataGrid discussion in Labs](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The Windows 10 [DataGrid](../datagrid.md) control is part of the Windows Community Toolkit DataGrid library. To use the DataGrid control in your Windows 10 application, you need to add the appropriate reference to your application as shown in the following section. + +## Getting started with the DataGrid control + +The toolkit is available as NuGet packages that can be added to any existing or new project using Visual Studio. + +1. Download [Visual Studio 2017](https://developer.microsoft.com/windows/downloads) and ensure you choose the **Universal Windows Platform development** Workload in the Visual Studio installer. + +2. Open an existing project, or create a new project using the Blank App template under Visual C# -> Windows -> Universal. **Important**: Build 16299 or higher is supported by current version of the Toolkit. + +3. In Solution Explorer panel, right click on your project name and select **Manage NuGet Packages**. Search for **Microsoft.Toolkit.UWP.UI.Controls.DataGrid**, and choose the [Microsoft.Toolkit.Uwp.UI.Controls.DataGrid](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls.DataGrid/) nuget package. + + ![NuGet Packages](../images/datagrid/managenugetpackages.png "Manage NuGet Packages Image") + +4. Add a reference to the toolkit and add the DataGrid control in your XAML page + + * Add a reference at the top of your page + + ```xaml + xmlns:controls="using:Microsoft.Toolkit.Uwp.UI.Controls" + ``` + + * Add the following XAML in your page to add the DataGrid control + + ```xaml + + + + ``` + +5. Alternatively, you can add the DataGrid control directly in C# in your page code behind. **Important** You would either add it to the XAML directly or the code behind, not both. + + * Add the namespaces to the toolkit + + ```csharp + using Microsoft.Toolkit.Uwp.UI.Controls; + ``` + + * Add the control in your Loaded event + + ```csharp + DataGrid dataGrid1 = new DataGrid(); + LayoutRoot.Children.Add(dataGrid1); + ``` + +## Binding a DataGrid to a data source + +You can use the **DataGrid.ItemsSource** property to bind to a collection that will be used to generate the contents of the DataGrid control. The following example demonstrates how to use the **ItemsSource** and **AutoGenerateColumns** properties to automatically display a collection of Customer data in rows and columns. + +```xaml + +``` + +```csharp +//backing data source in MyViewModel +public class Customer +{ + public String FirstName { get; set; } + public String LastName { get; set; } + public String Address { get; set; } + public Boolean IsNew { get; set; } + + public Customer(String firstName, String lastName, + String address, Boolean isNew) + { + this.FirstName = firstName; + this.LastName = lastName; + this.Address = address; + this.IsNew = isNew; + } + + public static List Customers() + { + return new List(new Customer[4] { + new Customer("A.", "Zero", + "12 North Third Street, Apartment 45", + false), + new Customer("B.", "One", + "34 West Fifth Street, Apartment 67", + false), + new Customer("C.", "Two", + "56 East Seventh Street, Apartment 89", + true), + new Customer("D.", "Three", + "78 South Ninth Street, Apartment 10", + true) + }); + } +} +``` + +## Customizing columns + +By default, the DataGrid control generates columns automatically when you set the ItemsSource property as shown above. The generated columns are of type **DataGridCheckBoxColumn** for bound Boolean (and nullable Boolean) properties, and of type **DataGridTextColumn** for all other properties. If a property does not have a String or numeric value type, the generated text box columns are read-only and display the data object's ToString value. + +You can override the default automatic generation of columns by setting the **AutoGenerateColumns** property to False and explicitly creating the bound columns with styling in XAML as shown below. + +```xaml + + + + + + + + + + + + + + + +``` + +### DataGridComboBoxColumn + +In display mode the combobox column looks like the normal text column. In edit mode the column allows the user to select a value from a provided collection displayed in a **ComboBox** control. + +The **DataGridComboBoxColumn** contains the following specific properties: + +* **ItemsSource** (IEnumerable): This property is bound to a collection of objects representing the elements of the combobox (the source is the same for all cells in the column). The **ItemsSource** elements of the column must have at least one property with the same name as the elements of the **ItemsSource** belonging to the **DataGrid** itself. + +* **Binding** (Binding): This property binds the column to a property in the **DataGrid**'s **ItemsSource**. It also links this property to a property with the same name within the column's **ItemsSource**. + +* **DisplayMemberPath** (string): This property tells the column which property value to show in both display and edit mode. It's value must match the name of a property within the column's **ItemsSource** elements. + +The following code example demonstrates how to specify and configure a **DataGridComboBoxColumn** in XAML. + +```xaml + + + + + + + + +``` + +Code-Behind: + +```csharp +public class Department +{ + public int DepartmentId { get; set; } + public string DepartmentName { get; set; } +} + +public class Person +{ + public int PersonId { get; set; } + public int DepartmentId { get; set; } + public string FirstName { get; set; } + public string LastName { get; set; } + public string Position { get; set; } +} +public sealed partial class MainPage : Page +{ + public List Departments { get; set; } + public List Persons { get; set; } + + public MainPage() + { + this.InitializeComponent(); + + Departments = new List + { + new Department {DepartmentId = 1, DepartmentName = "R&D"}, + new Department {DepartmentId = 2, DepartmentName = "Finance"}, + new Department {DepartmentId = 3, DepartmentName = "IT"} + }; + + Persons = new List + { + new Person + { + PersonId = 1, DepartmentId = 3, FirstName = "Ronald", LastName = "Rumple", + Position = "Network Administrator" + }, + new Person + { + PersonId = 2, DepartmentId = 1, FirstName = "Brett", LastName = "Banner", + Position = "Software Developer" + }, + new Person + { + PersonId = 3, DepartmentId = 2, FirstName = "Alice", LastName = "Anderson", + Position = "Accountant" + } + }; + } +} +``` + +### DataGridTemplateColumn + +The DataGridTemplateColumn type enables you to create your own column types by specifying the cell templates used to display values and enable editing. Set the **CellTemplate** property to specify the contents of cells that display values, but do not allow editing. Set the **CellEditingTemplate** property to specify the contents of cells in editing mode. If you set the column's **IsReadOnly** property to true, the CellEditingTemplate property value is never used. + +The following code example demonstrates how to specify and configure a DataGridTemplateColumn in XAML. + +```xaml + + + + + + + + + + + + + + + + + + + + + + + +``` + +## See Also + +* [Customize the DataGrid control using styling and formatting options](styling-formatting-options.md) +* [Sizing options in the DataGrid control](sizing-options.md) +* [Default keyboard navigation and selection patterns](keyboard-navigation-selection.md) +* [Display and configure Row Details](rowdetails.md) +* [Configure Auto-generated columns in the DataGrid control](customize-autogenerated-columns.md) +* [Group, sort and filter data using LINQ and the DataGrid control](group-sort-filter.md) +* [Editing and input validation in the DataGrid control](editing-inputvalidation.md) +* [DataGrid Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid) diff --git a/docs/archive/windows/datagrid-guidance/editing-inputvalidation.md b/docs/archive/windows/datagrid-guidance/editing-inputvalidation.md new file mode 100644 index 00000000..3b8ff6c2 --- /dev/null +++ b/docs/archive/windows/datagrid-guidance/editing-inputvalidation.md @@ -0,0 +1,80 @@ +--- +title: How to - Implement editing functionality +author: harinikmsft +description: Guidance document that shows how to implement editing and input validation functionality in the DataGrid control +keywords: windows 10, uwp, windows community toolkit, windows toolkit, DataGrid, xaml control, xaml +--- + +# How to: Implement editing and input validation in DataGrid control (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component directly to 8.x, it's important to understand that: +- The WCT 7.x DataGrid is still usable alongside WCT 8.x components for existing projects. +- The DataGrid control has been deprecated in favor of the new DataTable component. + +For new development, we recommend using the DataTable component which offers improved functionality and is actively maintained. If you have specific needs that DataTable doesn't meet, please consider contributing to WCT Labs where component improvements are prototyped and incubated. + +For more information: +- [DataGrid discussion in Labs](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +## Cell and Row editing + +The [DataGrid](../datagrid.md) control supports cell and row editing functionality. By default, you can edit items directly in the DataGrid. The user can enter edit mode in a cell by pressing F2 key or double tapping on a cell. Alternatively, you can set the [DataGridColumn.IsReadOnly](/dotnet/api/microsoft.toolkit.uwp.ui.controls.datagridcolumn.isreadonly) property to true to disable editing in specific columns of the DataGrid. + +```xaml + +``` + +![Sample edit UI](../images/datagrid/editing.png) + +A cell-level edit is committed when you move to another cell in the same row. All edits in a row are committed when you press ENTER or move to another row. + +To guarantee that edits can be committed and canceled correctly, the objects in the DataGrid must implement the [IEditableObject](/dotnet/api/system.componentmodel.ieditableobject) interface. + +### Editing methods and events + +The following table lists the methods and events supported by DataGrid for cell and row editing functionality. + +Type | Name | Description +---|--- | --- +Method | PreparingCellForEdit | Occurs when a cell in a DataGridTemplateColumn enters editing mode. This event does not occur for cells in other column types. +Method | PrepareCellForEdit | Occurs when a cell in a column derived from DataGridColumn enters editing mode. This event does not occur for cells of type DataGridTemplateColumn. +Method | BeginEdit | Causes the data grid to enter editing mode for the current cell and current row, unless the data grid is already in editing mode. +Method | CommitEdit | Causes the data grid to commit the current edit to the data source, and optionally exit editing mode. +Method | CancelEdit | Causes the data grid to cancel the current edit, restore the original value, and exit editing mode. +Event | BeginningEdit | Occurs before a cell or row enters editing mode. This event lets you perform special processing before a cell or row enters editing mode. +Event | CellEditEnding | Occurs when a cell edit is ending. You can cancel this event by setting the Cancel property of the e argument to true in the event handler. If this event is not canceled, the specified **EditAction** will be performed to commit or cancel the edit. After the edit has been successfully committed or canceled, the CellEditEnded event occurs. +Event | CellEditEnded | Occurs when a cell edit has been committed or canceled. +Event | RowEditEnding | Occurs when a row edit is ending. You can cancel this event by setting the Cancel property of the e argument to true in the event handler. If this event is not canceled, the specified **EditAction** will be performed to commit or cancel the edit. After the edit has been successfully committed or canceled, the RowEditEnded event occurs. +Event | RowEditEnded | Occurs when a row edit has been committed or canceled. + +### Enumerations + +* **DataGridEditAction** enumeration : Specifies constants that define what action was taken to end an edit. Supported members are: + * Cancel: Edit was canceled. + * Commit: Edit was committed. +* **DataGridEditingUnit** enumeration : Specifies constants that define whether editing is enabled on a cell level or on a row level. Supported members are: + * Cell: Cell editing is enabled. + * Row: Row editing is enabled. + +## Input Validation + +DataGrid control supports input validation through **INotifyDataErrorInfo** in your DataModel or ViewModel. Implement data validation logic by implementing **DataErrorsChangedEventArgs**, **HasErrors** and **GetErrors** methods. The DataGrid control automatically shows the error UI in the editing cell/row when the error conditions are met. + +![Sample UI with INotifyDataErrorInfo](../images/datagrid/validation.png) + +See [DataGrid Sample](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid) for an example of how to handle input validation in the DataGrid control. + +## See Also + +* [Add a DataGrid control to a page](datagrid-basics.md) +* [Customize the DataGrid control through UI formatting options](styling-formatting-options.md) +* [Keyboard navigation and selection](keyboard-navigation-selection.md) +* [DataGrid Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid) diff --git a/docs/archive/windows/datagrid-guidance/group-sort-filter.md b/docs/archive/windows/datagrid-guidance/group-sort-filter.md new file mode 100644 index 00000000..e8ba3692 --- /dev/null +++ b/docs/archive/windows/datagrid-guidance/group-sort-filter.md @@ -0,0 +1,254 @@ +--- +title: How to - Group, Sort and Filter data in the DataGrid Control +author: harinikmsft +description: Guidance document that shows how to group, sort and filter data in the DataGrid control +keywords: windows 10, uwp, windows community toolkit, windows toolkit, DataGrid, xaml control, xaml, group, sort, filter +--- + +# How to: Group, sort and filter data in the DataGrid Control (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component directly to 8.x, it's important to understand that: +- The WCT 7.x DataGrid is still usable alongside WCT 8.x components for existing projects. +- The DataGrid control has been deprecated in favor of the new DataTable component. + +For new development, we recommend using the DataTable component which offers improved functionality and is actively maintained. If you have specific needs that DataTable doesn't meet, please consider contributing to WCT Labs where component improvements are prototyped and incubated. + +For more information: +- [DataGrid discussion in Labs](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +It is often useful to view data in a DataGrid in different ways by grouping, sorting, and filtering the data. To group, sort, and filter the data in a DataGrid, you bind it to a [CollectionViewSource](/uwp/api/windows.ui.xaml.data.collectionviewsource). You can then manipulate the data in the backing data source using LINQ queries without affecting the underlying data. The changes in the collection view are reflected in the DataGrid user interface (UI). + +The following walk-throughs demonstrate how to implement grouping, sorting and filtering for the DataGrid control through examples. + +See [DataGrid Sample](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid) for the complete sample code and running app. + +## 1. Grouping + +The DataGrid control has built-in row group header visuals for one-level grouping. You can set the DataGrid.ItemsSource to a grouped collection through [CollectionViewSource](/uwp/api/windows.ui.xaml.data.collectionviewsource) with **IsSourceGrouped** property set to True and the DataGrid will automatically show the contents grouped under row group headers based on the data source. + +The following walk-through shows how to implement and customize grouping in the DataGrid control. + +1. Add the DataGrid control to your XAML page + + ```xaml + + + + ``` + +2. Create the grouped collection using LINQ + + ```csharp + // Create grouping for collection + ObservableCollection> mountains = new ObservableCollection>(); + + //Implement grouping through LINQ queries + var query = from item in _items + group item by item.Range into g + select new { GroupName = g.Key, Items = g }; + + //Populate Mountains grouped collection with results of the query + foreach (var g in query) + { + GroupInfoCollection info = new GroupInfoCollection(); + info.Key = g.GroupName; + foreach (var item in g.Items) + { + info.Add(item); + } + mountains.Add(info); + } + ``` + +3. Populate a CollectionViewSource instance with the grouped collection and set IsSourceGrouped property to True. + + ```csharp + //Create the CollectionViewSource and set to grouped collection + CollectionViewSource groupedItems = new CollectionViewSource(); + groupedItems.IsSourceGrouped = true; + groupedItems.Source = mountains; + ``` + +4. Set the ItemsSource of the DataGrid control + + ```csharp + //Set the datagrid's ItemsSource to grouped collection view source + dg.ItemsSource = groupedItems.View; + ``` + +5. Customize the Group header values through **RowGroupHeaderStyles**, **RowGroupHeaderPropertyNameAlternative** properties and by handling the **LoadingRowGroup** event to alter the auto-generated values in code. + + ```xaml + + + + + + + ``` + + ```csharp + //Handle the LoadingRowGroup event to alter the grouped header property value to be displayed + private void dg_loadingRowGroup(object sender, DataGridRowGroupHeaderEventArgs e) + { + ICollectionViewGroup group = e.RowGroupHeader.CollectionViewGroup; + Mountain item = group.GroupItems[0] as Mountain; + e.RowGroupHeader.PropertyValue = item.Range; + } + ``` + +![Group](../images/datagrid/grouping.png) + +## 2. Sorting + +Users can sort columns in the DataGrid control by tapping on the desired column headers. To implement sorting, the DataGrid control exposes the following mechanisms: + +* You can indicate columns are sortable in 2 ways. **CanUserSortColumns** property on DataGrid can be set to True to indicate all columns in the DataGrid control are sortable by the end user. Alternatively, you can also set **CanUserSort** property on individual DataGridColumns to control which columns are sortable by the end user. The default values for both properties is *True*. If both properties are set, any value of False will take precedence over a value of True. +* You can indicate the sort direction of a column by setting **DataGridColumn.SortDirection?** property. The **DataGridSortDirection** enumeration allows the values of *Ascending* and *Descending*. The default value for SortDirection property is *null* (unsorted). +* If DataGridColumn.SortDirection property is set to *Ascending*, an ascending sort icon (upward facing arrow) will be shown to the right of the column header indicating that the specific column has been sorted in the ascending order. The reverse is true for *Descending*. When the value is *null*, no icon will be shown. +*Note: the DataGrid control does not automatically perform a sort when this property is set. The property is merely a tool for showing the correct built-in icon visual.* +* If *DataGrid.CanUserSortColumns* and *DataGridColumn.CanUserSort* properties are both true, **DataGrid.Sorting** event will be fired when the end user taps on the column header. Sorting functionality can be implemented by handling this event. +* You can use the **DataGridColumn.Tag** property to keep track of the bound column header during sort. + +The following walk-through shows how to implement sorting in the DataGrid control. + +1. Add the DataGrid control to your XAML page. Set the appropriate sort properties and add a handler for Sorting event. + + ```xaml + + + + + + + ``` + +2. Handle the Sorting event to implement logic for sorting + + ```csharp + private void dg_Sorting(object sender, DataGridColumnEventArgs e) + { + //Use the Tag property to pass the bound column name for the sorting implementation + if (e.Column.Tag.ToString() == "Range") + { + //Use the Tag property to pass the bound column name for the sorting implementation + if (e.Column.Tag.ToString() == "Range") + { + //Implement sort on the column "Range" using LINQ + if (e.Column.SortDirection == null || e.Column.SortDirection == DataGridSortDirection.Descending) + { + dg.ItemsSource = new ObservableCollection(from item in _items + orderby item.Range ascending + select item); + e.Column.SortDirection = DataGridSortDirection.Ascending; + } + else + { + dg.ItemsSource = new ObservableCollection(from item in _items + orderby item.Range descending + select item); + e.Column.SortDirection = DataGridSortDirection.Descending; + } + } + // add code to handle sorting by other columns as required + + // Remove sorting indicators from other columns + foreach (var dgColumn in dg.Columns) + { + if (dgColumn.Tag.ToString() != e.Column.Tag.ToString()) + { + dgColumn.SortDirection = null; + } + } + } + } + ``` + +3. Set the SortDirection property to the appropriate value for showing the built-in ascending sort icon in column header + + ```csharp + //Show the ascending icon when acending sort is done + e.Column.SortDirection = DataGridSortDirection.Ascending; + + //Show the descending icon when descending sort is done + e.Column.SortDirection = DataGridSortDirection.Descending; + + //Clear the SortDirection in a previously sorted column when a different column is sorted + previousSortedColumn.SortDirection = null; + ``` + +![Sort](../images/datagrid/sorting.png) + +## 3. Filtering + +The DataGrid control does not support any built-in filtering capabilities. The following walk-through shows how you can implement your own filtering visuals and apply it to the DataGrid's content. + +1. Add the DataGrid control to your XAML page. + + ```xaml + + ``` + +2. Add buttons for filtering the DataGrid's content. It is recommended to use the **CommandBar** control with **AppBarButtons** to add filtering visuals at the top of your page. The following example shows a CommandBar with the title for the table and one filter button. + + ```xaml + + + + ``` + +3. Handle the AppBarButton's Click event to implement the filtering logic. + + ```csharp + private void rankLowFilter_Click(object sender, RoutedEventArgs e) + { + dg.ItemsSource = new ObservableCollection(from item in _items + where item.Rank < 50 + select item); + } + ``` + +## Example app + +For the complete example of all the capabilities in this section in a running application, see [DataGrid Sample](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid). + +## See Also + +* [Add a DataGrid control to a page](datagrid-basics.md) +* [Configure Auto-generated columns in the DataGrid control](customize-autogenerated-columns.md) +* [Editing and input validation in the DataGrid control](editing-inputvalidation.md) diff --git a/docs/archive/windows/datagrid-guidance/keyboard-navigation-selection.md b/docs/archive/windows/datagrid-guidance/keyboard-navigation-selection.md new file mode 100644 index 00000000..1820fb09 --- /dev/null +++ b/docs/archive/windows/datagrid-guidance/keyboard-navigation-selection.md @@ -0,0 +1,121 @@ +--- +title: Keyboard navigation and selection concepts in the DataGrid control +author: harinikmsft +description: Guidance document that shows how to use keyboard to navigate the DataGrid control and selection models +keywords: windows 10, uwp, windows community toolkit, windows toolkit, DataGrid, xaml control, xaml, keyboard +--- + +# DataGrid keyboard navigation and selection modes (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component directly to 8.x, it's important to understand that: +- The WCT 7.x DataGrid is still usable alongside WCT 8.x components for existing projects. +- The DataGrid control has been deprecated in favor of the new DataTable component. + +For new development, we recommend using the DataTable component which offers improved functionality and is actively maintained. If you have specific needs that DataTable doesn't meet, please consider contributing to WCT Labs where component improvements are prototyped and incubated. + +For more information: +- [DataGrid discussion in Labs](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +## Keyboard behaviors + +### Keyboarding in Column headers + +The user can use TAB key to set keyboard focus to the current column headers. If the user can sort the columns, pressing ENTER key on the column header sorts that column. LEFT/RIGHT arrow keys move focus to column headers to the left and right of the currently focused column header. DOWN arrow key from a column header moves focus to the cell in the first row directly below the column header. + +### Keyboarding in cells + +The following table lists the default keyboard behavior within the cells of the DataGrid control. + +Key or key combination | Description +---|--- +DOWN ARROW | Moves the focus to the cell directly below the current cell. If the focus is in the last row, pressing the DOWN ARROW does nothing. +UP ARROW | Moves the focus to the cell directly above the current cell. If the focus is in the first row, pressing the UP ARROW does nothing. +LEFT ARROW | Moves the focus to the previous cell in the row. If the focus is in the first cell in the row, pressing the LEFT ARROW does nothing. If the focus is on a row group header, pressing the LEFT ARROW collapses the group. +RIGHT ARROW | Moves the focus to the next cell in the row. If the focus is in the last cell in the row, pressing the RIGHT ARROW does nothing. If the focus is on a row group header, pressing the RIGHT ARROW expands the group. +HOME | Moves the focus to the first cell in the current row. +END | Moves the focus to the last cell in the current row. +PAGE DOWN | Scrolls the control downward by the number of rows that are displayed. Moves the focus to the last displayed row without changing columns. If the last row is only partially displayed, scrolls the grid to fully display the last row. +PAGE UP | Scrolls the control upward by the number of rows that are displayed. Moves focus to the first displayed row without changing columns. If the first row is only partially displayed, scrolls the grid to fully display the first row. +TAB | If the current cell is in edit mode, moves the focus to the next cell in the current row. If the focus is already in the last cell of the row, commits any changes that were made and moves the focus to the first cell in the next row. If the focus is in the last cell in the control, moves the focus to the next control in the tab order of the parent container. If the current cell is not in edit mode, moves the focus to the next control in the tab order of the parent container. +SHIFT+TAB | If the current cell is in edit mode, moves the focus to the previous cell in the current row. If the focus is already in the first cell of the row, commits any changes that were made and moves the focus to the last cell in the previous row. If the focus is in the first cell in the control, moves the focus to the previous control in the tab order of the parent container. If the current cell is not in edit mode, moves the focus to the previous control in the tab order of the parent container. +CTRL+DOWN ARROW | Moves the focus to the last cell in the current column. +CTRL+UP ARROW | Moves the focus to the first cell in the current column. +CTRL+RIGHT ARROW | Moves the focus to the last cell in the current row. +CTRL+LEFT ARROW | Moves the focus to the first cell in the current row. +CTRL+HOME | Moves the focus to the first cell in the control. +CTRL+END | Moves the focus to the last cell in the control. +CTRL+PAGE DOWN | Same as PAGE DOWN. +CTRL+PAGE UP | Same as PAGE UP. +F2 | If the DataGrid.IsReadOnly property is false and the DataGridColumn.IsReadOnly property is false for the current column, puts the current cell into cell edit mode. +ENTER | Commits any changes to the current cell and row and moves the focus to the cell directly below the current cell. If the focus is in the last row, commits any changes without moving the focus. +ESC | If the control is in edit mode, cancels the edit and reverts any changes that were made in the control. If the underlying data source implements IEditableObject, pressing ESC a second time cancels edit mode for the entire row. +BACKSPACE | Deletes the character before the cursor when editing a cell. +DELETE | Deletes the character after the cursor when editing a cell. +CTRL+ENTER | Commits any changes to the current cell without moving the focus. + +## Selection behaviors + +The DataGrid control supports single row selection as well as multiple rows selection through the **DataGrid.SelectionMode** property. The **DataGridSelectionMode** enumeration has the following member values: + +* **Extended** : The user can select multiple items while holding down the SHIFT or CTRL keys during selection. +* **Single** : The user can select only one item at a time. + +```xaml + +``` + +![Sample for SelectionMode](../images/datagrid/selection.png) + +If the **SelectionMode** property is set to **Extended**, the navigation behavior does not change, but navigating with the keyboard while pressing SHIFT (including CTRL+SHIFT) will modify a multi-row selection. Before navigation starts, the control marks the current row as an anchor row. When you navigate while pressing SHIFT, the selection includes all rows between the anchor row and the current row. + +The following selection keys modify multi-row selection. + +* SHIFT+DOWN ARROW +* SHIFT+UP ARROW +* SHIFT+LEFT ARROW +* SHIFT+RIGHT ARROW +* SHIFT+HOME +* SHIFT+END +* SHIFT+PAGE DOWN +* SHIFT+PAGE UP +* CTRL+SHIFT+DOWN ARROW +* CTRL+SHIFT+UP ARROW +* CTRL+SHIFT+LEFT ARROW +* CTRL+SHIFT+RIGHT ARROW +* CTRL+SHIFT+HOME +* CTRL+SHIFT+END +* CTRL+SHIFT+PAGE DOWN +* CTRL+SHIFT+PAGE UP + +## Pointer behaviors + +The following table lists the default behaviors for pointer (mouse/touch/pen) actions. + +Pointer action | Description +---|--- +Tap an unselected cell | Makes the tapped cell's row the currently selected row with focus on the tapped cell. +Double-tap a cell | Puts the cell into edit mode. +Drag a column header cell | If the DataGrid.CanUserReorderColumns property is true and the DataGridColumn.CanUserReorder property is true for the current column, moves the column so that it can be dropped into a new position. +Drag a column header separator | If the DataGrid.CanUserResizeColumns property is true and the DataGridColumn.CanUserResize property is true for the current column, resizes the column. +Tap a column header | If the DataGrid.CanUserSortColumns property is true and the DataGridColumn.CanUserSort property is true for the current column, sorts the column. Tapping the header of a column that is already sorted will reverse the sort direction of that column. +CTRL+tap a row | If SelectionMode is set to Extended, modifies a non-contiguous multi-row selection. If the row is already selected, deselects the row. +SHIFT+tap a row | If SelectionMode is set to Extended, modifies a contiguous multi-row selection. +Tap a row group header expander button | Expands or collapses the group. +Double-tap a row group header | Expands or collapses the group. + +## See Also + +* [Add a DataGrid control to a page](datagrid-basics.md) +* [Customize the DataGrid control using styling and formatting options](styling-formatting-options.md) +* [Sizing options in the DataGrid control](sizing-options.md) +* [Group, sort and filter data using LINQ and the DataGrid control](group-sort-filter.md) +* [Editing and input validation in the DataGrid control](editing-inputvalidation.md) +* [DataGrid Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid) diff --git a/docs/archive/windows/datagrid-guidance/rowdetails.md b/docs/archive/windows/datagrid-guidance/rowdetails.md new file mode 100644 index 00000000..c003f4db --- /dev/null +++ b/docs/archive/windows/datagrid-guidance/rowdetails.md @@ -0,0 +1,116 @@ +--- +title: Display and Configure Row Details in DataGrid +author: harinikmsft +description: Guidance document that shows how to customize row details section in the DataGrid control +keywords: windows 10, uwp, windows community toolkit, windows toolkit, DataGrid, xaml control, xaml, RowDetails +--- + +# How to: Display and Configure Row Details in the DataGrid Control (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component directly to 8.x, it's important to understand that: +- The WCT 7.x DataGrid is still usable alongside WCT 8.x components for existing projects. +- The DataGrid control has been deprecated in favor of the new DataTable component. + +For new development, we recommend using the DataTable component which offers improved functionality and is actively maintained. If you have specific needs that DataTable doesn't meet, please consider contributing to WCT Labs where component improvements are prototyped and incubated. + +For more information: +- [DataGrid discussion in Labs](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +Each row in the [DataGrid](../datagrid.md) control can be expanded to display a row details section. The row details section is defined by a [DataTemplate](/uwp/api/windows.ui.xaml.datatemplate) that specifies the appearance of the section and the data to be displayed. + +![Sample row details UI](../images/datagrid/rowdetails.png) + +The row details section can be displayed for selected rows, displayed for all rows, or it can be collapsed. The row details section can also be frozen so that it does not scroll horizontally when the DataGrid is scrolled. + +## To display a row details section using inline XAML + +1. Create a [DataTemplate](/uwp/api/windows.ui.xaml.datatemplate) that defines the appearance of the row details section. +2. Place the DataTemplate inside the tags. + +```xaml + + + + + + + + + + + + + +``` + +## To display a row details section using a DataTemplate resource + +1. Create a [DataTemplate](/uwp/api/windows.ui.xaml.datatemplate) that defines the appearance of the row details section. +2. Identify the DataTemplate by assigning a value to the [x:Key Attribute](/windows/uwp/xaml-platform/x-key-attribute). +3. Bind the DataTemplate to the DataGrid's **RowDetailsTemplate** property. + +```xaml + + + + + + + + + + +``` + +## To change the visibility of a row details section + +Set the **RowDetailsVisibilityMode** property to a value of the **DataGridRowDetailsVisibilityMode** enumeration: + +* *Collapsed* : The row details section is not displayed for any rows. +* *Visible* : The row details section is displayed for all rows. +* *VisibleWhenSelected* : The row details section is displayed only for selected rows. + +The following example shows how to use the RowDetailsVisibilityMode property to change the row details display mode programmatically from the selection of a value in a ComboBox: + +```csharp +// Set the row details visibility to the option selected in the combo box. +private void cbRowDetailsVis_SelectionChanged(object sender, RoutedEventArgs e) +{ + ComboBox cb = sender as ComboBox; + ComboBoxItem cbi = cb.SelectedItem as ComboBoxItem; + if (this.dataGrid1 != null) + { + if (cbi.Content.ToString() == "Selected Row (Default)") + dataGrid1.RowDetailsVisibilityMode = DataGridRowDetailsVisibilityMode.VisibleWhenSelected; + else if (cbi.Content.ToString() == "None") + dataGrid1.RowDetailsVisibilityMode = DataGridRowDetailsVisibilityMode.Collapsed; + else if (cbi.Content.ToString() == "All") + dataGrid1.RowDetailsVisibilityMode = DataGridRowDetailsVisibilityMode.Visible; + } +} +``` + +## To prevent a row details section from scrolling horizontally + +Set the **AreRowDetailsFrozen** property to true. + +```xaml + +``` + +## See Also + +* [Add a DataGrid control to a page](datagrid-basics.md) +* [Customize the DataGrid control using styling and formatting options](styling-formatting-options.md) +* [Sizing options in the DataGrid control](sizing-options.md) +* [DataGrid Sample](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid). diff --git a/docs/archive/windows/datagrid-guidance/sizing-options.md b/docs/archive/windows/datagrid-guidance/sizing-options.md new file mode 100644 index 00000000..fe59ec56 --- /dev/null +++ b/docs/archive/windows/datagrid-guidance/sizing-options.md @@ -0,0 +1,108 @@ +--- +title: Sizing options in the DataGrid control +author: harinikmsft +description: Guidance document that shows how to size the rows, columns and headers of the DataGrid control +keywords: windows 10, uwp, windows community toolkit, windows toolkit, DataGrid, xaml control, xaml +--- + +# Sizing Options in the DataGrid Control (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component directly to 8.x, it's important to understand that: +- The WCT 7.x DataGrid is still usable alongside WCT 8.x components for existing projects. +- The DataGrid control has been deprecated in favor of the new DataTable component. + +For new development, we recommend using the DataTable component which offers improved functionality and is actively maintained. If you have specific needs that DataTable doesn't meet, please consider contributing to WCT Labs where component improvements are prototyped and incubated. + +For more information: +- [DataGrid discussion in Labs](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +Various options are available to control how the [DataGrid](../datagrid.md) sizes itself. The DataGrid, and individual rows and columns in the DataGrid, can be set to size automatically to their contents or can be set to specific values. By default, the DataGrid will grow and shrink to fit the size of its contents. + +## Sizing the DataGrid + +### Cautions When Using Automatic Sizing + +By default, the **Height** and **Width** properties of the [DataGrid](../datagrid.md) are set to *Double.NaN* ("Auto" in XAML), and the DataGrid will adjust to the size of its contents. + +When placed inside a container that does not restrict the size of its children, such as a [StackPanel](/uwp/api/windows.ui.xaml.controls.stackpanel), the DataGrid, like [ListView](/uwp/api/windows.ui.xaml.controls.listview) and other scrollable controls, will stretch beyond the visible bounds of the container and scrollbars will not be shown. This condition has both usability and performance implications. + +When bound to a data set, if the Height of the DataGrid is not restricted, it will continue to add a row for each data item in the bound data set. This can cause the DataGrid to grow outside the visible bounds of your application as rows are added. The DataGrid will not show scrollbars in this case because its Height will continue to grow to accommodate the new rows. + +An object is created for each row in the DataGrid. If you are working with a large data set and you allow the DataGrid to automatically size itself, the creation of a large number of objects may affect the performance of your application. + +To avoid these issues when you work with large data sets, it is recommended that you specifically set the Height of the DataGrid or place it in a container that will restrict its Height, such as a [Grid](/uwp/api/windows.ui.xaml.controls.grid) or [RelativePanel](/uwp/api/windows.ui.xaml.controls.relativepanel). When the Height is restricted, the DataGrid will only create the rows that will fit within its specified Height, and will recycle those rows as needed to display new data. + +### Setting the DataGrid Size + +The DataGrid can be set to automatically size within specified boundaries, or the DataGrid can be set to a specific size. The following table shows the properties that can be set to control the DataGrid size. + +| Property | Description | +|---|---| +| Height | Sets a specific height for the DataGrid. | +| MaxHeight | Sets the upper bound for the height of the DataGrid. The DataGrid will grow vertically until it reaches this height. | +| MinHeight | Sets the lower bound for the height of the DataGrid. The DataGrid will shrink vertically until it reaches this height. | +| Width | Sets a specific width for the DataGrid. | +| MaxWidth | Sets the upper bound for the width of the DataGrid. The DataGrid will grow horizontally until it reaches this width.| +| MinWidth | Sets the lower bound for the width of the DataGrid. The DataGrid will shrink horizontally until it reaches this width. | + +## Sizing Rows and Row Headers + +### DataGrid Rows + +By default, a DataGrid row's Height property is set to Double.NaN ("Auto" in XAML), and the row height will expand to the size of its contents. The height of all rows in the DataGrid can be specified by setting the **DataGrid.RowHeight** property. Users cannot change the row height by dragging the row header dividers. + +### DataGrid Row Headers + +By default, DataGrid row headers are not displayed. To display row headers, the **HeadersVisibility** property must be set to *DataGridHeadersVisibility.Row* or *DataGridHeadersVisibility.All* and the DataGrid's ControlTemplate should be altered to provide a visual for the RowHeader as desired. By default, when row headers are displayed, they automatically size to fit their content. The row headers can be given a specific width by setting the **DataGrid.RowHeaderWidth** property. + +## Sizing Columns and Column Headers + +### DataGrid Columns + +The DataGrid uses values of the **DataGridLength** and the **DataGridLengthUnitType** structure to specify absolute or automatic sizing modes. +The following table shows the values provided by the DataGridLengthUnitType structure. + +| Name | Description | +|---|---| +| Auto | The default automatic sizing mode sizes DataGrid columns based on the contents of both cells and column headers. | +| SizeToCells | The cell-based automatic sizing mode sizes DataGrid columns based on the contents of cells in the column, not including column headers.| +| SizeToHeader | The header-based automatic sizing mode sizes DataGrid columns based on the contents of column headers only.| +| Pixel | The pixel-based sizing mode sizes DataGrid columns based on the numeric value provided.| +| Star | The star sizing mode is used to distribute available space by weighted proportions. In XAML, star values are expressed as n\* where n represents a numeric value. 1\* is equivalent to \*. For example, if two columns in a DataGrid had widths of \* and 2\*, the first column would receive one portion of the available space and the second column would receive two portions of the available space. + +The **DataGridLengthConverter** class can be used to convert data between numeric or string values and DataGridLength values. + +By default, the **DataGrid.ColumnWidth** property is set to Auto, and the **DataGridColumn.Width** property is null. When the sizing mode is set to Auto or SizeToCells, columns will grow to the width of their widest visible content. When scrolling, these sizing modes will cause columns to expand if content that is larger than the current column size is scrolled into view. The column will not shrink after the content is scrolled out of view. + +Columns in the DataGrid can also be set to automatically size only within specified boundaries, or columns can be set to a specific size. The following table shows the properties that can be set to control column sizes. + +| Property | Description | +|---|---| +| DataGrid.MaxColumnWidth | Sets the upper bound for all columns in the DataGrid.| +| DataGridColumn.MaxWidth | Sets the upper bound for an individual column. Overrides DataGrid.MaxColumnWidth.| +| DataGrid.MinColumnWidth | Sets the lower bound for all columns in the DataGrid.| +| DataGridColumn.MinWidth | Sets the lower bound for an individual column. Overrides DataGrid.MinColumnWidth.| +| DataGrid.ColumnWidth | Sets a specific width for all columns in the DataGrid.| +| DataGridColumn.Width | Sets a specific width for an individual column. Overrides DataGrid.ColumnWidth.| + +### DataGrid Column Headers + +By default, DataGrid column headers are displayed. To hide column headers, the **HeadersVisibility** property must be set to *DataGridHeadersVisibility.Row* or *DataGridHeadersVisibility.None*. By default, when column headers are displayed, they automatically size to fit their content. The column headers can be given a specific height by setting the **DataGrid.ColumnHeaderHeight** property. + +### Resizing columns by the end user + +Users can resize DataGrid columns by dragging the column header dividers with mouse/touch/pen. The DataGrid does not support automatic resizing of columns by double-clicking the column header divider. To prevent a user from resizing particular columns, set the **DataGridColumn.CanUserResize** property to false for the individual columns. To prevent users from resizing all columns, set the **DataGrid.CanUserResizeColumns** property to false. + +## See Also + +* [Add a DataGrid control to a page](datagrid-basics.md) +* [Customize the DataGrid control using styling and formatting options](styling-formatting-options.md) +* [DataGrid Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid) diff --git a/docs/archive/windows/datagrid-guidance/styling-formatting-options.md b/docs/archive/windows/datagrid-guidance/styling-formatting-options.md new file mode 100644 index 00000000..c3d7d346 --- /dev/null +++ b/docs/archive/windows/datagrid-guidance/styling-formatting-options.md @@ -0,0 +1,164 @@ +--- +title: Customize the DataGrid control +author: harinikmsft +description: Guidance document that shows how to use the different formatting options to customize the look and feel of the DataGrid control +keywords: windows 10, uwp, windows community toolkit, windows toolkit, DataGrid, xaml control, xaml +--- + +# How to - Customize the DataGrid control through UI formatting options (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component directly to 8.x, it's important to understand that: +- The WCT 7.x DataGrid is still usable alongside WCT 8.x components for existing projects. +- The DataGrid control has been deprecated in favor of the new DataTable component. + +For new development, we recommend using the DataTable component which offers improved functionality and is actively maintained. If you have specific needs that DataTable doesn't meet, please consider contributing to WCT Labs where component improvements are prototyped and incubated. + +For more information: +- [DataGrid discussion in Labs](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [DataGrid](../datagrid.md) control supports various styling and formatting options both through XAML at design time as well as procedurally in code. Some of the common ways to customize the look and feel of the DataGrid control include the following: + +## 1. GridLines + +You can control the visibility of the grid lines separating inner cells using the **DataGrid.GridLinesVisibility** property. The **DataGridGridLinesVisibility** enumeration has the following member values: + +* *None*: No grid lines are shown +* *Horizontal*: Only horizontal grid lines, which separate rows, are shown. +* *Vertical*: Only vertical grid lines, which separate columns, are shown. +* *All*: Both horizontal and vertical grid lines are shown. + +You can also change the color of the gridlines using **HorizontalGridLinesBrush** and/or **VerticalGridLinesBrush** properties. + +```xaml + +``` + +![Sample grid lines UI](../images/datagrid/gridlines.png) + +## 2. Alternating rows + +You can set the **RowBackground**, **RowForeground**, **AlternatingRowBackground** and **AlternatingRowForeground** properties to desired brushes and create customized alternating rows for your DataGrid control. + +The RowBackground and RowForeground properties are used to paint the background and foreground of all rows in the DataGrid control. If AlternatingRowBackground and/or AlternatingRowForeground properties are not null, their values override the RowBackground and RowForeground values for odd-numbered rows. + +```xaml + +``` + +![AlternatingRowBackground](../images/datagrid/alternaterowbackground.png) + +## 3. Headers visibility + +You can toggle the visibility of row and column headers using the **DataGrid.HeadersVisibility** property. The **DataGridHeadersVisibility** enumeration has the following member values: + +* *All*: Both column and row header cells are displayed. +* *Column*: Only column header cells are displayed. +* *Row*: Only row header cells are displayed. +* *None*: No header cells are displayed. + +Note: By default, DataGrid row headers are not displayed. To display row headers, the **HeadersVisibility** property must be set to *DataGridHeadersVisibility.Row* or *DataGridHeadersVisibility.All* and the DataGrid's ControlTemplate should be altered to provide a visual for the RowHeader as desired. + +```xaml + +``` + +![Headers](../images/datagrid/gridlines.png) + +## 4. Customizable templates and styling for cells, rows and headers + +All individual parts of the DataGrid control are customizable through simple Style properties such as: + +* *CellStyle* : style that is used when rendering the data grid cells. +* *RowStyle* : style that is used when rendering the rows. +* *ColumnHeaderStyle* : style that is used when rendering the column headers. +* *RowGroupHeaderStyles* : style that is used when rendering the row group header. The DataGrid control currently supports one-level grouping only - the first style specified as part of RowGroupHeaderStyles will be applied to the row group header. +* *RowHeaderStyle* : style that is used when rendering the row headers. The DataGrid control does not have a default visual for the row header. To provide one you must provide a `ContentTemplate` for `Microsoft.Toolkit.Uwp.UI.Controls.Primitives.DataGridRowHeader`. For Example: + +```xaml +xmlns:wctprimitives="using:Microsoft.Toolkit.Uwp.UI.Controls.Primitives" + +// This will display the column headers as one cell with the heading text + + + +``` + +OR + +```xaml +// This will display the individual column headers if defined + + + +``` + +Whether defined as an inline style or as a resource, the Style defines the appearance of cells/rows/columns/headers in the data grid, and should specify the appropriate TargetType (say, **DataGridCell** for CellStyle). You typically specify setters for individual properties, and might also use a setter for the Template property if you wanted to change the composition of elements. + +You can also use properties such as **RowHeight**, **RowHeaderWidth**, **ColumnWidth**, **ColumnHeaderHeight** etc., to customize the sizing of the various parts of the DataGrid control. + +```xaml + + + +``` + +## 5. Frozen columns + +Frozen columns are columns that are always displayed and cannot be scrolled out of visibility. Frozen columns are always the leftmost columns in display order. You cannot drag frozen columns into the group of unfrozen columns or drag unfrozen columns into the group of frozen columns. Set the **DataGrid.FrozenColumnCount** property to the desired number of columns that the user should not scroll horizontally. + +```xaml + +``` + +![Frozen columns UI](../images/datagrid/frozencolumns.png) + +## 6. Reorder and resize columns + +You can allow users to: + +* Adjust all column widths using mouse/touch/pen through the **DataGrid.CanUserResizeColumns** property. +* Change the column display order by dragging the column headers using mouse/touch/pen through the **DataGrid.CanUserReorderColumns** property. +* Set this behavior for individual columns by setting the **DataGridColumn.CanUserReorder/CanUserResize** properties. If the individual column properties and the global DataGrid.** properties are both set, a value of false will take precedence over a value of true. + +```xaml + +``` + +![Sample resize columns UI](../images/datagrid/resizecolumns.png) + +## See Also + +* [Add a DataGrid control to a page](datagrid-basics.md) +* [Sizing options in the DataGrid control](sizing-options.md) +* [Default keyboard navigation and selection patterns](keyboard-navigation-selection.md) +* [Display and configure Row Details](rowdetails.md) +* [Configure Auto-generated columns in the DataGrid control](customize-autogenerated-columns.md) +* [Group, sort and filter data using LINQ and the DataGrid control](group-sort-filter.md) +* [Editing and input validation in the DataGrid control](editing-inputvalidation.md) +* [DataGrid Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid) diff --git a/docs/archive/windows/datagrid.md b/docs/archive/windows/datagrid.md new file mode 100644 index 00000000..c8dcc44c --- /dev/null +++ b/docs/archive/windows/datagrid.md @@ -0,0 +1,75 @@ +--- +title: DataGrid +author: harinikmsft +description: The DataGrid Control presents data in a customizable table of rows and columns. +keywords: windows 10, uwp, uwp community toolkit, uwp toolkit, DataGrid, xaml control, xaml +--- + +# DataGrid (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component directly to 8.x, it's important to understand that: +- The WCT 7.x DataGrid is still usable alongside WCT 8.x components for existing projects. +- The DataGrid control has been deprecated in favor of the new DataTable component. + +For new development, we recommend using the DataTable component which offers improved functionality and is actively maintained. + +If you have specific needs that DataTable doesn't meet, please consider contributing to WCT Labs where component improvements are prototyped and incubated. + +For more information: +- [DataTable discussion in Labs](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The DataGrid control provides a flexible way to display a collection of data in rows and columns. + +![DataGrid control](images/datagrid.gif) + +> [!NOTE] +> The DataGrid control is not part of the WinUI 3 controls available in the Windows Community Toolkit version 8.0 and later yet. The control is available for UWP and Uno Platform apps in Windows Community Toolkit version 7.1.0. + +The built-in column types include a text column, a check box column, a combobox column and a template column for hosting custom content. The built-in row type includes a drop-down details section that you can use to display additional content below the cell values. + +The DataGrid control supports common table formatting options, such as alternating row backgrounds and foregrounds and the ability to show or hide headers, grid lines, and scroll bars. Additionally, the control provides several style and template properties that you can use to completely change the appearance of the control and its rows, columns, cells, and row or column headers. + +The DataGrid has built-in support for Narrator and Touch Narrator to help blind users to navigate and interact easily with the control. Additionally, the control has built-in support for extensive keyboard navigation through cells, headers, rows and columns. + +## How-Tos + +The following guidance sections describe the additional concepts and techniques that you can use to build DataGrid control features into your applications: + +* [Add a DataGrid control to a page](datagrid-guidance/datagrid-basics.md) +* [Customize the DataGrid control using styling and formatting options](datagrid-guidance/styling-formatting-options.md) +* [Sizing options in the DataGrid control](datagrid-guidance/sizing-options.md) +* [Default keyboard navigation and selection patterns](datagrid-guidance/keyboard-navigation-selection.md) +* [Display and configure Row Details](datagrid-guidance/rowdetails.md) +* [Configure Auto-generated columns in the DataGrid control](datagrid-guidance/customize-autogenerated-columns.md) +* [Group, sort and filter data using LINQ and the DataGrid control](datagrid-guidance/group-sort-filter.md) +* [Editing and input validation in the DataGrid control](datagrid-guidance/editing-inputvalidation.md) + +## Sample Project + +Here's the [DataGrid sample source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/DataGrid). + +If you have the **WinUI 2 Gallery** app installed, you can use the app to see the DataGrid in action. + +* [Get the WinUI 2 Gallery app (Microsoft Store)](https://apps.microsoft.com/detail/9msvh128x2zt) + +See the other controls available in the **[Windows Community Toolkit Gallery app](https://apps.microsoft.com/detail/9nblggh4tlcq)** or try them with the gallery app [in your browser](https://toolkitlabs.dev/). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls.DataGrid](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls.DataGrid/) | + +## API + +* [DataGrid source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.DataGrid/DataGrid) +* [Silverlight DataGrid API](/previous-versions/windows/silverlight/dotnet-windows-silverlight/cc189753(v=vs.95)) diff --git a/docs/archive/windows/deeplinkparsers.md b/docs/archive/windows/deeplinkparsers.md new file mode 100644 index 00000000..bce4965a --- /dev/null +++ b/docs/archive/windows/deeplinkparsers.md @@ -0,0 +1,163 @@ +--- +title: DeepLinkParser +author: nmetulev +description: Provides a way to create, Dictionary - inheriting object that provides an additional .Root property to pull the base path of the URI +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, DeepLinkParser +dev_langs: + - csharp + - vb +--- + +# DeepLinkParser (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [DeepLinkParser Class](/dotnet/api/microsoft.toolkit.uwp.helpers.deeplinkparser) provides a way to create, from `IActivatedEventArgs` a `Dictionary`-inheriting object that provides an additional `.Root` property to pull the base path of the URI (eg: in `MainPage/Options?option1=value1`, `.Root` would be `MainPage/Options`. +Once you have an instance, simply saying `instance["optionName"]` will pull the value from the querystring for that option. + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| Root | string | Gets or sets the root path of the Deep link URI | + +## Methods + +| Methods | Return Type | Description | +| -- | -- | -- | +| Create(String) | DeepLinkParser | Creates an instance of `DeepLinkParser` for the given `string` | +| Create(Uri) | DeepLinkParser | Creates an instance of DeepLinkParser for the given Uri | +| Create(IActivatedEventArgs) | DeepLinkParser | Creates an instance of DeepLinkParser for the given [IActivatedEventArgs](/uwp/api/Windows.ApplicationModel.Activation.IActivatedEventArgs) | +| ValidateSourceUri(String) | Uri | Validates the source URI | + +### Example + +In OnLaunched of App.xaml.cs: + +```csharp +if (e.PrelaunchActivated == false) +{ + if (rootFrame.Content == null) + { + var parser = DeepLinkParser.Create(args); + if (parser["username"] == "John Doe") + { + // do work here + } + if (parser.Root == "Signup") + { + rootFrame.Navigate(typeof(Signup)); + } +... +``` + +```vb +If e.PrelaunchActivated = False Then + If rootFrame.Content Is Nothing Then + Dim parser = DeepLinkParser.Create(args) + If parser("username") = "John Doe" Then + ' do work here + End If + + If parser.Root = "Signup" Then + rootFrame.Navigate(GetType(Signup)) + End If +... +``` + +## CollectionFormingDeepLinkParser + +The [CollectionFormingDeepLinkParser Class](/dotnet/api/microsoft.toolkit.uwp.helpers.collectionformingdeeplinkparser) will to be able to do something like `?pref=this&pref=that&pref=theOther` and have a pull of `pref` come back with `this,that,theOther` as its value. This derivative of `DeepLinkParser` provides this functionality. + +### Example + +in OnLaunched of App.xaml.cs: + +```csharp +if (e.PrelaunchActivated == false) +{ + if (rootFrame.Content == null) + { + var parser = CollectionFormingDeepLinkParser.Create(args); + if (parser["username"] == "John Doe") + { + // do work here + } + if (parser.Root == "Signup") + { + var preferences = parser["pref"].Split(','); // now a string[] of all 'pref' querystring values passed in URI + rootFrame.Navigate(typeof(Signup)); + } +... +``` + +```vb +If e.PrelaunchActivated = False Then + If rootFrame.Content Is Nothing Then + Dim parser = CollectionFormingDeepLinkParser.Create(args) + If parser("username") = "John Doe" Then + ' do work here + End If + + If parser.Root = "Signup" Then + Dim preferences = parser("pref").Split(","c) ' now a string[] of all 'pref' querystring values passed in URI + rootFrame.Navigate(GetType(Signup)) + End If +... +``` + +Both of these are createable using a `.Create(IActivatedEventArgs)` method. Should you wish to create one in a different manner, the default constructor is `protected` so inheriting from either of these can provide extensibility. +The method that does the heavy lifting of parsing in to the `Dictionary` (`ParseUriString`) is also `protected` and `virtual` so can be used/overridden by any inheriting class. + +## QueryParameterCollection + +The [QueryParameterCollection](/dotnet/api/microsoft.toolkit.uwp.helpers.queryparametercollection) helper class aids in the creation of a `Collection>` populated with they key-value pairs of all parameters in a query string. + +### Example + +```csharp +var myUrl = "https://microsoft.com/?user=fooUser&email=fooUser@outlook.com&firstName=John&lastName=Doe" +var paramCollection = new QueryParameterCollection(myUrl); +foreach (var pair in paramCollection) +{ + Console.WriteLine($"{pair.Key} - {pair.Value}"); +} +``` + +```vb +Dim myUrl = "https://microsoft.com/?user=fooUser&email=fooUser@outlook.com&firstName=John&lastName=Doe" +Dim paramCollection = New QueryParameterCollection(myUrl) +For Each pair In paramCollection + Console.WriteLine($"{pair.Key} - {pair.Value}") +Next +``` + +### Output + +``` +user - fooUser +email - fooUser@outlook.com +firstname - John +lastName - Doe +``` + +### Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +### API + +* [DeepLinkParser source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/DeepLinkParser) diff --git a/docs/archive/windows/eyedropper.md b/docs/archive/windows/eyedropper.md new file mode 100644 index 00000000..36d82479 --- /dev/null +++ b/docs/archive/windows/eyedropper.md @@ -0,0 +1,137 @@ +--- +title: Eyedropper +author: HHChaos +description: The Eyedropper Control can pick up a color from anywhere in your application. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Eyedropper, xaml Control, xaml +dev_langs: + - csharp + - vb +--- + +# Eyedropper (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [GitHub tracking issue for Eyedropper port](https://github.com/CommunityToolkit/Windows/issues/51) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [Eyedropper](/dotnet/api/microsoft.toolkit.uwp.ui.controls.eyedropper) control can pick up a color from anywhere in your application. + +> [!NOTE] +> The Eyedropper Control uses [RenderTargetBitmap](/uwp/api/windows.ui.xaml.media.imaging.rendertargetbitmap) to get a screenshot of your app. In some cases, RenderTargetBitmap may render incorrectly, which will cause eyedropper not to get the correct color value. Please make sure your xaml layout is reasonable, see [here](/uwp/api/windows.ui.xaml.media.imaging.rendertargetbitmap#xaml-visuals-and-rendertargetbitmap-capture-capabilities) for details. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=Eyedropper) + +## Syntax + +Use EyedropperToolButton in xaml. + +```xaml + + + +``` + +Or use the global Eyedropper in code. + +```csharp +var eyedropper = new Eyedropper(); +var color = await eyedropper.Open(); +``` + +```vb +Dim eyedropper = New Eyedropper() +Dim color = Await eyedropper.Open() +``` + +## Sample Output + +![Eyedropper animation](images/eyedropper.png) + +## Properties + +### Eyedropper Properties + +| Property | Type | Description | +| -------- | ----------- | ------------------------------------------------ | +| Color | Color | Gets the current color value. | +| Preview | ImageSource | Gets the enlarged pixelated preview image. | +| WorkArea | Rect | Gets or sets the working area of the eyedropper. | + +### EyedropperToolButton Properties + +| Property | Type | Description | +| ----------------- | ---------------- | ------------------------------------------------------------ | +| Color | Color | Gets the current color value. | +| EyedropperEnabled | bool | Gets or sets a value indicating whether eyedropper is opened. | +| EyedropperStyle | Style | Gets or sets a value for the style to use for the eyedropper. | +| TargetElement | FrameworkElement | Gets or sets the working target element of the eyedropper. | + +## Methods + +### Eyedropper Methods + +| Methods | Return Type | Description | +| -------------- | ----------- | --------------------- | +| Open([Point?]) | Task\ | Open the eyedropper. | +| Close() | void | Close the eyedropper. | + +## Events + +### Eyedropper Events + +| Events | Description | +| ------------- | ------------------------------------------------ | +| ColorChanged | Occurs when the Color property has changed. | +| PickStarted | Occurs when the eyedropper begins to take color. | +| PickCompleted | Occurs when the eyedropper stops to take color. | + +### EyedropperToolButton Events + +| Events | Description | +| ------------- | ------------------------------------------------ | +| ColorChanged | Occurs when the Color property has changed. | +| PickStarted | Occurs when the eyedropper begins to take color. | +| PickCompleted | Occurs when the eyedropper stops to take color. | + +## Examples + +- Use the global Eyedropper in code. + +```csharp +var eyedropper = new Eyedropper(); +var color = await eyedropper.Open(); +``` + +```vb +Dim eyedropper = New Eyedropper() +Dim color = Await eyedropper.Open() +``` + +## Sample Project + +[Eyedropper Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Eyedropper). You can [see this in action](uwpct://Controls?sample=Eyedropper) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[Eyedropper XAML File](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Media/Eyedropper/Eyedropper.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| ------------- | ------------------------------------------------------------ | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +- [Eyedropper source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Media/Eyedropper) diff --git a/docs/archive/windows/facebook.md b/docs/archive/windows/facebook.md new file mode 100644 index 00000000..b17c4697 --- /dev/null +++ b/docs/archive/windows/facebook.md @@ -0,0 +1,309 @@ +--- +title: Facebook Service +author: nmetulev +description: The Facebook Service allows you to retrieve or publish data to the Facebook graph. Examples of the types of objects you can work with are Posts, Tagged Objects, and the primary user feed (outdated docs). +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Facebook Service +dev_langs: + - csharp + - vb +--- + +# Facebook (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +The community is welcome to express interest or contribute to its inclusion, although we want to note that: +- We aren't open to porting this component to 8.x. +- There is no known recommended substitute for this component. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +> [!WARNING] +> The Facebook Service is no longer available in the Windows Community Toolkit. The underlying dependent library was no longer maintained. + +The Facebook Service allows you to retrieve or publish data to the Facebook graph. Examples of the types of objects you can work with are Posts, Tagged Objects, and the primary user feed. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Services?sample=Facebook%20Service) + +## Getting Windows Store SID + +The Windows Store SID is a unique value per application generated, and it not tied to the actual store publication. Creating a local application will give you a valid SID that you can use for debugging against Facebook. + +```csharp +// Put the following code in your mainform loaded event +// Note that this will not work in the App.xaml.cs Loaded +#if DEBUG + System.Diagnostics.Debug.WriteLine("Windows Store SID = " + Microsoft.Toolkit.Uwp.Services.Facebook.FacebookService.Instance.WindowsStoreId); +#endif +``` + +```vb +' Put the following code in your mainform loaded event +' Note that this will not work in the App.xaml.cs Loaded +#If DEBUG Then + System.Diagnostics.Debug.WriteLine("Windows Store SID = " & Microsoft.Toolkit.Uwp.Services.Facebook.FacebookService.Instance.WindowsStoreId) +#End If +``` + +> [!NOTE] +> You may have to turn on the Output window in Visual Studio to see this debug writeline. + +The above code will output something like this: + +``` +Windows Store SID = ms-app://s-1-15-2-12341451-1486691014-2395677208-123421631-1234998043-1234490472-123452499/ +``` + +When entering the value into the Facebook Developer site you must strip the ms-app:// and the trailing / off the string. + +## Creating a new Application on Facebook Developer Site + +1. To get a **Facebook.WindowsStoreID**, go to: . +2. Select **Create a New App ID**, to start integration Facebook into your app or website. +3. Click, **Create a New App** +4. From the app Dashboard choose the **Settings** item on the left. It should select the *Basic* item under it by default. +5. **+Add Platform** choose Windows App. Leave the *Namespace* and *App Domains* entries blank. +6. Enter the **Windows Store SID** from within your app (see *Getting Windows Store SID* section) +7. From left side menu choose **+Add Product** Click to add *Facebook Login*. Ensure you set the following options in the UI: + +| Setting | Value | +|----------|------:| +| Client OAuth Login | Yes | +| Web OAuth Login | No | +| Embedded Browser OAuth Login | Yes | +| Force Web OAuth Redirection | No | +| Login from Devices | No | +| Valid OAuth redirect URIs | Blank | + +## Syntax + +```csharp +// Initialize service +FacebookService.Instance.Initialize(AppIDText.Text); + +// Login to Facebook +if (!await FacebookService.Instance.LoginAsync()) +{ + return; +} + +// Get user's feed +ListView.ItemsSource = await FacebookService.Instance.RequestAsync(FacebookDataConfig.MyFeed, 50); + +// Get current user profile picture +ProfileImage.DataContext = await FacebookService.Instance.GetUserPictureInfoAsync(); + +// Post a message on your wall using Facebook Dialog +await FacebookService.Instance.PostToFeedWithDialogAsync(TitleText.Text, DescriptionText.Text, UrlText.Text); + +// Get current user's photo albums +await FacebookService.Instance.GetUserAlbumsAsync(); + +// Get current user's photos by album Id +await FacebookService.Instance.GetUserPhotosByAlbumIdAsync(addedItem.Id); +``` + +```vb +' Initialize service +FacebookService.Instance.Initialize(AppIDText.Text) + +' Login to Facebook +If Not Await FacebookService.Instance.LoginAsync() Then + Return +End If + +' Get user's feed +ListView.ItemsSource = Await FacebookService.Instance.RequestAsync(FacebookDataConfig.MyFeed, 50) + +' Get current user profile picture +ProfileImage.DataContext = Await FacebookService.Instance.GetUserPictureInfoAsync() + +' Post a message on your wall using Facebook Dialog +Await FacebookService.Instance.PostToFeedWithDialogAsync(TitleText.Text, DescriptionText.Text, UrlText.Text) + +' Get current user's photo albums +Await FacebookService.Instance.GetUserAlbumsAsync() + +' Get current user's photos by album Id +Await FacebookService.Instance.GetUserPhotosByAlbumIdAsync(addedItem.Id) +``` + +## FacebookAlbum Class + +FacebookAlbum has properties to hold album details + +### Properties + +| Property | Type | Description | +| -- | -- | -- | +| Cover_Photo | FacebookPhoto | Gets or sets cover_photo property | +| Description | string | Gets or sets description property | +| Id | string | Gets or sets id property | +| Name | string | Gets or sets name property | +| Picture | FacebookPictureData | Gets or sets picture property | + +## FacebookDataConfig Class + +Configuration object for specifying richer query information + +### Fields + +| Field | Type | Description | +| -- | -- | -- | +| MyFeed | FacebookDataConfig | Gets a predefined config to get user feed. The feed of posts (including status updates) and links published by this person, or by others on this person's profile | +| MyPosts | FacebookDataConfig | Gets a predefined config to show only the posts that were published by this person | +| MyTagged | FacebookDataConfig | Gets a predefined config to show only the posts that this person was tagged in | + +### Properties + +| Property | Type | Description | +| -- | -- | -- | +| Query | string | Gets or sets the query string for filtering service results | + +## FacebookOAuthTokens Class + +Facebook OAuth tokens + +### Properties + +| Property | Type | Description | +| -- | -- | -- | +| AppId | string | Gets or sets facebook AppId | +| WindowsStoreId | string | Gets or sets Windows Store ID | + +## FacebookPhoto Class + +FacebookAlbum has properties to hold photo details + +### Properties + +| Property | Type | Description | +| -- | -- | -- | +| Album | int | Gets or sets album property | +| Created_Time | int | Gets or sets time the entity instance was created | +| Id | string | Gets or sets id property | +| Images | int | Gets or sets images property | +| Link | string | Gets or sets a link to the entity instance | +| Name | string | Gets or sets name property | +| Picture | string | Gets or sets picture property | + +## FacebookPicture Class + +Class for presenting picture data returned from service provider + +### Properties + +| Property | Type | Description | +| -- | -- | -- | +| Id | string | Gets or sets the ID of the picture | +| Is_Silhouette | bool | Gets or sets a value indicating whether the picture is a silhouette or not | +| Link | string | Gets or sets the url of the page with the picture | +| Url | string | Gets or sets an url to the picture | + +## FacebookPictureData Class + +Holds picture data + +### Properties + +| Property | Type | Description | +| -- | -- | -- | +| Data | FacebookPicture | Gets or sets data property | + +## FacebookPlatformImageSource Class + +Holds image details + +### Properties + +| Property | Type | Description | +| -- | -- | -- | +| Height | string | Gets or sets height property | +| Source | string | Gets or sets source property | +| Width | string | Gets or sets width property | + +## FacebookPost Class + +Holds facebook post data + +### Properties + +| Property | Type | Description | +| -- | -- | -- | +| Id | string | Gets or sets id property | +| Message | string | Gets or sets message or post text | +| Created_Time | DateTime | Gets or sets time the entity instance was created | +| Link | string | Gets or sets a link to the entity instance | +| Full_Picture | string | Gets or sets a link to the accompanying image | + +## FacebookRequestSource\ Class + +Type to handle paged requests to Facebook Graph + +### Constructor + +| Constructor | Description | +| -- | -- | +| FacebookRequestSource(FacebookDataConfig, string, string, int) | Initializes a new instance of the `FacebookRequestSource` class | + +### Methods + +| Methods | Return Type | Description | +| -- | -- | -- | +| GetPagedItemsAsync(int, int, CancellationToken) | Task\> | Returns strong typed page of data | + +## FacebookService Class + +Class for connecting to Facebook + +### Properties + +| Property | Type | Description | +| -- | -- | -- | +| WindowsStoreId | string | Gets a Windows Store ID associated with the current app | +| Instance | FacebookService | Gets public singleton property | +| LoggedUser | string | Gets the current logged user name | +| Provider | FBSession | Gets a reference to an instance of the underlying data provider | +| B | int | Description | +| B | int | Description | + +### Methods + +| Methods | Return Type | Description | +|-------------------------------------------------------|-----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| +| Initialize(FacebookOAuthTokens, FacebookPermissions) | bool | Initialize underlying provider with relevant token information | +| LoginAsync() | Task\ | Login with set of required requiredPermissions | +| LogoutAsync() | Task | Log out of the underlying service instance | +| RequestAsync(FacebookDataConfig, int) | Task> | Request list data from service provider based upon a given config / query | +| RequestAsync\(FacebookDataConfig, int, string) | Task> | Request list data from service provider based upon a given config / query | +| RequestAsync(FacebookDataConfig, int, int) | Task, FacebookPost>> | Request list data from service provider based upon a given config / query | +| RequestAsync\(FacebookDataConfig, int, int, string) | Task, T>> | Request generic list data from service provider based upon a given config / query | +| GetUserPictureInfoAsync() | Task\ | Returns the `FacebookPicture` object associated with the logged user | +| GetUserAlbumsAsync(int, string) | Task> | Retrieves list of user photo albums | +| GetUserAlbumsAsync(int, int, string) | Task, FacebookAlbum>> | Retrieves list of user photo albums | +| GetUserPhotosByAlbumIdAsync(string, int, string) | Task> | Retrieves list of user photos by album id | +| GetUserPhotosByAlbumIdAsync(string, int, int, string) | Task, FacebookPhoto>> | Retrieves list of user photos by album id | +| GetPhotoByPhotoIdAsync(string) | Task\ | Retrieves a photo by id | +| PostToFeedWithDialogAsync(string) | Task\ | Enables posting data to the timeline using Facebook dialog | + +## Sample Project + +[Facebook Service Sample Page Source](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/6.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Facebook%20Service). You can [see this in action](uwpct://Services?sample=Facebook%20Service) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp.Services | +| NuGet package | [Microsoft.Toolkit.Uwp.Services](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.Services/) | + +## API + +* [Facebook Service source code](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/6.1.0/Microsoft.Toolkit.Uwp.Services/Services/Facebook) diff --git a/docs/archive/windows/gazeinteractionlibrary.md b/docs/archive/windows/gazeinteractionlibrary.md new file mode 100644 index 00000000..22e81be6 --- /dev/null +++ b/docs/archive/windows/gazeinteractionlibrary.md @@ -0,0 +1,224 @@ +--- +title: Gaze Interaction Library +author: harishsk +description: The Gaze Interaction library contains a set of helper classes built on the Windows gaze input APIs to more easily leverage eye tracking and integrate gaze interactions into your UWP application. +keywords: windows 10, uwp, uwp community toolkit, uwp toolkit, windows community toolkit, gaze, eye gaze, gaze input, gaze interaction, eye tracking, eye tracker +--- + +# GazeInteractionLibrary (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +Microsoft announced native support for eye tracking in Windows in the [Windows 10 Fall Creators Update](https://blogs.msdn.microsoft.com/accessibility/2017/08/01/from-hack-to-product-microsoft-empowers-people-with-eye-control-for-windows-10/). In the Windows 10 April 2018 update, Microsoft added developer support by releasing [Windows Gaze Input APIs](/uwp/api/windows.devices.input.preview) to build UWP applications that can interact with gaze input and eye trackers. + +This Gaze Interaction Library is built on top of the Windows Gaze Input APIs and provides a set of developer helper classes to more easily enable UWP applications to respond to where the user is looking on the screen. This library is intended to abstract away some of the complexities of dealing with the raw stream of gaze input coming from the eye tracking device exposed through the Windows APIs. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Gaze?sample=GazeInteraction) + +## Prerequisites + +In order to use the Windows 10 Gaze Input APIs or this Gaze Interaction Library, you need to have the following: + +* A device with the Windows 10 April 2018 Update +* A [supported eye tracker](https://support.microsoft.com/help/4043921/windows-10-get-started-eye-control#supported-devices), like the [Tobii EyeX 4C](https://tobiigaming.com/products/) + +To use the gaze input APIs, you must register the gazeInput capability in the app manifest. Add the following DeviceCapability to the Capabilities node in the Package.appxmanifest file of your project (you can do this by checking Gaze Input in the Capabilities tab in Visual Studio when you have Package.appxmanifest open in the App Manifest Designer): + +```xaml + + + +``` + +## Supported Features + +The Gaze Interaction Library currently supports the following features: + +* Dwell based activation of XAML button and toggle button controls +* Enabling gaze interactions for the entire XAML page or for a portion of it (like a single control) +* Customizing the dwell times associated with specific controls +* Controlling repetition of the dwell invocation of controls + +## Gaze Concepts + +Below are a few eye gaze related concepts that are helpful in order to better understand the rest of the document: + +* **Saccade.** A saccade is a rapid movement of the eyes from one fixation point to another. Our eyes alternate between fixations and saccades. +* **Fixation.** A fixation is the collection of gaze points on a single location of the screen for a relatively short amount of time (roughly around 200ms). This happens after a saccade when the eye comes to rest upon an object and it comes into sharp focus. +* **Dwell.** A dwell is the conscious fixation by the user for a duration greater than the fixation time. This mechanism is typically used to identify user intent when the user is using only their eyes as an input method. The dwell time duration can be application and control dependent. +* **Enter/Exit.** These are states and properties specific to this API to help manage gaze related interactions and refer to the time elapsed since the first recorded gaze sample and the last recorded gaze sample on a particular control (Button, ToggleButton etc.) + +The Gaze Interaction Library enables dwell based gaze interactions on the page by reading the data from the eye tracker over the page invoking specific controls when the user's gaze dwells on a control for a specific time. The application can configure this time based on its usage scenario. + +## PointerState Properties + +The Windows Gaze Input APIs delivers a stream of timestamped gaze point coordinates of the user's gaze location on the screen. This library aggregates these samples over each control and converts the stream into gaze events. Corresponding to these events, are the following states: + +| Property | Type | Description | +| -- | -- | -- | +|Enter | enum | A user's gaze has entered the control | +|Fixation | enum | A user eye's are focused on the control. | +|Dwell | enum | A user is consciously dwelling on the control and has exceeded the dwell time. This is interpreted as the user's intent to activate or invoke the control, e.g. click a button| +|Exit | enum | A user's gaze is no longer within the control| + +## GazeInput Properties + +If the XAML page is enabled for gaze based interactions, the visibility and size of the gaze cursor, and the timings associated with the states above can be configured using the properties below: + +| Property | Type | Description | +| -- | -- | -- | +| IsDeviceAvailable | bool | Returns whether a compatible eye tracker is connected. When this property changes an `IsDeviceAvailableChanged` event is fired. | +| Interaction | enum | Gets or sets the status of gaze interaction over that particular XAML element. There are three options:
  • **Enabled.** Gaze interaction is enabled on this element and all its children
  • **Disabled** Gaze interaction is disabled on this element and all its children
  • **Inherited** Gaze interaction status is inherited from the nearest ancestor
| +| CursorVisible | bool | The gaze cursor shows where the user is looking at on the screen. This boolean property shows the gaze cursor when set to `true` and hides it when set to `false`. The default value is `false`| +|CursorRadius|int| Gets or sets the size of the gaze cursor radius. The default value is X| +| ThresholdDuration | TimeSpan | This duration controls when the PointerState moves to either the `Enter` state or the `Exit` state. When this duration has elapsed after the user's gaze first enters a control, the `PointerState` is set to `Enter`. And when this duration has elapsed after the user's gaze has left the control, the `PointerState` is set to `Exit`. In both cases, a `StateChanged` event is fired. The default value is 50ms. | +| FixationDuration | TimeSpan | Gets or sets the duration for the control to transition from the `Enter` state to the `Fixation` state. At this point, a `StateChanged` event is fired with `PointerState` set to `Fixation`. This event should be used to control the earliest visual feedback the application needs to provide to the user about the gaze location. The default value is 350ms. | +| DwellDuration | TimeSpan | Gets or sets the duration for the control to transition from the `Fixation` state to the `Dwell` state. At this point, a `StateChanged` event is fired with `PointerState` set to `Dwell`. The `Enter` and `Fixation` states are typically achieved too rapidly for the user to have much control over. In contrast `Dwell` is a more conscious activity. This is the point at which the control is invoked, e.g. a button click. The application can modify this property to control when a gaze enabled UI element gets invoked after a user starts looking at it. The default value is 400 ms. | +| MaxDwellRepeatCount | int | The maximum amount of times the control will invoked repeatedly without the user's gaze having to leave and re-enter the control. The default value is zero which disables repeated invocation of a control. Developers can set a higher value to enable repeated invocation. | +| DwellRepeatDuration | TimeSpan | Gets or sets the duration of repeated dwell invocations, should the user continue to dwell on the control. The first repeat will occur after an additional delay specified by `RepeatDelayDuration`. Subsequent repeats happen after every period of `DwellRepeatDuration`. _A control is invoked repeatedly only if MaxDwellRepeatCount is set to greater than zero_. | +| RepeatDelayDuration | TimeSpan | Gets or sets the additional duration for the first repeat to occur. This prevents inadvertent repeated invocation. See above for details. | +| IsSwitchEnabled | bool | Gets or sets whether switch activation is enabled. When Switch support is enabled, the currently fixated element will not transition to the dwell state. Further, when the `GazePointer.Click()` method is called the currently fixated element will be invoked. | + +## GazeElement Events + +Add description here. + +| Events | Description | +| -- | -- | +| StateChanged | This event is raised in response to each of the states associated with `PointerState` (except for the `DwellRepeat` state). An application can add a handler for this event to customize gaze related processing with respect to the various gaze pointer states mentioned above.| +|DwellProgressFeedback| This event is fired to indicate progress towards a dwell event. An application can handle this event to either customize visual feedback and/or turn off the default animation for dwell by setting `DwellProgressEventArgs.Handled` to `true`| +|Invoked|This event is fired when the library is about to invoke the control in response to a dwell event. An application can handle this even to perform custom processing before invocation, and/or suppress invocation by setting the `DwellInvokedRoutedEventArgs.Handled` to `true`| + +## StateChangedEventArgs Properties + +This parameter is passed to the `StateChanged` event which is fired when the `PointerState` changes. + +| Property | Type | Description | +| -- | -- | -- | +|PointerState|GazePointerState|The `GazePointerState` associated with this event| +|ElapsedTime|TimeSpan|The time the user has spent looking at the control to reach the specific pointer state above| + +## DwellProgressEventArgs Properties + +This parameter is passed to the event handling the `DwellProgressFeedback` event. + +| Property | Type | Description | +| -- | -- | -- | +|State|enum|This enum indicates the state of the control towards dwell in three values `Idle`, `Progressing` and `Complete`| +|Progress|double|A value between 0 and 1 that indicates the fractional progress towards completing dwell| +|Handled|bool|If an application sets this value to `true` the default animation provided by the library is suppressed| + +## DwellInvokedRoutedEventArgs Properties + +This parameter is passed to the GazeElement::Invoked event and allows the application to prevent default invocation when the user dwells on a control. + +| Property | Type | Description | +| -- | -- | -- | +| Handled | bool | This parameter is passed to the `GazeElement.Invoked` event. If set to `true` the library will suppress invoking the control on a dwell event| + +## Examples + +### To enable gaze interactions on the entire XAML page + +Add the following lines to your Page element to enable gaze interaction on the entire page. + +```xaml + xmlns:gaze="using:Microsoft.Toolkit.Uwp.Input.GazeInteraction" + gaze:GazeInput.Interaction="Enabled" +``` + +For e.g. + +```xaml + +``` + +### To enable gaze interactions on a portion of the page + +Gaze interaction can also be enabled only on a portion of the page by adding the same attributes to any XAML element on the page. + +To enable only a subset of the page, e.g. just one Grid on the page: + +```xaml + + +``` + +```csharp +private void OnInvokeProgress(object sender, DwellProgressEventArgs e) +{ + e.Handled = true; +} +``` + + + + + +## Sample Project + +[GazeInteractionPage](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/GazeInteraction/). You can [see this in action](uwpct://Gaze?sample=GazeInteraction) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal,10.0.17134.1 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.Input.GazeInteraction | +| NuGet package | [NuGet package](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.Input.GazeInteraction/) | + +## API + +* [Gaze Interaction Library source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.Input.GazeInteraction) + +## Related Topics + +* [Windows 10 Gaze Input APIs](/uwp/api/windows.devices.input.preview) diff --git a/docs/archive/windows/imagecache.md b/docs/archive/windows/imagecache.md new file mode 100644 index 00000000..f3947a32 --- /dev/null +++ b/docs/archive/windows/imagecache.md @@ -0,0 +1,101 @@ +--- +title: ImageCache +author: nmetulev +description: The ImageCache provides methods and tools to cache images in a temporary local folder. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, ImageCache +dev_langs: + - csharp + - vb +--- + +# ImageCache (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [ImageCache](/dotnet/api/microsoft.toolkit.uwp.ui.imagecache) provides methods and tools to cache images in a temporary local folder. ImageCache also supports optional in-memory layer of caching, that provides better performance when same images are requested multiple times (like in long virtualized lists of images). This type of caching is disabled by default, but can be enabled by setting MaxMemoryCacheSize to desired size. For example: setting MaxMemoryCacheSize to 100 means that 100 last requested images will be held in memory to be instantly available, without disk reads. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Helpers?sample=ImageCache) + +## Syntax + +```csharp +// Set cache duration +ImageCache.Instance.CacheDuration = TimeSpan.FromHours(24); + +// Enable in-memory caching +ImageCache.Instance.MaxMemoryCacheCount = 100; + +var distantUri = new Uri("https://www.myserver.com/image.jpg"); + +// Load a specific image from the cache. If the image is not in the cache, ImageCache will try to download and store it +var bitmapImage = await ImageCache.Instance.GetFromCacheAsync(distantUri); + +// Clear the cache. Please note that you can provide a parameter to define a timespan from now to select cache entries to delete. +await ImageCache.Instance.ClearAsync(); +``` + +```vb +' Set cache duration +ImageCache.Instance.CacheDuration = TimeSpan.FromHours(24) + +' Enable in-memory caching +ImageCache.Instance.MaxMemoryCacheCount = 100 + +Dim distantUri = New Uri("https://www.myserver.com/image.jpg") + +' Load a specific image from the cache. If the image is not in the cache, ImageCache will try to download and store it +Dim bitmapImage = Await ImageCache.Instance.GetFromCacheAsync(distantUri) + +' Clear the cache. Please note that you can provide a parameter to define a timespan from now to select cache entries to delete. +Await ImageCache.Instance.ClearAsync() +``` + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| CacheDuration | TimeSpan | Gets or sets the life duration of every cache entry | +| HttpClient | HttpClient | Gets instance of HttpClient | +| Instance | ImageCache | Gets public singleton property | +| MaintainContext | bool | Gets or sets a value indicating whether context should be maintained until type has been instantiated or not | +| MaxMemoryCacheCount | int | Gets or sets max in-memory item storage count | +| RetryCount | uint | Gets or sets the number of retries trying to ensure the file is cached | + +## Methods + +| Methods | Return Type | Description | +|----------------------------------------------------------------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ClearAsync() | Task | Clears all files in the cache | +| ClearAsync(TimeSpan) | Task | Clears file if it has expired | +| GetFileFromCacheAsync(Uri) | Task\ | Gets the StorageFile containing cached item for given Uri | +| GetFromCacheAsync(Uri, Boolean, CancellationToken, List>) | Task\ | Retrieves item represented by Uri from the cache. If the item is not found in the cache, it will try to downloaded and saved before returning it to the caller | +| GetFromMemoryCache(Uri) | T | Retrieves item represented by Uri from the in-memory cache if it exists and is not out of date. If item is not found or is out of date, default instance of the generic type is returned | +| PreCacheAsync(Uri, Boolean, Boolean, CancellationToken) | Task | Assures that item represented by Uri is cached | +| RemoveAsync(IEnumerable) | Task | Removed items based on uri list passed | +| RemoveExpiredAsync(Nullable) | Task | Removes cached files that have expired | + +## Sample Project + +[Image Cache Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/ImageCache). You can [see this in action](uwpct://Helpers?sample=ImageCache) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +## API + +* [ImageCache source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI/Cache/ImageCache.cs) diff --git a/docs/archive/windows/imageex.md b/docs/archive/windows/imageex.md new file mode 100644 index 00000000..3dfd1768 --- /dev/null +++ b/docs/archive/windows/imageex.md @@ -0,0 +1,67 @@ +--- +title: ImageEx +author: nmetulev +description: The ImageEx Control and downloads images asynchronously, while showing a loading indicator. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, ImageEx, xaml control, xaml +--- + +# ImageEx (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +This component was deprecated in WCT 7.x as it can be built piecemeal using platform features. While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [GitHub tracking issue for ImageEx port](https://github.com/CommunityToolkit/Windows/issues/51) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [ImageEx](/dotnet/api/microsoft.toolkit.uwp.ui.controls.imageex) control downloads images asynchronously, while showing a loading indicator. Source images are then stored in the application's local cache to preserve resources and load time. ImageEx also extends the default *Image* and *ImageBrush* Platform controls respectively to improve performance through caching. You can also use a placeholder image that will be displayed while loading the main image. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=ImageEx) + +## Syntax + +```xaml + +``` + +## Sample Output + +![ImageEx animation](images/imageex.gif) + +## ImageEx Properties + +| Property | Type | Description | +| -- | -- | -- | +| NineGrid | Thickness | Gets or sets the nine-grid used by the image | +| IsCacheEnabled | bool | Gets or sets a value indicating whether gets or sets cache state | +| ImageExCachingStrategy | enum | Gets or sets a value indicating how the Image will be cached | +| CornerRadius | double | Get or set the radius of image corner | +| EnableLazyLoading | bool | Gets or sets a value indicating is lazy loading enabled. | +| LazyLoadingThreshold | double | Gets or sets a value indicating the threshold for triggering lazy loading. Default value is 300 px. | + +## Sample Project + +[ImageExControl Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/ImageEx). You can [see this in action](uwpct://Controls?sample=ImageEx) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +- [ImageEx Control XAML File](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Core/ImageEx/ImageEx.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +- [ImageEx source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Core/ImageEx) diff --git a/docs/archive/windows/images/bladeview.gif b/docs/archive/windows/images/bladeview.gif new file mode 100644 index 00000000..d0e12c6d Binary files /dev/null and b/docs/archive/windows/images/bladeview.gif differ diff --git a/docs/archive/windows/images/carousel-overview.gif b/docs/archive/windows/images/carousel-overview.gif new file mode 100644 index 00000000..13b07c7a Binary files /dev/null and b/docs/archive/windows/images/carousel-overview.gif differ diff --git a/docs/archive/windows/images/datagrid.gif b/docs/archive/windows/images/datagrid.gif new file mode 100644 index 00000000..dea049e9 Binary files /dev/null and b/docs/archive/windows/images/datagrid.gif differ diff --git a/docs/archive/windows/images/datagrid/alternaterowbackground.png b/docs/archive/windows/images/datagrid/alternaterowbackground.png new file mode 100644 index 00000000..51d500ba Binary files /dev/null and b/docs/archive/windows/images/datagrid/alternaterowbackground.png differ diff --git a/docs/archive/windows/images/datagrid/editing.png b/docs/archive/windows/images/datagrid/editing.png new file mode 100644 index 00000000..dd8ebcd2 Binary files /dev/null and b/docs/archive/windows/images/datagrid/editing.png differ diff --git a/docs/archive/windows/images/datagrid/frozencolumns.png b/docs/archive/windows/images/datagrid/frozencolumns.png new file mode 100644 index 00000000..22761138 Binary files /dev/null and b/docs/archive/windows/images/datagrid/frozencolumns.png differ diff --git a/docs/archive/windows/images/datagrid/gridlines.png b/docs/archive/windows/images/datagrid/gridlines.png new file mode 100644 index 00000000..fcfb251a Binary files /dev/null and b/docs/archive/windows/images/datagrid/gridlines.png differ diff --git a/docs/archive/windows/images/datagrid/grouping.png b/docs/archive/windows/images/datagrid/grouping.png new file mode 100644 index 00000000..35a39086 Binary files /dev/null and b/docs/archive/windows/images/datagrid/grouping.png differ diff --git a/docs/archive/windows/images/datagrid/managenugetpackages.png b/docs/archive/windows/images/datagrid/managenugetpackages.png new file mode 100644 index 00000000..c5f10b29 Binary files /dev/null and b/docs/archive/windows/images/datagrid/managenugetpackages.png differ diff --git a/docs/archive/windows/images/datagrid/resizecolumns.png b/docs/archive/windows/images/datagrid/resizecolumns.png new file mode 100644 index 00000000..f6d5239c Binary files /dev/null and b/docs/archive/windows/images/datagrid/resizecolumns.png differ diff --git a/docs/archive/windows/images/datagrid/rowdetails.png b/docs/archive/windows/images/datagrid/rowdetails.png new file mode 100644 index 00000000..814ef357 Binary files /dev/null and b/docs/archive/windows/images/datagrid/rowdetails.png differ diff --git a/docs/archive/windows/images/datagrid/selection.png b/docs/archive/windows/images/datagrid/selection.png new file mode 100644 index 00000000..d751df3f Binary files /dev/null and b/docs/archive/windows/images/datagrid/selection.png differ diff --git a/docs/archive/windows/images/datagrid/sorting.png b/docs/archive/windows/images/datagrid/sorting.png new file mode 100644 index 00000000..3e346313 Binary files /dev/null and b/docs/archive/windows/images/datagrid/sorting.png differ diff --git a/docs/archive/windows/images/datagrid/validation.png b/docs/archive/windows/images/datagrid/validation.png new file mode 100644 index 00000000..b122a22c Binary files /dev/null and b/docs/archive/windows/images/datagrid/validation.png differ diff --git a/docs/archive/windows/images/eyedropper.png b/docs/archive/windows/images/eyedropper.png new file mode 100644 index 00000000..053d2f39 Binary files /dev/null and b/docs/archive/windows/images/eyedropper.png differ diff --git a/docs/archive/windows/images/imageex.gif b/docs/archive/windows/images/imageex.gif new file mode 100644 index 00000000..1613f532 Binary files /dev/null and b/docs/archive/windows/images/imageex.gif differ diff --git a/docs/archive/windows/images/infinitecanvas.gif b/docs/archive/windows/images/infinitecanvas.gif new file mode 100644 index 00000000..eb9f1ba5 Binary files /dev/null and b/docs/archive/windows/images/infinitecanvas.gif differ diff --git a/docs/archive/windows/images/listdetailsview.gif b/docs/archive/windows/images/listdetailsview.gif new file mode 100644 index 00000000..79f479ba Binary files /dev/null and b/docs/archive/windows/images/listdetailsview.gif differ diff --git a/docs/archive/windows/images/livetile.gif b/docs/archive/windows/images/livetile.gif new file mode 100644 index 00000000..c4a4b0b3 Binary files /dev/null and b/docs/archive/windows/images/livetile.gif differ diff --git a/docs/archive/windows/images/loading.gif b/docs/archive/windows/images/loading.gif new file mode 100644 index 00000000..18fc431a Binary files /dev/null and b/docs/archive/windows/images/loading.gif differ diff --git a/docs/archive/windows/images/markdowntextblock.gif b/docs/archive/windows/images/markdowntextblock.gif new file mode 100644 index 00000000..531d1074 Binary files /dev/null and b/docs/archive/windows/images/markdowntextblock.gif differ diff --git a/docs/archive/windows/images/orbitview.gif b/docs/archive/windows/images/orbitview.gif new file mode 100644 index 00000000..94d76610 Binary files /dev/null and b/docs/archive/windows/images/orbitview.gif differ diff --git a/docs/archive/windows/images/poptoast.gif b/docs/archive/windows/images/poptoast.gif new file mode 100644 index 00000000..0456e52a Binary files /dev/null and b/docs/archive/windows/images/poptoast.gif differ diff --git a/docs/archive/windows/images/rotatortile.gif b/docs/archive/windows/images/rotatortile.gif new file mode 100644 index 00000000..a05031cd Binary files /dev/null and b/docs/archive/windows/images/rotatortile.gif differ diff --git a/docs/archive/windows/images/squircle.gif b/docs/archive/windows/images/squircle.gif new file mode 100644 index 00000000..8fd9a791 Binary files /dev/null and b/docs/archive/windows/images/squircle.gif differ diff --git a/docs/archive/windows/images/texttoolbar.png b/docs/archive/windows/images/texttoolbar.png new file mode 100644 index 00000000..b30e9125 Binary files /dev/null and b/docs/archive/windows/images/texttoolbar.png differ diff --git a/docs/archive/windows/images/tilecontrol.gif b/docs/archive/windows/images/tilecontrol.gif new file mode 100644 index 00000000..1be12cdb Binary files /dev/null and b/docs/archive/windows/images/tilecontrol.gif differ diff --git a/docs/archive/windows/infinitecanvas.md b/docs/archive/windows/infinitecanvas.md new file mode 100644 index 00000000..72cfb402 --- /dev/null +++ b/docs/archive/windows/infinitecanvas.md @@ -0,0 +1,97 @@ +--- +title: InfiniteCanvas +author: IbraheemOsama +description: InfiniteCanvas is a canvas that supports Infinite Scrolling, Ink, Text, Format Text, Zoom in/out, Redo, Undo, Export canvas data, Import canvas data. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, InfiniteCanvas, XAML Control, xaml +--- + +# InfiniteCanvas (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [GitHub tracking issue for InfiniteCanvas port](https://github.com/CommunityToolkit/Windows/issues/91) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [InfiniteCanvas](/dotnet/api/microsoft.toolkit.uwp.ui.controls.infinitecanvas) control is a canvas that supports Infinite Scrolling, Ink, Text, Format Text, Zoom in/out, Redo, Undo, Export canvas data, Import canvas data. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=InfiniteCanvas) + +## Syntax + +```xaml + + + +``` + +## Sample Output + +![InfiniteCanvas animation](images/infinitecanvas.gif) + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| CanvasWidth | double | Gets or sets the width of the drawing area, default value is 2097152. This is different from the `Width` property which specifies the Width of the control | +| CanvasHeight | double | Gets or sets the height of the drawing area, default value is 2097152. This is different from the `Height` property which specifies the Height of the control | +| IsToolbarVisible | bool | Gets or sets a value indicating whether the toolbar is visible or not. | +| MaxZoomFactor | double | Gets or sets the MaxZoomFactor for the canvas, range between 1 to 10 and the default value is 4. | +| MinZoomFactor | double | Gets or sets the MinZoomFactor for the canvas, range between .1 to 1 the default value is .25. | + +## Methods + +| Method | Return Type | Description | +| -- | -- | -- | +| Redo() | void | Redo the last action. | +| Undo() | void | Undo the last action. | +| ExportAsJson() | string | Export the InfiniteCanvas as json string. | +| ImportFromJson(string json) | void | Import InfiniteCanvas from json string and render the new canvas, this function will empty the Redo/Undo queue. | + +## Events + +### ReRenderCompleted + +This event triggered after each render happened because of any change in the canvas elements. +This event could be used to do the Auto Save functionality. + +## Examples + +The following sample demonstrates how to add InfiniteCanvas Control + +```xaml + + + + + + +``` + +## Sample Project + +[InfiniteCanvas Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/InfiniteCanvas). You can [see this in action](uwpct://Controls?sample=InfiniteCanvas) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[InfiniteCanvas XAML File](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Media/InfiniteCanvas/InfiniteCanvas.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +* [InfiniteCanvas source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Media/InfiniteCanvas) diff --git a/docs/archive/windows/linkedin.md b/docs/archive/windows/linkedin.md new file mode 100644 index 00000000..8c55bd78 --- /dev/null +++ b/docs/archive/windows/linkedin.md @@ -0,0 +1,121 @@ +--- +title: LinkedIn Service +author: nmetulev +description: The LinkedIn Service allows you to retrieve or publish data to the LinkedIn graph. Examples of the types of objects you can work with are User profile data and sharing Activity. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, LinkedIn Service +dev_langs: + - csharp + - vb +--- + +# LinkedIn Service (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. +- We aren't open to porting this component to 8.x. +- There is no known recommended substitute for this component. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +> [!WARNING] +> (This API will be removed in the future.) + +The **LinkedIn Service** allows you to retrieve or publish data to the LinkedIn graph. Examples of the types of objects you can work with are User profile data and sharing Activity. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Services?sample=LinkedIn%20Service) + +## Creating a new Application on LinkedIn Developer Site + +1. Go to: . +2. Select **Create Application**, to start integrating LinkedIn into your app. +3. Complete all mandatory fields signified by the red star. If you agree to the terms and conditions, hit **Submit**. +4. Make a note of the **Client Id** and **Client Secret** for your app - you will need to supply these in your code. +5. Take note of the **Default Application Permissions**. You can either set these in this portal or via code. These are the permissions your user will need to agree to for you to make calls on their behalf. +6. Under **OAuth 2.0** you will need to enter a **Authorized Redirect URLs**. For UWP app development purposes this is arbitrary, but it will need to match what you have in your code (e.g. ). +7. Once you have done, hit **Update**. + +## Syntax + +```csharp +// Initialize service - use overload if you need to supply additional permissions +LinkedInService.Instance.Initialize(ClientId.Text, ClientSecret.Text, CallbackUri.Text); + +// Login to LinkedIn +if (!await LinkedInService.Instance.LoginAsync()) +{ + return; +} + +// Get current user's profile details +await LinkedInService.Instance.GetUserProfileAsync(); + +// Share message to LinkedIn (text should include a Url so LinkedIn can scrape preview information) +await LinkedInService.Instance.ShareActivityAsync(ShareText.Text); +``` + +```vb +' Initialize service - use overload if you need to supply additional permissions +LinkedInService.Instance.Initialize(ClientId.Text, ClientSecret.Text, CallbackUri.Text) + +' Login to LinkedIn +If Not Await LinkedInService.Instance.LoginAsync() Then + Return +End If + +' Get current user's profile details +Await LinkedInService.Instance.GetUserProfileAsync() + +' Share message to LinkedIn (text should include a Url so LinkedIn can scrape preview information) +Await LinkedInService.Instance.ShareActivityAsync(ShareText.Text) +``` + +[LinkedIn Service Sample Page Source](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/6.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/LinkedIn%20Service). You can see this in action in [Windows Community Toolkit Sample App](https://www.microsoft.com/store/apps/9NBLGGH4TLCQ). + +## Using the service on non-UWP platforms + +This service has built-in UWP and .NET Framework support. To use the service outside of UWP and .NET Framework platform, you'll need to implement some interfaces. These interfaces are the IAuthenticationBroker, IPasswordManager and IStorageManager. + +### IAuthenticationBroker + +The IAuthenticationBroker only has the Authenticate method. This method receives a request uri and a callback uri, which you'll use to authenticate with the API. The method returns an AuthenticationResult that tells the service the authentication result. + +### IPasswordManager + +The IPasswordManager will allow the service to manage passwords. The methods you'll have to implement are Get, Store and Remove. + +The Get method receives a string key and returns a PasswordCredential. + +The Store method receives a string resource and a PasswordCredential. + +The Remove method receives a string key. + +### IStorageManager + +Finally, the IStorageManager will allow the service to store application data. The methods you'll have to implement are Get and Set. + +The Get method receives a string key and returns the saved string. + +The Set method receives a string key and a string value. + +The toolkit has implementations of each of them for UWP. You can find them as UwpAuthenticationBroker, UwpPasswordManager and UwpStorageManager. + +## Sample Project + +[LinkedIn Service Sample Page Source](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/6.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/LinkedIn%20Service). You can [see this in action](uwpct://Services?sample=LinkedIn%20Service) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Services | +| NuGet package | [Microsoft.Toolkit.Services](https://www.nuget.org/packages/Microsoft.Toolkit.Services/) | + +## API + +* [LinkedIn Service source code](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/6.1.0/Microsoft.Toolkit.Services/Services/LinkedIn) diff --git a/docs/archive/windows/loading.md b/docs/archive/windows/loading.md new file mode 100644 index 00000000..241da5d3 --- /dev/null +++ b/docs/archive/windows/loading.md @@ -0,0 +1,99 @@ +--- +title: Loading +author: nmetulev +description: The loading control is for showing an animation with some content when the user should wait in some tasks of the app. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Loading, XAML Control , xaml +dev_langs: + - csharp + - vb +--- + +# Loading (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +This component was deprecated and not superseded, as it can be built piecemeal using platform features. The functionality provided by this component can be achieved through standard Windows platform features. + +For more information: +- [GitHub tracking issue for Loading port (closed)](https://github.com/CommunityToolkit/Windows/issues/92) +- [Windows Community Toolkit GitHub](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [Loading](/dotnet/api/microsoft.toolkit.uwp.ui.controls.loading) control is for showing an animation with some content when the user should wait in some tasks of the app. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=Loading) + +## Syntax + +```xaml + + + + + +``` + +## Sample Output + +![Loading animation](images/loading.gif) + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| IsLoading | bool | Gets or sets a value indicating whether the control is in the loading state | + +## Examples + +An example of how we can build the loading control. + +- `Background` and `Opacity` are for the panel who appears and disappears behind our custom control. +- Use the `LoadingControl` to show specialized content. +- You can also use `BorderBrush` and `BorderThickness` to change the `LoadingControl`. + +```xaml + + + + + + + + + +``` + +Finally that the loading control appears, we must set the `IsLoading` property to `true` + +```csharp +LoadingControl.IsLoading = true; +``` + +```vb +LoadingControl.IsLoading = true +``` + +## Sample Project + +[Loading Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Loading). You can [see this in action](uwpct://Controls?sample=Loading) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[Loading XAML File](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Core/Loading/Loading.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +- [Loading source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Core/Loading) diff --git a/docs/archive/windows/markdownparser.md b/docs/archive/windows/markdownparser.md new file mode 100644 index 00000000..6707197b --- /dev/null +++ b/docs/archive/windows/markdownparser.md @@ -0,0 +1,107 @@ +--- +title: Markdown Parser +author: williamabradley +description: The Markdown Parser allows you to parse a Markdown String into a Markdown Document, and then Render it with a Markdown Renderer. +keywords: windows community toolkit, uwp community toolkit, uwp toolkit, microsoft community toolkit, microsoft toolkit, markdown, markdown parsing, parser, markdown rendering +dev_langs: + - csharp + - vb +--- + +# MarkdownParser (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. +- The new `MarkdownTextBlock` control in Windows Community Toolkit Labs uses Markdig under the hood, not this `MarkdownParser`. +- For custom parsing needs, consider using Markdig directly in your application. + +For more information: +- [Windows Community Toolkit Labs GitHub](https://github.com/CommunityToolkit/Labs-Windows) +- [Windows Community Toolkit GitHub](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +> [!WARNING] +> (This API is will be removed in the future. Please consider using [Markdig](https://github.com/lunet-io/markdig) for Markdown document parsing. + +The [MarkdownDocument](/dotnet/api/microsoft.toolkit.parsers.markdown.markdowndocument) class allows you to parse a Markdown String into a Markdown Document, and then Render it with a Markdown Renderer. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Helpers?sample=Markdown%20Parser) + +## Example + +```csharp +string md = "This is **Markdown**"; +MarkdownDocument document = new MarkdownDocument(); +document.Parse(md); + +// Takes note of all of the Top Level Headers. +foreach (var element in document.Blocks) +{ + if (element is HeaderBlock header) + { + Console.WriteLine($"Header: {header.ToString()}"); + } +} +``` + +```vb +Dim md As String = "This is **Markdown**" +Dim document As MarkdownDocument = New MarkdownDocument() +document.Parse(md) + +For Each element In document.Blocks + If TypeOf element Is HeaderBlock Then + Console.WriteLine($"Header: {element.ToString()}") + End If +Next +End Sub +``` + +## Classes + +| Class | Purpose | +| --- | --- | +| **Microsoft.Toolkit.Parsers.Markdown.MarkdownDocument** | Represents a Markdown Document. | +| **Microsoft.Toolkit.Parsers.Markdown.Render.MarkdownRendererBase** | A base renderer for Rendering Markdown into Controls. | + +### MarkdownDocument + +#### Properties + +| Property | Type | Description | +| -- | -- | -- | +| Blocks | IList\ | Gets or sets the list of block elements. | + +#### Methods + +| Methods | Return Type | Description | +| -- | -- | -- | +| Parse(string) | void | Parses markdown document text. | +| LookUpReference(string) | LinkReferenceBlock | Looks up a reference using the ID. | + +## Create a Markdown Renderer + +In order to create a Markdown Renderer, you can either implement your own, or inherit from `MarkdownRendererBase`, this class already has all the required methods, and some assistive code to make implementing a Renderer easy, all you have to do is implement the Block and Inline Rendering, and the output. + +This requires an inherited `IRenderContext`, which allows you to keep track of the Context of the rendering. + +The best way to figure out how to create a Renderer, is to look at the [implementation](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/6.1.1/Microsoft.Toolkit.Uwp.UI.Controls/MarkdownTextBlock/Render) for the UWP MarkdownTextBlock control. + +## Sample Project + +[Markdown Parser Sample Page Source](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/6.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/MarkdownParser/MarkdownParserPage.xaml.cs). You can [see this in action](uwpct://Helpers?sample=Markdown%20Parser) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Implementation | .NET Standard 1.4. | +| -- | -- | +| Namespace | Microsoft.Toolkit.Parsers | +| NuGet package | [Microsoft.Toolkit.Parsers](https://www.nuget.org/packages/Microsoft.Toolkit.Parsers/) | + +## API + +* [Markdown Parser source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Markdown/Parsers/Markdown) diff --git a/docs/archive/windows/markdowntextblock.md b/docs/archive/windows/markdowntextblock.md new file mode 100644 index 00000000..cfe025e5 --- /dev/null +++ b/docs/archive/windows/markdowntextblock.md @@ -0,0 +1,251 @@ +--- +title: MarkdownTextBlock +author: williamabradley +description: The MarkdownTextBlock control provides full markdown parsing and rendering for Universal Windows Apps. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, MarkdownTextBlock, xaml, xaml control +--- + +# MarkdownTextBlock (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. +- A new `MarkdownTextBlock` control is in the works in Windows Community Toolkit Labs, rebuilt from the ground up using Markdig. + +For more information: +- [`MarkdownTextBlock` GitHub tracking issue in Windows Community Toolkit Labs](https://github.com/CommunityToolkit/Labs-Windows/issues/606) +- [Windows Community Toolkit GitHub](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [MarkdownTextBlock](/dotnet/api/microsoft.toolkit.uwp.ui.controls.markdowntextblock) control provides full markdown parsing and rendering for Universal Windows Apps. Originally created for the open source reddit app Baconit, the control was engineered to be simple to use and very efficient. One of the main design considerations for the control was it needed to be performant enough to provide a great user experience in virtualized lists. With the custom markdown parser and efficient XAML rendering, we were able to achieve excellent performance; providing a smooth UI experience even with complex Markdown on low end hardware. + +Under the hood, the control uses XAML sub-elements to build the visual rendering tree for the Markdown input. We chose to use full XAML elements overusing the RichEditTextBlock control because the RichEditTextBlock isn't flexible enough to correctly render all of the standard Markdown styles. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=MarkdownTextBlock) + +## Syntax + +```xaml + + +``` + +## Limitations + +Here are some limitations you may encounter: + +- All images are stretched with the same stretch value (defined by ImageStretch property) +- Relative Links & Relative Images needs to be handled manually using `LinkClicked` event. + +## Sample Output + +Note: scrolling is smooth, the gif below is not. + +![MarkdownTextBlock animation](images/markdowntextblock.gif "MarkdownTextBlock") + +## Properties + +The MarkdownTextBlock control is highly customizable to blend with any theme. Customizable properties include: + +| Property | Type | Description | +| -- | -- | -- | +| CodeBackground | Brush | Gets or sets the brush used to fill the background of a code block | +| CodeBorderBrush | Brush | Gets or sets the brush used to render the border fill of a code block | +| CodeBorderThickness | Thickness | Gets or sets the thickness of the border around code blocks | +| CodeFontFamily | FontFamily | Gets or sets the font used to display code. If this is `null`, then Windows.UI.Xaml.Media.FontFamily is used | +| CodeForeground | Brush | Gets or sets the brush used to render the text inside a code block. If this is `null`, then Foreground is used | +| CodeMargin | Thickness | Gets or sets the space between the code border and the text | +| CodePadding | Thickness | Gets or sets space between the code border and the text | +| CodeStyling | StyleDictionary | Gets or sets the Default Code Styling for Code Blocks | +| EmojiFontFamily | FontFamily | Gets or sets the font used to display emojis. If this is `null`, then Segoe UI Emoji font is used | +| Header1FontSize | double | Gets or sets the font size for level 1 headers | +| Header1FontWeight | FontWeight | Gets or sets the font weight to use for level 1 headers | +| Header1Foreground | Brush | Gets or sets the foreground brush for level 1 headers | +| Header1Margin | Thickness | Gets or sets the margin for level 1 headers | +| Header2FontSize | double | Gets or sets the font size for level 2 headers | +| Header2FontWeight | FontWeight | Gets or sets the font weight to use for level 2 headers | +| Header2Foreground | Brush | Gets or sets the foreground brush for level 2 headers | +| Header2Margin | Thickness | Gets or sets the margin for level 2 headers | +| Header3FontSize | double | Gets or sets the font size for level 3 headers | +| Header3FontWeight | FontWeight | Gets or sets the font weight to use for level 3 headers | +| Header3Foreground | Brush | Gets or sets the foreground brush for level 3 headers | +| Header3Margin | Thickness | Gets or sets the margin for level 3 headers | +| Header4FontSize | double | Gets or sets the font size for level 4 headers | +| Header4FontWeight | FontWeight | Gets or sets the font weight to use for level 4 headers | +| Header4Foreground | Brush | Gets or sets the foreground brush for level 4 headers | +| Header4Margin | Thickness | Gets or sets the margin for level 4 headers | +| Header5FontSize | double | Gets or sets the font size for level 5 headers | +| Header5FontWeight | FontWeight | Gets or sets the font weight to use for level 5 headers | +| Header5Foreground | Brush | Gets or sets the foreground brush for level 5 headers | +| Header5Margin | Thickness | Gets or sets the margin for level 5 headers | +| Header6FontSize | double | Gets or sets the font size for level 6 headers | +| Header6FontWeight | FontWeight | Gets or sets the font weight to use for level 6 headers | +| Header6Foreground | Brush | Gets or sets the foreground brush for level 6 headers | +| Header6Margin | Thickness | Gets or sets the margin for level 6 headers | +| HorizontalRuleBrush | Brush | Gets or sets the brush used to render a horizontal rule. If this is `null`, then HorizontalRuleBrush is used | +| HorizontalRuleMargin | Thickness | Gets or sets the margin used for horizontal rules | +| HorizontalRuleThickness | double | Gets or sets the vertical thickness of the horizontal rule | +| ImageMaxHeight | double | Gets or sets the MaxHeight for images | +| ImageMaxWidth | double | Gets or sets the MaxWidth for images | +| ImageStretch | Stretch | Gets or sets the stretch used for images | +| InlineCodeBackground | Brush | Gets or sets the foreground brush for inline code. | +| InlineCodeBorderBrush | Brush | Gets or sets the border brush for inline code | +| InlineCodeBorderThickness | Thickness | Gets or sets the thickness of the border for inline code | +| InlineCodeFontFamily | FontFamily | Gets or sets the font used to display code. If this is `null`, then `Windows.UI.Xaml.Media.FontFamily` is used | +| InlineCodePadding | Thickness | Gets or sets the padding for inline code | +| InlineCodeMargin | Thickness | Gets or sets the margin for inline code | +| IsTextSelectionEnabled | bool | Gets or sets a value indicating whether text selection is enabled | +| LinkForeground | Brush | Gets or sets the brush used to render links. If this is `null`, then Foreground is used | +| ListBulletSpacing | double | Gets or sets the space between the list item bullets/numbers and the list item content | +| ListGutterWidth | double | Gets or sets the width of the space used by list item bullets/numbers | +| ListMargin | Thickness | Gets or sets the margin used by lists | +| ParagraphMargin | Thickness | Gets or sets the margin used for paragraphs | +| ParagraphLineHeight | int | Gets or sets the line hegiht used for paragraphs. | +| QuoteBackground | Brush | Gets or sets the brush used to fill the background of a quote block | +| QuoteBorderBrush | Brush | Gets or sets the brush used to render a quote border. If this is null, then [QuoteBorderBrush](/dotnet/api/microsoft.toolkit.uwp.ui.controls.markdowntextblock.quoteborderbrush#Microsoft_Toolkit_Uwp_UI_Controls_MarkdownTextBlock_QuoteBorderBrush) is used | +| QuoteBorderThickness | Thickness | Gets or sets the thickness of quote borders. | +| QuoteForeground | Brush | Gets or sets the brush used to render the text inside a quote block. If this is `null`, then Foreground is used | +| QuoteMargin | Thickness | Gets or sets the space outside of quote borders | +| QuotePadding | Thickness | Gets or sets the space between the quote border and the text | +| SchemeList | string(separated by comma) | Gets or sets the custom SchemeList to render a URL. | +| TableBorderBrush | Brush | Gets or sets the brush used to render table borders. If this is null, then [TableBorderBrush](/dotnet/api/microsoft.toolkit.uwp.ui.controls.markdowntextblock.tableborderbrush#Microsoft_Toolkit_Uwp_UI_Controls_MarkdownTextBlock_TableBorderBrush) is used | +| TableBorderThickness | double | Gets or sets the thickness of any table borders | +| TableCellPadding | Thickness | Gets or sets the padding inside each cell | +| TableMargin | Thickness | Gets or sets the margin used by tables | +| YamlBorderThickness | Thickness | Gets or sets the thickness of any yaml header borders. | +| YamlBorderBrush | Brush | Gets or sets the brush used to render yaml header borders. If this is null, then [TableBorderBrush](/dotnet/api/microsoft.toolkit.uwp.ui.controls.markdowntextblock.tableborderbrush#Microsoft_Toolkit_Uwp_UI_Controls_MarkdownTextBlock_TableBorderBrush) is used | +| Text | string | Gets or sets the markdown text to display | +| TextWrapping | TextWrapping | Gets or sets the word wrapping behavior | +| UriPrefix | string | Gets or sets the Prefix of Uri | +| UseSyntaxHighlighting | bool | Gets or sets a value indicating whether to use Syntax Highlighting on Code | +| WrapCodeBlock | bool | Gets or sets a value indicating whether to Wrap the Code Block or use a Horizontal Scroll | + +## Events + +| Events | Description | +| -- | -- | +| CodeBlockResolving | Fired when a Code Block is being Rendered. The default implementation is to output the CodeBlock as Plain Text. You must set `Handled` to `true` in order to process your changes | +| ImageClicked | Fired when an image element in the markdown was tapped | +| ImageResolving | Fired when an image from the markdown document needs to be resolved. The default implementation is basically. You must set `Handled` to `true` in order to process your changes | +| LinkClicked | Fired when a link element in the markdown was tapped | +| MarkdownRendered | Fired when the text is done parsing and formatting. Fires each time the markdown is rendered | + +### LinkClicked + +Use this event to handle clicking on links for Markdown, by default the MarkdownTextBlock does not handle Clicking on Links. + +```csharp +private async void MarkdownText_LinkClicked(object sender, LinkClickedEventArgs e) +{ + if (Uri.TryCreate(e.Link, UriKind.Absolute, out Uri link)) + { + await Launcher.LaunchUriAsync(link); + } +} +``` + +### ImageClicked + +Use this event to handle clicking on images for Markdown, by default the MarkdownTextBlock does not handle Clicking on Images. + +```csharp +private async void MarkdownText_ImageClicked(object sender, LinkClickedEventArgs e) +{ + if (Uri.TryCreate(e.Link, UriKind.Absolute, out Uri link)) + { + await Launcher.LaunchUriAsync(link); + } +} +``` + +### ImageResolving + +Use this event to customize how images in the markdown document are resolved. + +Set the ImageResolvingEventArgs.Image property to the image that should be shown in the rendered markdown document. +Also don't forget to set the ImageResolvingEventArgs.Handled flag to true, otherwise your custom image will not be used. + +```csharp +private void MarkdownText_OnImageResolving(object sender, ImageResolvingEventArgs e) +{ + // This is basically the default implementation + e.Image = new BitmapImage(new Uri(e.Url)); + e.Handled = true; +} +``` + +This event also supports loading the image in an asynchronous way. +Just request a Deferral which you complete when you're done. + +```csharp +private async void MarkdownText_OnImageResolving(object sender, ImageResolvingEventArgs e) +{ + var deferral = e.GetDeferral(); + + e.Image = await GetImageFromDatabaseAsync(e.Url); + e.Handled = true; + + deferral.Complete(); +} +``` + +### CodeBlockResolving + +Use this event to customise how Code Block text is rendered, this is useful for providing Cusom Syntax Highlighting. Built in Syntax Highlighting is already provided with `UseSyntaxHighlighting`. + +Manipulate the Inline Collection, and then set e.Handled to true, otherwise the changes won't be processed. + +```csharp +private void MarkdownText_CodeBlockResolving(object sender, CodeBlockResolvingEventArgs e) +{ + if (e.CodeLanguage == "CUSTOM") + { + e.Handled = true; + e.InlineCollection.Add(new Run { Foreground = new SolidColorBrush(Colors.Red), Text = e.Text, FontWeight = FontWeights.Bold }); + } +} +``` + +## Rendering + +You can customise the rendering of the **MarkdownTextBlock**, by inheriting from `MarkdownRenderer` and setting it as the renderer: + +```csharp +var block = new MarkdownTextBlock(); +block.SetRenderer(); +``` + +This will likely require intimate knowledge of the implementation of the `MarkdownRenderer`, take a look at the following: + +- MarkdownRenderer and Helpers (`https://github.com/windows-toolkit/WindowsCommunityToolit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Markdown/MarkdownTextBlock/Render`) +- [Sample App custom markdown renderer](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/6.1.1/Microsoft.Toolkit.Uwp.SampleApp/Controls/SampleAppMarkdownRenderer.cs) + +## Sample Project + +[MarkdownTextBlock Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/MarkdownTextBlock). You can [see this in action](uwpct://Controls?sample=MarkdownTextBlock) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[MarkdownTextBlock XAML File](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Markdown/MarkdownTextBlock/MarkdownTextBlock.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +- [MarkdownTextBlock source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Markdown/MarkdownTextBlock) + +## Related Topics + +- [Markdown Parser](markdownparser.md) diff --git a/docs/archive/windows/masterdetailsview.md b/docs/archive/windows/masterdetailsview.md new file mode 100644 index 00000000..6ef06999 --- /dev/null +++ b/docs/archive/windows/masterdetailsview.md @@ -0,0 +1,76 @@ +--- +title: ListDetailsView +author: nmetulev +description: The ListDetailsView Control presents items in a list/details pattern. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, ListDetailsView, XAML Control, xaml +--- + +# ListDetailsView (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [GitHub discussion for ListDetailsView port](https://github.com/CommunityToolkit/Windows/discussions/405) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [ListDetailsView](/dotnet/api/microsoft.toolkit.uwp.ui.controls.listdetailsview) control presents items in a list/details pattern. It shows a collection of items within the "list panel" and the details for that item within the "details panel". The ListDetailsView reacts to the width it is given to determine if it should show both the list and details or just one of the two. There is a dependency property `ViewState` or an event `ViewStateChanged` that can be used to track which state the control is in. + +> **Platform APIs:** [`ListDetailsView`](/dotnet/api/microsoft.toolkit.uwp.ui.controls.listdetailsview), [`ListDetailsViewState`](/dotnet/api/microsoft.toolkit.uwp.ui.controls.listdetailsviewstate) + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=ListDetailsView) + +## Syntax + +```xaml + +``` + +## Sample Output + +![ListDetailsView animation](images/listdetailsview.gif) + +## Multi Screen Devices + +This control is spanning-aware and adapts it self for multi screen devices. +For this internally the [Two-pane view](/windows/uwp/design/controls-and-patterns/two-pane-view) is used. + +## BackButtonBehavior + +When in compact mode, the `ListDetailsView` will either show the List or the Details view, not both. If an item is selected, the control will *navigate* forward to the Details view. If the CurrentItem is set to `null`, the control will navigate *back* to the List view. + +If there is a Frame in the parent visual tree, the ListDetailsView control will use the Frame navigation events to transition from the Details view to the List view. If the host Frame is attempting back navigation while the Details view state is active, the ListDetailsView will transition to the the List view and cancel the back navigation. + +To help with back navigation, The ListDetailsView can handle back button visibility of the SystemNavigationManager back button, a parent NavigationView back button, or an inline back button. Use the `BackButtonBehavior` property to control the behavior: + +- `Automatic` will let the control decide which back button to make visible/enabled. + - If the system back button is visible the control won't use any other buttons + - Else, if the control parent tree contains a Frame hosted in a NavigationView, the NavigationView back button will be used + - Otherwise, an inline button will be used +- `System` will use the system back button controlled by the SystemNavigationManager. The control will make the button visible (if not already visible) when in the Details view and restore the visibility when transitioning to the List view. This is the default value. +- `Inline` will use a back button built into the control +- `Manual` will not enable any back buttons (if using a custom button). + +## Sample Project + +[ListDetailsView Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/ListDetailsView). You can [see this in action](uwpct://Controls?sample=ListDetailsView) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[ListDetailsView XAML File](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Layout/ListDetailsView/ListDetailsView.xaml) is the XAML template used in the toolkit for the default styling. + +## API + +- [ListDetailsView source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Layout/ListDetailsView) diff --git a/docs/archive/windows/notificationsoverview.md b/docs/archive/windows/notificationsoverview.md new file mode 100644 index 00000000..c5e6e6f0 --- /dev/null +++ b/docs/archive/windows/notificationsoverview.md @@ -0,0 +1,66 @@ +--- +title: Notifications Overview +author: andrewleader +description: Instead of having to deal with XML, you can now use Windows Community toolkit and its notification extensions to work with Tiles and notifications using a complete object model. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, adaptive live tiles, interactive toast, tiles, notifications +--- + +# Notifications Overview (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. + +For WinUI 3 apps, notifications were superseded by the [App notifications](/windows/apps/windows-app-sdk/notifications/app-notifications/) feature in the Windows App SDK. + +For UWP apps, the original notifications package was ported to [Windows Community Toolkit Labs](https://github.com/CommunityToolkit/Labs-Windows) and is available only for UWP applications. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +Adaptive Live Tiles and interactive Toasts are key engagement components of a UWP Application on Windows 10. +Instead of having to deal with XML, you can now use Windows Community toolkit and its notification extensions to work with Tiles and notifications using a complete object model. + +## Tiles + +| Documentation | +| --- | +| [Create Adaptive Tile](/windows/uwp/design/shell/tiles-and-notifications/create-adaptive-tiles) | +| [Sending a local Tile notification](/windows/uwp/design/shell/tiles-and-notifications/sending-a-local-tile-notification) | + +### Sample Output + +![LiveTile Image](images/livetile.gif) + +## Toasts + +| Documentation | +| --- | +| [Interactive Toast Notifications](/windows/uwp/design/shell/tiles-and-notifications/adaptive-interactive-toasts) | +| [Send a local toast](/windows/uwp/design/shell/tiles-and-notifications/send-local-toast) + +### Sample Output + +![Toast](images/poptoast.gif "Toast") + +### Sending toasts from desktop C# apps + +If you're developing a non-UWP C# app for Windows, the Windows Community Toolkit makes it easier to send an interactive toast notification from your desktop C# app. To learn more, see [Send a local toast notification from C# apps](/windows/uwp/design/shell/tiles-and-notifications/send-local-toast). + +## Requirements + +| Device family | Universal, 10.0.10240.0 or higher | +| --- | --- | +| Namespace for C# | Microsoft.Toolkit.Uwp.Notifications | +| Namespace for JavaScript | Microsoft.Toolkit.Uwp.Notifications.Javascript | + +## API + +* [Notifications source code](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.Notifications) + +## Related Topics + +* [Toast Notification UX Guidance](/windows/uwp/design/shell/tiles-and-notifications/toast-ux-guidance) diff --git a/docs/archive/windows/objectserializer.md b/docs/archive/windows/objectserializer.md new file mode 100644 index 00000000..be90785f --- /dev/null +++ b/docs/archive/windows/objectserializer.md @@ -0,0 +1,127 @@ +--- +title: Object Serializer +author: simop +description: IObjectSerializer is an interface that you can implement to provide a serializer of your choice to ObjectStorageHelper. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, serialization +dev_langs: + - csharp + - vb +--- + +# ObjectSerializer (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +You should implement IObjectSerializer when you need to write data using this toolkit's helpers with a custom serializer. If you don't, a default JSON serializer will be used otherwise. + +## Methods + +| Methods | Return Type | Description | +|---------|-------------|-------------| +| Serialize\(T) | object | Serialize an object of type T into a object. | +| Deserialize\(object) | T | Deserialize a object to an object of type T. | + +## Examples + +### System.Text.Json + +```cs +using Microsoft.Toolkit.Uwp.Helpers; +using System.Text.Json; + +namespace Contoso.Helpers +{ + public class SystemTextJsonObjectSerializer : IObjectSerializer + { + public object Serialize(T value) => JsonSerializer.Serialize(value); + + public T Deserialize(object value) => JsonSerializer.Deserialize((string)value); + } +} +``` + +### Json.NET + +```csharp +using Microsoft.Toolkit.Uwp.Helpers; +using Newtonsoft.Json; + +namespace Contoso.Helpers +{ + public class JsonNetObjectSerializer : IObjectSerializer + { + // Specify your serialization settings + private readonly JsonSerializerSettings settings = new JsonSerializerSettings(); + + public object Serialize(T value) => JsonConvert.SerializeObject(value, typeof(T), Formatting.Indented , settings); + + public T Deserialize(object value) => JsonConvert.DeserializeObject((string)value, settings); + } +} +``` + +### DataContract + +```csharp +using Microsoft.Toolkit.Uwp.Helpers; +using System.IO; +using System.Runtime.Serialization; +using System.Xml; + +namespace Contoso.Helpers +{ + public class DataContractObjectSerializer : IObjectSerializer + { + // Specify your serialization settings + private readonly DataContractSerializerSettings settings = new DataContractSerializerSettings(); + + public object Serialize(T value) + { + var serializer = new DataContractSerializer(typeof(T), settings); + + using (var stringWriter = new StringWriter()) + using (var xmlWriter = XmlWriter.Create(stringWriter)) + { + serializer.WriteObject(xmlWriter, value); + return stringWriter.ToString(); + } + } + + public T Deserialize(object value) + { + var serializer = new DataContractSerializer(typeof(T), settings); + + using (var stringReader = new StringReader((string)value)) + using (var xmlReader = XmlReader.Create(stringReader)) + { + return (T)serializer.ReadObject(xmlReader); + } + } + } +} +``` + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +## API + +* [IObjectSerializer source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/ObjectStorage/IObjectSerializer.cs) + +## Related topics + +* [ObjectStorage](./objectstorage.md) diff --git a/docs/archive/windows/objectstorage.md b/docs/archive/windows/objectstorage.md new file mode 100644 index 00000000..eb39670a --- /dev/null +++ b/docs/archive/windows/objectstorage.md @@ -0,0 +1,244 @@ +--- +title: Object Storage +author: nmetulev +description: The Object Storage Helper will help you handle storage of generic objects within UWP applications, both locally and across all devices (roaming). +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Object Storage, local storage, roaming storage +dev_langs: + - csharp + - vb +--- + +# Object Storage (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The Object Storage Helper will help you handle storage of generic objects within UWP applications, both locally and across all devices (roaming). + +- [LocalObjectStorageHelper Class](/dotnet/api/microsoft.toolkit.uwp.helpers.localobjectstoragehelper) store data in the Local environment (only on the current device) +- [RoamingObjectStorageHelper Class](/dotnet/api/microsoft.toolkit.uwp.helpers.roamingobjectstoragehelper) + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Helpers?sample=Object%20Storage) + +## Constructors + +LocalObjectStorageHelper and RoamingObjectStorageHelper have the same constructor with an optional parameter: + +| Constructor | Description | +|-------------|-------------| +| ObjectStorageHelper(IObjectSerializer = null) | Initializes a new instance of the ObjectStorageHelper class with the provided [IObjectSerializer](objectserializer.md), that will be used when serializing and deserializing data in Settings or in Storage; if no serializer is provided, a default JSON serializer will be used. | + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| Folder | StorageFolder | Gets or sets storage folder | +| Settings | ApplicationDataContainer | Gets or sets settings container | + +## Methods + +| Methods | Return Type | Description | +|---------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| FileExistsAsync(String) | Task\ | Detect if a file already exists | +| KeyExists(String) | bool | Detect if a setting already exists | +| KeyExists(String, String) | bool | Detect if a setting already exists in composite | +| Read(String, T) | T | Retrieve single item by its key | +| Read(String, String, T) | T | Retrieve single item by its key in composite | +| ReadFileAsync(String, T) | Task\ | Retrieve object from file | +| Save(String, IDictionary) | void | Save a group of items by its key in a composite. This method should be considered for objects that do not exceed 8k bytes during the lifetime of the application (refers to SaveFileAsync\(String, T) for complex/large objects) and for groups of settings which need to be treated in an atomic way | +| Save(String, T) | void | Save single item by its key. This method should be considered for objects that do not exceed 8k bytes during the lifetime of the application (refers to SaveFileAsync\(String, T) for complex/large objects) | +| SaveFileAsync(String, T) | Task\ | Save object inside file. There is no limitation to use this method (refers to Save\(String, T) method for simple objects) | + +## Example + +### Local Storage + +If you need to handle local saves of any object (generic), you can use [LocalObjectStorageHelper](/dotnet/api/microsoft.toolkit.uwp.helpers.localobjectstoragehelper). + +```csharp +var helper = new LocalObjectStorageHelper(); + +// Read simple objects +string keySimpleObject = "simple"; +if (helper.KeyExists(keySimpleObject)) +{ + string result = helper.Read(keySimpleObject); +} + +// Read simple objects in a composite +string keyCompositeObject = "composite"; +if (helper.KeyExists(keyCompositeObject, keySimpleObject)) +{ + string result = helper.Read(keyCompositeObject, keySimpleObject); +} + +// Save simple objects +helper.Save(keySimpleObject, 47); + +// Save simple objects in a composite +Dictionary simpleObjects = new Dictionary(); +simpleObjects.Add("simpleObjectValueOne", 47); +simpleObjects.Add("simpleObjectValueTwo", "hello!"); +helper.Save(keyCompositeObject, simpleObjects); + +// Read complex/large objects +string keyLargeObject = "large"; +if (await helper.FileExistsAsync(keyLargeObject)) +{ + var result = await helper.ReadFileAsync(keyLargeObject); +} + +// Save complex/large objects +var o = new MyLargeObject +{ + ... +}; +await helper.SaveFileAsync(keySimpleObject, o); +``` + +```vb +Dim helper = New LocalObjectStorageHelper() + +' Read simple objects +Dim keySimpleObject As String = "simple" +If helper.KeyExists(keySimpleObject) Then + Dim result As String = helper.Read(Of String)(keySimpleObject) +End If + +' Read simple objects in a composite +Dim keyCompositeObject As String = "composite" +If helper.KeyExists(keyCompositeObject, keySimpleObject) Then + Dim result As String = helper.Read(Of String)(keyCompositeObject, keySimpleObject) +End If + +' Save simple objects +helper.Save(keySimpleObject, 47) + +' Save simple objects in a composite +Dictionary(Of String, Object) simpleObjects = New Dictionary(Of String, Object)() +simpleObjects.Add("simpleObjectValueOne", 47) +simpleObjects.Add("simpleObjectValueTwo", "hello!") +helper.Save(keyCompositeObject, simpleObjects) + +' Read complex/large objects +Dim keyLargeObject As String = "large" +If Await helper.FileExistsAsync(keyLargeObject) Then + Dim result = Await helper.ReadFileAsync(Of MyLargeObject)(keyLargeObject) +End If + +' Save complex/large objects +Dim o = New MyLargeObject With { + ... +} +Await helper.SaveFileAsync(keySimpleObject, o) +``` + +### Roaming Storage + +In the same way, if you need to handle roaming saves across all of user devices, you can use `RoamingObjectStorageHelper`. +The implementation of the `RoamingObjectStorageHelper` is absolutely similar to `LocalObjectStorageHelper`. + +```csharp +var helper = new RoamingObjectStorageHelper(); + +// Read simple objects +string keySimpleObject = "simple"; +if (helper.KeyExists(keySimpleObject)) +{ + string result = helper.Read(keySimpleObject); +} + +// Read simple objects in a composite +string keyCompositeObject = "composite"; +if (helper.KeyExists(keyCompositeObject, keySimpleObject)) +{ + string result = helper.Read(keyCompositeObject, keySimpleObject); +} + +// Save simple objects +helper.Save(keySimpleObject, 47); + +// Save simple objects in a composite +Dictionary simpleObjects = new Dictionary(); +simpleObjects.Add("simpleObjectValueOne", 47); +simpleObjects.Add("simpleObjectValueTwo", "hello!"); +helper.Save(keyCompositeObject, simpleObjects); + +// Read complex/large objects +string keyLargeObject = "large"; +if (await helper.FileExistsAsync(keyLargeObject)) +{ + var result = await helper.ReadFileAsync(keyLargeObject); +} + +// Save complex/large objects +var o = new MyLargeObject +{ + ... +}; +await helper.SaveFileAsync(keySimpleObject, o); +``` + +```vb +Dim helper = New RoamingObjectStorageHelper() + +' Read simple objects +Dim keySimpleObject As String = "simple" +If helper.KeyExists(keySimpleObject) Then + Dim result As String = helper.Read(Of String)(keySimpleObject) +End If + +' Read simple objects in a composite +Dim keyCompositeObject As String = "composite" +If helper.KeyExists(keyCompositeObject, keySimpleObject) Then + Dim result As String = helper.Read(Of String)(keyCompositeObject, keySimpleObject) +End If + +' Save simple objects +helper.Save(keySimpleObject, 47) + +' Save simple objects in a composite +Dictionary(Of String, Object) simpleObjects = New Dictionary(Of String, Object)() +simpleObjects.Add("simpleObjectValueOne", 47) +simpleObjects.Add("simpleObjectValueTwo", "hello!") +helper.Save(keyCompositeObject, simpleObjects) + +' Read complex/large objects +Dim keyLargeObject As String = "large" +If Await helper.FileExistsAsync(keyLargeObject) Then + Dim result = Await helper.ReadFileAsync(Of MyLargeObject)(keyLargeObject) +End If + +' Save complex/large objects +Dim o = New MyLargeObject With { + ... +} +Await helper.SaveFileAsync(keySimpleObject, o) +``` + +## Sample Project + +[Object Storage sample page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Object%20Storage). You can [see this in action](uwpct://Helpers?sample=Object%20Storage) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +## API + +- [LocalObjectStorageHelper source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/ObjectStorage/LocalObjectStorageHelper.cs) +- [RoamingObjectStorageHelper source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/ObjectStorage/RoamingObjectStorageHelper.cs) +- [IObjectSerializer source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/ObjectStorage/IObjectSerializer.cs) diff --git a/docs/archive/windows/orbitview.md b/docs/archive/windows/orbitview.md new file mode 100644 index 00000000..556facc0 --- /dev/null +++ b/docs/archive/windows/orbitview.md @@ -0,0 +1,166 @@ +--- +title: OrbitView +author: nmetulev +description: The OrbitView is an ItemsControl where all items are arranged in circle around a center element +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, OrbitView, xaml control, xaml +--- + +# OrbitView (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: + +https://github.com/CommunityToolkit/Windows/issues/90 +- [GitHub tracking issue for OrbitView port](https://github.com/CommunityToolkit/Labs-Windows/issues/606) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [OrbitView](/dotnet/api/microsoft.toolkit.uwp.ui.controls.orbitview) control provides a new control, inherited from the `ItemsControl`. All items are arranged in circle around a center element + +[OrbitViewDataItem](/dotnet/api/microsoft.toolkit.uwp.ui.controls.orbitviewdataitem) is a helper class used for specifying size and distance of each item of the `OrbitView`. To work properly, the `ItemSource` of the `OrbitView` should be set to en `IEnumerable`. Objects extending OrbitViewDataItem will also work. Alternatively, OrbitViewDataItem has the `Item` object property that can be used to store additional objects and properties. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=OrbitView) + +## Syntax + +```xaml + + + + + + + + + + + + + + + + + + + +``` + +## Sample Output + +![OrbitView Overview](images/orbitview.gif) + +## Properties + +### OrbitView Properties + +| Property | Type | Description | +| -- | -- | -- | +| AnchorColor | Brush | Gets or sets a value indicating the color of anchors | +| AnchorsEnabled | bool | Gets or sets a value indicating whether anchors are enabled | +| AnchorThickness | double | Gets or sets a value indicating the thickness of the anchors | +| CenterContent | object | Gets or sets a value representing the center element | +| IsItemClickEnabled | bool | Gets or sets a value indicating whether elements are clickable | +| MaxItemSize | double | Gets or sets a value indicating the maximum size of items | +| MinItemSize | double | Gets or sets a value indicating the minimum size of items Note: for this property to work, Data Context must be derived from OrbitViewItems and Diameter must be between 0 and 1 | +| OrbitColor | Brush | Gets or sets a value indicating the color of orbits | +| OrbitDashArray | DoubleCollection | Gets or sets a value indicating the dash array for the orbit | +| OrbitsEnabled | bool | Gets or sets a value indicating whether orbits are enabled or not | +| OrbitThickness | double | Gets or sets a value indicating the thickness of the orbits | + +> [!IMPORTANT] +> For `MaxItemSize` and `MinItemSize` property to work, Data Context must be derived from OrbitViewItems and Diameter must be between 0 and 1 + +### OrbitViewDataItem Properties + +| Property | Type | Description | +| -- | -- | -- | +| Diameter | double | Gets or sets a value indicating the diameter of the item. Expected value betweeen 0 and 1 | +| Distance | double | Gets or sets a value indicating the distance from the center. Expected value betweeen 0 and 1 | +| Image | ImageSource | Gets or sets a value indicating the image of the item | +| Item | object | Gets or sets a value of an object that can be used to store model data | +| Label | string | Gets or sets a value indicating the name of the item. Used for [AutomationProperties](/uwp/api/Windows.UI.Xaml.Automation.AutomationProperties) | + +## Events + +### OrbitView Events + +| Events | Description | +| -- | -- | +| ItemClick | Raised when an item has been clicked or activated with keyboard/controller | + +> [!IMPORTANT] +> `IsItemClickedEnabled` should be true for this event to work + +## Examples + +The following sample demonstrates how to add OrbitView Control. + +```xaml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +## Sample Project + +[Carousel Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/OrbitView).You can [see this in action](uwpct://Controls?sample=OrbitView) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[OrbitView XAML File](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Layout/OrbitView/OrbitView.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +* [OrbitView source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Layout/OrbitView) diff --git a/docs/archive/windows/printhelper.md b/docs/archive/windows/printhelper.md new file mode 100644 index 00000000..98c7a9fa --- /dev/null +++ b/docs/archive/windows/printhelper.md @@ -0,0 +1,333 @@ +--- +title: Print Helper +author: nmetulev +description: The PrintHelper is a Windows Community Toolkit helper class that enables the rendering of a framework element per page for printing purposes +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, PrintHelper +dev_langs: + - csharp + - vb +--- + +# Print Helper (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The PrintHelper is a class used to simplify document printing. +It allows you to render a framework element per page. + +To use it, you only have to instantiate a `PrintHelper` object and call `AddFrameworkElementToPrint` method to add the XAML controls you want to print. +Please note that controls cannot be linked to a visual tree. This means that their parent property has to be null. +If you want to use a control from your current XAML page, you can disconnect it before sending it to print (by removing it from its container) or you can create just create a new one from scratch. + +Please check the sample app code to see how to disconnect/reconnect a control that you want to print: + + +Several events are available to control the printing process: + +* OnPrintFailed will be triggered if the user cancels the print or if something goes wrong +* OnPrintSucceeded will be triggered after a successful print +* OnPreviewPagesCreated will be triggered after print preview pages are generated. This allows you to control the look and feel of your page before they are sent to the spooler. + +In addition, you can customize the printing dialog using the `PrintHelperOptions` class. To use it, create an instance of the class, add the options you'd like to display on the printing dialog and set the default options. Then, you can use it as a parameter in the `PrintHelper` class constructor to set them as the default for the instance, or send them as parameters to `ShowPrintUIAsync` to use them for a single print job. + +You can call `ShowPrintUIAsync` with a second parameter to determine that the list of controls to print should directly be taken from the content of the container passed to the PrintHelper constructor. In this mode you are responsible for the sizing and the layout. + +> [!IMPORTANT] +> Printing in Dark Theme will likely print white text, which won't be visible. To fix this, ensure the text is a visible color before printing, then restore the original color. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Helpers?sample=PrintHelper) + +## Syntax + +```csharp +var printHelper = new PrintHelper(container); + +printHelper.AddFrameworkElementToPrint(frameworkElement); + +await printHelper.ShowPrintUIAsync("Title"); +``` + +```vb +Dim printHelper = New PrintHelper(container) + +printHelper.AddFrameworkElementToPrint(frameworkElement) + +Await printHelper.ShowPrintUIAsync("Title") +``` + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| ApplicationContentMarginLeft | double | Gets or sets the percent of app's margin width | +| ApplicationContentMarginTop | double | Gets or sets the percent of app's margin height | + +## Methods + +| Methods | Return Type | Description | +| -- | -- | -- | +| AddFrameworkElementToPrint(FrameworkElement) | void | Add an element to the list of printable elements | +| ClearListOfPrintableFrameworkElements() | void | Empties the list of printable elements | +| Dispose() | void | Release associated resources | +| RemoveFrameworkElementToPrint(FrameworkElement) | void | Remove an element from the list of printable elements | +| ShowPrintUIAsync(String, Boolean) | Task | Start the print task | + +## Events + +| Events | Description | +| -- | -- | +| OnPreviewPagesCreated | Event which is called after print preview pages are generated | +| OnPrintCanceled | Event raised when print is cancelled by the user | +| OnPrintFailed | Event raised when print failed | +| OnPrintSucceeded | Event raised when print was successful | + +## Example + +```csharp +// Create a new PrintHelper instance +// "container" is a XAML panel that will be used to host printable control. +// It needs to be in your visual tree but can be hidden with Opacity = 0 +var printHelper = new PrintHelper(container); + +// Add controls that you want to print +printHelper.AddFrameworkElementToPrint(await PrepareWebViewForPrintingAsync()); + +// Connect to relevant events +printHelper.OnPrintFailed += PrintHelper_OnPrintFailed; +printHelper.OnPrintSucceeded += PrintHelper_OnPrintSucceeded; + +// Start printing process +await printHelper.ShowPrintUIAsync("Windows Community Toolkit Sample App"); + +// Event handlers + +private async void PrintHelper_OnPrintSucceeded() +{ + printHelper.Dispose(); + var dialog = new MessageDialog("Printing done."); + await dialog.ShowAsync(); +} + +private async void PrintHelper_OnPrintFailed() +{ + printHelper.Dispose(); + var dialog = new MessageDialog("Printing failed."); + await dialog.ShowAsync(); +} +``` + +```vb +' Create a new PrintHelper instance +' "container" is a XAML panel that will be used to host printable control. +' It needs to be in your visual tree but can be hidden with Opacity = 0 +Dim printHelper = New PrintHelper(container) + +' Add controls that you want to print +printHelper.AddFrameworkElementToPrint(Await PrepareWebViewForPrintingAsync()) + +' Connect to relevant events +printHelper.OnPrintFailed += PrintHelper_OnPrintFailed +printHelper.OnPrintSucceeded += PrintHelper_OnPrintSucceeded + +' Start printing process +Await printHelper.ShowPrintUIAsync("Windows Community Toolkit Sample App") + +' Event handlers + +Private Async Sub PrintHelper_OnPrintSucceeded() + printHelper.Dispose() + Dim dialog = New MessageDialog("Printing done.") + Await dialog.ShowAsync() +End Sub + +Private Async Sub PrintHelper_OnPrintFailed() + printHelper.Dispose() + Dim dialog = New MessageDialog("Printing failed.") + Await dialog.ShowAsync() +End Sub +``` + +**Direct print example:** + +```csharp +// Create a new PrintHelper instance +// "container" is a XAML panel that will be used to get the list of printable controls. +var printHelper = new PrintHelper(container); + +// Start printing process +await printHelper.ShowPrintUIAsync("Windows Community Toolkit Sample App", true); +``` + +```vb +' Create a new PrintHelper instance +' "container" is a XAML panel that will be used to get the list of printable controls. +Dim printHelper = New PrintHelper(container) + +' Start printing process +Await printHelper.ShowPrintUIAsync("Windows Community Toolkit Sample App", True) +``` + +**Using custom default settings:** + +```csharp +// Create a new PrintHelperOptions instance +var defaultPrintHelperOptions = new PrintHelperOptions(); + +//Add options that you want to be displayed on the print dialog +defaultPrintHelperOptions.AddDisplayOption(StandardPrintTaskOptions.Orientation); + +//Set preselected settings +defaultPrintHelperOptions.Orientation = PrintOrientation.Landscape; + +// Create a new PrintHelper instance +// "container" is a XAML panel that will be used to get the list of printable controls. +var printHelper = new PrintHelper(container, defaultPrintHelperOptions); +``` + +```vb +' Create a new PrintHelperOptions instance +Dim defaultPrintHelperOptions = New PrintHelperOptions() + +' Add options that you want to be displayed on the print dialog +defaultPrintHelperOptions.AddDisplayOption(StandardPrintTaskOptions.Orientation) + +' Set preselected settings +defaultPrintHelperOptions.Orientation = PrintOrientation.Landscape + +' Create a new PrintHelper instance +' "container" is a XAML panel that will be used to get the list of printable controls. +Dim printHelper = New PrintHelper(container, defaultPrintHelperOptions) +``` + +**Using custom settings for one print job:** + +```csharp +// Create a new PrintHelper instance +// "container" is a XAML panel that will be used to get the list of printable controls. +// "defaultPrintHelperOptions" is a PrintHelperOptions instance that will be used to get the default options for printing. +var printHelper = new PrintHelper(container, defaultPrintHelperOptions); + +// Create a new PrintHelperOptions instance +var printHelperOptions = new PrintHelperOptions(); + +//Add options that you want to be displayed on the print dialog +printHelperOptions.AddDisplayOption(StandardPrintTaskOptions.Orientation); + +//Set preselected settings +printHelperOptions.Orientation = PrintOrientation.Landscape; + +// Start printing process +await _printHelper.ShowPrintUIAsync("Windows Community Toolkit Sample App", printHelperOptions); +``` + +```vb +' Create a new PrintHelper instance +' "container" is a XAML panel that will be used to get the list of printable controls. +' "defaultPrintHelperOptions" is a PrintHelperOptions instance that will be used to get the default options for printing. +Dim printHelper = New PrintHelper(container, defaultPrintHelperOptions) + +' Create a new PrintHelperOptions instance +Dim printHelperOptions = New PrintHelperOptions() + +' Add options that you want to be displayed on the print dialog +printHelperOptions.AddDisplayOption(StandardPrintTaskOptions.Orientation) + +' Set preselected settings +printHelperOptions.Orientation = PrintOrientation.Landscape + +' Start printing process +Await _printHelper.ShowPrintUIAsync("Windows Community Toolkit Sample App", printHelperOptions) +``` + +**Print a list with each item on a separate page with static header and page number:** + +```csharp +// Create a new PrintHelper instance +// "container" is a XAML panel that will be used to get the list of printable controls. +var printHelper = new PrintHelper(container); + +var pageNumber = 0; + +foreach (var item in PrintSampleItems) +{ + var grid = new Grid(); + grid.RowDefinitions.Add(new RowDefinition() { Height = GridLength.Auto }); + grid.RowDefinitions.Add(new RowDefinition() { Height = new GridLength(1, GridUnitType.Star) }); + grid.RowDefinitions.Add(new RowDefinition() { Height = GridLength.Auto }); + + // Static header + var header = new TextBlock { Text = "Windows Community Toolkit Sample App - Print Helper - Custom Print", Margin = new Thickness(0, 0, 0, 20) }; + Grid.SetRow(header, 0); + grid.Children.Add(header); + + // Main content with layout from data template + var cont = new ContentControl(); + cont.ContentTemplate = Resources["CustomPrintTemplate"] as DataTemplate; + cont.DataContext = item; + Grid.SetRow(cont, 1); + grid.Children.Add(cont); + + // Footer with page number + pageNumber++; + var footer = new TextBlock { Text = string.Format("page {0}", pageNumber), Margin = new Thickness(0, 20, 0, 0) }; + Grid.SetRow(footer, 2); + grid.Children.Add(footer); + + printHelper.AddFrameworkElementToPrint(grid); +} + +// Start printing process +await printHelper.ShowPrintUIAsync("Windows Community Toolkit Sample App", printHelperOptions); +``` + +```vb + Dim printHelper = New PrintHelper(container) + Dim pageNumber = 0 + For Each item In PrintSampleItems + Dim grid = New Grid() + grid.RowDefinitions.Add(New RowDefinition() With {.Height = GridLength.Auto}) + grid.RowDefinitions.Add(New RowDefinition() With {.Height = New GridLength(1, GridUnitType.Star)}) + grid.RowDefinitions.Add(New RowDefinition() With {.Height = GridLength.Auto}) + Dim header = New TextBlock With {.Text = "Windows Community Toolkit Sample App - Print Helper - Custom Print", .Margin = New Thickness(0, 0, 0, 20)} + Grid.SetRow(header, 0) + grid.Children.Add(header) + Dim cont = New ContentControl() + cont.ContentTemplate = TryCast(Resources("CustomPrintTemplate"), DataTemplate) + cont.DataContext = item + Grid.SetRow(cont, 1) + grid.Children.Add(cont) + pageNumber += 1 + Dim footer = New TextBlock With {.Text = String.Format("page {0}", pageNumber), .Margin = New Thickness(0, 20, 0, 0)} + Grid.SetRow(footer, 2) + grid.Children.Add(footer) + printHelper.AddFrameworkElementToPrint(grid) + Next + + Await printHelper.ShowPrintUIAsync("Windows Community Toolkit Sample App", printHelperOptions) +``` + +## Sample Project + +[PrintHelper Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/PrintHelper). You can [see this in action](uwpct://Helpers?sample=PrintHelper) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +## API + +* [Print Helper source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/PrintHelper/) diff --git a/docs/archive/windows/remotedevicehelper.md b/docs/archive/windows/remotedevicehelper.md new file mode 100644 index 00000000..31a9ea4e --- /dev/null +++ b/docs/archive/windows/remotedevicehelper.md @@ -0,0 +1,117 @@ +--- +title: RemoteDeviceHelper +author: avknaidu +description: The RemoteDeviceHelper is a Helper to get a List Remote Devices that are accessible. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, RemoteDeviceHelper, helper +dev_langs: + - csharp +--- + +# RemoteDeviceHelper (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [RemoteDeviceHelper](/dotnet/api/microsoft.toolkit.uwp.helpers.remotedevicehelper) gives you a list of Remote Systems. All the systems must be signed in with the same Microsoft Account (MSA) + +> [!IMPORTANT] +> Make sure you enable the [RemoteSystem capability](/windows/uwp/packaging/app-capability-declarations#general-use-capabilities) in your app's `package.appxmanifest` to access remote system information. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Helpers?sample=RemoteDeviceHelper) + +## Syntax + +```csharp + +RemoteDeviceHelper _remoteDeviceHelper = new RemoteDeviceHelper(); + +``` + +You can also use default filter types for initializing. Like Below. + +```csharp + +var filters = new List +{ + new RemoteSystemDiscoveryTypeFilter(RemoteSystemDiscoveryType.Cloud), + new RemoteSystemAuthorizationKindFilter(RemoteSystemAuthorizationKind.SameUser), + new RemoteSystemStatusTypeFilter(RemoteSystemStatusType.Available) +}; + +RemoteDeviceHelper _remoteDeviceHelper = new RemoteDeviceHelper(filters); +``` + +## Example + +```csharp +// without filters + +RemoteDeviceHelper _remoteDeviceHelper = new RemoteDeviceHelper(); +DevicesList.DataContext = _remoteDeviceHelper; + + +// with filters + +var filters = new List +{ + new RemoteSystemDiscoveryTypeFilter(RemoteSystemDiscoveryType.Cloud), + new RemoteSystemAuthorizationKindFilter(RemoteSystemAuthorizationKind.SameUser), + new RemoteSystemStatusTypeFilter(RemoteSystemStatusType.Available) +}; + +RemoteDeviceHelper _remoteDeviceHelper = new RemoteDeviceHelper(filters); +DevicesList.DataContext = _remoteDeviceHelper; + +``` + +```xaml + + + + + + + + + + + + + + + + +``` + +## Sample Project + +[RemoteDeviceHelper Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/RemoteDeviceHelper). You can [see this in action](uwpct://Helpers?sample=RemoteDeviceHelper) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp.Helpers | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +## API + +* [RemoteDeviceHelper source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/RemoteDeviceHelper) + +## Related Topics + +* [Project Rome](https://developer.microsoft.com/windows/project-rome) +* [Remote Systems Sample](https://github.com/microsoft/Windows-universal-samples/tree/main/Samples/RemoteSystems) +* [Connected apps and devices (Project Rome)](/windows/uwp/launch-resume/connected-apps-and-devices) +* [Communicate with a remote app service](/windows/uwp/launch-resume/communicate-with-a-remote-app-service) +* [AppServices Sample](https://github.com/microsoft/Windows-universal-samples/tree/main/Samples/AppServices) diff --git a/docs/archive/windows/remotedevicepicker.md b/docs/archive/windows/remotedevicepicker.md new file mode 100644 index 00000000..54ba9aca --- /dev/null +++ b/docs/archive/windows/remotedevicepicker.md @@ -0,0 +1,89 @@ +--- +title: RemoteDevicePicker +author: avknaidu +description: The RemoteDevicePicker control helps you to pick a device that you can use to Remote Launch Apps, Services. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, RemoteDevicePicker, picker +dev_langs: + - csharp +--- + +# RemoteDevicePicker (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [RemoteDevicePicker](/dotnet/api/microsoft.toolkit.uwp.ui.controls.remotedevicepicker) gives you a list of Remote Systems. All the systems must be signed in with the same Microsoft Account (MSA) + +> [!IMPORTANT] +> Make sure you enable the [RemoteSystem capability](/windows/uwp/packaging/app-capability-declarations#general-use-capabilities) in your app's `package.appxmanifest` to access remote system information. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=RemoteDevicePicker) + +## Syntax + +```csharp +RemoteDevicePicker remoteDevicePicker = new RemoteDevicePicker() +{ + Title = "Pick Remote Device", + SelectionMode = RemoteDevicesSelectionMode.Multiple +}; +var result = await remoteDevicePicker.PickDeviceAsync(); +await new MessageDialog($"You picked {result.Count.ToString()} Device(s)" + Environment.NewLine + string.Join(",", result.Select(x => x.DisplayName.ToString()).ToList())).ShowAsync(); +``` + +You can also use default filter types for initializing. Like Below. + +```csharp +RemoteDevicePicker remoteDevicePicker = new RemoteDevicePicker(RemoteSystemDiscoveryType.Proximal, RemoteSystemAuthorizationKind.Anonymous, RemoteSystemStatusType.Any) +{ + Title = "Pick Remote Device", + SelectionMode = RemoteDevicesSelectionMode.Multiple +}; + +var remoteSystems = await remoteDevicePicker.PickDeviceAsync(); +await new MessageDialog($"You picked {remoteSystems.Count().ToString()} Device(s)" + Environment.NewLine + string.Join(",", remoteSystems.Select(x => x.DisplayName.ToString()).ToList())).ShowAsync(); +``` + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| SelectionMode | RemoteDevicesSelectionMode | Gets or sets the DeviceList Selection Mode. Defaults to RemoteDevicesSelectionMode.Single | +| ShowAdvancedFilters | Boolean | Gets or sets a value indicating whether Advanced Filters are visible or not. Defaults to false | + +## Sample Project + +[RemoteDevicePicker Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/RemoteDevicePicker). You can [see this in action](uwpct://Controls?sample=RemoteDevicePicker) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[RemoteDevicePicker XAML File](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Input/RemoteDevicePicker/RemoteDevicePicker.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +* [RemoteDevicePicker source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Input/RemoteDevicePicker) + +## Related Topics + +* [Project Rome](https://developer.microsoft.com/windows/project-rome) +* [Remote Systems Sample](https://github.com/microsoft/Windows-universal-samples/tree/main/Samples/RemoteSystems) +* [Connected apps and devices (Project Rome)](/windows/uwp/launch-resume/connected-apps-and-devices) +* [Communicate with a remote app service](/windows/uwp/launch-resume/communicate-with-a-remote-app-service) +* [AppServices Sample](https://github.com/microsoft/Windows-universal-samples/tree/main/Samples/AppServices) diff --git a/docs/archive/windows/rotatortile.md b/docs/archive/windows/rotatortile.md new file mode 100644 index 00000000..b496df8e --- /dev/null +++ b/docs/archive/windows/rotatortile.md @@ -0,0 +1,73 @@ +--- +title: Rotator Tile Control +author: nmetulev +description: The RotatorTile Control is an ItemsControl that rotates through a set of items one-by-one. It enables you to show multiple items of data in a live-tile like way. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, RotatorTile Control, xaml control, xaml +--- + +# RotatorTile XAML Control (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [Rotator Tile Control](/dotnet/api/microsoft.toolkit.uwp.ui.controls.rotatortile) is an ItemsControl that rotates through a set of items one-by-one. It enables you to show multiple items of data in a live-tile like way. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=RotatorTile) + +## Syntax + +```xaml + + + +``` + +## Example Image + +![RotatorTile animation](images/rotatortile.gif) + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| CurrentItem | object | Gets or sets the currently selected visible item | +| Direction | [RotateDirection](/dotnet/api/microsoft.toolkit.uwp.ui.controls.rotatortile.rotatedirection) | Gets or sets the direction the tile slides in | +| ExtraRandomDuration | TimeSpan | Gets or sets the extra randomized duration to be added to the `RotationDelay` property. A value between zero and this value in seconds will be added to the `RotationDelay` | +| ItemsSource | object | Gets or sets the ItemsSource | +| ItemTemplate | DataTemplate | Gets or sets the item template | +| RotationDelay | TimeSpan | Gets or sets the duration for tile rotation | + +## Sample Project + +[RotatorTile Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/RotatorTile). You can [see this in action](uwpct://Controls?sample=RotatorTile) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[RotatorTile XAML File](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Core/RotatorTile/RotatorTile.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +* [RotatorTile source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Core/RotatorTile) diff --git a/docs/archive/windows/storagefiles.md b/docs/archive/windows/storagefiles.md new file mode 100644 index 00000000..b023588f --- /dev/null +++ b/docs/archive/windows/storagefiles.md @@ -0,0 +1,129 @@ +--- +title: StorageFileHelper +author: nmetulev +description: The StorageFileHelper is a static utility class that provides functions to help with reading and writing of text and bytes to the disk. These functions are all wrapped into Async tasks. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, StorageFileHelper +dev_langs: + - csharp + - vb +--- + +# StorageFileHelper (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [StorageFileHelper](/dotnet/api/microsoft.toolkit.uwp.helpers.storagefilehelper) is a static utility class that provides functions to help with reading and writing of text and bytes to the disk. These functions are all wrapped into Async tasks. + +## Syntax + +```csharp +// NOTE This must be used from an async function +string myText = "Great information that the users wants to keep"; +StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder; + +// Save some text to a file named appFilename.txt (in the local cache folder) +var storageFile = await StorageFileHelper.WriteTextToLocalCacheFileAsync(myText, "appFilename.txt"); + +// Load some text from a file named appFilename.txt in the local cache folder +string loadedText = await StorageFileHelper.ReadTextFromLocalCacheFileAsync("appFilename.txt"); + +// Save some text to a file named appFilename.txt (in the local folder) +storageFile = await StorageFileHelper.WriteTextToLocalFileAsync(myText, "appFilename.txt"); + +// Load some text from a file named appFilename.txt in the local folder +loadedText = await StorageFileHelper.ReadTextFromLocalFileAsync("appFilename.txt"); + +// Check if a file exists in a specific folder +bool exists = await localFolder.FileExistsAsync("appFilename.txt"); + +// Check if a file exists in a specific folder or in one of its subfolders +bool exists = await localFolder.FileExistsAsync("appFilename.txt", true); + +// Check if a file name is valid or not +bool isFileNameValid = StorageFileHelper.IsFileNameValid("appFilename.txt"); + +// Check if a file path is valid or not +bool isFilePathValid = StorageFileHelper.IsFilePathValid("folder/appFilename.txt"); +``` + +```vb +' NOTE This must be used from an async function +Dim myText As String = "Great information that the users wants to keep" +Dim localFolder As StorageFolder = Windows.Storage.ApplicationData.Current.LocalFolder + +' Save some text to a file named appFilename.txt (in the local cache folder) +Dim storageFile = Await StorageFileHelper.WriteTextToLocalCacheFileAsync(myText, "appFilename.txt") + +' Load some text from a file named appFilename.txt in the local cache folder +Dim loadedText As String = Await StorageFileHelper.ReadTextFromLocalCacheFileAsync("appFilename.txt") + +' Save some text to a file named appFilename.txt (in the local folder) +storageFile = Await StorageFileHelper.WriteTextToLocalFileAsync(myText, "appFilename.txt") + +' Load some text from a file named appFilename.txt in the local folder +loadedText = Await StorageFileHelper.ReadTextFromLocalFileAsync("appFilename.txt") + +' Check if a file exists in a specific folder +Dim exists As Boolean = Await localFolder.FileExistsAsync("appFilename.txt") + +' Check if a file exists in a specific folder or in one of its subfolders +Dim exists As Boolean = Await localFolder.FileExistsAsync("appFilename.txt", True) + +' Check if a file name is valid or not +Dim isFileNameValid As Boolean = StorageFileHelper.IsFileNameValid("appFilename.txt") + +' Check if a file path is valid or not +Dim isFilePathValid As Boolean = StorageFileHelper.IsFilePathValid("folder/appFilename.txt") +``` + +## Methods + +| Methods | Return Type | Description | +|------------------------------------------------------------------------------------------|-------------------------|--------------------------------------------------------------------------------------------| +| FileExistsAsync(StorageFolder, String, Boolean) | Task<bool> | Gets a value indicating whether a file exists in the current folder | +| IsFileNameValid(String) | bool | Gets a value indicating whether a filename is correct or not using the Storage feature | +| IsFilePathValid(String) | bool | Gets a value indicating whether a file path is correct or not using the Storage feature | +| ReadBytesAsync(StorageFile) | Task<byte[]> | Gets an array of bytes from a `StorageFile` | +| ReadBytesFromFileAsync(StorageFolder, String) | Task<byte[]> | Gets an array of bytes from a `StorageFile` located in the given `StorageFolder` | +| ReadBytesFromKnownFoldersFileAsync(KnownFolderId, String) | Task<byte[]> | Gets an array of bytes from a `StorageFile` located in a well known folder | +| ReadBytesFromLocalCacheFileAsync(String) | Task<byte[]> | Gets an array of bytes from a `StorageFile` located in the application local cache folder | +| ReadBytesFromLocalFileAsync(String) | Task<byte[]> | Gets an array of bytes from a `StorageFile` located in the application local folder | +| ReadBytesFromPackagedFileAsync(String) | Task<byte[]> | Gets an array of bytes from a `StorageFile` located in the application installation folder | +| ReadTextFromFileAsync(StorageFolder, String) | Task<string> | Gets a string value from a `StorageFile` located in the given `StorageFolder` | +| ReadTextFromKnownFoldersFileAsync(KnownFolderId, String) | Task<string> | Gets a string value from a `StorageFile` located in a well known folder | +| ReadTextFromLocalCacheFileAsync(String) | Task<string> | Gets a string value from a `StorageFile` located in the application local cache folder | +| ReadTextFromLocalFileAsync(String) | Task<string> | Gets a string value from a `StorageFile` located in the application local folder | +| ReadTextFromPackagedFileAsync(String) | Task<string> | Gets a string value from a `StorageFile` located in the application installation folder | +| WriteBytesToFileAsync(StorageFolder, Byte[], String, CreationCollisionOption) | Task<StorageFile> | Saves an array of bytes to a `StorageFile` in the given `StorageFolder` | +| WriteBytesToKnownFolderFileAsync(KnownFolderId, Byte[], String, CreationCollisionOption) | Task<StorageFile> | Saves an array of bytes to a `StorageFile` to well known folder | +| WriteBytesToLocalCacheFileAsync(Byte[], String, CreationCollisionOption) | Task<StorageFile> | Saves an array of bytes to a `StorageFile` to application local cache folder | +| WriteBytesToLocalFileAsync(Byte[], String, CreationCollisionOption) | Task<StorageFile> | Saves an array of bytes to a `StorageFile` to application local folder | +| WriteTextToFileAsync(StorageFolder, String, String, CreationCollisionOption) | Task<StorageFile> | Saves a string value to a `StorageFile` in the given `StorageFolder` | +| WriteTextToKnownFolderFileAsync(KnownFolderId, String, String, CreationCollisionOption) | Task<StorageFile> | Saves a string value to a Windows.Storage.StorageFile in well known folder | +| WriteTextToLocalCacheFileAsync(String, String, CreationCollisionOption) | Task<StorageFile> | Saves a string value to a Windows.Storage.StorageFile in application local cache folder | +| WriteTextToLocalFileAsync(String, String, CreationCollisionOption) | Task<StorageFile> | Saves a string value to a Windows.Storage.StorageFile in application local folder | + +## Sample Code + +You can find more examples in our [unit tests](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/UnitTests/UnitTests.UWP/Helpers/Test_StorageFileHelper.cs) + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +## API + +* [Storage File Helper source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/StorageFileHelper.cs) diff --git a/docs/archive/windows/streams.md b/docs/archive/windows/streams.md new file mode 100644 index 00000000..e114a63c --- /dev/null +++ b/docs/archive/windows/streams.md @@ -0,0 +1,96 @@ +--- +title: Streams Helper +author: nmetulev +description: There are several operations that apps need commonly to do against their APPX, or from the Internet that are not easy. This helper class wraps up some of the most common operations we need in multiple apps. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Streams +dev_langs: + - csharp + - vb +--- + +# Streams Helper (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +There are several operations that apps need commonly to do against their APPX, or from the Internet that are not easy. [Streams helper](/dotnet/api/microsoft.toolkit.uwp.helpers.streamhelper) class wraps up some of the most common operations we need in multiple apps. + +## Some common scenarios + +* Get a stream from a URI using an in memory stream (rather than needing to download it first). +* Download a URI and write it to a local storage file. +* Get a packaged file stream (files included in the APPX as *Content - do not copy*). +* Does a file exist local folder? +* Read text from a file using ASCII or specified encoding. + +## Methods + +| Methods | Return Type | Description | +|----------------------------------------------------------------------|---------------------------|------------------------------------------------------------------------------------| +| GetHttpStreamAsync(Uri, CancellationToken) | Task\ | Get the response stream returned by a HTTP get request | +| GetHttpStreamToStorageFileAsync(Uri, StorageFile) | Task | Get the response stream returned by a HTTP get request and save it to a local file | +| GetKnowFoldersFileStreamAsync(KnownFolderId, String, FileAccessMode) | Task\ | Return a stream to a specified file from the application local cache folder | +| GetLocalCacheFileStreamAsync(String, FileAccessMode) | Task\ | Return a stream to a specified file from the application local cache folder | +| GetLocalFileStreamAsync(String, FileAccessMode) | Task\ | Return a stream to a specified file from the application local folder | +| GetPackagedFileStreamAsync(String, FileAccessMode) | Task\ | Return a stream to a specified file from the installation folder | +| IsFileExistsAsync(StorageFolder, String) | Task\ | Test if a file exists in the application local folder | +| IsKnownFolderFileExistsAsync(KnownFolderId, String) | Task\ | Test if a file exists in the application local cache folder | +| IsLocalCacheFileExistsAsync(String) | Task\ | Test if a file exists in the application local cache folder | +| IsLocalFileExistsAsync(String) | Task\ | Test if a file exists in the application local folder | +| IsPackagedFileExistsAsync(String) | Task\ | Test if a file exists in the application installation folder | +| ReadTextAsync(IRandomAccessStream, Encoding) | Task\ | Read stream content as a string | + +## Example + +```csharp +// Get access to a text file that was included in solution as Content | do not copy local +using (var stream = await StreamHelper.GetPackagedFileStreamAsync("Assets/Sub/test.txt")) +{ + // Read the contents as ASCII text + var readText = await stream.ReadTextAsync(); +} + +// Get access to a HTTP resource +using (var stream = await StreamHelper.GetHttpStreamAsync(new Uri("https://dev.windows.com"))) +{ + ... +} +``` + +```vb +' Get access to a text file that was included in solution as Content | do not copy local +Using stream = Await StreamHelper.GetPackagedFileStreamAsync("Assets/Sub/test.txt") + ' Read the contents as ASCII text + Dim readText = Await stream.ReadTextAsync() + ... +End Using + +' // Get access to a HTTP resource +Using stream = Await StreamHelper.GetHttpStreamAsync(New Uri("https://dev.windows.com")) + ... +End Using +``` + +## Sample Code + +You can find more examples in our [unit tests](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/UnitTests/UnitTests.UWP/Helpers/Test_StreamHelper.cs) + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +## API Source Code + +* [Stream Helper source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/StreamHelper.cs) diff --git a/docs/archive/windows/systeminformation.md b/docs/archive/windows/systeminformation.md new file mode 100644 index 00000000..82cbfe89 --- /dev/null +++ b/docs/archive/windows/systeminformation.md @@ -0,0 +1,77 @@ +--- +title: SystemInformation +author: nmetulev +description: The SystemInformation class is a utility class that provides properties with some system, application and device information. + +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, SystemInformation +--- + +# SystemInformation (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [SystemInformation](/dotnet/api/microsoft.toolkit.uwp.helpers.systeminformation?view=uwp-toolkit-dotnet&preserve-view=true) class is a utility class that provides properties with some system, application and device information. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Helpers?sample=SystemInformation) + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| ApplicationName | string | Gets the application's name as a `string` | +| ApplicationVersion | [PackageVersion](/uwp/api/Windows.ApplicationModel.PackageVersion) | Gets the application's version as a [PackageVersion](/uwp/api/Windows.ApplicationModel.PackageVersion) | +| AppUptime | TimeSpan | Gets the length of time this instance of the app has been running. | +| AvailableMemory | float | Gets the available memory in _MB_ as a `float` | +| Culture | CultureInfo | Gets the most preferred language by the user as a [CultureInfo](/dotnet/api/system.globalization.cultureinfo) | +| DeviceFamily | string | Gets the family of used device as a `string`. Common `DeviceFamily` values include: Windows.Desktop, Windows.Mobile, Windows.Xbox, Windows.Holographic, Windows.Team, Windows.IoT. Prepare your code for other values | +| DeviceManufacturer | string | Gets the name of device manufacturer as a `string`. The value will be empty if the device manufacturer couldn't be determined (ex: when running in a virtual machine). | +| DeviceModel | string | Gets the model of the device as a `string`. The value will be empty if the device model couldn't be determined (ex: when running in a virtual machine). | +| FirstUseTime | DateTime | Gets the DateTime (in UTC) that the app as first used. | +| FirstVersionInstalled | [PackageVersion](/uwp/api/Windows.ApplicationModel.PackageVersion) | Gets the first version of the app that was installed. | +| PreviousVersionInstalled | [PackageVersion](/uwp/api/Windows.ApplicationModel.PackageVersion) | Gets the previous version of the app that was installed. | +| Instance | SystemInformation | Gets public singleton property. | +| IsFirstRun | bool | Gets a value indicating whether the app is being used for the first time since it was installed. | +| IsAppUpdated | bool | Gets a value indicating whether the app is being used for the first time since being upgraded from an older version. | +| LastLaunchTime | DateTime | Gets the DateTime (in UTC) that this was previously launched. | +| LastResetTime | DateTime | Gets the DateTime (in UTC) when the launch count was previously reset. | +| LaunchCount | long | Gets the number of times the app has been launched since the last reset. | +| LaunchTime | DateTime | Gets the DateTime (in UTC) that this instance of the app was launched. | +| OperatingSystem | string | Gets the operating system as a `string` | +| OperatingSystemArchitecture | [ProcessorArchitecture](/uwp/api/Windows.System.ProcessorArchitecture) | Gets used processor architecture as `ProcessorArchitecture` | +| OperatingSystemVersion | [OSVersion](/dotnet/api/microsoft.toolkit.uwp.helpers.osversion) | Gets the operating system version (for example 10.0.10586.0) as `OSVersion` structure | +| TotalLaunchCount | long | Gets the number of times the app has been launched. | + +## Methods + +| Method | Return Type | Description | +| ------ | ----------- | -- | +| AddToAppUptime(TimeSpan) | void | Add to the record of how long the app has been running. Use this to optionally include time spent in background tasks or extended execution | +| LaunchStoreForReviewAsync() | Task | Launch the store app so the user can leave a review. | +| ResetLaunchCount() | void | Reset launch count so you can get launch count from a new perspective | +| TrackAppUse() | void | Track app launch time and count. | + +## Sample Project + +[System Information Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/SystemInformation). You can [see this in action](uwpct://Helpers?sample=SystemInformation) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp | +| NuGet package | [Microsoft.Toolkit.Uwp](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp/) | + +## API + +* [SystemInformation source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp/Helpers/SystemInformation.cs) diff --git a/docs/archive/windows/texttoolbar.md b/docs/archive/windows/texttoolbar.md new file mode 100644 index 00000000..687c8e93 --- /dev/null +++ b/docs/archive/windows/texttoolbar.md @@ -0,0 +1,137 @@ +--- +title: TextToolbar +author: williamabradley +description: The TextToolbar Control is a universal Text Editing Control for the RichEditBox Control. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, TextToolbar, RichEditBox, XAML Control, xaml +dev_langs: + - csharp + - vb +--- + +# TextToolbar (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. This control could be ported with enough community interest. + +For more information: +- [GitHub tracking issue for TextToolbar port](https://github.com/CommunityToolkit/Windows/issues/81) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [TextToolbar](/dotnet/api/microsoft.toolkit.uwp.ui.controls.texttoolbar) control is a universal Text Editing Control for the [RichEditBox Control](/uwp/api/Windows.UI.Xaml.Controls.RichEditBox). It can format with Markdown Formatting, Rich Text Format (RTF) Formatting, and it also allows you to implement your own Formatter, so you can edit Text for any other format using the Toolbar. +It supports Keyboard Shortcuts, Button Toggling for indicating whether a Format is enabled, such as putting the cursor on Bold Text in Rich Text Formatting. +You can also Remove Default Buttons from any format, or Add Custom buttons to any format, without restyling the whole control, or inheriting a Formatter Class. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=TextToolbar) + +## Syntax + +```xaml + + +``` + +## Sample Output + +![TextToolbar Sample](images/texttoolbar.png) + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| ButtonModifications | [DefaultButtonModificationList](/dotnet/api/microsoft.toolkit.uwp.ui.controls.texttoolbarbuttons.defaultbuttonmodificationlist) | Gets or sets a list of Default buttons to remove from the UI | +| ControlKeyDown | bool | Gets a value indicating whether Control is pressed down | +| CustomButtons | [ButtonMap](/dotnet/api/microsoft.toolkit.uwp.ui.controls.texttoolbarbuttons.buttonmap) | Gets or sets a list of buttons to add to the Default Button set | +| DefaultButtons | [ButtonMap](/dotnet/api/microsoft.toolkit.uwp.ui.controls.texttoolbarbuttons.buttonmap) | Gets the default buttons for this format | +| Editor | RichEditBox | Gets or sets the RichEditBox to Attach to, this is required for any formatting to work | +| Format | [Format](/dotnet/api/microsoft.toolkit.uwp.ui.controls.texttoolbarformats.format) | Gets or sets which formatter to use, and which buttons to provide | +| Formatter | [Formatter](/dotnet/api/microsoft.toolkit.uwp.ui.controls.texttoolbarformats.formatter) | Gets or sets the formatter which is used to format the text from the buttons | +| LastKeyPress | [VirtualKey](/uwp/api/Windows.System.VirtualKey) | Gets the last key pressed using the Editor | +| ShiftKeyDown | bool | Gets a value indicating whether Shift is pressed down | +| UseURIChecker | bool | Gets or sets a value indicating whether to enable use of URI Checker for Link Creator. This allows you to verify Absolute URIs, before creating the Link | + +## Create a Custom Formatter + +In order to create your own Formatter, you need to Inherit from the **Formatter** Class. Then on the TextToolbar, Set the `Format` property to `Custom` and then Set the `Formatter` property with your instantiated Custom Formatter. + +When you create the Class, you will need to override the `DefaultButtons` Property. This will allow you to define what buttons you want your Format to display on the **Toolbar**. + +If you want to use a Common Button Template, such as Bold, Italics, etc. You can get those by Instantiating a `CommonButtons` Instance in your Formatter Class, however, you will need to implement the **ButtonActions** Class, and Instantiate it in your Formatter's `ButtonActions` property, or replace the `Action`/`Shift Action` Property on each button you use. + +_See the MarkDownFormatter Class for reference on how to create a Formatter:_ +[MarkDownFormatter Code](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Markdown/TextToolbar/Formats/MarkDown/MarkDownFormatter.cs) + +_See the Sample Formatter Class from the Sample App:_ +[SampleFormatter Code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/TextToolbar/SampleFormatter.cs) + +_Available CommonButtons:_ +[CommonButton Definitions](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Core/TextToolbar/ToolbarItems/Common/CommonButtons.cs) + +## Examples + +Example of adding Add/Remove Buttons + +```xaml + + + + + + + + + + +``` + +```csharp +var button = Toolbar.GetDefaultButton(ButtonType.Headers); +button.Visibility = Windows.UI.Xaml.Visibility.Collapsed; +Toolbar.CustomButtons.Add(new ToolbarButton +{ + Name = "CustomButton", + Icon = new SymbolIcon(Symbol.ReportHacked), + Position = 1, + Activation = button => System.Diagnostics.Debug.WriteLine($"{button.Name} Activated"), + ShortcutKey = Windows.System.VirtualKey.H +}); +Toolbar.CustomButtons.Add(new ToolbarSeparator { Position = 2 }); +``` + +```vb +Dim button = Toolbar.GetDefaultButton(ButtonType.Headers) +button.Visibility = Windows.UI.Xaml.Visibility.Collapsed +Toolbar.CustomButtons.Add(New ToolbarButton With { + .Name = "CustomButton", + .Icon = New SymbolIcon(Symbol.ReportHacked), + .Position = 1, + .Activation = Sub(btn) Debug.WriteLine($"{btn.Name} Activated"), + .ShortcutKey = Windows.System.VirtualKey.H}) +Toolbar.CustomButtons.Add(New ToolbarSeparator With {.Position = 2}) +``` + +## Sample Project + +[TextToolbar Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/TextToolbar). You can [see this in action](uwpct://Controls?sample=TextToolbar) in [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +* [TextToolbar source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Core/TextToolbar) diff --git a/docs/archive/windows/tilecontrol.md b/docs/archive/windows/tilecontrol.md new file mode 100644 index 00000000..f21c4095 --- /dev/null +++ b/docs/archive/windows/tilecontrol.md @@ -0,0 +1,79 @@ +--- +title: TileControl +author: samoteph +description: The Tile Control is a control that repeats an image many times. It enables you to use animation and synchronization with a ScrollViewer to create parallax effect. XAML or Microsoft Composition are automatically used to render the control. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, TileControl, XAML Control, xaml +--- + +# TileControl (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. The control could be ported with enough community interest. + +For more information: +- [GitHub tracking issue for TileControl port](https://github.com/CommunityToolkit/Windows/issues/88) +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [TileControl](/dotnet/api/microsoft.toolkit.uwp.ui.controls.tilecontrol) is a control that repeats an image many times. It enables you to use animation and synchronization with a ScrollViewer to create parallax effect. XAML or Microsoft Composition are automatically used to render the control. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Controls?sample=TileControl) + +## Syntax + +```xaml + +``` + +## Sample Output + +![TileControl animation](images/tilecontrol.gif) + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| AnimationDuration | double | Gets or sets a duration for the animation of the tile | +| AnimationStepX | double | Gets or sets the animation step of the OffsetX | +| AnimationStepY | double | Gets or sets the animation step of the OffsetY | +| ImageAlignment | [ImageAlignment](/dotnet/api/microsoft.toolkit.uwp.ui.controls.imagealignment) | Gets or sets the alignment of the tile when the `ScrollOrientation` is set to Vertical or Horizontal. Valid values are Left or Right for `ScrollOrientation` set to Horizontal and Top or Bottom for `ScrollOrientation` set to Vertical | +| ImageSource | Uri | Gets or sets the uri of the image to load | +| IsAnimated | bool | Gets or sets a value indicating whether the tile is animated or not | +| IsCompositionSupported | bool | Gets a value indicating whether the platform supports Composition | +| OffsetX | double | Gets or sets an X offset of the image | +| OffsetY | double | Gets or sets an Y offset of the image | +| ParallaxSpeedRatio | int | Gets or sets the speed ratio of the parallax effect with the `ScrollViewerContainer` | +| ScrollOrientation | [ScrollOrientation](/dotnet/api/microsoft.toolkit.uwp.ui.controls.scrollorientation) | Gets or sets the scroll orientation of the tile. Less images are drawn when you choose the Horizontal or Vertical value | +| ScrollViewerContainer | FrameworkElement | Gets or sets a ScrollViewer or a frameworkElement containing a ScrollViewer. The tile control is synchronized with the offset of the scrollviewer | + +## Events + +| Events | Description | +| -- | -- | +| ImageLoaded | The image loaded event | + +## Sample Project + +[TileControl Sample Page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/TileControl). You can [see this in action](uwpct://Controls?sample=TileControl) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Default Template + +[TileControl XAML File](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Core/TileControl/TileControl.xaml) is the XAML template used in the toolkit for the default styling. + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| -- | -- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Controls | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Controls/) | + +## API + +* [TileControl source code](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Core/TileControl) diff --git a/docs/archive/windows/twitter.md b/docs/archive/windows/twitter.md new file mode 100644 index 00000000..16a4af7e --- /dev/null +++ b/docs/archive/windows/twitter.md @@ -0,0 +1,233 @@ +--- +title: Twitter Service +author: nmetulev +description: The Twitter Service allows users to retrieve or publish data to Twitter. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Twitter +dev_langs: + - csharp + - vb +--- + +# Twitter Service (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. +- We aren't open to porting this component to 8.x. +- There is no known recommended substitute for this component. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +> [!WARNING] +> (This API will be removed in the future.) + +The **Twitter Service** allows users to retrieve or publish data to Twitter. + +[Twitter Developer Site](https://dev.twitter.com) is the main content site for all Twitter developers. Visit the [Twitter Apps List](https://apps.twitter.com/) to manage existing apps. + +[Create new Twitter App](https://developer.twitter.com/en) can be used to create a new app within the Twitter portal. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Services?sample=Twitter%20Service) + +## App Setup + +**Consumer Key** +Copy this from the *Keys and Access Tokens* tab on your application page. + +**Consumer Secret** +Copy this from the *Keys and Access Tokens* tab on your application page. + +**Callback URI** Enter a unique URI for your application. This must match the *Callback URL* field on the *Application Details* tab in Twitter. +*Example*: `https://myapp.company.com` - (this does not have to be a working URL) + +## Overview + +In the code section below the GetUserTimeLineAsync method returns some Tweet objects. The Tweet class returns some basic information along with the tweet text itself. + +| Property | Type | Description | +| -- | -- | -- | +| **CreatedAt** | string | The date and time of the Tweet formatted by Twitter | +| **Text** | string | The text of the Tweet (if retweet, the text might not be complete - use the RetweetedStatus object for the original tweet)| +| **Id** | string | The Twitter status identifier | +| **GeoData** | TwitterGeoData | A class containing the latitude and longitude of the Tweet | +| **User** | TwitterUser | A class containing the user ID, Name, ScreenName, and ProfileImageUrl | +| **RetweetedStatus** | Tweet | if this tweet is a retweet, this object will contain the original tweet | + +## Syntax + +```csharp +// Initialize service +TwitterService.Instance.Initialize(ConsumerKey.Text, ConsumerSecret.Text, CallbackUri.Text); + +// Login to Twitter +if (!await TwitterService.Instance.LoginAsync()) +{ + return; +} + +// Get current user info +var user = await TwitterService.Instance.GetUserAsync(); +ProfileImage.DataContext = user; + +// Get user time line +ListView.ItemsSource = await TwitterService.Instance.GetUserTimeLineAsync(user.ScreenName, 50); + +// Post a tweet +await TwitterService.Instance.TweetStatusAsync(TweetText.Text); + +var status = new TwitterStatus + { + Message = TweetText.Text, + + // Optional parameters defined by the Twitter "update" API (they may all be null or false) + + DisplayCoordinates = true, + InReplyToStatusId = "@ValidAccount", + Latitude = validLatitude, + Longitude = validLongitude, + PlaceId = "df51dec6f4ee2b2c", // As defined by Twitter + PossiblySensitive = true, // As defined by Twitter (nudity, violence, or medical procedures) + TrimUser = true + } + +await TwitterService.Instance.TweetStatusAsync(status); + +// Post a tweet with a picture +await TwitterService.Instance.TweetStatusAsync(TweetText.Text, stream); + +await TwitterService.Instance.TweetStatusAsync(status, stream); + +// Search for a specific tag +ListView.ItemsSource = await TwitterService.Instance.SearchAsync(TagText.Text, 50); + +// Open a connection with the stream service in order to receive live tweets and events +ListView.ItemsSource = _tweets; +await TwitterService.Instance.StartUserStreamAsync(async tweet => +{ + await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () => + { + if (tweet != null) + { + _tweets.Insert(0, tweet); + } + }); +}); + +// Stop receiving live tweets and events +TwitterService.Instance.StopUserStream(); +``` + +```vb +' Initialize service +TwitterService.Instance.Initialize(ConsumerKey.Text, ConsumerSecret.Text, CallbackUri.Text) + +' Login to Twitter +If Not Await TwitterService.Instance.LoginAsync() Then + Return +End If + +' Get current user info +Dim user = Await TwitterService.Instance.GetUserAsync() +ProfileImage.DataContext = user + +' Get user time line +ListView.ItemsSource = Await TwitterService.Instance.GetUserTimeLineAsync(user.ScreenName, 50) + +' Post a tweet +Await TwitterService.Instance.TweetStatusAsync(TweetText.Text) +Dim status = New TwitterStatus With { + .Message = TweetText.Text, + + ' Optional parameters defined by the Twitter "update" API (they may all be null or false) + + .DisplayCoordinates = True, + .InReplyToStatusId = "@ValidAccount", + .Latitude = validLatitude, + .Longitude = validLongitude, + .PlaceId = "df51dec6f4ee2b2c", ' As defined by Twitter + .PossiblySensitive = True, ' As defined by Twitter (nudity, violence, or medical procedures) + .TrimUser = True +} +Await TwitterService.Instance.TweetStatusAsync(status) + +' Post a tweet with a picture +Await TwitterService.Instance.TweetStatusAsync(TweetText.Text, stream) +Await TwitterService.Instance.TweetStatusAsync(status, stream) + +' Search for a specific tag +ListView.ItemsSource = Await TwitterService.Instance.SearchAsync(TagText.Text, 50) + +' Open a connection with the stream service in order to receive live tweets and events +ListView.ItemsSource = _tweets +Await TwitterService.Instance.StartUserStreamAsync( + Async Sub(tweet) + Await Dispatcher.RunAsync( + CoreDispatcherPriority.Normal, + Sub() + If tweet IsNot Nothing Then + _tweets.Insert(0, tweet) + End If + End Sub) + End Sub) + +' Stop receiving live tweets and events +TwitterService.Instance.StopUserStream() +``` + +## Posting to timeline fails to appear + +Twitter app models allows for read only applications. If the app is tagged as Readonly, but attempts to post there is *no error returned*. The post is just eaten by the service. + +If you are posting from your app and never seeing them show up in the timeline check the *Permissions* tab on the app page. You want to ensure that you have *Read and Write* checked on that tab. + +## Using the service on non-UWP platforms + +This service has built-in UWP and .NET Framework support. To use the service outside of UWP and .NET Framework platform, you'll need to implement some interfaces. These interfaces are the IAuthenticationBroker, IPasswordManager and IStorageManager. + +### IAuthenticationBroker + +The IAuthenticationBroker only has the Authenticate method. This method receives a request uri and a callback uri, which you'll use to authenticate with the API. The method returns an AuthenticationResult that tells the service the authentication result. + +### IPasswordManager + +The IPasswordManager will allow the service to manage passwords. The methods you'll have to implement are Get, Store and Remove. + +The Get method receives a string key and returns a PasswordCredential. + +The Store method receives a string resource and a PasswordCredential. + +The Remove method receives a string key. + +### IStorageManager + +The IStorageManager will allow the service to store application data. The methods you'll have to implement are Get and Set. + +The Get method receives a string key and returns the saved string. + +The Set method receives a string key and a string value. + +### ISignatureManager + +Finally, the ISignatureManager will provide a GetSignature method, to sign an OAuth request. This method receives a baseString, a secret string and an append boolean. In return, you'll get the signed baseString. In case the append boolean is true, the final string will have a `&` at the end. + +The toolkit has implementations of each of them for UWP. You can find them as UwpAuthenticationBroker, UwpPasswordManager, UwpStorageManager and UwpSignatureManager. + +## Sample Project + +[Twitter Service Sample Page Source](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/6.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Twitter%20Service). You can [see this in action](uwpct://Services?sample=Twitter%20Service) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp.Services | +| NuGet package | [Microsoft.Toolkit.Uwp.Services](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.Services/) | + +## API + +* [Twitter Service source code](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/6.1.0/Microsoft.Toolkit.Services/Services/Twitter) diff --git a/docs/archive/windows/viewextensions.md b/docs/archive/windows/viewextensions.md new file mode 100644 index 00000000..6e8edb49 --- /dev/null +++ b/docs/archive/windows/viewextensions.md @@ -0,0 +1,54 @@ +--- +title: View extensions +author: nmetulev +description: The ApplicationViewExtensions and TitleBarExtensions types provide a declarative way of setting ApplicationView, CoreApplicationView and ApplicationViewTitleBar properties from XAML. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, ViewExtensions, ApplicationViewExtensions, StatusBarExtensions, TitleBarExtensions, statusbar, titlebar, xaml +--- + +# View Extensions (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [`ApplicationViewExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.applicationviewextensions) and [`TitleBarExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.titlebarextensions) provide a declarative way of setting [`ApplicationView`](/uwp/api/windows.ui.viewmanagement.applicationview), [`CoreApplicationView`](/uwp/api/windows.applicationmodel.core.coreapplicationview) and [`ApplicationViewTitleBar`](/uwp/api/windows.ui.viewmanagement.applicationviewtitlebar) properties from XAML. + +> **Platform APIs:** [`ApplicationViewExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.applicationviewextensions), [`TitleBarExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.titlebarextensions) + +## Example + +These attached properties all target a [`Page`](/uwp/api/windows.ui.xaml.controls.page) element, so they can be used directly from XAML when declaring a control of this type in an application: + +```xaml + + + + +``` + +## Examples + +You can find more examples in the [unit tests](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/UnitTests). diff --git a/docs/archive/windows/webview.md b/docs/archive/windows/webview.md new file mode 100644 index 00000000..4c59b807 --- /dev/null +++ b/docs/archive/windows/webview.md @@ -0,0 +1,45 @@ +--- +title: WebView extension +author: nmetulev +ms.date: 08/20/2017 +description: The UWP Community Toolkit WebView extensions allow attaching HTML content to WebView through XAML directly or through Binding +keywords: windows 10, uwp, uwp community toolkit, uwp toolkit, WebViewExtensions, webview, extensions +--- + +# WebView extension (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +> [!WARNING] +> These extensions have been moved to a different type, please refer to docs page for the [`WebViewExtensions`](webviewextensions.md) type. +The **WebViewExtensions** allows attaching HTML content to a WebView. + +## Example + +```xaml + + + + + +``` + +## Requirements (Windows 10 Device Family) + +| [Device family](/windows/uwp/get-started/universal-application-platform-guide) | Universal, 10.0.14393.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp.UI.Extensions | + +## API + +* [WebViewExtensions source code](https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.UI/Extensions/WebViewExtensions.cs) diff --git a/docs/archive/windows/webviewextensions.md b/docs/archive/windows/webviewextensions.md new file mode 100644 index 00000000..c0da4fd9 --- /dev/null +++ b/docs/archive/windows/webviewextensions.md @@ -0,0 +1,47 @@ +--- +title: WebViewExtensions +author: nmetulev +description: The WebViewExtensions class allows attaching HTML content to a WebView control through XAML directly or through a binding +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, WebViewExtensions, webview, extensions +--- + +# WebViewExtensions (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, community interest could potentially lead to its inclusion. The component would require significant changes related to WebView2 integration. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The [`WebViewExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.webviewextensions) allows attaching HTML content to [`WebView`](/uwp/api/windows.ui.xaml.controls.webview). + +> **Platform APIs:** [`WebViewExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.webviewextensions) + +## Syntax + +Here is how the `WebViewExtensions` properties can be used in XAML: + +```xaml + + + + + +``` + +> [!NOTE] +> In this example, the classic binding syntax is used, but the faster `{x:Bind}` syntax is supported as well. You're free to pick which one to use depending on your use case scenario. + +## Examples + +You can find more examples in the [unit tests](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.1.0/UnitTests). diff --git a/docs/archive/windows/weibo.md b/docs/archive/windows/weibo.md new file mode 100644 index 00000000..ae7bd1a4 --- /dev/null +++ b/docs/archive/windows/weibo.md @@ -0,0 +1,123 @@ +--- +title: Weibo service +author: validvoid +description: Learn about the Weibo Service, which allows users to retrieve or publish data to Weibo. See app setup instructions, syntax examples, and requirements. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Weibo +dev_langs: + - csharp + - vb +--- + +# Weibo Service (Archived) + +**Important Note:** This document has been archived and the component is not available in the current version of the Windows Community Toolkit. +- We aren't open to porting this component to 8.x. +- There is no known recommended substitute for this component. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +> [!WARNING] +> (This API will be removed in the future.) + +The **Weibo Service** allows users to retrieve or publish data to Weibo. Visit [https://open.weibo.com](https://open.weibo.com) to create a new app or manage existing apps. + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Services?sample=Weibo%20Service) + +## App Setup + +Go to [我的应用(my apps)](https://open.weibo.com/apps) and select your app. Then click the *应用信息*(app info) tab on the left sidebar you will be able to find the following fields: + +**App Key** +Copy this from the *应用基本信息*(basic information) section on your application page. + +**App Secret** +Copy this from the *应用基本信息*(basic information) section on your application page. + +**Secure Domains** +Due to the restriction by Weibo API, a status you post must include a url which starts with "http"/"https". You can add a url to the list of secure domains in the *应用基本信息*(basic information) section on your application page. + +**Redirect URI** Enter a unique URI for your application. This must match the *Redirect URL* field in the *OAuth2.0 授权设置*(OAuth 2.0 Authorization Settings) section on the *高级信息*(advanced Info) page. You can visit the page by clicking on the left sidebar. +*Example*: `https://myapp.company.com` - (this does not have to be a working URL) + +## Syntax + +```csharp +// Initialize service +WeiboService.Instance.Initialize(AppKey, AppSecret, RedirectUri); + +// Login to Weibo +if (!await WeiboService.Instance.LoginAsync()) +{ + return; +} + +// Get current user info +var user = await WeiboService.Instance.GetUserAsync(); + +// Get user timeline +ListView.ItemsSource = await WeiboService.Instance.GetUserTimeLineAsync(user.ScreenName, 50); + +// Post a status +await WeiboService.Instance.PostStatusAsync(StatusText.Text); + +// Post a status with a picture +await WeiboService.Instance.PostStatusAsync(StatusText.Text, stream); + +``` + +```vb + +' Initialize service +WeiboService.Instance.Initialize(AppKey, AppSecret, RedirectUri) + +' Login to Weibo +If Not Await WeiboService.Instance.LoginAsync() Then + Return +End If + +' Get current user info +Dim user = Await WeiboService.Instance.GetUserAsync() + +' Get user timeline +ListView.ItemsSource = Await WeiboService.Instance.GetUserTimeLineAsync(user.ScreenName, 50) + +' Post a status +Await WeiboService.Instance.PostStatusAsync(StatusText.Text) + +' Post a status with a picture +Await WeiboService.Instance.PostStatusAsync(StatusText.Text, stream) + +``` + +## Methods + +| Methods | Return Type | Description | +| -- | -- | -- | +| Initialize(string, string, string, IAuthenticationBroker, IPasswordManager, IStorageManager) | bool | Initialize underlying provider with relevant token information. | +| LoginAsync() | Task<bool> | Log user in to Weibo. | +| GetUserAsync(string) | Task<WeiboUser> | Retrieve user data. | +| GetUserTimeLineAsync(string, int) | Task<IEnumerable<WeiboStatus>> | Retrieve user timeline data. | +| PostStatusAsync(string) | Task<WeiboStatus> | Post a status. | +| PostStatusAsync(string, Stream) | Task<WeiboStatus> | Post a status with a picture. | + +## Sample Project + +[Weibo Service Sample Page Source](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/6.1.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/Weibo%20Service). You can [see this in action](uwpct://Services?sample=Weibo%20Service) in the [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + +## Requirements + +| Device family | Universal, 10.0.16299.0 or higher | +| --- | --- | +| Namespace | Microsoft.Toolkit.Uwp.Services | +| NuGet package | [Microsoft.Toolkit.Uwp.Services](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.Services/) | + +## API + +* [Weibo Service source code](https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/6.1.0/Microsoft.Toolkit.Services/Services/Weibo) diff --git a/docs/archive/windows/win2d-path-mini-language.md b/docs/archive/windows/win2d-path-mini-language.md new file mode 100644 index 00000000..829d5727 --- /dev/null +++ b/docs/archive/windows/win2d-path-mini-language.md @@ -0,0 +1,875 @@ +--- +title: Win2D Path Mini Language +author: ratishphilip +description: The Win2D Path Mini Language is a powerful language based on the SVG Path language specification. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Win2D, Win2D path mini language +dev_langs: + - csharp +--- + +# Win2D Path Mini Language (Archived) + +**Important Note:** This component has been archived and is not available in the current version of the Windows Community Toolkit. + +While there are no immediate plans to port this component to 8.x, the community is welcome to express interest or contribute to its inclusion. + +For more information: +- [Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Windows) +- [Documentation feedback and suggestions](https://github.com/MicrosoftDocs/CommunityToolkit/issues) + +Original documentation follows below. + +--- + +The _Win2D Path Mini Language_ is a powerful and sophisticated language based on the [SVG Path language](https://www.w3.org/TR/SVG11/paths.html) specification. It facilitates specifying complex geometries, color, brushes, strokes and stroke styles in a more compact manner. + +Using the Win2D Path Mini Language, the geometry from the initial [CanvasPathGeometry](canvaspathgeometry.md) example can be created in the following way: + +```cs +string pathData = “M 1 1 300 300 1 300 Z”; +CanvasGeometry triangleGeometry = CanvasPathGeometry.CreateGeometry(device, pathData); +``` + +## Requirements + +| Device family | Universal, MinVersion or higher | +| ------------- | ------------------------------------------------------------------------------------------------ | +| Namespace | Microsoft.Toolkit.Uwp.UI.Media.Geometry | +| NuGet package | [Microsoft.Toolkit.Uwp.UI.Media](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Media/) | + +## Table of Contents + +- [Introduction](#win2d-path-mini-language-archived) + - [Requirements](#requirements) +- [Win2D Path Mini Language](#win2d-path-mini-language-overview) +- [Path Mini Language](#path-mini-language) + - [Fill Behavior](#fill-behavior) + - [MoveTo](#moveto) + - [LineTo](#lineto) + - [Horizontal LineTo](#horizontal-lineto) + - [Vertical LineTo](#vertical-lineto) + - [Cubic Bézier](#cubic-bézier) + - [Smooth Cubic Bézier](#smooth-cubic-bézier) + - [Quadratic Bézier](#quadratic-bézier) + - [Smooth Quadratic Bézier](#smooth-quadratic-bézier) + - [Arc](#arc) + - [Close Path](#close-path) + - [Ellipse Figure](#ellipse-figure) + - [Polygon Figure](#polygon-figure) + - [Rectangle Figure](#rectangle-figure) + - [RoundedRectangle Figure](#roundedrectangle-figure) +- [CanvasBrush Mini Language](#canvasbrush-mini-language) + - [ICanvasBrush Attribute Commands](#icanvasbrush-attribute-commands) + - [Start Point](#start-point) + - [End Point](#end-point) + - [Opacity](#opacity) + - [Alpha Mode](#alpha-mode) + - [Buffer Precision](#buffer-precision) + - [Edge Behavior](#edge-behavior) + - [Pre Interpolation Color Space](#pre-interpolation-color-space) + - [Post Interpolation Color Space](#post-interpolation-color-space) + - [Origin Offset](#origin-offset) + - [GradientStop](#gradientstop) + - [GradientStopHdr](#gradientstophdr) + - [SolidColorBrush](#solidcolorbrush) + - [LinearGradientBrush](#lineargradientbrush) + - [LinearGradientBrush with GradientStopHdr](#lineargradientbrush-with-gradientstophdr) + - [RadialGradientBrush](#radialgradientbrush) + - [RadialGradientBrush with GradientStopHdr](#radialgradientbrush-with-gradientstophdr) +- [CanvasStrokeStyle Mini Language](#canvasstrokestyle-mini-language) + - [CanvasStrokeStyle Attributes](#canvasstrokestyle-attributes) + - [Dash Style](#dash-style) + - [Line Join](#line-join) + - [Miter Limit](#miter-limit) + - [Dash Offset](#dash-offset) + - [Start Cap](#start-cap) + - [End Cap](#end-cap) + - [Dash Cap](#dash-cap) + - [Transform Behavior](#transform-behavior) + - [Custom Dash Style](#custom-dash-style) + - [Defining the CanvasStrokeStyle](#defining-the-canvasstrokestyle) +- [CanvasStroke Mini Language](#canvasstroke-mini-language) + - [ICanvasStroke interface and CanvasStroke class](#icanvasstroke-interface-and-canvasstroke-class) +- [Creating Geometries, Brushes, Strokes and StrokeStyles](#creating-geometries-brushes-strokes-and-strokestyles) + +## Win2D Path Mini Language Overview + +Win2D Path Mini Language syntax derives from the SVG path syntax. It is a prefix notation (i.e., commands followed by parameters). In order to ensure that the data, specified in Win2D Path Mini Language, is concise the following rules must be followed + +- The commands are can be expressed as `one` , `two` or `three` characters (e.g., a `Move` command is expressed as an `M` , a LinearGradientBrush command is expressed as `LG` ). +- Superfluous white space and separators such as commas can be eliminated (e.g., `M 100 100 L 200` `200` contains unnecessary spaces and could be expressed more compactly as `M100 100L200 200` ). +- The command letter can be eliminated on subsequent commands if the same command is used multiple times in a row (e.g., you can drop the second "L" in "M 100 200 L 200 100 L - 100 -200" and use "M 100 200 L 200 100 -100 -200" instead). +- Relative versions of all commands are available (uppercase means absolute coordinates, lowercase means relative coordinates). +- Most of the parameters are either integer or floating-point values. The only allowable decimal point is a Unicode U+0046 FULL STOP (".") character (also referred to in Unicode as PERIOD, dot, and decimal point) and no other delimiter characters are allowed [UNICODE]. (For example, the following is an invalid numeric value in a path data stream: "13,000.56". Instead, say: "13000.56".) +- For the relative versions of the commands, all coordinate values are relative to the current point at the start of the command. + +In the following sections, the following notation is used: + +- `()` indicates the grouping of parameters. +- `+` indicates one or more of the given parameter(s) is required. +- `[]` indicates any one of the values specified within the square brackets. For e.g. [01] means either 0 or 1. +- `?` denotes an optional parameter + +## Path Mini Language + +Paths represent the outline of a shape, which can be filled, stroked, used as a clipping path, or any combination of the three. + +A path is described using the concept of a current point. In an analogy with drawing on paper, the current +point can be thought of as the location of the pen. The position of the pen can be changed, and the outline +of a shape (open or closed) can be traced by dragging the pen in either straight lines or curves. + +A path can be defined using the following commands + +### Fill Behavior + +| Format | Description | +| ------ | ----------- | +| F [01] | _Absolute_ | +| f [01] | _Relative_ | + +`Fill Behavior` specifies how the intersecting areas of geometries or figures are combined to form the area of the composite geometry. It represents the `CanvasFilledRegionDetermination` enumeration which is based on `D2D1_FILL_MODE` enumeration. The Fill Behavior parameter can be either `0` or `1`. + +The parameter value `0` indicates `CanvasFilledRegionDetermination.Alternate` which determines whether a point is in the fill region by drawing a ray from that point to infinity in any direction, and then counting the number of path segments within the given shape that the ray crosses. If this number is odd, the point is in the fill region; if even, the point is outside the fill region. + +The parameter value `1` indicates `CanvasFilledRegionDetermination.Winding` which determines whether a point is in the fill region of the path by drawing a ray from that point to infinity in any direction, and then examining the places where a segment of the shape crosses the ray. Starting with a count of zero, add one each time a segment crosses the ray from left to right and subtract one each time a path segment crosses the ray from right to left, as long as left and right are seen from the perspective of the ray. After counting the crossings, if the result is zero, then the point is outside the path. Otherwise, it is inside the path. + +> Each Path data should have only one Fill Behavior specified. Otherwise, an exception will be raised. + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.SetFilledRegionDetermination()` API for this command. + +### MoveTo + +| Format | Description | +| ---------- | ----------- | +| `M` (x y)+ | _Absolute_ | +| `m` (x y)+ | _Relative_ | + +The `MoveTo` command establishes a new current point. The effect is as if the "pen" were lifted and moved to a new location. A path data segment must begin with a Move command. Subsequent "moveto" commands (i.e., when the Move is not the first command) represent the start of a new subpath. + +`M` (uppercase) indicates that absolute coordinates will follow whereas `m` (lowercase) indicates that relative coordinates will follow. + +If a `MoveTo` command is followed by multiple pairs of coordinates, the subsequent pairs are +treated as implicit `LineTo` commands. Hence, implicit `LineTo` commands will be relative if the `MoveTo` command is relative and absolute if the `MoveTo` command is absolute. + +> If a relative `MoveTo` (`m`) command appears as the first element of the path, then its parameters are treated as a pair of absolute coordinates. +> +> In this case, subsequent pairs of coordinates are treated as relative even though the initial `MoveTo` is interpreted as an absolute `MoveTo`. + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.BeginFigure()` API for this command. + +### LineTo + +| Format | Description | +| ---------- | ----------- | +| `L` (x y)+ | _Absolute_ | +| `l` (x y)+ | _Relative_ | + +Draws a line from the current point to the specified (`x`,`y`) coordinate. (`x`,`y`) becomes the new current point. + +`L` (uppercase) indicates that absolute coordinates will follow whereas `l` (lowercase) indicates that relative coordinates will follow. + +> A number of coordinates pairs may be specified to draw a polyline. At the end of the command, the new current point is set to the final set of coordinates provided. + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.AddLine()` API for this command. + +### Horizontal LineTo + +| Format | Description | +| ------ | ----------- | +| `H` x+ | _Absolute_ | +| `h` x+ | _Relative_ | + +Draws a horizontal line from the current point (`cpx`, `cpy`) to (`x`, `cpy`). + +`H` (uppercase) indicates that absolute coordinates will follow whereas `h` (lowercase) indicates that relative coordinates will follow. + +> Multiple `x` values can be provided (although usually this doesn't make sense). At the end of the command, the new current point becomes ( `x`, `cpy` ) for the final value of `x`. + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.AddLine()` API for this command. + +### Vertical LineTo + +| Format | Description | +| ------ | ----------- | +| `V` y+ | _Absolute_ | +| `v` y+ | _Relative_ | + +Draws a vertical line from the current point (`cpx`, `cpy`) to (`cpx`, `y`). + +`V` (uppercase) indicates that absolute coordinates will follow whereas `v` (lowercase) indicates that relative coordinates will follow. + +> Multiple `y` values can be provided (although usually this doesn't make sense). At the end of the command, the new current point becomes (`cpx`, `y`) for the final value of `y`. + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.AddLine()` API for this command. + +### Cubic Bézier + +| Format | Description | +| ---------------------- | ----------- | +| `C` (x1 y1 x2 y2 x y)+ | _Absolute_ | +| `c` (x1 y1 x2 y2 x y)+ | _Relative_ | + +Draws a cubic Bézier curve from the current point to (`x`,`y`) using (`x1`,`y1`) as the control point at the beginning of the curve and (`x2`,`y2`) as the control point at the end of the curve. + +`C` (uppercase) indicates that absolute coordinates will follow whereas `c` (lowercase) indicates that relative coordinates will follow. + +> Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (`x`,`y`) coordinate pair used in the polybézier. + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.AddCubicBezier()` API for this command. + +### Smooth Cubic Bézier + +| Format | Description | +| ---------------- | ----------- | +| `S` (x2 y2 x y)+ | _Absolute_ | +| `s` (x2 y2 x y)+ | _Relative_ | + +Draws a cubic Bézier curve from the current point to (`x`,`y`). The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point. (_If there is no previous command or if the previous command was not a `C`, `c`, `S` or `s` , assume the first control point is coincident with the current point._) + +(`x2`,`y2`) is the second control point (i.e., the control point at the end of the curve). + +`S` (uppercase) indicates that absolute coordinates will whereas `s` (lowercase) indicates that relative coordinates will follow. + +> Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, +> the new current point becomes the final (`x`,`y`) coordinate pair used in the polybézier. + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.AddCubicBezier()` API for this command. + +### Quadratic Bézier + +| Format | Description | +| ---------------- | ---------- | +| `Q` (x1 y1 x y)+ | _Absolute_ | +| `q` (x1 y1 x y)+ | _Relative_ | + +Draws a quadratic Bézier curve from the current point to (`x`,`y`) using (`x1`,`y1`) as the control point. + +`Q` (uppercase) indicates that absolute coordinates will whereas `q` (lowercase) indicates that relative coordinates will follow. + +> Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (`x`,`y`) coordinate pair used in the polybézier. + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.AddQuadraticBezier()` API for this command. + +### Smooth Quadratic Bézier + +| Format | Description | +| ---------- | ----------- | +| `T` (x y)+ | _Absolute_ | +| `t` (x y)+ | _Relative_ | + +Draws a quadratic Bézier curve from the current point to (x,y). The control point is assumed to be the reflection of the control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not a `Q`, `q`, `T` or `t` , assume the control point is coincident with the current +point.) + +`T` (uppercase) indicates that absolute coordinates will whereas `t` (lowercase) indicates that relative coordinates will follow. + +> Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command the new current point becomes the final (`x`,`y`) coordinate pair used in the polybézier. + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.AddQuadraticBezier()` API for this command. + +### Arc + +| Format | Description | +| ---------------------------------------------------------- | ----------- | +| `A` (radius radiusY angle IsLargeFlag SweepDirection x y)+ | _Absolute_ | +| `a` (radius radiusY angle IsLargeFlag SweepDirection x y)+ | _Relative_ | + +Draws an elliptical arc from the current point to ( `x` , `y` ). The size and orientation of the ellipse are defined by two radii ( `rx` , `ry` ) and an `x-axis-rotation` , which indicates how the ellipse as a whole is rotated relative to the current coordinate system. The center ( `cx` , `cy` ) of the ellipse is calculated automatically to satisfy the constraints +imposed by the other parameters. + +`IsLargeFlag` specifies whether an arc should take the longer or shorter way, around the ellipse to join its start and end points (`0` denotes the arc’s sweep should be π or less whereas `1` denotes the arc’s sweep should be π or more). + +`SweepDirection` specifies the direction that an elliptical arc is drawn (`0` means +CounterClockwise and `1` means Clockwise). + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.AddArc()` API for this command. + +### Close Path + +| Format | +| ------ | +| `Z` | +| `z` | + +Closes the current subpath by drawing a straight line from the current point to current subpath's initial point. _Since the `Z` and `z` commands take no parameters, they have an identical effect._ + +`CanvasPathGeometry` invokes the `CanvasPathBuilder.EndFigure()` API for this command. + +### Ellipse Figure + +| Format | Description | +| -------------------------- | ----------- | +| `O` (radiusX radiusY x y)+ | _Absolute_ | +| `o` (radiusX radiusY x y)+ | _Relative_ | + +Adds an Ellipse Figure to the path. The `radiusX` and `radiusY` parameters denote the elliptical radii on the x-axis and y-axis respectively. ( `x y` ) denotes the center of the Ellipse. _The current point remains unchanged._ + +`CanvasPathGeometry` internally invokes the `CanvasPathBuilder.AddEllipseFigure()` extension method for this command. + +### Polygon Figure + +| Format | Description | +| -------------------------- | ----------- | +| `P` (numSides radius x y)+ | _Absolute_ | +| `p` (numSides radius x y)+ | _Relative_ | + +Adds an n-sided Polygon to the path. The `radius` parameter denotes the radius of the circle circumscribing the polygon vertices. ( `x y` ) denotes the center of the polygon. _The current point remains unchanged._ + +This command internally invokes the `CanvasPathBuilder.AddPolygonFigure()` extension method. + +### Rectangle Figure + +| Format | Description | +| ----------------------- | ----------- | +| `R` (x y width height)+ | _Absolute_ | +| `r` (x y width height)+ | _Relative_ | + +Adds a Rectangle to the path. ( `x y` ) denotes the top left corner of the Rectangle. The current point remains unchanged. + +`CanvasPathGeometry` internally invokes the `CanvasPathBuilder.AddRectangleFigure()` extension method for this command. + +### RoundedRectangle Figure + +| Format | Description | +| --------------------------------------- | ----------- | +| `U` (x y width height radiusX radiusY)+ | _Absolute_ | +| `u` (x y width height radiusX radiusY)+ | _Relative_ | + +Adds a RoundedRectangle to the path. ( `x y` ) denotes the top left corner of the RoundedRectangle. `radiusX` and `radiusY` denote the radii of the corner curves on the x-axis and y-axis respectively. _The current point remains unchanged._ + +`CanvasPathGeometry` internally invokes the `CanvasPathBuilder.AddRoundedRectangleFigure()` extension method for this command. + +## CanvasBrush Mini Language + +This section describes in detail how a Win2D brush can be defined as a string and an instance created from it. Using the CanvasBrush Mini Language the following Win2D brushes can be created (they all implement the `ICanvasBrush` interface) + +- `SolidColorBrush` +- `CanvasLinearGradientBrush` +- `CanvasRadialGradientBrush` + +The Win2D Path Mini Language uses the following syntax to define a brush and its attributes + +| Format | +| -------------------------------------------------------------------------- | +| ` ( )`+ | + +Some of the attributes are optional while the others are mandatory. The order in which the attributes are specified should be maintained. + +### ICanvasBrush Attribute Commands + +This section describes the various brush attributes that will be used to define and construct an ICanvasBrush. + +#### Start Point + +| Format | +| --------- | +| `M` (x y) | + +Denotes the point on the canvas where the gradient starts. + +#### End Point + +| Format | +| --------- | +| `Z` (x y) | + +Denotes the point on the canvas where the gradient ends. + +#### Opacity + +| Format | +| ----------- | +| `O` opacity | + +Denotes the opacity of the brush. The `opacity` parameter should have a value in the range [0, 1]. + +#### Alpha Mode + +| Format | +| --------- | +| `A` [012] | + +Specifies the way in which an alpha channel affects color channels. This attribute corresponds to the [CanvasAlphaMode](https://microsoft.github.io/Win2D/WinUI3/html/T_Microsoft_Graphics_Canvas_CanvasAlphaMode.htm) enumeration. Default is `0` ( `Premultiplied` ). + +| Member | Value | Description | +| --------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Premultiplied` | 0 | The alpha value has been premultiplied. In blending, each color is scaled by the alpha value. Note that the alpha value itself is the same in both straight and premultiplied alpha. Typically, no color channel value is greater than the alpha channel value. | +| `Straight` | 1 | The alpha channel indicates the transparency of the color. | +| `Ignore` | 2 | The alpha value is ignored. | + +#### Buffer Precision + +| Format | +| ----------- | +| `B` [01234] | + +Specifies the bit depth used for graphical computations. This attribute corresponds to the +[CanvasBufferPrecision](https://microsoft.github.io/Win2D/WinUI3/html/T_Microsoft_Graphics_Canvas_CanvasBufferPrecision.htm) | enumeration |. Default is `0` ( |`Precision8UIntNormalized` ). + +| Member | Value | Description | +| ------------------------------ | ----- | ----------------------------------------------------------- | +| `Precision8UIntNormalized` | 0 | Use 8-bit normalized integer per channel. | +| `Precision8UIntNormalizedSrgb` | 1 | Use 8-bit normalized integer standard RGB data per channel. | +| `Precision16UIntNormalized` | 2 | Use 16-bit normalized integer per channel. | +| `Precision16Float` | 3 | Use 16-bit floats per channel. | +| `Precision32Float` | 4 | Use 32-bit floats per channel. | + +#### Edge Behavior + +| Format | +| --------- | +| `E` [012] | + +Specifies the behavior for pixels which fall outside of the gradient's typical rendering area. This attribute corresponds to the [CanvasEdgeBehavior](https://microsoft.github.io/Win2D/WinUI3/html/T_Microsoft_Graphics_Canvas_CanvasEdgeBehavior.htm) enumeration. Default is `0` ( `Clamp` ). + +| Member | Value | Description | +| ------ | ----- | ----------------------------------------------------------- | +| Clamp | 0 | Repeat the edge pixels of the brush's content. | +| Wrap | 1 | Tile the brush's content. | +| Mirror | 2 | Tile the the brush's content, and flip each alternate tile. | + +#### Pre Interpolation Color Space + +| Format | +| --------- | +| `P` [012] | + +Specifies the color space to be used before interpolation. This attribute corresponds to the CanvasColorSpace +enumeration. Default value is `1` ( `Srgb` ). + +| Member | Value | Description | +| ------ | ----- | ------------------------------------------------------- | +| Custom | 0 | The color space is a custom ICC ColorManagementProfile. | +| Srgb | 1 | The color space is sRGB. | +| ScRgb | 2 | The color space is scRGB. | + +#### Post Interpolation Color Space + +| Format | +| --------- | +| `R` [012] | + +Specifies the color space to be used after interpolation. This attribute corresponds to the CanvasColorSpace +enumeration. Default value is `1` ( `Srgb` ). + +| Member | Value | Description | +| ------ | ----- | ------------------------------------------------------- | +| Custom | 0 | The color space is a custom ICC ColorManagementProfile. | +| Srgb | 1 | The color space is sRGB. | +| ScRgb | 2 | The color space is scRGB. | + +#### Origin Offset + +| Format | +| --------- | +| `F` (x y) | + +Specifies a displacement from Center, used to form the brush's radial gradient. + +#### GradientStop + +| Format | +| ---------------------- | +| `S` (offset hexColor)+ | + +Specifies one or more gradient stops (using Hexadecimal Color) in a gradient brush. + +The parameter `offset` refers to the position of the gradient stop and should be a floating-point number between 0 and 1, inclusive. + +The parameter `hexColor` denotes the color specified in `#RRGGBB` or `#AARRGGBB` format. + +Example: + +``` +“S 0.2 FF112233” +“S 0.1 #FF0000 0.4 #00FF00 0.9 #0000FF” +``` + +#### GradientStopHdr + +| Format | +| --------------------- | +| `S` (offset x y z w)+ | + +Specifies one or more high dynamic range gradient stops in a gradient brush. + +The parameter `offset` refers to the position of the gradient stop and it should be a floating-point number between 0 and 1, inclusive. + +The parameters `x, y, z` and `w` denote the components of the high dynamic range color. + +Example: + +``` +“S 0.2 0.2 .5 .75 1” +“S 0.1 0.3 0.4 0.5 1.0 0.4 .3 .2 .1 0.9” +``` + +### SolidColorBrush + +| Format | +| ---------------------------- | +| `SC` hexColor (`O` opacity)? | +| `SC` x y z w (`O` opacity)? | + +The SolidColorBrush is defined by the `SC` command. It has two attributes - `Color` and `Opacity`. + +The `Color` attribute is specified as either a Hexadecimal Color or a High Dynamic Range Color. + +The `Opacity` attribute is optional and can be specified with the `O` attribute command and an opacity value in the range [0, 1]. + +Example: + +``` +“SC #FFAABBCC” +“SC #FF1233AA O .75” +“SC 0.1 0.3 0.4 0.5” +“SC 0.1 0.3 0.4 0.5 O 0.9” +``` + +### LinearGradientBrush + +| Format | +| ------------------------------------------------------------------------------------------------------------------ | +| `LG` `M` x0 y0 `Z` x1 y1 (`O` opacity `A` [012] `B` [01234] `E` [012] `P` [012] `R` [012])? `S` (offset hexColor)+ | + +The LinearGradientBrush is defined by the `LG` command. It has the following mandatory attributes + +- StartPoint ( `M` ) +- EndPoint ( `Z` ) +- GradientStops ( `S` ) + +It also has the following optional attributes + +- Opacity ( `O` ) +- Alpha Mode ( `A` ) +- Buffer Precision ( `B` ) +- Edge Behavior ( `E` ) +- Pre Interpolation Color Space ( `P` ) +- Post Interpolation Color Space ( `R` ) + +Example: + +``` +“LG M 0 80 Z0 0 S 0.00 #ffee5124, 0.18 #fff05627, 0.26 #fff15b29, 0.6 #fff58535, 1.00 #fff9af41” +“LG M 0 80 Z0 0 O 0.75 A 1 E 2 S 0.00 #ffee5124, 0.3 #fff05627, 0.7 #fff58535, 1.00 #fff9af41” +``` + +### LinearGradientBrush with GradientStopHdr + +| Format | +| --------------------------------------------------------------------------------------------------------------- | +| `LH M` x0 y0 `Z` x1 y1 (`O` opacity `A` [012] `B` [01234] `E` [012] `P` [012] `R` [012])? `S` (offset x y z w)+ | + +The LinearGradientBrush with GradientStopHdr is defined by the `LH` command. It has the following mandatory attributes + +- StartPoint ( `M` ) +- EndPoint ( `Z` ) +- GradientStopHdrs ( `S` ) + +It also has the following optional attributes + +- Opacity ( `O` ) +- Alpha Mode ( `A` ) +- Buffer Precision ( `B` ) +- Edge Behavior ( `E` ) +- Pre Interpolation Color Space ( `P` ) +- Post Interpolation Color Space ( `R` ) + +Example: + +``` +“LH M 0 80 Z0 0 P 1 R 1 S 0.00 0.9333333, 0.3176471, 0.1411765, 1, 0.14 0.9411765, 0.3372549, 0.1529412, 1, 0.26 0.945098, 0.3568628, 0.1607843, 1, 0.72 0.9607843, 0.5215687, 0.2078431, 1, 1.00 0.9764706, 0.6862745, 0.254902, 1” +``` + +### RadialGradientBrush + +| Format | +| ---------------------------------------------------------------------------------------------------------------------- | +| `RG` radX radY x y (`O` opacity `A` [012] `B` [01234] `E` [012] `F` x1 y1 `P` [012] `R` [012])? `S` (offset hexColor)+ | + +The RadialGradientBrush is defined by the `RG` command. It has the following mandatory attributes + +- RadiusX +- RadiusY +- CenterX ( `x` ) +- CenterY ( `y` ) +- GradientStops ( `S` ) + +It also has the following optional attributes + +- Opacity ( `O` ) +- Alpha Mode ( `A` ) +- Buffer Precision ( `B` ) +- Edge Behavior ( `E` ) +- Origin Offset ( `F` ) +- Pre Interpolation Color Space ( `P` ) +- Post Interpolation Color Space ( `R` ) + +Example: + +``` +“RG 40 6 0 32 0 4 00 S 0.00 #ffee5124, 0.18 #fff05627, 0.26 #fff15b29, 0.7 #fff58535, 1.00 #fff9af41” +“RG 40 60 320 40 0 A 1 B 2 E 2 S 0.00 #ffee5124, 0.3 #fff05627, 0.7 #fff58535, 1.00 #fff9af41” +``` + +### RadialGradientBrush with GradientStopHdr + +| Format | +| --------------------------------------------------------------------------------------------------------------------- | +| `RH` radX radY x y (`O` opacity `A` [012] `B` [01234] `E` [012] `F` x1 y1 `P` [012] `R` [012])? `S` (offset x y z w)+ | + +Command Parameter + +The RadialGradientBrush is defined by the `RG` command. It has the following mandatory attributes + +- RadiusX +- RadiusY +- CenterX ( `x` ) +- CenterY ( `y` ) +- GradientStopHdrs ( `S` ) + +It also has the following optional attributes + +- Opacity ( `O` ) +- Alpha Mode ( `A` ) +- Buffer Precision ( `B` ) +- Edge Behavior ( `E` ) +- Origin Offset ( `F` ) +- Pre Interpolation Color Space ( `P` ) +- Post Interpolation Color Space ( `R` ) + +Example: + +``` +“RH 400 400 32 0 3 20 O 0.94 A 1 E 2 S 0.00 0.9333333, 0.3176471, 0.1411765, 1, 0.18 0.9411765, 0.3372549, 0.1529412, 1, 0.26 0.945098, 0.3568628, 0.1607843, 1, 0.72 0.9607843, 0.5215687, 0.2078431, 1, 1.00 0.9764706, 0.6862745, 0.254902, 1” +``` + +## CanvasStrokeStyle Mini Language + +The `Microsoft.Graphics.Canvas.Geometry.CanvasStrokeStyle` class defines a stroke style for drawing lines. +The stroke style describes whether the line comprises of dashes, dots, or solid line, how to join line segments, how to cap the ends, etc. + +This section describes in detail how a `CanvasStrokeStyle` can be defined as a string and a `CanvasStrokeStyle` instance created from it. + +The Win2D Path Mini Language uses the following format to define a CanvasStrokeStyle and its attributes + +| Format | +| -------------------------------------------------------------------------- | +| `CSS` (`` ``)+ | + +Some of the attributes are optional while the others are mandatory. The order in which the attributes are +specified should be maintained. + +### CanvasStrokeStyle Attributes + +This section describes the various stroke attributes that are used to define and construct a CanvasStrokeStyle object. + +#### Dash Style + +| Format | +| ------------ | +| `DS` [01234] | + +Describes the sequence of dashes, dots, and gaps in a stroke style. This attribute is ignored if the +`CustomDashStyle` attribute is set. This attribute corresponds to the [CanvasDashStyle](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Geometry_CanvasDashStyle.htm) enumeration. Default +value is `0` ( `Solid` ). + +| Member | Value | Description | +| ---------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Solid | 0 | A solid line with no breaks. | +| Dash | 1 | A dash followed by a gap of equal length. The dash and the gap are each twice as long as the stroke thickness. The equivalent custom dash style is {2, 2}. | +| Dot | 2 | A dot followed by a longer gap. The equivalent custom dash style is {0, 2}. | +| DashDot | 3 | A dash, followed by a gap, followed by a dot, followed by another gap. The equivalent custom dash style is {2, 2, 0, 2}. | +| DashDotDot | 4 | A dash, followed by a gap, followed by a dot, followed by another gap, followed by another dot, followed by another gap. The equivalent custom dash style is {2, 2, 0, 2, 0, 2}. | + +#### Line Join + +| Format | +| ----------- | +| `LJ` [0123] | + +Describes the shape that joins two lines or segments. This attribute corresponds to the [CanvasLineJoin](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Geometry_CanvasLineJoin.htm) +enumeration. Default value is `0` (`Miter`). + +| Member | Value | Description | +| ------------ | ----- | ---------------------------------------------------------------------------------------------------------- | +| Miter | 0 | Regular angular vertices. | +| Bevel | 1 | Beveled vertices. | +| Round | 2 | Rounded vertices. | +| MiterOrBevel | 3 | Regular angular vertices unless the join would extend beyond the miter limit; otherwise, beveled vertices. | + +#### Miter Limit + +| Format | +| ---------- | +| `ML` limit | + +Describes the limit on the ratio of the miter length to half the stroke's thickness. + +#### Dash Offset + +| Format | +| ----------- | +| `DO` offset | + +Describes how far into the dash sequence the stroke will start. + +#### Start Cap + +| Format | +| ----------- | +| `SC` [0123] | + +Describes the type of shape used at the beginning of a stroke. This attribute corresponds to the +[CanvasCapStyle](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Geometry_CanvasCapStyle.htm) enumeration. Default value is `0` (`Flat`). + +| Member | Value | Description | +| -------- | ----- | --------------------------------------------------------------------------------------------- | +| Flat | 0 | A cap that does not extend past the last point of the line. | +| Square | 1 | Half of a square that has a length equal to the line thickness. | +| Round | 2 | A semicircle that has a diameter equal to the line thickness. | +| Triangle | 3 | An isosceles right triangle whose hypotenuse is equal in length to the thickness of the line. | + +#### End Cap + +| Format | +| ----------- | +| `EC` [0123] | + +Describes the type of shape used at the beginning of a stroke. This attribute corresponds to the +[CanvasCapStyle](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Geometry_CanvasCapStyle.htm) enumeration. Default value is `0` (`Flat`). + +| Member | Value | Description | +| -------- | ----- | --------------------------------------------------------------------------------------------- | +| Flat | 0 | A cap that does not extend past the last point of the line. | +| Square | 1 | Half of a square that has a length equal to the line thickness. | +| Round | 2 | A semicircle that has a diameter equal to the line thickness. | +| Triangle | 3 | An isosceles right triangle whose hypotenuse is equal in length to the thickness of the line. | + +#### Dash Cap + +| Format | +| ----------- | +| `DC` [0123] | + +Describes the type of shape used at the beginning of a stroke. This attribute corresponds to the +[CanvasCapStyle](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Geometry_CanvasCapStyle.htm) enumeration. Default value is `0` ( `Flat` ). + +| Member | Value | Description | +| -------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| Flat | 0 | A cap that does not extend past the last point of the line. If `Dash Cap` is set to Flat, dots will have zero size so only dashes are visible. | +| Square | 1 | Half of a square that has a length equal to the line thickness. | +| Round | 2 | A semicircle that has a diameter equal to the line thickness. | +| Triangle | 3 | An isosceles right triangle whose hypotenuse is equal in length to the thickness of the line. | + +#### Transform Behavior + +| Format | +| ---------- | +| `TB` [012] | + +Describes how the world transforms, dots per inch (DPI), and stroke width affect the shape of the pen. This attribute corresponds to the [CanvasStrokeTransformBehavior](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Geometry_CanvasStrokeTransformBehavior.htm) enumeration. Default value is `0` (`Normal`). + +| Member | Value | Description | +| -------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- | +| Normal | 0 | The stroke respects the width. currently set world transform, the DPI, and the stroke | +| Fixed | 1 | The stroke does not respect the world transform but it does respect the DPI and stroke width. | +| Hairline | 2 | The stroke is forced to 1 pixel wide (in device space) and does not respect theworld transform, the DPI, or the stroke width. | + +#### Custom Dash Style + +| Format | +| --------------------------- | +| `CDS` (dashSize spaceSize)+ | + +Describes an array describing a custom dash pattern. The array elements specify the length of each dash and space in the pattern. The first element sets the length of a dash, the second element sets the length of a space, and the third element sets the length of a dash, and so on. The length of each dash and space in the dash pattern is the product of the element value in the array and the stroke width. + +> [!NOTE] +> This overrides the `DashStyle` property, which is only used when `CustomDashStyle` is set to null. + +**This array must contain an even number of elements.** + +Example: + +``` +“CDS 2 2 0 2 1 3” +``` + +### Defining the CanvasStrokeStyle + +Using the attributes defined in the previous section the CanvasStrokeStyle can be defined in the following way + +| Format | +| ------------------------------------------------------------------------------------------------------------------------------------ | +| `CSS` (`DS` [01234] `LJ` [0123] `ML` limit `DO` offset `SC` [0123] `EC` [0123] `DC` [0123] `TB` [012] `CDS` (dashSize spaceSize)+ )? | + +All the attributes of `CanvasStrokeStyle` are optional. If none of the attributes is specified in the `CanvasStrokeStyle` definition string, then the default `CanvasStrokeStyle` object is created. + +> [!NOTE] +> While specifying the attributes, the order of the attributes must be maintained. + +Example: + +``` +“CSS CDS 2 2 0 2 1 3” +“CSS” +“CSS DS 2 DO 2 SC 1 EC 2 ” +``` + +## CanvasStroke Mini Language + +### ICanvasStroke interface and CanvasStroke class + +In Win2D, the stroke, that is used to render an outline to a CanvasGeometry, is comprised of three components + +- Stroke Width – defines the width of the stroke. +- Stroke Brush – defines the `ICanvasBrush` that will be used to render the stroke. +- Stroke Style – defines the `CanvasStrokeStyle` for the stroke. +- Transform - defines the Transform property of the stroke brush. + +`ICanvasStroke` interface, defined in the `Microsoft.Toolkit.Uwp.UI.Media.Geometry` namespace, encapsulates these three components and the `CanvasStroke` class implements this interface. + +```cs +public interface ICanvasStroke +{ + ICanvasBrush Brush { get; } + float Width { get; } + CanvasStrokeStyle Style { get; } + Matrix3x2 Transform { get; set; } +} + +public sealed class CanvasStroke : ICanvasStroke +{ + public ICanvasBrush Brush { get; } + public float Width { get; } + public CanvasStrokeStyle Style { get; } + public Matrix3x2 Transform { get; set; } + + public CanvasStroke(ICanvasBrush brush, float strokeWidth = 1f); + public CanvasStroke(ICanvasBrush brush, float strokeWidth, CanvasStrokeStyle strokeStyle); + public CanvasStroke(ICanvasResourceCreator device, Color strokeColor, float strokeWidth = 1f); + public CanvasStroke(ICanvasResourceCreator device, Color strokeColor, float strokeWidth, CanvasStrokeStyle strokeStyle); +} +``` + +In order to define a CanvasStroke using the Mini Language, the `ST` command is used in the following way + +| Format | +| ---------------------------------------------------------- | +| `ST` strokeWidth `` `` | + +In this command string, `strokeWidth` is a positive floating point number, `CanvasBrushML` denotes the CanvasBrush Mini Language and the `CanvasStrokeStyleML` denotes the CanvasStrokeStyle Mini Language. + +Example: + +``` +“ST 4.5 LG M 0 0 Z80 80 S 0.00 #ffff0000, 0.5 #ff00ff00, 0.99 #ff0000ff CSS DS 2 Do 2 SC 1 EC 2 CDS 2 2 0 2 1 3” +“ST 2 SC #ff0000” +``` + +## Creating Geometries, Brushes, Strokes and StrokeStyles + +To create instances of CanvasGeomety, Brushes, CanvasStrokes, and CanvasStrokeStyles you can use the `CanvasPathGeometry` class in the `Microsoft.Toolkit.Uwp.UI.Media.Geometry` namespace. + +## Related Topics + +- [More details about `CanvasPathGeometry` class here.](canvaspathgeometry.md)