From 1816b5e580f1ab71c7f4c851ea9e2cc4bf3a4549 Mon Sep 17 00:00:00 2001 From: dsiders Date: Fri, 14 Jul 2023 13:35:53 +0100 Subject: [PATCH] Docs: LCL/stdctrls. Restores documentation after reverting commit 9f577dc5. (cherry picked from commit 957d62af5622061d7f5bcac5b3eab5db894280e7) --- docs/xml/lcl/stdctrls.xml | 343 +++----------------------------------- 1 file changed, 23 insertions(+), 320 deletions(-) diff --git a/docs/xml/lcl/stdctrls.xml b/docs/xml/lcl/stdctrls.xml index 2ca151f3a8..4f3e5d87f0 100644 --- a/docs/xml/lcl/stdctrls.xml +++ b/docs/xml/lcl/stdctrls.xml @@ -10016,12 +10016,6 @@ mechanism. - - -Member used to suppress calls to OnClicked in TCustomCheckBox. - - - Implements the default handler for the LM_CLICKED message. @@ -10088,16 +10082,17 @@ Performs actions needed when a click message is handled for the control.

-Click is an overridden method in TButtonControl. It -ensures that an OnChange notification occurs when needed. Click calls the -DoOnChange method which signals the OnEditingDone and -OnChange event handlers (when assigned). +Click is an overridden method in TButtonControl. Click +calls the DoOnChange method which signals the +OnEditingDone and OnChange event handlers (when +assigned).

Click calls the inherited method prior to exit. The inherited method (in -TControl) signals either the OnClick handler for the control or the OnExecute -handler in the Action. OnClick is used when Action has not been assigned, or when OnClick contains a handler routine that differs from the one assigned to -the OnExecute handler in the Action. +TControl) signals either the OnClick event handler or the OnExecute handler +in the Action. OnClick is used when Action has not been assigned, or when +OnClick contains a handler routine that differs from the one assigned to the +OnExecute handler in the Action.

Click can be called in two different usage scenarios. If standard click @@ -10108,19 +10103,10 @@ ControlStyle. This avoids duplicate click notifications when csClickEvents is enabled in ControlStyle and Click is handled when the WMLButtonUp method is executed.

-

-Click is overridden and re-implemented in the TCustomCheckBox descendent to -provide support for Delphi VCL-compatible OnClick notifications. -

 - -Modified in LCL 3.0 to support Delphi VCL-compatible OnClick notifications. - - - TControl.Click TControl.Action TControl.OnEditingDone @@ -11346,52 +11332,37 @@ handler. Use ClicksDisabled is control the event handler signalled.

Click is an overridden method in TCustomCheckBox. It -performs actions needed when a mouse click or its keyboard equivalent occurs -for the control. +performs actions needed when the value in the Checked or State property is +changed for the control, whether by mouse click or setting the value in +program code.

TCustomCheckBox re-implements the method from the TButtonControl ancestor to -provide support for OnClick event notifications. The VCL_OnClick_Emulation -class variable determines whether Delphi VCL-compatible OnClick event -notifications are used. No actions are performed in the method when -VCL_OnClick_Emulation is set to True. The OnClick event is signalled -when the LM_CLICKED message is applied in the ancestor class -(TButtonControl). +ignore the mouse click event. It has an empty implementation, and does not call the inherited method.

-See VCL_OnClick_Emulation for more information about Delphi VCL-compatible -OnClick event notifications. +In TCustomCheckBox, the click action may be handled in two different ways. +The action may be performed (in TControl) when the left mouse button is +released and standard click events are enabled in ControlStyle. The click +action may be performed in DoClickOnChange (by calling the inherited Click +method) when the value in State is changed and ClicksDisabled is False.

-When VCL_OnClick_Emulation is False, the inherited Click method (in -TButtonControl) is called to perform the actions needed. This includes -signalling the OnChange event handler (when assigned and not already -performed), and executing the OnClick handler in the control or the OnExecute -handler from an assigned Action. -

-

