From a3f8f3c24bb537f936db4bd5ff708ae5325bba3c Mon Sep 17 00:00:00 2001 From: dsiders Date: Tue, 28 Dec 2021 03:31:08 +0000 Subject: [PATCH] Docs: LCL. Adds or updates topic content. (cherry picked from commit b4b11c6f2a47bb4472cc02b0287ec669c1a51ada) --- docs/xml/lcl/controls.xml | 73 +++++++++++++++++++++++++++++++++------ docs/xml/lcl/dialogs.xml | 44 ++++++++++++++++------- 2 files changed, 93 insertions(+), 24 deletions(-) diff --git a/docs/xml/lcl/controls.xml b/docs/xml/lcl/controls.xml index a0d14c1e70..45d9e0b595 100644 --- a/docs/xml/lcl/controls.xml +++ b/docs/xml/lcl/controls.xml @@ -8660,22 +8660,38 @@ - The Caption property. + Value for the Caption property. - Sets the Caption property. + Sets the value for the Caption property. - This method is called by SetText, when SetTextBuf is not overridden. +

+ RealSetText is a method used to apply the TCaption value in AValue to the text or caption for the control. RealSetText is called by the private SetText method, when SetTextBuf has not been overridden. +

+

+ Notes on TControl.Caption, TControl.Text, et. al. +

+

+ The Delphi VCL implementation relies on the virtual GetTextBuf and SetTextBuf methods to exchange text for controls.. This requires a lot of (unnecessary) copies to move values between Text and Caption. +

+

+ The LCL uses strings to exchange text values because it is more efficient. To maintain VCL compatibility, the virtual RealGetText and RealSetText methods were introduced. These functions use the LCLInterface. The default GetTextBuf and SetTextBuf implementations calls the RealGetText and RealSetText methods as needed. As long as the GetTextBuf and/or SetTextBuf aren't overridden, GetText and SetText call RealGetText and RealSetText to avoid copying PChar values. +

+

+ To keep things optimal, LCL implementations should always override RealGetText and RealSetText. GetTextBuf and SetTextBuf are only kept for compatibility with Delphi code. +

- + + + - The string to store. + The string value to store in the Text / Caption properties. @@ -8700,9 +8716,19 @@ Here: FCaption (can be overridden). - + + Sets the value for the Action property. + +

+ Ensures that ActionLink is updated when the value for the property is updated. When Value is unassigned (Nil), ActionLink is freed and set to Nil. The control style flags are also updated to remove the value csActionClient. Otherwise, a new ActionLink class instance is created for ActionLink and Value is assigned to its Action property. Its OnChange handler is assigned, and the ActionChange method is called to apply values from the action to the control. +

+ + + + + - + New value for the Action property. @@ -8723,9 +8749,19 @@ New value for the Color property. - + + Sets the value for the Enabled property. + +

+ Calls EnabledChanging to notify handlers for the chtOnEnabledChanged type. Stores the new value for the property, and performs a CM_ENABLEDCHANGED control message. Calls EnabledChanged to notify handlers for the chtOnEnabledChanged type. +

+ + + + + - + New value for the Enabled property. @@ -15112,9 +15148,24 @@ Value for the MouseCapture property. - + + Sets the text / caption for the control. + +

+ RealSetText is an overridden method in TWinControl. It ensures that the new value is applied to the widgetset class when its Handle has been allocated, and the control size is adjusted when needed/enabled. The inherited method is called to apply AValue to the Text and/or Caption properties for the control. +

+ + + + + + + + + + - + New value for the text / caption for the control. diff --git a/docs/xml/lcl/dialogs.xml b/docs/xml/lcl/dialogs.xml index 762b2dcafe..e92bb8a216 100644 --- a/docs/xml/lcl/dialogs.xml +++ b/docs/xml/lcl/dialogs.xml @@ -1970,7 +1970,7 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; Constructor for the class instance.

- Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create allocates resources needed for the Font property, and sets the default values in the Options property. + Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create allocates resources needed for the Font property, and sets the default values in the Options property.

@@ -2012,12 +2012,13 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; Minimum font size allowed in the font selection dialog.

- MinFontSize is an Integer property which contains the minimum font size allowed in the font selection dialog. Limiting font size selection to the range in MinFontSize and MaxFontSize must be enabled using the Options property. + MinFontSize is an Integer property which contains the minimum font size allowed in the font selection dialog. Limiting font size selection to the range in MinFontSize and MaxFontSize must be enabled by including fdLimitSize in the Options property.

+ @@ -2025,17 +2026,18 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; Maximum font size allowed in the font selection dialog.

- MaxFontSize is an Integer property which contains the maximum font size allowed in the font selection dialog. Limiting font size selection to the range in MinFontSize and MaxFontSize must be enabled using the Options property. + MaxFontSize is an Integer property which contains the maximum font size allowed in the font selection dialog. Limiting font size selection to the range in MinFontSize and MaxFontSize must be enabled by including fdLimitSize in the Options property.

+ - A set of options available from TFontDialogOptions. + A set of TFontDialogOption options enabled for the dialog.

Options is a TFontDialogOptions property which controls the options enabled for the font selection dialog. Options contains zero or more values from the TFontDialogOption enumeration. The default value for the property is [fdEffects], and enables the font effects check boxes in the dialog. @@ -2044,7 +2046,7 @@ ADialog.CustomColors.Values['ColorA'] := 'FFFF00'; See TFontDialogOption for more information about the values in the enumeration and their usage.

- Set (or Include and Exclude) values in the property prior to calling the Execute method. + Include or Exclude values for the property prior to calling the Execute method.

@@ -4623,7 +4625,7 @@ end; - Base class for a dialog form used for copy to clipboard operations. + Base class for a dialog form used during copy to clipboard operations. @@ -4662,7 +4664,9 @@ end; Enables key preview and adds the OnKeyDown handler for the specified dialog. - + + + Dialog form instance updated in the routine. @@ -4697,7 +4701,7 @@ end; - Input Query Edit size in % of monitor width. + Input Query Edit size as a percentage of the monitor width. @@ -4712,16 +4716,30 @@ end; List of options available when selecting a directory. - + Allows a new directory to be created in a select directory dialog. - + + Indicates a directory that does not already exist should be created following execution of the dialog. + - + + Indicates the dialog should prompt the user for confirmation of the selected action. + + - Set type for directory selection options. + Set type used to store directory selection options. + +

+ TSelectDirOpts is a set type used to store zero or more values from the TSelectDirOpt enumeration. Values added to the set indicate the options enabled for a directory selection dialog. A TSelectDirOpts argument is passed to the SelectDirectory routine. +

+ + + + + @@ -4941,7 +4959,7 @@ end; - String with the item selected in the combo-box, or and empty string if the dialog is cancelled. + String with the item selected in the combo-box, or an empty string if the dialog is cancelled.