From a44d1ab453ddca416e055a9312686702e37960ae Mon Sep 17 00:00:00 2001 From: dsiders Date: Thu, 20 Oct 2022 02:31:16 +0100 Subject: [PATCH] Docs: LCL/controls. Adds, updates topic content. Fixes awkward grammar. Removes tagging not needed for private members. --- docs/xml/lcl/controls.xml | 614 +++++++++++++++++++------------------- 1 file changed, 302 insertions(+), 312 deletions(-) diff --git a/docs/xml/lcl/controls.xml b/docs/xml/lcl/controls.xml index a15c86c649..dbb6ee8363 100644 --- a/docs/xml/lcl/controls.xml +++ b/docs/xml/lcl/controls.xml @@ -556,26 +556,42 @@ Value is '{37417989-8C8F-4A2D-9D26-0FA377E8D8CC}' Defines an interface used in the Lazarus Object Inspector. - - + +

+Allows the Lazarus object inspector to query controls which implement the +interface about the ability to add or delete items in the control. +

+ + +TFlowPanelControl +TFlowPanelControlList + - + +Returns True an item can be added in a control. + - + +Returns True if an item can be added to a control. + - + +Returns True if an item can be deleted from a control. + - + +Returns True an item can be delteted in a control. + @@ -2158,7 +2174,7 @@ TDragImageListResolution is used in the implementation of Value for the property. - + List with images used in Drag and Drop operations. @@ -2427,7 +2443,7 @@ location. New value for the DragHotSpot property. - + initializes the cursor shape and image index for the list. @@ -3044,7 +3060,7 @@ the visual user feedback.

