From 70a57201e103a3dab931a05dd4d2a30451a36a2f Mon Sep 17 00:00:00 2001 From: dsiders Date: Wed, 6 Dec 2023 03:54:17 +0000 Subject: [PATCH] Docs: LCL/extctrls. Adds and updates topics for changes in ca219eca, including: * TBoundLabel * TBoundLabel.Create * TBoundLabel.FocusControl * TBoundLabel.Alignment * TBoundLabel.Layout * TLabelPosition * TCustomLabeledEdit * TCustomLabeledEdit.DoPositionLabel * TLabeledEdit * Admonitions based on discussions in https://forum.lazarus.freepascal.org/index.php/topic,65452.msg498672.html#msg498672 (cherry picked from commit cd93389a8e75f98b5001170dc5bd568eebd20d5a) --- docs/xml/lcl/extctrls.xml | 259 +++++++++++++++++++++++++++++++++----- 1 file changed, 230 insertions(+), 29 deletions(-) diff --git a/docs/xml/lcl/extctrls.xml b/docs/xml/lcl/extctrls.xml index a8baead549..76d131611a 100644 --- a/docs/xml/lcl/extctrls.xml +++ b/docs/xml/lcl/extctrls.xml @@ -6377,7 +6377,9 @@ determine their order and layout. -Implements a label bound to another control. + +Implements a label bound to another control. +

TBoundLabel is a TCustomLabel descendant which @@ -6386,36 +6388,73 @@ implement the EditLabel property in TCustomLabeledEdit and TLabeledEdit.

-Use Caption to assign the text displayed in the label. Use -Layout to specify the text alignment used for the Caption value. +Use Caption to assign the text displayed in the label. An +accelerator key can be specified in Caption to activate the control to which it +is bound.

The FocusControl property specifies the control given focus when a -Dialog accelerator key or other input event in the class is handled. Use one -of the AnchorSide* properties to specify the edge anchored to the -FocusControl. +Dialog accelerator key or other input event in the class is handled. The +AnchorSide* properties indicate the edge anchored to the FocusControl.

-Other than a constructor, the class does not have any new methods or event -handlers. +Use Alignment and Layout to specify the horizontal and +vertical alignment used for the label Caption. Values in these properties may +be ignored (in the implementing control) if they do not apply to the position +for the bound label relative to its FocusControl. Alignment does not apply when +the label is positioned on the left or right of its FocusControl. Layout does +not apply when the label is positioned above or below its FocusControl.

+ +Modified in LCL version 4.0 to include the Alignment and Layout properties. + - - + + + + + + +TCustomLabel Constructor for the class instance. +

Create is the constructor for TBoundLabel. It calls the inherited Create method, and makes itself a SubComponent of the -Owner. The Caption in the control is changed to the Name in the Owner. +Owner. The default values for the following properties are set: +

+
+
Alignment
+
+Set to taLeftJustify to align text to the left in the label. +
+
Layout
+
+Set to tlCenter to center the text vertically on the label. The top of the +label is determined using the height for the control to which it is bound. +
+
+

+The Caption for the label is changed to the value from the Name property in the +Owner control. +

 + +Modified in LCL version 4.0 to set default values for the Alignment and Layout +properties. + + + + TCustomLabel.Create +TComponent.SetSubComponent @@ -6424,15 +6463,77 @@ Owner. The Caption in the control is changed to the Name in the Owner. -FocusControl is the control to receive focus when the label is -activated. +Control focused when the accelerator key for the label is detected.

-FocusControl also receives key messages in the DialogChar method. +FocusControl is a public TWinControl property in +TBoundLabel. A label control cannot receive the input focus (it is +read-only), but can display an accelerator key indicator, just like a menu +entries. A windowed control (Edit...) can receive focus, but cannot indicate an +accelerator key. +

+

+An accelerator key is designated using an Ampersand '&' in the label +Caption, immediately preceding the character to be used as the accelerator key. +The marked character appears with an underline on the screen when ShowAccelChar +is set to True. +

+

+FocusControl receives key messages in the DialogChar method.

- + +TCustomLabel.DialogChar +TCustomLabel.FocusControl +TCustomLabel.ShowAccelChar + + + + + +Horizontal alignment for the Caption displayed on the bound label. + + +

+Alignment is a published TAlignment property in +TBoundLabel which controls how Caption text is aligned horizontally +on the label. +

+

+The default value for Alignment is taCenter as assigned in the Create +constructor. Please note that this is different than the default property value +(taLeftJustify) used in the TCustomLabel ancestor. +

+

+See TAlignment for the values +allowed in the property and their meanings. +

+

+The property value is used when it is relevant to the position for the bound +label relative to its FocusControl. In short, when the bound label appears +above or below the FocusControl. The property value is not used when the bound +label is positioned to the left or right of the FocusControl; the label width +is auto-sized in this use case. See + for more information. +

+

+Use the Layout property to control the vertical alignment for the Caption text +displayed on the label. +

+ + +Added in LCL version 4.0. + + + + + + + +TCustomLabel.Alignment +TAlignment + @@ -6454,7 +6555,44 @@ FocusControl also receives key messages in the DialogChar method. - + + + +Specifies the vertical alignment for the Caption text on the label. + + +

