From 2790a6996db73b0a9a76276d416be8dedb41d889 Mon Sep 17 00:00:00 2001 From: dsiders Date: Tue, 3 Jun 2025 11:51:02 -0400 Subject: [PATCH] Docs: LCL/controls. Fixes XML tagging, spelling. * Other whitespace changes are editor-induced word wrapping. (cherry picked from commit cf1d97517f9d8e935f81c642d40aac5ec2f00bdb) --- docs/xml/lcl/controls.xml | 299 +++++++++++++++++++++----------------- 1 file changed, 162 insertions(+), 137 deletions(-) diff --git a/docs/xml/lcl/controls.xml b/docs/xml/lcl/controls.xml index 4692e28f7a..c43bab2831 100644 --- a/docs/xml/lcl/controls.xml +++ b/docs/xml/lcl/controls.xml @@ -19216,40 +19216,59 @@ which determine the position / alignment for the child control. Anchored or aligned controls are excluded from the grid layout.

-There are different algorithm for sizing the rows and columns in the grid. -All algorithms base their calculations on the "PreferredSize" of the child-controls. -This is usually the size to which the controls would autosize. For controls -that have constraints, the PreferredSize is the size after applying those constraints. -(E.g., a TLabel with 20 pixel of text, but a MinSize of 50 will report a PreferredSize of 50)
-For each column or row in the grid, all child-controls in that column/row are checked for their PreferredSize. -Each columns/rows size is then based on the largest PreferredSize it contains. +There are different algorithm for sizing the rows and columns in the grid. All +algorithms base their calculations on the "PreferredSize" of the +child-controls. This is usually the size to which the controls would autosize. +For controls that have constraints, the PreferredSize is the size after +applying those constraints. (E.g., a TLabel with 20 pixel of text, but a +MinSize of 50 will report a PreferredSize of 50).

-Rows/Columns will not shrink below the MinWidth/MinHeight of any child that they contain, even if the algorithm would compute a lower value. -Any algorithm will instead shrink other Rows/Columns more aggressively. -As a result other row/columns can become invisible due to being zero sized. -Also the grid may become wider than the control in which it is shown and will be cut off or need scrolling.
-Rows/Columns will shrink (even if being otherwise enlarged) to the smallest MaxWidth/MaxHeight of any child they contain, if - and only if - that child has -CellAlignHorizontal/CellAlignVertical = ccaFill. For other alignments rows/cells will grow based on the PreferredSize. -If the PreferredSize is the constrained Maximum, then the cell will still be scaled according to the algorithm, but the child will not fill the entire cell. -If rows/columns are constrained by maximum values, then the grid may not fill the entire control in which it is shown. +For each column or row in the grid, all child-controls in that column/row are +checked for their PreferredSize. Each columns/rows size is then based on the +largest PreferredSize it contains. +

+

+Rows/Columns will not shrink below the MinWidth/MinHeight of any child that +they contain, even if the algorithm would compute a lower value. Any algorithm +will instead shrink other Rows/Columns more aggressively. As a result other row +/columns can become invisible due to being zero sized. Also the grid may +become wider than the control in which it is shown and will be cut off or need +scrolling. +

+

+Rows/Columns will shrink (even if being otherwise enlarged) to the smallest +MaxWidth/MaxHeight of any child they contain, if - and only if - that child +has CellAlignHorizontal/CellAlignVertical = ccaFill. For other alignments rows/ +cells will grow based on the PreferredSize. If the PreferredSize is the +constrained Maximum, then the cell will still be scaled according to the +algorithm, but the child will not fill the entire cell. If rows/columns are +constrained by maximum values, then the grid may not fill the entire control +in which it is shown. +

+

+All algorithms (except crsAnchorAligning) distribute the entire available +parent's ClientArea to the grid for the children. Space for each +child-controls' BorderSpacing and the parent's ChildSizing's spacing will be +put around and between the cells.

-All algorithms (except crsAnchorAligning) distribute the entire available parent's ClientArea to the grid for the children. -Space for each child-ontrols' BorderSpacing and the parent's ChildSizing's spacing will be put around and between the cells. -
See TControl.BorderSpacing and TControl.ChildSizing for more information. -
-When Constraints.MinWidth/MinHeight is used, the grid can become larger than the ClientArea. -And when Constraints.MaxWidth/MaxHeight is used together with ccaFill, then the grid may end up smaller. +

+