-Use the OnChange event handler to perform any actions needed when a new value -is assigned to the State (or Checked) property. -

-

-Use the OnClick event handler to perform any actions needed when mouse is clicked on the control. +This avoids a duplicate click notification when csClickEvents is enabled in +ControlStyle and Click is handled when the WMLButtonUp method is executed, or +when the click is triggered by an associated Action.

- -Modified in LCL 3.0 to support Delphi VCL-compatible OnClick notifications. - - - TControl.Click -TControl.OnClick TControl.Action TControl.ControlState TControl.ControlStyle +TControl.WMLButtonUp @@ -11639,142 +11610,6 @@ TextChanged calls the inherited method prior to exit. Creation parameters updated in the method. - - -Indicates whether the OnClick behavior used in the Delphi VCL is enabled for -the control. - - -

-VCL_OnClick_Emulation is a class variable which indicates whether -the OnClick event is signalled using the behavior implemented in the Delphi -VCL. -

-

-For check box-style controls, there are two events of particular -significance: OnChange and OnClick. -

-

-In the LCL (Lazarus Component Library), these events are separate and -distinct. OnChange occurs when the value in either the State or the Checked -property is changed to a new value. This can result from assignment in -program code, by clicking the mouse, or using a keyboard equivalent which -causes the property to be updated. OnClick occurs only when the mouse or -keyboard is used to interact with the control. -

-

-In the Delphi VCL, the OnChange event does not exist. The OnClick handler is -signalled when the value in State is changed and when the control is clicked. -This class member allows use of Delphi handling for OnClick when the -application has not accounted for the difference between the events and their -usage in the LCL. -

-

-When set to True, the OnClick event is signalled each time the State -property is changed to a new value - including when the value was assigned -instead of using the mouse or keyboard to perform the change. OnClick (and -OnChange) are signalled only when a change in the State or Checked value -occurs. -

-

-The OnChange event in the VCL emulation mode has the same semantics and would -be fired immediately before calling OnClick. This allows developers to -migrate their applications from Delphi and gradually rework their code -preparing for the behavior switch. -

-

-For example, when a user clicks TRadioButton many times the event handler -would only be called when the button transits to the selected state. -Subsequent clicks on the already selected radio button would not result in -additional OnClick event notifications. The OnChange event is also suppressed -in this scenario. -

-

-When set to False, LCL event handling is used. The OnChange event -handler is signalled when the State or Checked property is changed to a new -value, whether the change was caused by a user action or assignment in -program code. -

-

-The OnClick event handler in this mode is signalled each time the control is -activated using the mouse, the keyboard, or by any other user action the -operating system considers equal to clicking. It is signalled even when the -State for the control is not changed. For radio buttons, repeated clicks on -an already Checked control would result in an OnClick event notification for -each mouse click. -

-

-VCL_OnClick_Emulation does not require a class instance to access the member -value. Changing the value affects all instances of the TCustomCheckBox -control and descendants (like TToggleBox and TRadioButton) used in the -application. -

-

-For example: -

- -// enable Delphi OnClick behavior for all check boxes and descendants -TCheckBox.VCL_OnClick_Emulation := True; - -// enable LCL OnClick behavior for all check boxes and descendants -TCheckBox.VCL_OnClick_Emulation := False; - -

-The default value for the member is True as assigned in the -CreateClass class constructor. This enables Delphi VCL-compatible OnClick -event notifications. -

-

-VCL_OnClick_Emulation is used in the Click method to prevent calls to -the inherited Click method when enabled. It is also used in the -DoClickOnChange method to ensure that the inherited Click method is called -when enabled and not already handled by an assigned Action. -

- - -Added in LCL version 3.0. - - - - - - - - - -TControl.OnClick -TControl.Click - - - - - -Class constructor for the TCustomCheckBox class type. - - -

-CreateClass is the class constructor for the -TCustomCheckBox class type. It allows class variables and class -properties to be initialized before the class type is used. The class -constructor is not explicitly called in program code; it is called -before entry into the initialization section for the stdctrls.pp -unit. -

-

