From 24d0ade4bcc45bd5b15a450dfed3c12d468bac35 Mon Sep 17 00:00:00 2001 From: dsiders Date: Tue, 29 Nov 2022 20:57:27 +0000 Subject: [PATCH] Docs: LCL/stdctrls. Adds and updastes topics for changes in 369b6b25. * Adds TCustomLabel.SetVisible topic. * Modifies TCustomLabel.AutoSize to clarify interactions with Width, Height, WordWrap, Anchors, and Alignment properties. * Updates topics to follow declaration order in the interface. --- docs/xml/lcl/stdctrls.xml | 538 ++++++++++++++++++++++---------------- 1 file changed, 313 insertions(+), 225 deletions(-) diff --git a/docs/xml/lcl/stdctrls.xml b/docs/xml/lcl/stdctrls.xml index f456488c7b..d03843cc7f 100644 --- a/docs/xml/lcl/stdctrls.xml +++ b/docs/xml/lcl/stdctrls.xml @@ -12951,6 +12951,268 @@ and TextChanged methods, and when setting a new value for the + + +Sets the value for the Visible property. + + +

+SetVisible is an overridden method in TCustomLabel used +to set the value for the Visible property. It ensures that the Left property +is updated when taRightJustify is used in the Alignment property. For a +right-aligned value, Left is moved as needed to display the new Width for the +control. This action is performed when the value in Visible is changed to True +and either AutoSize or OptimalFill is also enabled. +

+ + +Added in LCL version 2.4. + + + + + +TControl.Visible +TControl.Width +TControl.Left +TControl.SetVisible +TAlignment + + + + +New value for the Visible property. + + + + + +Horizontal text justification in the control (centered, left- or +right-justified). + + +

+Alignment is a TAlignment property which controls the +horizontal justification of the text displayed in the control. The default +value for the property is taLeftJustify. When a new value is +assigned to the Alignment property, the Invalidate method is +called to repaint the control. +

+

+Alignment (and other properties) are used in the Paint method when +the text is rendered to the Canvas for the control. It is also +used in UpdateSize when right alignment needs to be considered for +an auto-sized or optimal-filled control. +

+

+Use the Layout property to control the vertical alignment of the +text displayed in the control. +

+

+Use OptimalFill to indicate if the font height can be adjust to +fill the client area for the control. +

+ + + + + + + +TControl.Invalidate +TAlignment + + + + + +The control associated with the label and its accelerator key (AccelChar). + + +

+Set FocusControl to the control which is focused when the +accelerator key in the label is pressed. +

+

+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. +

+

+Using a combination of a label and another control allows setting the +accelerator key in the label caption. The other control receives focus when +the user presses the accelerator key. +

+

+An accelerator key is marked by an Ampersand '&' in the label caption, +immediately preceding the character to be used as the accelerator key. The +marked character appears underlined on screen, when ShowAccelChar is set to +True. +

+

+For example: When you have a NameEdit1 control on a form, preceded by a label +NameLabel1, you can set NameLabel1.FocusControl to NameEdit1, and +NameLabel1.Caption to '&Name'. +

+ + + + + + + + +Vertical alignment for control text (at the top, bottom, or center). + + +

+Layout is a TTextLayout property with the vertical +alignment used for the text displayed in the control. The default value for +the property is tlTop. Changing the value in Layout causes the +Invalidate method to be called to redraw the control. +

+

+Use the Alignment property to control the horizontal alignment for +the text in the control. +

+

+Use OptimalFill to indicate if the font height can be adjusted to +fill the client area for the control. +

+ + + + +TTextLayout +TControl.Invalidate + + + + + +Underlines the character in the label that acts as the accelerator or short +cut key. + + +

+When False, an Ampersand (&) character in the label caption +is displayed as an ordinary character (as used in the Object Inspector). +

+

+When True, the character following the Ampersand is drawn with +an underline. When the user presses the accelerator key, input focus is given +to the associated FocusControl. +

+ + + +TControl.Caption + + + + +Indicates whether the viewer can see through the control. + +

+When Transparent is set to False, the enclosing rectangle for the +control is filled with the background Color for the label. When set to +True, Color is not used to fill the background for the control and the +underlying control is visible. +

+

+The property value is True when csOpaque has not been included in the +style flags for the control. Changing the value for the property causes +ControlStyle to be updated. When set to True, csOpaque is +removed from ControlStyle. When set to False, csOpaque is included in +ControlStyle. The control is redrawn when a new value is assigned to the +property. +