A default DragObject is created automatically when a dragging -operation starts, and is destroyed when the operation has ended; you do not +operation starts, and is destroyed when the operation has ended; you do not need to maintain it. But an application can provide a customized DragObject in the or handlers for the source control (the one being @@ -3359,8 +3375,11 @@ and DragImages. The Image list to be used in dragging this control. + -Creates an object to be destroyed after use. + +Constructor for the class instance. + The control to drag. @@ -3460,8 +3479,8 @@ it. The handler can specify whether a drop will be accepted or rejected. The type used for OnUnDock event handler.

-An UnDock event is sent by a dock site, before a control is undocked from it. -The handler can reject undocking, by setting Allow to False. +An UnDock event is sent by a dock site, and occurs before a control is +undocked. The handler can reject undocking, by setting Allow to False.

@@ -3944,21 +3963,37 @@ Generates visual feedback for mouse movement in a drag operation. -Ends dragging. - + +Ends a drag operation when a mouse up event has occurred. + + +

+MouseUp is an abstract virtual method in TDragManager. +It must be implemented in a descendent class to perform actions needed for +the notification. +

+ - + +Mouse button for the notification. + - + +Ctrl, Shift, or Alt modifier for the notification. + - + +Horizontal pointer position when the mouse event was detected. + - + +Vertical pointer position when the mouse event was detected. + @@ -4002,12 +4037,16 @@ The Delphi VCL sets DragImmediate to True and DragThreshold to 5. -True if the specified control is being dragged. + +Indicates whether the specified control is being dragged. + - + +True if the specified control is being dragged. + @@ -4031,7 +4070,7 @@ sites outside any DragManager instance. -Starts dragging a control. +Starts a drag operation for a control.

A DragObject must be created, depending on the Control.DragKind. The mouse @@ -6607,7 +6646,7 @@ Accessibility support in Lazarus is also documented on the Wiki at: Member with the value for AccessibleRole. - + Gets the value for the AccessibleValue property. @@ -6785,7 +6824,7 @@ Searches in sub-controls for the next child accessibility object. Returns the currently selected child accessible object or Nil if none -are selected; Override this method in your sub class. +are selected; Override this method in your sub class. @@ -7363,136 +7402,52 @@ is set to False. New value for the BorderSpacing property. - - - - - - - - - - - - - - - - - - - - - - - - - - -Sets the value for the Constraints property. - - - - - - -New value for the Constraints property. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Sets the value for the Text property. - -Uses the RealSetText method instead of SetTextBuf, when possible. - - - - - - - - -The new value for the Text property. - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Member with the accessibility object for the control. @@ -8096,7 +8051,7 @@ Value applied to the Height member in the control. Scales the minimum and maximum Width and Height.

-ScaleConstraints is called from the ChangeScale method; never +ScaleConstraints is called from the ChangeScale method; never call it directly. Multiplier and Divider contain the values passed as arguments to the ChangeScale method.

@@ -10376,7 +10331,9 @@ Always returns False in TControl. Overridden in TWinControl. - + +Always returns False in TControl. + @@ -10420,12 +10377,24 @@ its clipping rectangle to the bounds for the control. -Invokes the OnShowHint event handler. - - +Signals the OnShowHint event handler. + +

+Called when the CM_HINTSHOW message is handled for the control. +

+ + + + + + + - + +Pointer to the structure with the position, width, color, and hint text for +the event handler. + @@ -10462,17 +10431,13 @@ not to the up and down handlers [Delphi compatible]. -Invokes the OnMouseWheelDown handler. +Signals the OnMouseWheelDown handler. True if handled. - - - - - - + + Invokes the OnMouseWheelUp handler. @@ -10480,12 +10445,8 @@ not to the up and down handlers [Delphi compatible]. True if handled. - - - - - - + + @@ -14255,7 +14216,7 @@ event handlers in the Parent control. Anchors is a TAnchors property which contains the edges used to align the position of the control relative to its Parent. Anchors allow the control to be repositioned and/or resized when the parent control is resized. Coordinate -values in the control - like Left, Top, Bottom, and Right properties - are +values in the control - like Left, Top, Bottom, and Right properties - are updated when the corresponding edge is anchored to its Parent.

@@ -16597,45 +16558,21 @@ DoubleBuffered property.

 - - - - + - - - - - - - + + - - - - + - - - - + - - - - - - - + + - - - - + - - - + Gets the value for the IsSpecialSubControl property. @@ -16649,23 +16586,11 @@ DoubleBuffered property.

 - - - - - - - - - - - - - + + + - - - + Sets the value for the DesignerDeleting property. @@ -16684,43 +16609,20 @@ DoubleBuffered property.

 - -New value for the Handle property. - + - -New value for the BorderWidth property. - - - - - - - - - - - + + + - -New value for the ParentWindow property. - - + - -New value for the TabOrder property. - - - - - - - - - -New value for the TabStop property. - + + + + + @@ -16883,13 +16785,13 @@ alignment and are visible. -Member used to store the value for the DoubleBuffered property. + +Member used to store the value for the DoubleBuffered property. + Contains various window control state flags. - - @@ -17339,8 +17241,8 @@ Shrinks or enlarges the control to accommodate its children.

-Because this method is frequently overridden, the LCL calls the method instead; it checks whether DoAutoSize +Because this method is frequently overridden, the LCL calls the + method instead; it checks whether DoAutoSize really should be called right now.

@@ -17366,7 +17268,7 @@ Performs actions to resize and align the control and all of its children.

-DoAllAutoSize is an overridden method in TWinControl. +DoAllAutoSize is an overridden method in TWinControl.

No actions are performed in the method when wcfAllAutoSizing has already been @@ -17409,7 +17311,7 @@ control flags when the method is called. -Called from DoAllAutoSize after all bounds are computed for the control. +Called from DoAllAutoSize after all bounds have been computed for the control. @@ -17501,8 +17403,8 @@ Calls the specified procedure for each child control with Root as the Owner.

-Iterates the value in Controls to locate any controls where Root is the Owner -of the control instance. Calls the procedure in Proc using the control +Iterates the values in Controls to locate any controls where Root is the +Owner of the control instance. Calls the procedure in Proc using the control instance as an argument. An application must implement an object procedure using the signature in TGetChildProc, and pass the procedure in the Proc argument. @@ -17524,10 +17426,10 @@ Checks whether the specified class type is allowed as a child control.

-ChildClassAllowed is an overridden method in TWinControl used to determine if -instances of the class type in ClassType are allowed as child controls. -Returns True if the specified class type is allowed as a child control -in the Controls property. +ChildClassAllowed is an overridden method in TWinControl used to +determine if instances of the class type in ClassType are allowed as child +controls. Returns True if the specified class type is allowed as a +child control in the Controls property.

In TWinControl, the return value is True when ChildClass has been @@ -17726,8 +17628,9 @@ Scales (resizes) the control and all of its child controls.

-ChangeScale is an overridden method in TWinControl used to ensure that child -controls are scaled using the values in the Multiplier and Divider arguments. +ChangeScale is an overridden method in TWinControl used to ensure +that child controls are scaled using the values in the Multiplier and Divider +arguments.

ChangeScale extends the inherited method by calling DisableAlign before @@ -17760,10 +17663,10 @@ Handles a CM_BIDIMODECHANGED control message for the control.

-CMBiDiModeChanged is an overridden method in TWinControl used to handle a -CM_BIDIMODECHANGED control message received for the control. It calls the -inherited method on entry to invalidate the control when needed. It extends -the inherited method to notify child controls of the change using a +CMBiDiModeChanged is an overridden method in TWinControl used to +handle a CM_BIDIMODECHANGED control message received for the control. It +calls the inherited method on entry to invalidate the control when needed. It +extends the inherited method to notify child controls of the change using a CM_PARENTBIDIMODECHANGED message.

@@ -17829,14 +17732,31 @@ be redrawn. -Handler for changed Enabled -message; notifies the widgetset. +Handler signalled when the Enabled property has been changed. - - + +

+If the control is not Enabled and has a Parent control, the RemoveFocus +method is called to defocus the control on its Parent form. If the window +Handle has been allocated for the control, the EnableWindow routine in the +LCL interface is called to set the enabled state for the handle. +

+

+CMEnabledChanged calls the inherited method prior to exit to Invalidate the +control. +

+ + + + + + + - + +CM_ENABLEDCHANGED control message which triggered the handler. + @@ -18109,21 +18029,36 @@ itself. Manages paint requests, and handles double buffering. + + +This topic needs more detail. +Which platforms define BUFFERED_WMPAINT? + + - + +LM_PAINT window message examined and handled in the method. + Handler for widget destroyed message; clears the Handle. - + +

+Sets Handle to the unassigned value (0) when the windowed control no longer +exists. +

+ - + +LM_DESTROY window message which triggerred the handler. + @@ -19362,9 +19297,18 @@ Prepares to remove the window (called before the Handle is destroyed). -Assigns sequential TabOrder values to all child controls. - - + +Assigns sequential TabOrder values to child controls. + + +

+Called from the Loaded method when LCL component streaming is completed. It +occurs before auto-sizing is enabled for the component. +

+ + + + @@ -19374,10 +19318,10 @@ control.

-FontChanged is an overridden method in TWinControl which implements the -handler assigned for OnChange events in the Font for the control. The -assignment occurs in the inherited constructor. FontChanged is called when a -new value of assigned to the Font property in the control. +FontChanged is an overridden method in TWinControl +which implements the handler assigned for OnChange events in the control +Font. The assignment occurs in the inherited constructor. FontChanged is +called when a new value of assigned to the Font property in the control.

FontChanged ensures that the widgetset class instance uses the TFont instance @@ -19401,7 +19345,9 @@ child controls of the change to their parent font. -Copies cached control properties to the just created widget. + +Copies cached control properties to the newly created widget. +

Called after the Handle is created, and before child handles are created. @@ -19416,11 +19362,11 @@ Performs actions when a component has been loaded during LCL streaming.

-Loaded is an overridden method in TWinControl used to perform actions needed -when a component has been loaded from a resource during LCL streaming. It -extends the inherited method to align and resize it child Controls, as well -synchronize property values with those in the widgetset class instance when -its handle has been allocated. +Loaded is an overridden method in TWinControl used to +perform actions needed when a component has been loaded from a resource +during LCL streaming. It extends the inherited method to align and resize it +child Controls, as well synchronize property values with those in the +widgetset class instance when its handle has been allocated.

Loaded calls the inherited method to update the BaseBounds for control, and @@ -19432,13 +19378,14 @@ ordered by their TabOrder property.

+ -Realizes all cached changes after a bulk update of the form. Calls the +Realizes all cached changes after a bulk update to a form. Calls the inherited FormEndUpdated method, then informs each child control. @@ -23627,19 +23574,62 @@ its IsDragging method. -Set the mouse capture to AWinControl or its child at the given coordinates. +Set the mouse capture to the specified control, or one of its children, at +the given coordinates. - - + +

+SetCaptureControl is an overloaded procedure in +controls.pp. It ensures that the CaptureControl variable +maintained in the LCL is updated when an control receives or loses the mouse +input focus. +

+

+The overloaded variants allow the new mouse capture control to be specified +as either a TControl or a TWinControl instance. No actions are performed in +the routine if the specified control is already the CaptureControl. +

+

+If the new capture control is unassigned (Nil), the value in +CaptureControl is cleared and the ReleaseCapture routine is called. No +additional actions are performed in the routine. +

+

+Otherwise, the control class is used to determine the actions needed. For a +TWinControl instance, the ControlAtPos method is called determine if a child +control is active at the specified position and the new capture control. For +a TControl instance, which does not have a handle, the Parent control is +used as the new capture control. +

+

+ReleaseCapture is called to remove mouse capture for the previous control. +The SetCapture routine in the LCL interface is called to change the mouse +capture to the control with the specified handle. +

+

+Use GetCaptureControl to retrieve the control which currently has the mouse +capture. +

+ + + + - + +TControl instance (or Nil) representing the control for the mouse capture. + - + +TWinControl instance (or Nil) representing the windowed control for +the mouse capture. + - + +TPoint instance with the coordinates for the mouse input. + @@ -23784,13 +23774,13 @@ transparent.

-CheckTransparentWindow is procedure used to check whether the handle for a -windowed control (or a parent control) is transparent. CheckTransparentWindow -uses the current mouse position to locate controls or forms under the mouse -rectangle. The LM_NCHITTEST message is performed for AWinControl to determine -if the handle is drawn transparently. Additional Forms in the Z-Order are -visited until an opaque windowed control is located. Parent controls are -searched too (when needed). +CheckTransparentWindow is procedure used to check whether the +handle for a windowed control (or a parent control) is transparent. +CheckTransparentWindow uses the current mouse position to locate controls or +forms under the mouse rectangle. The LM_NCHITTEST message is performed for +AWinControl to determine if the handle is drawn transparently. Additional +Forms in the Z-Order are visited until an opaque windowed control is located. +Parent controls are searched too (when needed).

CheckTransparentWindow updates the values in Handle and AWinControl to @@ -23853,7 +23843,7 @@ virtual keyboard keys:

VK_MENU
Includes ssAlt when the Alt key is pressed
VK_LWIN or VK_RWIN
-
Includes ssMeta when one of the WIN keys (or Alt+GR on Mac) is +
Includes ssMeta when one of the WIN keys (or Alt+GR on Mac) is pressed

@@ -23873,8 +23863,8 @@ Adjusts the border space around the control to the client rectangle.

-AdjustBorderSpace is an overloaded routines used to determine the space -reserved for borders on the corresponding edges of a control. +AdjustBorderSpace is an overloaded routine used to determine the +space reserved for borders on the corresponding edges of a control. AdjustBorderSpace is called from methods in a widgetset class when the its bounds and constraints are realized and child controls are aligned to the new dimensions.