-CreateClass ensures that the VCL_OnClick_Emulation class variable is set to -True before an instance of the class is created. This enables Delphi -VCL-compatible OnClick behavior in TCustomCheckBox and descendent classes -like TCheckBox, TRadioButton and TToggleBox. -

- - -Added in LCL version 3.0. - - - - - - Constructor for the class instance. @@ -12031,50 +11866,6 @@ enables auto-sizing of the text displayed for the control instance. - - -Event handler signalled when a mouse click occurs on the control. - - -

-OnClick is a published TNotifyEvent property in -TCheckBox. It contains the event handler signalled when a mouse -click, or the keyboard equivalent, occurs when the control has focus. The -actions performed for the click event can be specified in a user-supplied -method, or by selecting an Action from an ActionList. -

-

-OnClick is signalled (when assigned) from the Click method in the -TButtonControl ancestor. It occurs when the event has not been handled in the -descendant class and an Action has not been assigned using the ActionLink for -the control. When Action is assigned, the Execute method in the ActionLink is -called instead. -

-

-TButtonControl descendants, like TCheckBox and TRadioButton, may signal the -event handler when the value in State (or Checked) is changed. The -VCL_OnClick_Emulation class variable enables this Delphi VCL-compatible -behavior when it is set to True. When set to False, the event -occurs only when mouse or keyboard is used to interact with the control. -

-

-Use the OnChange event handler to perform actions needed when the value in -the State property is changed. -

- - - - - - -TControl.OnClick -TControl.Action -TControl.ActionLink -TBasicAction -TNotifyEvent - - - @@ -12198,51 +11989,7 @@ TabStop (True) and ParentColor (False) properties. - - - -Event handler signalled when the mouse is clicked on the control. - - -

-OnClick is a published TNotifyEvent in -TToggleBox. It contains the event handler signalled when a mouse -click, or the keyboard equivalent, occurs when the control has focus. The -actions performed for the click event can be specified in a user-supplied -method, or by selecting an Action from an ActionList. -

-

-OnClick is signalled (when assigned) from the Click method in the -TButtonControl ancestor. It occurs when the event has not been handled in the -descendant class and an Action has not been assigned using the ActionLink for -the control. When Action is assigned, the Execute method in the ActionLink is -called instead. -

-

-TButtonControl descendants, like TCheckBox and TToggleBox, may signal the -event handler when the value in State (or Checked) is changed. The -VCL_OnClick_Emulation class variable enables this Delphi VCL-compatible -behavior when it is set to True. When set to False, the event -occurs only when mouse or keyboard is used to interact with the control. -

-

-Use the OnChange event handler to perform actions needed when the value in -the State property is changed. -

- - - - - - -TControl.OnClick -TControl.Action -TControl.ActionLink -TBasicAction -TNotifyEvent - - - + @@ -12511,51 +12258,7 @@ The default value for the property is True in TRadioButton. - - - -Event handler signalled when the mouse is clicked on the control. - - -

-OnClick is a published TNotifyEvent in -TRadioButton. It contains the event handler signalled when a mouse -click, or the keyboard equivalent, occurs when the control has focus. The -actions performed for the click event can be specified in a user-supplied -method, or by selecting an Action from an ActionList. -

-

-OnClick is signalled (when assigned) from the Click method in the -TButtonControl ancestor. It occurs when the event has not been handled in the -descendant class and an Action has not been assigned using the ActionLink for -the control. When Action is assigned, the Execute method in the ActionLink is -called instead. -

-

-TButtonControl descendants, like TCheckBox and TToggleBox, may signal the -event handler when the value in State (or Checked) is changed. The -VCL_OnClick_Emulation class variable enables this Delphi VCL-compatible -behavior when it is set to True. When set to False, the event -occurs only when mouse or keyboard is used to interact with the control. -

-

-Use the OnChange event handler to perform actions needed when the value in -the State property is changed. -

- - - - - - -TControl.OnClick -TControl.Action -TControl.ActionLink -TBasicAction -TNotifyEvent - - - +