+

+The default value for Transparent in the LCL is True. This differs +from the default value in the Delphi VCL. +

+

+Values in Transparent and Color are used in the Paint method when the +background and text for the control are drawn. When Transparent is +False and Color has a value other than clNone, a solid brush is used +to fill the display area with the value in Color. +

+ + +Modified in LCL version 2.4. Transparent is no longer toggled when Color is +changed. Its value is independent of Color. + + + + +TControl.ControlStyle + + + + + +Allows the caption to wrap to multiple lines when it is longer than the +available Width. + + +

+WordWrap is a Boolean property which indicates if the +caption in the control can be wrapped to multiple lines when its length +exceeds the value in Width. The default value for the property is +False. +

+

+When a new value is assigned to the property, the Invalidate and +UpdateSize methods are called to auto-size and repaint the control. +

+

+When WordWrap is False, the text is truncated at the right boundary +when it is too long for the control Width. When WordWrap is True and +AutoSize is True, the maximum Width is +determined by anchoring the left and right sides for the control to its +Parent. +

+ + + + +TControl.Width +TControl.Invalidate + + + + + +If True, the font size is adjusted for optimal fill of the available +space. + + +

+OptimalFill is a Boolean property which indicates that +the Font height should be maximized to fill the available width in +the control. The default value for the property is False. +

+

+Setting OptimalFill to True causes AutoSize to be set to +False. The AdjustFontForOptimalFill method is called to get +and apply the maximum font height allowed for the Width and +Height in the control. +

+

+Changing the value for the property causes Invalidate to be called +to redraw the control. +

+ + + + +TControl.Width +TControl.Height +TControl.Font +TControl.Invalidate + + + Constructor for the class instance. @@ -13145,59 +13407,73 @@ enabled in the control. Calls the inherited method prior to exit. New Height for the control. - + -Horizontal text justification in the control (centered, left- or -right-justified). +Enables or disables auto-sizing the control to its content.

-Alignment is a TAlignment property which controls the -horizontal justification of the text displayed in the control. The default -value for the property is taLeftJustify. When a new value is -assigned to the Alignment property, the Invalidate method is -called to repaint the control. +AutoSize is a Boolean property reintroduced in TCustomLabel to set its default +value to True.

-Alignment (and other properties) are used in the Paint method when -the text is rendered to the Canvas for the control. It is also -used in UpdateSize when right alignment needs to be considered for -an auto-sized or optimal-filled control. +Auto-sizing behavior in TCustomLabel differs from the +implementation in the ancestor class (TControl). For example, a label can +become bigger or smaller to accommodate a longer or shorter caption. In other +controls, the property may control only the height for the control based on +the Font size.

-Use the Layout property to control the vertical alignment of the -text displayed in the control. +AutoSize causes the control to be resized to fit the content in the Caption +property. This can include changing the values in Top, Left, Width, or Height +if the corresponding edge(s) are not fixed using the Anchors property. Any +edge included in Anchors is not altered when the control is auto-sized.

-Use OptimalFill to indicate if the font height can be adjust to -fill the client area for the control. +In addition to Anchors, auto-sizing behavior is also influenced by the +Alignment and WordWrap properties for the control. When Alignment is set to +taLeftJust or taRightJustify, and AutoSize is not enabled, the control +displays the caption value aligned to the edge specified in Alignment. Excess +characters which do not fit in the Width for the control are truncated. +

+

+When AutoSize is enabled, the control is resized to fit the characters in +Caption by repositioning the opposite edge for the Alignment value. For +taLeftJustify, the right edge is expanded or contracted by changing the value +in Width. For taRightJustify, the value in Left is repositioned until all +characters are displayed using the Alignment. +

+

+Use the Anchors property to fix the position for an edge during auto-sizing +regardless of the value in the Alignment property. For example, when Anchors +is set to [akTop, akLeft, akRight], only the height for the control can be +altered when AutoSize is enabled. +

+

+When WordWrap is enabled, and both the left and right edges are included in +Anchors, the height for the label control is adjusted during auto-sizing. +

+

+Simultaneous use of both AutoSize and OptimalFill can have conflicting +results. AutoSize tries to use the existing Font to determine the control width +/height. OptimalFill adjusts the Font size to fill the control width/height. +

+