+When Constraints.MinWidth/MinHeight is used, the grid can become larger than +the ClientArea. And when Constraints.MaxWidth/MaxHeight is used together with +ccaFill, then the grid may end up smaller.

Conflicts between MaxWidth and MinWidth are solved by using the MaxWidth.

-

-Child-controls will be sized to their cells dimension if they have BorderSpacing.CellAlignHorizontal/CellAlignVertical = ccaFill. -Otherwise they will keep their preferred size and be placed inside the cell according to the specified position in CellAlign.

+Child-controls will be sized to their cells dimension if they have +BorderSpacing.CellAlignHorizontal/CellAlignVertical = ccaFill. Otherwise they +will keep their preferred size and be placed inside the cell according to the +specified position in CellAlign. +

crsAnchorAligning
@@ -19281,7 +19300,8 @@ Scales child keeps the relative proportion between the children sizes. crsScaleChilds scales the size of each column or row to fit the space in the parent, while keeping the ratio of the rows/columns equal to the ratio of the PreferredSizes -
+

+

The proportional ratio may not be kept, if child controls are limited by size constraints.

@@ -19315,11 +19335,12 @@ Enlarge or shrink child controls equally, i.e. by the same number of pixels.

crsHomogenousChildResize applies a homogenous size to child controls in the grid layout. All children are grown/shrunk by the same number of pixels. -
-The algorithm takes the difference between the parents ClientSize and the sum of -all PreferredSizes. This difference (free or missing space in the parent control) -is then divided by the number of rows/columns and the correct fraction of the -space is added/subtracted to/from the size of each cell. +

+

+The algorithm takes the difference between the parents ClientSize and the sum +of all PreferredSizes. This difference (free or missing space in the parent +control) is then divided by the number of rows/columns and the correct +fraction of the space is added/subtracted to/from the size of each cell.

For a horizontal left-to-right layout with 3 controls A, B, and C: @@ -19352,12 +19373,13 @@ Enlarges the space between child controls equally.

crsHomogenousSpaceResize applies a uniform number of pixels as horizontal or vertical spacing between child controls on the same column or row. -
-The algorithm takes the difference between the parents ClientSize and the sum of -all PreferredSizes. This difference (free or missing space in the parent control) -is then divided by the number of rows/columns and the correct fraction of the -space is added/subtracted to/from the spacing between the cells and the spacing -at the border of the grid. +

+

+The algorithm takes the difference between the parents ClientSize and the sum +of all PreferredSizes. This difference (free or missing space in the parent +control) is then divided by the number of rows/columns and the correct +fraction of the space is added/subtracted to/from the spacing between the +cells and the spacing at the border of the grid.

For a horizontal left-to-right layout with 3 controls A, B, and C: @@ -19506,7 +19528,8 @@ Provides settings to layout child-controls into a grid (table) layout. TControlChildSizing is a TPersistent descendant which provides properties and methods used to layout, align, and resize child controls fitting into a grid on their parent control. -
+

+

TControlChildSizing also provided "Spacing" settings. Those are applied to the grid and also to anchored or aligned controls outside the grid. @@ -19514,12 +19537,15 @@ outside the grid.

Layout and ControlsPerLine control if the grid is used, how it is sized and in which order the child-controls are placed into the grid. -
-EnlargeHorizontal, EnlargeVerticalHorizontal, -ShrinkHorizontal, ShrinkVerticalHorizontal define -how the cells of the grid are sized. Child-controls are then adjusted to that -size depending on their BorderSpacing.CellAlignHorizontal/CellAlignVertical properties. -
+

+

+EnlargeHorizontal, EnlargeVerticalHorizontal, +ShrinkHorizontal, ShrinkVerticalHorizontal define +how the cells of the grid are sized. Child-controls are then adjusted to that +size depending on their BorderSpacing.CellAlignHorizontal/CellAlignVertical +properties. +

+

HorizontalSpacing, VerticalSpacingHorizontalSpacing, LeftRightSpacing, TopBottomSpacing can be used to add space between and around the cells. @@ -19530,7 +19556,8 @@ id="TControlChildrenLayout"/> for details about the enumeration values used in the properties.

-Additional information about child sizing and layout can be found on the Lazarus Wiki at: +Additional information about child sizing and layout can be found on the +Lazarus Wiki at:

@@ -19803,7 +19830,8 @@ implementation-specific properties and methods. -The number of controls displayed per column or row for the orientation / fill direction specified in Layout. +The number of controls displayed per column or row for the orientation / fill +direction specified in Layout.

