diff --git a/docs/extensions/GridExtensions.md b/docs/extensions/GridExtensions.md new file mode 100644 index 000000000..36fb0264f --- /dev/null +++ b/docs/extensions/GridExtensions.md @@ -0,0 +1,168 @@ +--- +title: Grid Extensions +author: nandin-borjigin +description: Provide attached properties for the Grid type. +keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, Grid, extensions +dev_langs: + - csharp +--- + +# Grid Extensions + +[GridExtensions](/dotnet/api/microsoft.toolkit.uwp.ui.gridextensions) provides `ActiveLayout` and `Layouts` attached properties for [`Grid`](/uwp/api/windows.ui.xaml.grid) objects to enable dynamic layout switching capability. + +> **Platform APIs:** +[`GridExtensions`](/dotnet/api/microsoft.toolkit.uwp.ui.gridextensions) + + +> [!div class="nextstepaction"] +> [Try it in the sample app](uwpct://Extensions?sample=GridExtensions) + +## API + +### `GridExtensions.Layouts: IDictionary` + +Defines possible layouts for the `Grid` to dynamically switch among. + +```xml + + + ... + ... + ... + ... + + +``` + +### `GridExtensions.ActiveLayout: string` + +Specifies which layout in the `GridExtensions.Layouts` dictionary to apply upon the `Grid`. + +```xml + + + ... + ... + ... + + +``` + +### `GridLayoutDefinition` + +Defines a grid layout, consists of row definitions, column definitions and an area definition. + +`GridLayoutDefinition.RowDefinitions` and `GridLayoutDefinition.ColumnDefinitions` follow the same pattern as those of `Grid`. + +`GridLayoutDefinition.AreaDefinition` is a string that defines how to arrange child elements, i.e., it defines row index, column index, row span and column span of child elements. +Child elements have to be associated with a `x:Name` attribute and the `x:Name`s are expected to appear in the area definition following these rules: + +1. `x:Name` attribute of an element represents its place in the `Grid` layout in area definition string. +2. Rows are separated with semicolon +3. Cells in same row are separated with whitespace. +4. Row/Column span of an element is expressed by repeating the `x:Name` attribute of that element. + +```xml + + + ... + ... + + + + ElementA ElementB ElementC; + ElementA ElementD ElementD; + ElementE ElementE ElementE + + + + + + + + +``` +The above code describes a layout of +``` + +----------+----------+----------+ + | | ElementB | ElementC | + | ElementA +----------+----------+ + | | ElementD | + +----------+---------------------+ + | ElementE | + +--------------------------------+ +``` + +## Example + +Say we have a `Grid` and expect it to be +``` ++---+-------------+-------------------------------+ +| 1 | Lorem ipsum | Lorem ipsum dolor sit amet... | ++---+-------------+-------------------------------+ +``` +by default and switch to following layout in narrower viewport. +``` ++---+---------------------------+ +| 1 | Lorem ipsum | ++---+---------------------------+ +| Lorem ipsum dolor sit amet... | ++=------------------------------+ +``` +```xml + + + + + + + + + + + + + + + + + + + Number Title Description + + + + + + + + + + + Number Title; + Description Description + + + + 1 + + + Lorem Ipsum + + + Lorem ipsum dolor sit amet... + + +``` + +## Example Output + +![Dynamic layout in Grid element](../resources/images/Extensions/GridExtensions.dynamic-layout.gif) + +## Sample Project + +You can [see this in action](uwpct://Extensions?sample=GridExtensions) in [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). + + + diff --git a/docs/resources/images/Extensions/GridExtensions.dynamic-layout.gif b/docs/resources/images/Extensions/GridExtensions.dynamic-layout.gif new file mode 100644 index 000000000..97184cf56 Binary files /dev/null and b/docs/resources/images/Extensions/GridExtensions.dynamic-layout.gif differ diff --git a/docs/toc.md b/docs/toc.md index cd49e127f..d848537ac 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -365,6 +365,8 @@ ### [WebViewExtensions](extensions/WebViewExtensions.md) +### [GridExtensions](extensions/GridExtensions.md) + ## Collections ### [Observable Groups](collections/ObservableGroups.md)