diff --git a/src/Avalonia.Controls/Grid.cs b/src/Avalonia.Controls/Grid.cs index d1c65a273e..54fcefeb3f 100644 --- a/src/Avalonia.Controls/Grid.cs +++ b/src/Avalonia.Controls/Grid.cs @@ -183,13 +183,13 @@ namespace Avalonia.Controls } /// - /// Gets the result of last column measuring procedure. + /// Gets the result of the last column measurement. /// Use this result to reduce the arrange calculation. /// private GridLayout.MeasureResult _columnMeasureCache; /// - /// Gets the result of last row measuring procedure. + /// Gets the result of the last row measurement. /// Use this result to reduce the arrange calculation. /// private GridLayout.MeasureResult _rowMeasureCache; @@ -202,8 +202,7 @@ namespace Avalonia.Controls protected override Size MeasureOverride(Size constraint) { // Situation 1/2: - // If the grid doesn't have any column/row definitions, - // it behaviors like a nomal panel. + // If the grid doesn't have any column/row definitions, it behaves like a normal panel. // GridLayout supports this situation but we handle this separately for performance. if (ColumnDefinitions.Count == 0 && RowDefinitions.Count == 0) @@ -225,7 +224,7 @@ namespace Avalonia.Controls // Situation 2/2: // If the grid defines some columns or rows. // Debug Tip: - // - GridLayout doesn't hold any states, so you can drag the debugger execution + // - GridLayout doesn't hold any state, so you can drag the debugger execution // arrow back to any statements and re-run them without any side-effect. var measureCache = new Dictionary(); @@ -236,11 +235,11 @@ namespace Avalonia.Controls columnLayout.AppendMeasureConventions(safeColumns, child => MeasureOnce(child, constraint).Width); rowLayout.AppendMeasureConventions(safeRows, child => MeasureOnce(child, constraint).Height); - // Calculate for measuring result. + // Calculate measurement. var columnResult = columnLayout.Measure(constraint.Width); var rowResult = rowLayout.Measure(constraint.Height); - // Use the measure result to measure the rest children. + // Use the results of the measurement to measure the rest of the children. foreach (var child in Children.OfType()) { var (column, columnSpan) = safeColumns[child]; @@ -280,8 +279,7 @@ namespace Avalonia.Controls protected override Size ArrangeOverride(Size finalSize) { // Situation 1/2: - // If the grid doesn't have any column/row definitions, - // it behaviors like a nomal panel. + // If the grid doesn't have any column/row definitions, it behaves like a normal panel. // GridLayout supports this situation but we handle this separately for performance. if (ColumnDefinitions.Count == 0 && RowDefinitions.Count == 0) @@ -297,14 +295,14 @@ namespace Avalonia.Controls // Situation 2/2: // If the grid defines some columns or rows. // Debug Tip: - // - GridLayout doesn't hold any states, so you can drag the debugger execution + // - GridLayout doesn't hold any state, so you can drag the debugger execution // arrow back to any statements and re-run them without any side-effect. var (safeColumns, safeRows) = GetSafeColumnRows(); var columnLayout = new GridLayout(ColumnDefinitions); var rowLayout = new GridLayout(RowDefinitions); - // Calculate for arranging result. + // Calculate for arrange result. var columnResult = columnLayout.Arrange(finalSize.Width, _columnMeasureCache); var rowResult = rowLayout.Arrange(finalSize.Height, _rowMeasureCache); @@ -339,8 +337,9 @@ namespace Avalonia.Controls /// /// Get the safe column/columnspan and safe row/rowspan. - /// The result of this method ensure that none of the children has a column/row out of the definitions. + /// This method ensures that none of the children has a column/row outside the bounds of the definitions. /// + [Pure] private (Dictionary safeColumns, Dictionary safeRows) GetSafeColumnRows() { @@ -357,9 +356,9 @@ namespace Avalonia.Controls /// /// Gets the safe row/column and rowspan/columnspan for a specified range. - /// The user may assign the row/column properties out of the row count or column cout, this method helps to keep them in. + /// The user may assign row/column properties outside the bounds of the row/column count, this method coerces them inside. /// - /// The rows count or the columns count. + /// The row or column count. /// The row or column that the user assigned. /// The rowspan or columnspan that the user assigned. /// The safe row/column and rowspan/columnspan. diff --git a/src/Avalonia.Controls/Utils/GridLayout.cs b/src/Avalonia.Controls/Utils/GridLayout.cs index da2bf42f6d..1266afd2d4 100644 --- a/src/Avalonia.Controls/Utils/GridLayout.cs +++ b/src/Avalonia.Controls/Utils/GridLayout.cs @@ -16,7 +16,8 @@ namespace Avalonia.Controls.Utils { /// /// Initialize a new instance from the column definitions. - /// will forget that the layout data comes from the columns. + /// The instance doesn't care about whether the definitions are rows or columns. + /// It will not calculate the column or row differently. /// internal GridLayout([NotNull] ColumnDefinitions columns) { @@ -28,7 +29,8 @@ namespace Avalonia.Controls.Utils /// /// Initialize a new instance from the row definitions. - /// will forget that the layout data comes from the rows. + /// The instance doesn't care about whether the definitions are rows or columns. + /// It will not calculate the column or row differently. /// internal GridLayout([NotNull] RowDefinitions rows) { @@ -46,6 +48,7 @@ namespace Avalonia.Controls.Utils /// /// Gets all the length conventions that come from column/row definitions. /// These conventions provide limitations of each grid cell. + /// Limitations: the expected pixel length, the min/max pixel length, the * count. /// [NotNull] private readonly List _conventions; @@ -81,10 +84,10 @@ namespace Avalonia.Controls.Utils if (getDesiredLength == null) throw new ArgumentNullException(nameof(getDesiredLength)); // M1/7. Find all the Auto and * length columns/rows. - // Only these columns/rows' layout can be affected by the children desired size. + // Only these columns/rows' layout can be affected by the child desired size. // - // Find all columns/rows that has the length Auto or *. We'll measure the children in advance. - // Only these kind of columns/rows will affects the Grid layout. + // Find all columns/rows that have Auto or * length. We'll measure the children in advance. + // Only these kind of columns/rows will affect the Grid layout. // Please note: // - The columns/rows of Auto length will definitely be affected by the children size; // - However, only the Grid.DesiredSize can be affected by the *-length columns/rows unless the Grid has very much space (Infinitely). @@ -99,8 +102,8 @@ namespace Avalonia.Controls.Utils // 寻找所有行列范围中包含 Auto 和 * 的元素,使用全部可用尺寸提前测量。 // 因为只有这部分元素的布局才会被 Grid 的子元素尺寸影响。 // 请注意: - // - Auto 长度的行列必定会受到子元素布局影响,会影响到行列的布局长度; - // - 而对于 * 长度,一般只有 Grid.DesiredSize 会受到子元素布局影响,只有在 Grid 布局空间充足时行列长度才会被子元素布局影响。 + // - Auto 长度的行列必定会受到子元素布局影响,会影响到行列的布局长度和 Grid 本身的 DesiredSize; + // - 而对于 * 长度,只有 Grid.DesiredSize 会受到子元素布局影响,而行列长度不会受影响。 // Find all the Auto and * length columns/rows. var found = new Dictionary(); @@ -138,7 +141,7 @@ namespace Avalonia.Controls.Utils /// The container length. Usually, it is the constraint of the method. /// /// - /// The measured result that containing the desired size and all the column/row length. + /// The measured result that containing the desired size and all the column/row lengths. /// [NotNull, Pure] internal MeasureResult Measure(double containerLength) @@ -149,7 +152,7 @@ namespace Avalonia.Controls.Utils var aggregatedLength = 0.0; double starUnitLength; - // M2/7. Aggregate all the pixel lengths. Then we can get the rest length by `containerLength - aggregatedLength`. + // M2/7. Aggregate all the pixel lengths. Then we can get the remaining length by `containerLength - aggregatedLength`. // We mark the aggregated length as "fix" because we can completely determine their values. Same as below. // // +-----------------------------------------------------------+ @@ -176,7 +179,7 @@ namespace Avalonia.Controls.Utils while (shouldTestStarMin) { // Calculate the unit * length to estimate the length of each column/row that has * length. - // Under this estimated length, look for if there is a minimum value that has a length less than its constraint. + // Under this estimated length, check if there is a minimum value that has a length less than its constraint. // If there is such a *, then fix the size of this cell, and then loop it again until there is no * that can be constrained by the minimum value. // // 计算单位 * 的长度,以便预估出每一个 * 行列的长度。 @@ -245,7 +248,7 @@ namespace Avalonia.Controls.Utils var desiredStarMin = AggregateAdditionalConventionsForStars(conventions); aggregatedLength += desiredStarMin; - // M6/7. Determine the desired length of the grid for current container length. Its value stores in desiredLength. + // M6/7. Determine the desired length of the grid for current container length. Its value is stored in desiredLength. // Assume if the container has infinite length, the grid desired length is stored in greedyDesiredLength. // // +-----------------------------------------------------------+ @@ -370,7 +373,7 @@ namespace Avalonia.Controls.Utils // 1. Determine all one-span column's desired widths or row's desired heights. // 2. Order the multi-span conventions by its last index // (Notice that the sorting data source is much smaller than the original children source.) - // 3. Determin each multi-span last index by calculating the maximun desired size. + // 3. Determine each multi-span last index by calculating the maximun desired size. // Before we determine the behavior of this method, we just aggregate the one-span * columns. @@ -401,10 +404,10 @@ namespace Avalonia.Controls.Utils } /// - /// This method implement the last procedure (M7/7) of measure. - /// It expand all the * length to the fixed length according to the . + /// This method implements the last procedure (M7/7) of measure. + /// It expands all the * length to the fixed length according to the . /// - /// All the conventions that have almost been fixed except the rest *. + /// All the conventions that have almost been fixed except the remaining *. /// The container length. /// The final pixel length list. [Pure] @@ -466,7 +469,7 @@ namespace Avalonia.Controls.Utils /// We should clip the columns/rows that have been out of the container bounds. /// Note: This method may change the items value of . /// - /// All the column width list or the row height list with fixed pixel length. + /// A list of all the column widths and row heights with a fixed pixel length /// the container length. It can be positive infinity. private static void Clip([NotNull] IList lengthList, double constraint) { @@ -582,7 +585,7 @@ namespace Avalonia.Controls.Utils /// /// Contains the convention that comes from the grid children. - /// Some child span multiple columns or rows, so even a simple column/row can have multiple conventions. + /// Some children span multiple columns or rows, so even a simple column/row can have multiple conventions. /// [DebuggerDisplay("{" + nameof(DebuggerDisplay) + ",nq}")] internal struct AdditionalLengthConvention