+Layout is a published TTextLayout property in +TBoundLabel. The default value for the property is tlCenter in +TBoundLabel, and causes the Caption to be centered vertically using the Height +for the label. Please note that the default value differs from the default used +in the TCustomLabel ancestor (tlTop). +

+

+See TTextLayout for the values +allowed in the property and their meanings. +

+

+The property value is used when it is relevant to the position for the bound +label relative to its FocusControl. In short, when the bound label appears to +the left or right of the FocusControl. The property value is not used when the +bound label is positioned above or below the FocusControl; the label height is +auto-sized in this use case. See +for more information. +

+

+Use Alignment to control the horizontal alignment used for the Caption text. +

+ + + + + + +TCustomLabel.Layout + + + @@ -6473,12 +6611,26 @@ FocusControl also receives key messages in the DialogChar method. +Specifies the position for a label relative to an associated control. + + +

TLabelPosition is an enumerated type with values that represent the position of a label relative to an associated control: i. e. above, below, left, or right. - - - +

+

+TLabelPosition is the type used for the LabelPosition property in +TCustomLabeledEdit and descendent classes. It is used in the DoPositionLabel +method to position and anchor the EditLabel to its companion control. +

+ + + + + + + Label is displayed above the control. @@ -6497,9 +6649,9 @@ below, left, or right. Defines an edit control with a label bound to the control.

-TCustomLabeledEdit is a TCustomEdit descendant which defines an -edit control with a label bound to the control. TCustomLabeledEdit is the -base type for TLabeledEdit. +TCustomLabeledEdit is a TCustomEdit descendant which +defines an edit control with a label bound to the control. TCustomLabeledEdit +is the base type for TLabeledEdit.

Note particularly the +

+About TCustomLabeledEdit / TLabeledEdit +

+

+TCustomLabeledEdit and TLabeledEdit are based on the +similarly named controls from the Delphi VCL. While they offer code +compatibility with the VCL class, they have some drawbacks when used in the +LCL. They do not work very well with the positioning and anchoring mechanisms +used in LCL. They do not have an Align property used to position, align, and +stack controls towards one of the edges on the control. There are also +shortcomings when using BorderSpacing; the extra spacing is inserted between +the label and the edit box on the control instead around the composite control. +Labels with long captions are not ellipsified or aligned properly when longer +than the associated edit control. Multi-line captions on a label are not +positioned as expected; the label often overlaps (or is obscured by) adjacent +controls. +

+

+Despite the convenience of TCustomLabeledEdit / TLabeledEdit, most will elect +to use separate label and edit controls to avoid the shortcomings in the align +and anchoring mechanisms for the composite control. +

 @@ -6629,14 +6803,19 @@ for the Parent control prior to exiting from the method.

DoPositionLabel updates EditLabel to use the values assigned to the Parent and Visibility properties. The values in LabelPosition -and LabelSpacing are used to determine the anchoring to the -companion control applied to EditLabel. +and LabelSpacing are used to set the anchor position for the +EditLabel and the spacing between EditLabel and the edit box on the control.

+ +Modified in LCL version 4.0 to use the Layout property in the TBoundLabel +instance to determine vertical alignment for the label caption. + + TControl.Visible TWinControl.DisableAlign TWinControl.EnableAlign @@ -6865,15 +7044,16 @@ aligned. -Implements an edit control with a label bound to the control. + +Implements an edit control with a label bound to the control. +

TLabeledEdit is a TCustomLabeledEdit descendant which implements an edit control with a label bound to the control. It saves time and effort over placing separate Label and Edit Box on Form. The properties -are described in the parent component, TCustomLabeledEdit from which -most of the properties are inherited. +are described in the parent component, +TCustomLabeledEdit from which most of the properties are inherited.

Note particularly the @@ -6886,6 +7066,28 @@ Use LabelPosition to specify the location where EditLabel is displayed relative to the edit box in the control. Use LabelSpacing to set the spacing (in pixels) between EditLabel and the edit control.

+

+About TCustomLabeledEdit / TLabeledEdit +

+

+TCustomLabeledEdit and TLabeledEdit are based on the +similarly named controls from the Delphi VCL. While they offer code +compatibility with the VCL class, they have some drawbacks when used in the +LCL. They do not work very well with the positioning and anchoring mechanisms +used in LCL. They do not have an Align property used to position, align, and +stack controls towards one of the edges on the control. There are also +shortcomings when using BorderSpacing; the extra spacing is inserted between +the label and the edit box on the control instead around the composite control. +Labels with long captions are not ellipsified or aligned properly when longer +than the associated edit control. Multi-line captions on a label are not +positioned as expected; the label often overlaps (or is obscured by) adjacent +controls. +

+

+Despite the convenience of TCustomLabeledEdit / TLabeledEdit, most will elect +to use separate label and edit controls to avoid the shortcomings in the align +and anchoring mechanisms for the composite control. +

 @@ -6896,7 +7098,6 @@ relative to the edit box in the control. Use LabelSpacing to set the spacing TCustomEdit TCustomLabel -