+Changing the value for the property causes AdjustSize (in TControl) to be +called when the property is enabled.

- + + - - -TControl.Invalidate -TAlignment - - - - -Enables or disables auto-sizing for the control to its content. - -

-The action performed depends on the control type. For example, a label or -button can become bigger or smaller to accommodate a longer or shorter -caption. -

-

-The default value for the property is True in TCustomLabel. -

- - + + +TControl.Caption +TControl.Anchors TControl.AutoSize +TControl.AdjustSize @@ -13240,194 +13516,6 @@ Setting Color does not automatically change Transparent from True to - - -The control associated with the label and its accelerator key (AccelChar). - - -

-Set FocusControl to the control which is focused when the -accelerator key in the label is pressed. -

-

-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. -

-

-Using a combination of a label and another control allows setting the -accelerator key in the label caption. The other control receives focus when -the user presses the accelerator key. -

-

-An accelerator key is marked by an Ampersand '&' in the label caption, -immediately preceding the character to be used as the accelerator key. The -marked character appears underlined on screen, when ShowAccelChar is set to -True. -

-

-For example: When you have a NameEdit1 control on a form, preceded by a label -NameLabel1, you can set NameLabel1.FocusControl to NameEdit1, and -NameLabel1.Caption to '&Name'. -

- - - - - - - - -Vertical alignment for control text (at the top, bottom, or center). - - -

-Layout is a TTextLayout property with the vertical -alignment used for the text displayed in the control. The default value for -the property is tlTop. Changing the value in Layout causes the -Invalidate method to be called to redraw the control. -

-

-Use the Alignment property to control the horizontal alignment for -the text in the control. -

-

-Use OptimalFill to indicate if the font height can be adjusted to -fill the client area for the control. -

- - - - -TTextLayout -TControl.Invalidate - - - - - -If True, the font size is adjusted for optimal fill of the available -space. - - -

-OptimalFill is a Boolean property which indicates that -the Font height should be maximized to fill the available width in -the control. The default value for the property is False. -

-

-Setting OptimalFill to True causes AutoSize to be set to -False. The AdjustFontForOptimalFill method is called to get -and apply the maximum font height allowed for the Width and -Height in the control. -

-

-Changing the value for the property causes Invalidate to be called -to redraw the control. -

- - - - -TControl.Width -TControl.Height -TControl.Font -TControl.Invalidate - - - - - -Underlines the character in the label that acts as the accelerator or short -cut key. - - -

-When False, an Ampersand (&) character in the label caption -is displayed as an ordinary character (as used in the Object Inspector). -

-

-When True, the character following the Ampersand is drawn with -an underline. When the user presses the accelerator key, input focus is given -to the associated FocusControl. -

- - - -TControl.Caption - - - - -Indicates whether the viewer can see through the control. - -

-When Transparent is set to False, the enclosing rectangle for the -control is filled with the background Color for the label. When set to -True, Color is not used to fill the background for the control and the -underlying control is visible. -

-

-The property value is True when csOpaque has not been included in the -style flags for the control. Changing the value for the property causes -ControlStyle to be updated. When set to True, csOpaque is -removed from ControlStyle. When set to False, csOpaque is included in -ControlStyle. The control is redrawn when a new value is assigned to the -property. -

-

-The default value for Transparent in the LCL is True. This differs -from the default value in the Delphi VCL. -

-

-Values in Transparent and Color are used in the Paint method when the -background and text for the control are drawn. When Transparent is -False and Color has a value other than clNone, a solid brush is used -to fill the display area with the value in Color. -

- - -Modified in LCL version 2.4. Transparent is no longer toggled when Color is changed. Its value is independent of Color. - - - - -TControl.ControlStyle - - - - - -Allows the caption to wrap to multiple lines when it is longer than the -available Width. - - -

-WordWrap is a Boolean property which indicates if the -caption in the control can be wrapped to multiple lines when its length -exceeds the value in Width. The default value for the property is -False. -

-

-When a new value is assigned to the property, the Invalidate and -UpdateSize methods are called to auto-size and repaint the control. -

-

-When WordWrap is False, the text is truncated at the right boundary -when it is too long for the control Width. When WordWrap is True and -AutoSize is True, the maximum Width is -determined by anchoring the left and right sides for the control to its -Parent. -

- - - - -TControl.Width -TControl.Invalidate - - - Control used to display static text, possibly in multiple lines.