From 49b437e2e59ce13988ce02e98ffbbd638b73e3f8 Mon Sep 17 00:00:00 2001 From: dsiders Date: Tue, 15 Oct 2024 17:14:14 +0100 Subject: [PATCH] Docs: LCL/controls. Updates topics to specify how Height/ClientHeight and Width/ClientWidth differ from VCL. * TControl.ClientHeight * TControl.ClientWidth * TControl.Height * TControl.Width --- docs/xml/lcl/controls.xml | 99 ++++++++++++++++++++++++++++++++------- 1 file changed, 82 insertions(+), 17 deletions(-) diff --git a/docs/xml/lcl/controls.xml b/docs/xml/lcl/controls.xml index abc4478d5f..f3a0bec679 100644 --- a/docs/xml/lcl/controls.xml +++ b/docs/xml/lcl/controls.xml @@ -2634,7 +2634,7 @@ the values for internal members in the class instance. GetHotSpot is an overridden TPoint function which gets the HotSpot for the image list resolution. GetHotSpot uses the value from the DragHotspot property. It contains the screen -coordinates where the Drag and Drop operation was started. X is is the +coordinates where the Drag and Drop operation was started. X is the horizontal position, and Y is the vertical position in the TPoint type.

@@ -17886,10 +17886,10 @@ WMLButtonTripleClk, WMLButtonQuadClk, et. al.

ClientHeight is an Integer property with the number of -pixels needed for client area on the control. The property contains the value -from the Bottom member in ClientRect. Changing the value for ClientHeight -causes SetClientSize to be called to apply the existing ClientWidth and the -new value for the property. +pixels needed for the vertical client area on the control. The property +contains the value from the Bottom member in ClientRect. Changing the value for +ClientHeight causes SetClientSize to be called to apply the existing +ClientWidth and the new value for the property.

The value for ClientHeight is not stored or used to set the Height for the @@ -17898,10 +17898,29 @@ is restored and when auto-layout policies using Anchors are applied to the control. For example, when Anchors is set to [akBottom] the value in ClientHeight is needed / used.

+ +In the LCL, ClientHeight has the same value as Height. Derived classes (like +TCustomForm or TForm) may implement a ClientHeight property that differs from +Height - but in the current LCL version, they do not. This differs from the +behavior in the Delphi VCL where a TForm instance adjusts the value in +ClientHeight to remove pixels used in non-client areas like the title bar, +borders, frames, and scroll bars. LCL uses this approach because there is no +reliable way to determine the sizes for all of the non-client areas on all of +the platforms where LCL is supported. Without a reliable way, the LCL would +needlessly move the forms around on the screen or resize them endlessly. In the +LCL, neither Height nor ClientHeight include the non-client area on a form +instance. The height of a TMainMenu instance is omitted from both values as +well. + +

+Use ClientWidth to access the number of pixels needed for the horizontal client +area on the control. +

 + @@ -17970,8 +17989,8 @@ for the control.

ClientWidth is an Integer property with the number of -pixels need for the width of the client area on the control. The property -contains the value from the Right member in ClientRect. Changing the value +pixels need for the horizontal client area on the control. The property +contains the value from the Right member in ClientRect. Changing the value for ClientWidth causes SetClientSize to be called to apply the new property value and the existing ClientHeight for the control.

@@ -17982,10 +18001,27 @@ is restored and when auto-layout policies using Anchors are applied to the control. For example, when Anchors is set to [akRight] the value in ClientWidth is needed / used.

+ +In the LCL, ClientWidth has the same value as Width. Derived classes (like +TCustomForm or TForm) may implement a ClientWidth property that differs from +Width - but in the current LCL version, they do not. This differs from the +behavior in the Delphi VCL where a TForm instance adjusts the value in +ClientWidth to remove pixels used in non-client areas like the borders, frames, +and scroll bars. LCL uses this approach because there is no reliable way to +determine the sizes for all of the non-client areas on all of the platforms +where LCL is supported. Without a reliable way, the LCL would needlessly move +the forms around on the screen or resize them endlessly. In the LCL, neither +Width nor ClientWidth include the non-client area on a form instance. + +

+Use ClientHeight to access the number of pixels needed for the vertical client +area on the control. +

 + @@ -18825,11 +18861,13 @@ property along with the existing values in Top, Width, and Height. -The vertical size for the control. + +The vertical size for the control. +

-Height is an Integer property with the vertical size for the control in -pixels. +Height is an Integer property with the vertical size for +the control in pixels.

Setting a negative value in Height is not allowed, and the property defaults @@ -18839,9 +18877,8 @@ IDE).

Setting a new value for the property causes SetBounds and ChangeBounds to be -called. This ensures that the new value is is the range allowed in -Constraints, and that the control is aligned on its Parent using the Anchors -for the control. +called. This ensures that the new value is in the range allowed in Constraints, +and that the control is aligned on its Parent using the Anchors for the control.

A value assigned to Height is ignored when AutoSize is set to True; @@ -18853,8 +18890,22 @@ Values in Top, Left, Width, and Height are used to calculate the display area for the control in GetClientRect. They determine the clipping rectangle used when the control is drawn on its Parent.

+ +In the LCL, Height has the same value as ClientHeight. Derived classes (like +TCustomForm or TForm) may implement a ClientHeight property that differs from +Height - but in the current LCL version, they do not. This differs from the +behavior in the Delphi VCL where the value in Height includes pixels used in +non-client areas like the title bar, borders, frames, and scroll bars. LCL +uses this approach because there is no reliable way to determine the sizes for +all of the non-client areas on all of the platforms where LCL is supported. +Without a reliable way, the LCL would needlessly move the forms around on the +screen or resize them endlessly. In the LCL, neither Height nor ClientHeight +include the non-client area on a form instance. The height of a TMainMenu +instance is omitted from both values as well. + + @@ -18929,7 +18980,9 @@ property along with the existing values in Left, Width, and Height. -The horizontal size for the control. + +The horizontal size for the control. +

Width is an Integer property with the horizontal size @@ -18942,9 +18995,8 @@ to 0 (zero). At design-time, setting Width to a value not in the range

Setting a new value for the property causes SetBounds and ChangeBounds to be -called. This ensures that the new value is is the range allowed in -Constraints, and that the control is aligned on its Parent using the Anchors -for the control. +called. This ensures that the new value is in the range allowed in Constraints, +and that the control is aligned on its Parent using the Anchors for the control.

A value assigned to Width is ignored when AutoSize is set to True; the @@ -18955,8 +19007,21 @@ Values in Top, Left, Width, and Height are used to calculate the display area for the control in GetClientRect. They determine the clipping rectangle used when the control is drawn on its Parent.

+ +In the LCL, Width has the same value as ClientWidth. Derived classes (like +TCustomForm or TForm) may implement a ClientWidth property that differs from +Width - but in the current LCL version, they do not. This differs from the +behavior in the Delphi VCL where the value in Width includes pixels used in +non-client areas like the borders, frames, and scroll bars. LCL uses this +approach because there is no reliable way to determine the sizes for all of the +non-client areas on all of the platforms where LCL is supported. Without a +reliable way, the LCL would needlessly move the forms around on the screen or +resize them endlessly. In the LCL, neither Width nor ClientWidth include the +non-client area on a form instance. + +