@@ -19871,12 +19899,12 @@ parent Control after spacing and size constraints have been applied.

crsHomogenousSpaceResize

-Applies a uniform number of pixels as horizontal spacing between child controls -on the same row. The width for controls in a given column are derived using the -preferred width for the controls and any width constraints (minimum or maximum) -in the child controls. Any unused horizontal space on the Control is allocated -equally as spacing before, between, and after each column in the tabular layout -- including on the left and right edges of the Control. +Applies a uniform number of pixels as horizontal spacing between child +controls on the same row. The width for controls in a given column are derived +using the preferred width for the controls and any width constraints (minimum +or maximum) in the child controls. Any unused horizontal space on the Control +is allocated equally as spacing before, between, and after each column in the +tabular layout - including on the left and right edges of the Control.

Column widths do not change when the parent Control is resized; only the @@ -19886,11 +19914,11 @@ spacing between edges and columns is affected.

crsScaleChilds

-Scales the width for child controls while keeping the space between them fixed. -Children are resized so that the control widths are a ratio of their preferred -widths (or size constraints) relative to the client area on the parent Control. -Controls are scaled to fill the unused horizontal space. All controls in a -given column are given the same derived width. +Scales the width for child controls while keeping the space between them +fixed. Children are resized so that the control widths are a ratio of their +preferred widths (or size constraints) relative to the client area on the +parent Control. Controls are scaled to fill the unused horizontal space. All +controls in a given column are given the same derived width.

@@ -19914,10 +19942,10 @@ sizing layout algorithms.

The styles in EnlargeHorizontal, EnlargeVertical, ShrinkHorizontal, and ShrinkVertical are used when Layout is set to a value other than cclNone. The -styles apply to child controls which have their Anchors set to [akLeft, akTop], -Align set alNone, and are not anchored to another control using AnchorSide. Any -control with other Anchors or Align settings cannot be displayed in the tabular -layout. +styles apply to child controls which have their Anchors set to [akLeft, +akTop], Align set alNone, and are not anchored to another control using +AnchorSide. Any control with other Anchors or Align settings cannot be +displayed in the tabular layout.

