From 3fea61e3e5b781fe656137cfd8f8359455f68e19 Mon Sep 17 00:00:00 2001 From: Ana Wishnoff Date: Wed, 18 Dec 2019 13:20:33 -0800 Subject: [PATCH 1/5] Create rowcolumnapichange.md --- .../RowColumnAPIChange/rowcolumnapichange.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 active/RowColumnAPIChange/rowcolumnapichange.md diff --git a/active/RowColumnAPIChange/rowcolumnapichange.md b/active/RowColumnAPIChange/rowcolumnapichange.md new file mode 100644 index 000000000..3d11e3754 --- /dev/null +++ b/active/RowColumnAPIChange/rowcolumnapichange.md @@ -0,0 +1,78 @@ +> See comments in Markdown for how to use this spec template + + + + + +# Background + + + + + + + + + + + +# Description + + + +# Examples + + + + + + + +# Remarks + + + + +# API Notes + + + + +# API Details + + +# Appendix + From f8173aba3abb6c92345aea298448d0943f3bfb13 Mon Sep 17 00:00:00 2001 From: Ana Wishnoff Date: Wed, 18 Dec 2019 14:35:08 -0800 Subject: [PATCH 2/5] First draft of spec --- .../RowColumnAPIChange/rowcolumnapichange.md | 118 +++++++++++++++--- 1 file changed, 104 insertions(+), 14 deletions(-) diff --git a/active/RowColumnAPIChange/rowcolumnapichange.md b/active/RowColumnAPIChange/rowcolumnapichange.md index 3d11e3754..5b8cbecd1 100644 --- a/active/RowColumnAPIChange/rowcolumnapichange.md +++ b/active/RowColumnAPIChange/rowcolumnapichange.md @@ -1,4 +1,3 @@ -> See comments in Markdown for how to use this spec template @@ -29,12 +28,23 @@ modifying an existing API. --> area, just explanation enough to understand this new API, rather than telling the reader "go read 100 pages of background information posted at ...". --> +The current UWP API Reference has `RowDefinition` and `ColumnDefinition` classes, both of which respectively make up `Grid`'s `RowDefinitions` and `ColumnDefinitions` properties. Currently, RowDefinition and ColumnDefinition constructors do not take any arguments. Definition of a ColumnDefinition's `Width` property or a RowDefinition's `Height` property must be done inside the creation of a Row/ColumnDefinition, or on a separate line once the object has been created. + +This spec sets out to change that, and therefore sets out to change the following APIs: + +[RowDefinition Class](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.RowDefinition) + +[ColumnDefinition Class](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.columndefinition) # Description +This new feature will allow developers to define their column widths and row heights within the column and row definitions themselves, not only making the code-behind easier to write, but making it cleaner and more understandable to read as well. +The planned API change will overload the ColumnDefinition and RowDefinition constructors to take in one or two arguments. The first overloaded constructor for `ColumnDefinition()` will take only a double-type argument called Width (Height for `RowDefinition()`). The second overloaded constructor for ColumnDefinition() will take a double-type argument Width (Height for RowDefinition()) and a [GridUnitType](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.gridlength.gridunittype) argument. + +This overloaded constructor takes the same arguments as the [GridLength](https://docs.microsoft.com/en-us/uwp/api/Windows.UI.Xaml.GridLength) constructor does - a double and a GridUnitType. RowDefinition's Height property and ColumnDefinition's Width property are both of type GridLength, so with this change GridLength's arguments will be ported over to the ColumnDefinition and RowDefinition constructors directly. # Examples - - -# Remarks +Current syntax to define a Grid with one column in code-behind: +```csharp +var grid = new Grid(); +var column = new ColumnDefinition(); +column.Width = new GridLength(1.0, GridUnitType.Star); +grid.ColumnDefinitions.Add(column); +``` + +or + +```csharp +var column = new ColumnDefinition +{ + Width = new GridLength(1.0, GridUnitType.Star) +}; +``` + + +New syntax to define a Grid with one column in code-behind: +```csharp +var grid = new Grid(); +grid.ColumnDefinitions.Add(new ColumnDefinition(1.0, GridUnitType.Star)); // Width="1*" +``` + +New syntax to define a Grid wtih one simple (no GridUnitType value) column in code-behind: +```csharp +grid.ColumnDefinitions.Add(new ColumnDefinition(500.0)); // Width="500px" +``` + + # API Notes - +ColumnDefinition constructor will be overloaded to take a double `pixelWidth` OR take two arguments consisting of a double `width` and a GridUnitType `type`: - +```csharp +public ColumnDefinition(double pixelWidth) { ... } +``` -# API Details - +```csharp +public ColumnDefinition(double width, GridUnitType type) { ... } +``` + +RowDefinition constructor will be overloaded to take a double `pixelHeight` OR take two arguments consisting of a double `height` and a GridUnitType `type`: + +```csharp +public RowDefinition(double pixelHeight) { ... } +``` -# Appendix +```csharp +public RowDefinition(double height, GridUnitType type) { ... } +``` + +# API Details +```csharp +//RowDefinition API: +[contract(Windows.Foundation.UniversalApiContract, 1)] +[webhosthidden] +[static_name("Windows.UI.Xaml.Controls.IRowDefinitionStatics", 5adf3fe5-2056-4724-94d6-e4812b022ec8)] +[interface_name("Windows.UI.Xaml.Controls.IRowDefinition", 4abae829-d80c-4a5e-a48c-f8b3d3b6533d)] +runtimeclass RowDefinition + : Windows.UI.Xaml.DependencyObject +{ + // vvvv + RowDefinition(double pixelHeight, GridUnitType type); + RowDefinition(double height); + // ^^^^ + Windows.UI.Xaml.GridLength Height; + Double MaxHeight; + Double MinHeight; + Double ActualHeight{ get; }; + static Windows.UI.Xaml.DependencyProperty HeightProperty{ get; }; + static Windows.UI.Xaml.DependencyProperty MaxHeightProperty{ get; }; + static Windows.UI.Xaml.DependencyProperty MinHeightProperty{ get; }; +}; + +//ColumnDefinition API: +[contract(Windows.Foundation.UniversalApiContract, 1)] +[webhosthidden] +[static_name("Windows.UI.Xaml.Controls.IColumnDefinitionStatics", 06b0d728-d044-40c6-942e-ae60eac74851)] +[interface_name("Windows.UI.Xaml.Controls.IColumnDefinition", f7f1b229-f024-467f-970a-7e705615db7b)] +runtimeclass ColumnDefinition + : Windows.UI.Xaml.DependencyObject +{ + // vvvv + ColumnDefinition(double pixelWidth, GridUnitType type); + ColumnDefinition(double width); + // ^^^^ + Windows.UI.Xaml.GridLength Width; + Double MaxWidth; + Double MinWidth; + Double ActualWidth{ get; }; + static Windows.UI.Xaml.DependencyProperty WidthProperty{ get; }; + static Windows.UI.Xaml.DependencyProperty MaxWidthProperty{ get; }; + static Windows.UI.Xaml.DependencyProperty MinWidthProperty{ get; }; +}; +``` + + From 434792529e5ddb8edea0cacbe20e318959eeb021 Mon Sep 17 00:00:00 2001 From: Ana Wishnoff Date: Fri, 17 Jan 2020 10:08:27 -0800 Subject: [PATCH 3/5] Update rowcolumnapichange.md --- active/RowColumnAPIChange/rowcolumnapichange.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/active/RowColumnAPIChange/rowcolumnapichange.md b/active/RowColumnAPIChange/rowcolumnapichange.md index 5b8cbecd1..218f2afa9 100644 --- a/active/RowColumnAPIChange/rowcolumnapichange.md +++ b/active/RowColumnAPIChange/rowcolumnapichange.md @@ -28,7 +28,7 @@ modifying an existing API. --> area, just explanation enough to understand this new API, rather than telling the reader "go read 100 pages of background information posted at ...". --> -The current UWP API Reference has `RowDefinition` and `ColumnDefinition` classes, both of which respectively make up `Grid`'s `RowDefinitions` and `ColumnDefinitions` properties. Currently, RowDefinition and ColumnDefinition constructors do not take any arguments. Definition of a ColumnDefinition's `Width` property or a RowDefinition's `Height` property must be done inside the creation of a Row/ColumnDefinition, or on a separate line once the object has been created. +The current UWP API Reference has `RowDefinition` and `ColumnDefinition` classes, both of which respectively make up `Grid`'s `RowDefinitions` and `ColumnDefinitions` properties. Currently, RowDefinition and ColumnDefinition constructors do not take any arguments. Definition of a ColumnDefinition's `Width` property or a RowDefinition's `Height` property must be done by creating a GridLength object inside the creation of a Row/ColumnDefinition, or on a separate line once the object has been created. This spec sets out to change that, and therefore sets out to change the following APIs: @@ -83,7 +83,7 @@ var grid = new Grid(); grid.ColumnDefinitions.Add(new ColumnDefinition(1.0, GridUnitType.Star)); // Width="1*" ``` -New syntax to define a Grid wtih one simple (no GridUnitType value) column in code-behind: +New syntax to define a Grid with one simple column in code-behind, where the GridUnitType is a pixel: ```csharp grid.ColumnDefinitions.Add(new ColumnDefinition(500.0)); // Width="500px" ``` @@ -128,8 +128,8 @@ runtimeclass RowDefinition : Windows.UI.Xaml.DependencyObject { // vvvv - RowDefinition(double pixelHeight, GridUnitType type); - RowDefinition(double height); + RowDefinition(double height, GridUnitType type); + RowDefinition(double pixelHeight); // ^^^^ Windows.UI.Xaml.GridLength Height; Double MaxHeight; @@ -149,8 +149,8 @@ runtimeclass ColumnDefinition : Windows.UI.Xaml.DependencyObject { // vvvv - ColumnDefinition(double pixelWidth, GridUnitType type); - ColumnDefinition(double width); + ColumnDefinition(double width, GridUnitType type); + ColumnDefinition(double pixelWidth); // ^^^^ Windows.UI.Xaml.GridLength Width; Double MaxWidth; From 3997af77c59881c06ade22ff072ea720cc2a0132 Mon Sep 17 00:00:00 2001 From: Ana Wishnoff Date: Fri, 1 May 2020 13:46:04 -0700 Subject: [PATCH 4/5] Update rowcolumnapichange.md --- active/RowColumnAPIChange/rowcolumnapichange.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/active/RowColumnAPIChange/rowcolumnapichange.md b/active/RowColumnAPIChange/rowcolumnapichange.md index 218f2afa9..097e05fa1 100644 --- a/active/RowColumnAPIChange/rowcolumnapichange.md +++ b/active/RowColumnAPIChange/rowcolumnapichange.md @@ -28,23 +28,23 @@ modifying an existing API. --> area, just explanation enough to understand this new API, rather than telling the reader "go read 100 pages of background information posted at ...". --> -The current UWP API Reference has `RowDefinition` and `ColumnDefinition` classes, both of which respectively make up `Grid`'s `RowDefinitions` and `ColumnDefinitions` properties. Currently, RowDefinition and ColumnDefinition constructors do not take any arguments. Definition of a ColumnDefinition's `Width` property or a RowDefinition's `Height` property must be done by creating a GridLength object inside the creation of a Row/ColumnDefinition, or on a separate line once the object has been created. +[Grid](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.grid?view=winrt-18362) has ColumnDefinitions and RowDefinitions properties. The values for these properties are a collection of [ColumnDefinition](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.columndefinition?view=winrt-18362) and [RowDefinition](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.rowdefinition?view=winrt-18362) objects, respectively. Currently, RowDefinition and ColumnDefinition constructors do not take any arguments. Due to this, defining a ColumnDefinition or RowDefinition can be lengthy and unintuitive, with the steps as follows: +1. Create a Column or RowDefinition object with the blank constructor. +2. Define a GridLength object with the desired value for the Height or Width property of the Row/ColumnDefinition. +3. Assign the GridLength object to the Height or Width property of the Row/ColumnDefinition. -This spec sets out to change that, and therefore sets out to change the following APIs: +This spec sets out to change that process, and therefore sets out to change the [RowDefinition](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.RowDefinition) and [ColumnDefinition](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.columndefinition) APIs. -[RowDefinition Class](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.RowDefinition) - -[ColumnDefinition Class](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.columndefinition) +This new feature will allow developers to define their column widths and row heights within the column and row definitions themselves, not only making the code-behind easier to write, but making it cleaner and more understandable to read as well. # Description -This new feature will allow developers to define their column widths and row heights within the column and row definitions themselves, not only making the code-behind easier to write, but making it cleaner and more understandable to read as well. -The planned API change will overload the ColumnDefinition and RowDefinition constructors to take in one or two arguments. The first overloaded constructor for `ColumnDefinition()` will take only a double-type argument called Width (Height for `RowDefinition()`). The second overloaded constructor for ColumnDefinition() will take a double-type argument Width (Height for RowDefinition()) and a [GridUnitType](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.gridlength.gridunittype) argument. +ColumnDefinition and RowDefinition constructors will be overloaded to take in one or two arguments. The first overloaded constructor for `ColumnDefinition()` will take only a double-type argument called Width (Height for `RowDefinition()`). The second overloaded constructor for ColumnDefinition() will take a double-type argument Width (Height for RowDefinition()) and a [GridUnitType](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.gridlength.gridunittype) argument. -This overloaded constructor takes the same arguments as the [GridLength](https://docs.microsoft.com/en-us/uwp/api/Windows.UI.Xaml.GridLength) constructor does - a double and a GridUnitType. RowDefinition's Height property and ColumnDefinition's Width property are both of type GridLength, so with this change GridLength's arguments will be ported over to the ColumnDefinition and RowDefinition constructors directly. +These overloaded constructors take the same arguments as the [GridLength](https://docs.microsoft.com/en-us/uwp/api/Windows.UI.Xaml.GridLength) constructor does - a double and a GridUnitType. In turn, feeding these same arguments to a RowDefinition or ColumnDefinition constructor will create a GridLength object and assign it to the ColumnDefinition's Width property or the RowDefinition's Height property behind the scenes. # Examples +If defining a column or row with a GridUnitType of Auto, the value in the Width/Height parameter should be ignored - Auto should override the specified Width/Height value. + +For ColumnDefinitions or RowDefinitions that have `NaN` as their value for Height or Width in their constructor, an error should be thrown. + # API Notes ColumnDefinition constructor will be overloaded to take a double `pixelWidth` OR take two arguments consisting of a double `width` and a GridUnitType `type`: