From 394b03cd2b991d638ea0220d42fd07785f1e0380 Mon Sep 17 00:00:00 2001 From: dsiders Date: Tue, 10 Sep 2024 06:46:36 +0100 Subject: [PATCH] Docs: LCL/buttons. Updates TCustomSpeedButton topics for changes in d216b714. Issue #41119. * Modified topics: * TCustomSpeedButton.SetLayout * TCustomSpeedButton.CalculatePreferredSize * TCustomSpeedButton.MeasureDraw * TCustomSpeedButton.SetMargin * TCustomSpeedButton.Margin * TCustomSpeedButton.SetSpacing * TCustomSpeedButton.Spacing * TCustomSpeedButton.SetLayout * TCustomSpeedButton.Layout --- docs/xml/lcl/buttons.xml | 127 ++++++++++++++++++++++++++++++--------- 1 file changed, 99 insertions(+), 28 deletions(-) diff --git a/docs/xml/lcl/buttons.xml b/docs/xml/lcl/buttons.xml index 6bd419e50a..7b76431c09 100644 --- a/docs/xml/lcl/buttons.xml +++ b/docs/xml/lcl/buttons.xml @@ -2413,9 +2413,9 @@ The space prior to the glyph bitmap on the aligned edge of the button layout.

Margin is an Integer property with the space reserved prior to the Glyph or image displayed on the button control. It occurs on the -aligned edge specified in Layout, and generally refers to a number of pixels. -The value -1 has special meaning; it causes the glyph and caption to be -centered on the button surface. +aligned edge specified in Layout, and refers to a number of pixels. The value +-1 has special meaning; it causes the glyph and caption to be centered on the +button surface.

The default value for the property is -1. Changing the property value causes @@ -2966,8 +2966,16 @@ GroupIndex, or Down is changed. -Sets the value for the Layout property. - + +Sets the value for the Layout property. + + +

+Calls InvalidatePreferredSize to reset control flags which cause the preferred +size to be recalculated. Calls AdjustSize to apply smart (delayed) resizing for +the control. +

+ @@ -3183,24 +3191,36 @@ Calculates the default height and Width required for the control.

-Calls MeasureDraw to gets the values for the variable parameters in -PreferredWidth and PreferredHeight. +CalculatePreferredSize is an overridden method in TCustomSpeedButton. It calls +MeasureDraw to gets the values for the variable parameters in PreferredWidth +and PreferredHeight. If WithThemeSpace is enabled, additional spacing is +reserved in PreferredWidth and PreferredHeight for theme element details; both +arguments are increased by six (6) pixels. +

+

+CalculatePreferredSize is called from the GetPreferredSize method (in TControl) +when control flags indicate the value has not already been determined.

- -Please note that the WithThemeSpace parameter is NOT used in the -current implementation. - - + +TControl.GetPreferredSize + -Width calculated for the control. + +Preferred width for the control. + -Height calculated for the control. + +Preferred height for the control. + -Not used in the current implementation. + +Indicates if additional space is reserved in PreferredWidth and PreferredHeight +for theme element details. + @@ -3211,9 +3231,9 @@ optionally renders the control.

MeasureDraw determines the space needed to draw the content for the -speed button control. Values in the Caption, Glyph, Margin, Spacing, and -Layout properties are used to determine the layout for the control elements -and the space needed to draw the control without clipping. +speed button control. Values in the Caption, ShowCaption, Glyph, Margin, +Spacing, and Layout properties are used to determine the layout for the control +elements and the space needed to draw the control without clipping.

When Draw is enabled, the control is rendered to its Canvas using the State, @@ -3236,7 +3256,7 @@ any drawing effect applied in ThemeServices for the control State.

When Caption has been assigned and ShowCaption is enabled, the text size is included in the calculated space requirements. The values in Margins and -Spacing are included on the horizontal or vertical size based on the value in +Spacing are included in the horizontal or vertical size based on the value in Layout. Values in Alignment and UseRightToLeftReading are used when the text rectangle is calculated. If the Font matches the default System font settings, ThemeServices.DrawText is called to measure/render the text for the control. @@ -3254,6 +3274,7 @@ Used in the implementation of the CalculatePreferredSize and Paint methods. + @@ -3509,10 +3530,23 @@ whether or not button was pressed) Sets the value for the Margin property. -SetMargin - specifies the size of the margin +

+SetMargin sets the size of the Margin used on the control. Calls +InvalidatePreferredSize to update control flags which cause the preferred +height and width for the control to be recalculated using the new Margin value. +Calls adjust size to perform smart (delayed) resizing when needed. Calls +Invalidate to redraw the control. +

 + +Modified in LCL version 3.6 to recalculate the size and redisplay the control +when Margin is changed. + +TControl.InvalidatePreferredSize +TControl.AdjustSize +TControl.Invalidate @@ -3533,12 +3567,26 @@ whether or not button was pressed) -Sets the value for the Spacing property. + +Sets the value for the Spacing property. + -SetSpacing - specifies the spacing between buttons. +

+SetSpacing specifies the spacing used between adjacent controls. +Calls InvalidatePreferredSize to recalculate the preferred height and width for +the control. AdjustSize is called to perform smart (delayed) resizing when +needed. Invalidate is called to redraw the control. +

 + +Modified in LCL version 3.6 to recalculate preferred size and resize the +control when the property is changed. + +TControl.InvalidatePreferredSize +TControl.AdjustSize +TControl.Invalidate @@ -4333,7 +4381,8 @@ Margin, Glyph (or image), Spacing, and Caption to be aligned to the left edge of the button surface.

-Changing the property value causes the control to be redrawn. +Changing the property value causes the default size for the control to be +recalculated (in SetLayout), and the control is redrawn.

Layout is used in the MeasureDraw method to position and size the text and @@ -4364,10 +4413,14 @@ Space between the glyph bitmap and the aligned edge in the button layout.

Margin is an Integer property with the space reserved -between the Glyph image an the edge of the control. It occurs on the edge -specified in Layout, and generally refers to a number of pixels. The value -1 -has special meaning; it causes both the glyph and caption to be centered on -the button surface. +between the Glyph image an the edge of the control. It is applied on the edge +specified in Layout, and refers to a number of pixels. The value -1 has special +meaning; it causes both the glyph and caption to be centered on the button +surface. +

+

+Changing the value for the property causes the control to recalculate its +preferred size, and the control is redrawn (in SetMargin).

Margin is used in the MeasureDraw method when the glyph image and caption text @@ -4381,6 +4434,9 @@ bitmap and caption are aligned. Use Spacing to set the space reserved between the glyph bitmap and the caption for the control.

+

+BorderSpacing.InnerBorder can be used as an alternative to the Margin property. +

@@ -4389,7 +4445,10 @@ caption for the control. + TControl.Caption +TControl.BorderSpacing +TControlBorderSpacing.InnerBorder @@ -4537,8 +4596,20 @@ centered, with the same amount of unused space on each side of the control. If Spacing is -1 and Margin is not -1 then Spacing will fill the remaining unused space.

+

+Changing the value for the property causes the preferred size to be +recalculated, and the control is redrawn (in SetSpacing). +

- + + + + + + + +TControl.Caption +