The child controls are positioned using the BorderSpacing for the control (and @@ -19965,34 +19993,31 @@ parent Control. The default value for the property is crsAnchorAligning.

Child sizing styles include:

-
crsAnchorAligning

-Uses a static layout based on the preferred height and size constraints for the -child controls. Child controls heights are not changed when the parent Control -is resized. +Uses a static layout based on the preferred height and size constraints for +the child controls. Child controls heights are not changed when the parent +Control is resized.

-
crsScaleChilds

-Scales the width for child controls while keeping the space between them fixed. -Children are resized so that the control heights are a ratio of their preferred -widths (or size constraints) relative to the client area on the parent Control. -Controls are scaled to fill the unused vertical space. All controls in a -given row are given the same derived height. +Scales the width for child controls while keeping the space between them +fixed. Children are resized so that the control heights are a ratio of their +preferred widths (or size constraints) relative to the client area on the +parent Control. Controls are scaled to fill the unused vertical space. All +controls in a given row are given the same derived height.

-
crsHomogenousChildResize

Applies a homogenous height to child controls in a given row on the tabular -layout. The height of child controls is expanded to fill the unused area in the -parent Control after spacing and size constraints have been applied. +layout. The height of child controls is expanded to fill the unused area in +the parent Control after spacing and size constraints have been applied.

@@ -20000,18 +20025,17 @@ parent Control after spacing and size constraints have been applied.

Applies a uniform number of pixels as vertical spacing between child controls -on the same column. The height for controls in a given column are derived using -the preferred height for the controls and any height constraints (minimum or -maximum) in the child controls. Any unused vertical space on the Control is -allocated equally as spacing above, between, and below each row in the tabular -layout - including on the top and bottom edges of the Control. +on the same column. The height for controls in a given column are derived +using the preferred height for the controls and any height constraints ( +minimum or maximum) in the child controls. Any unused vertical space on the +Control is allocated equally as spacing above, between, and below each row in +the tabular layout - including on the top and bottom edges of the Control.

Row heights do not change when the parent Control is resized; only the spacing between edges and rows is affected.

-
crsSameSize

@@ -20031,10 +20055,10 @@ sizing layout algorithms.

The styles in EnlargeHorizontal, EnlargeVertical, ShrinkHorizontal, and ShrinkVertical are used when Layout is set to a value other than cclNone. The -styles apply to child controls which have their Anchors set to [akLeft, akTop], -Align set alNone, and are not anchored to another control using AnchorSide. Any -control with other Anchors or Align settings cannot be displayed in the tabular -layout. +styles apply to child controls which have their Anchors set to [akLeft, +akTop], Align set alNone, and are not anchored to another control using +AnchorSide. Any control with other Anchors or Align settings cannot be +displayed in the tabular layout.

The child controls are positioned using the BorderSpacing for the control (and @@ -20101,8 +20125,8 @@ arranged into rows and / or columns.

Layout is a TControlChildrenLayout property which indicates the layout behavior for adjacent controls in the parent Control. -Layout is used when methods in TControl descendants need to arrange their child -controls into columns or rows. +Layout is used when methods in TControl descendants need to arrange their +child controls into columns or rows.

The default value for the property is cclNone, and indicates that a layout @@ -20240,12 +20264,12 @@ parent Control after spacing and size constraints have been applied.

crsHomogenousSpaceResize

-Applies a uniform number of pixels as horizontal spacing between child controls -on the same row. The width for controls in a given column are derived using the -preferred width for the controls and any width constraints (minimum or maximum) -in the child controls. Any unused horizontal space on the Control is allocated -equally as spacing before, between, and after each column in the tabular layout -- including on the left and right edges of the Control. +Applies a uniform number of pixels as horizontal spacing between child +controls on the same row. The width for controls in a given column are derived +using the preferred width for the controls and any width constraints (minimum +or maximum) in the child controls. Any unused horizontal space on the Control +is allocated equally as spacing before, between, and after each column in the +tabular layout - including on the left and right edges of the Control.

Column widths do not change when the parent Control is resized; only the @@ -20255,11 +20279,11 @@ spacing between edges and columns is affected.

crsScaleChilds

-Scales the width for child controls while keeping the space between them fixed. -Children are resized so that the control widths are a ratio of their preferred -widths (or size constraints) relative to the client area on the parent Control. -Controls are scaled to fill the client width in the parent Control. All -controls in a given column are given the same derived width. +Scales the width for child controls while keeping the space between them +fixed. Children are resized so that the control widths are a ratio of their +preferred widths (or size constraints) relative to the client area on the +parent Control. Controls are scaled to fill the client width in the parent +Control. All controls in a given column are given the same derived width.

@@ -20283,10 +20307,10 @@ sizing layout algorithms.

The styles in EnlargeHorizontal, EnlargeVertical, ShrinkHorizontal, and ShrinkVertical are used when Layout is set to a value other than cclNone. The -styles apply to child controls which have their Anchors set to [akLeft, akTop], -Align set alNone, and are not anchored to another control using AnchorSide. Any -control with other Anchors or Align settings cannot be displayed in the tabular -layout. +styles apply to child controls which have their Anchors set to [akLeft, +akTop], Align set alNone, and are not anchored to another control using +AnchorSide. Any control with other Anchors or Align settings cannot be +displayed in the tabular layout.

The child controls are positioned using the BorderSpacing for the control (and @@ -20294,9 +20318,10 @@ its parent control) and the spacing values in LeftRightSpacing and HorizontalSpacing.

-Setting a new value for ShrinkHorizontal causes the Change method to be called. -This invalidate the preferred sizes for the child controls, and causes them to -be realigned. The OnChange event handler is also signalled (when assigned). +Setting a new value for ShrinkHorizontal causes the Change method to be +called. This invalidate the preferred sizes for the child controls, and causes +them to be realigned. The OnChange event handler is also signalled (when +assigned).

Use EnlargeHorizontal to specify the child sizing style applied when control @@ -20339,23 +20364,21 @@ Child sizing styles include:

crsAnchorAligning

-Uses a static layout based on the preferred height and size constraints for the -child controls. Child controls heights are not changed when the parent Control -is resized. +Uses a static layout based on the preferred height and size constraints for +the child controls. Child controls heights are not changed when the parent +Control is resized.

-
crsScaleChilds

-Scales the width for child controls while keeping the space between them fixed. -Children are resized so that the control heights are a ratio of their preferred -heights (or size constraints) relative to the client area on the parent -Control. Controls are scaled to fill the client height in the parent control. -All controls in a given row are given the same derived height. +Scales the width for child controls while keeping the space between them +fixed. Children are resized so that the control heights are a ratio of their +preferred heights (or size constraints) relative to the client area on the +parent Control. Controls are scaled to fill the client height in the parent +control. All controls in a given row are given the same derived height.

-
crsHomogenousChildResize

@@ -20364,23 +20387,21 @@ layout. The height of child controls is reduced to fill the client height in the parent Control after spacing and size constraints have been applied.

-
crsHomogenousSpaceResize

Applies a uniform number of pixels as vertical spacing between child controls -in the same column. The height for controls in a given column are derived using -the preferred height for the controls and any height constraints (minimum or -maximum) in the child controls. Any unused vertical space on the Control is -allocated equally as spacing above, between, and below each row in the tabular -layout - including on the top and bottom edges of the Control. +in the same column. The height for controls in a given column are derived +using the preferred height for the controls and any height constraints +(minimum or maximum) in the child controls. Any unused vertical space on the +Control is allocated equally as spacing above, between, and below each row in +the tabular layout - including on the top and bottom edges of the Control.

Row heights do not change when the parent Control is resized; only the spacing between edges and rows is affected.

-
crsSameSize

@@ -20400,10 +20421,10 @@ sizing layout algorithms.

The styles in EnlargeHorizontal, EnlargeVertical, ShrinkHorizontal, and ShrinkVertical are used when Layout is set to a value other than cclNone. The -styles apply to child controls which have their Anchors set to [akLeft, akTop], -Align set alNone, and are not anchored to another control using AnchorSide. Any -control with other Anchors or Align settings cannot be displayed in the tabular -layout. +styles apply to child controls which have their Anchors set to [akLeft, +akTop], Align set alNone, and are not anchored to another control using +AnchorSide. Any control with other Anchors or Align settings cannot be +displayed in the tabular layout.

The child controls are positioned using the BorderSpacing for the control (and @@ -20460,8 +20481,8 @@ TopBottomSpacing also affects control alignment when using Anchors for positioning child controls on a parent.

-Use VerticalSpacing to reserve space between vertically adjacent child controls -in a column on the tabular Layout. +Use VerticalSpacing to reserve space between vertically adjacent child +controls in a column on the tabular Layout.

Use LeftRightSpacing to reserved space on the left and right edges of the @@ -20492,8 +20513,8 @@ value for the property causes the Change method to be called to resize/realign child controls. The OnChange event handler is also signalled (when assigned).

-VerticalSpacing also affects control spacing when using Anchors for positioning -child controls on a parent. +VerticalSpacing also affects control spacing when using Anchors for +positioning child controls on a parent.

Use HorizontalSpacing to set the space reserved between horizontally adjacent @@ -24650,7 +24671,9 @@ Provides a grid (table) layout for the children of this control.

ChildSizing provides access to the TControlChildSizing properties and methods of the control. -Those manage how the child-controls are resized and placed into a grid layout.
+Those manage how the child-controls are resized and placed into a grid layout. +

+

ChildSizing is an alternative to using Anchors and Align properties to position and resize child controls.

@@ -24661,11 +24684,13 @@ in which child controls are aligned. This affects how TControlChildSizing.ControlsPerLine determines the size of grid setting either the amount of columns or rows. The default is cclNone and disables the grid layout. -
+

+

Choose a resize algorithm for shrinking or growing children's width and height. This does nothing when cclNone is chosen. -
+

+

Spacing between and around the cells of the grid can be set as part of the TControlChildSizing. It can also be set by using the BorderSpacing of individual child-controls. The TControlChildSizing properties for spacing @@ -24699,12 +24724,12 @@ Behavior modified in LCL version 3.4 to use the adjusted client rectangle when controls are aligned. -Implementation refactored in LCL version 4.0. This may result in behaviour that -differs from previous LCL versions.
-Children with Constraints.MaxWidth/MaxHeight now limit the size of their column/row. -In version 4.2 that was fixed to only apply for children with Constraints.MaxWidth/MaxHeight -and BorderSpacing.CellAlignHorizontal/CellAlignVertical = ccaFill. Values other than ccaFill -can be used to get the layout behaviour of version 3 +Implementation refactored in LCL version 4.0. This may result in behaviour +that differs from previous LCL versions. Children with Constraints.MaxWidth / +MaxHeight now limit the size of their column/row. In version 4.2 that was +fixed to only apply for children with Constraints.MaxWidth/MaxHeight and +BorderSpacing.CellAlignHorizontal/CellAlignVertical = ccaFill. Values other +than ccaFill can be used to get the layout behaviour of version 3.