diff --git a/docs/xml/lcl/controls.xml b/docs/xml/lcl/controls.xml index 3ba0d61f9d..90ea435bca 100644 --- a/docs/xml/lcl/controls.xml +++ b/docs/xml/lcl/controls.xml @@ -1838,12 +1838,12 @@ Indicates if the Control has called but not completed its Paint method. ControlIsPainting is a Boolean function which indicates if the Control has called but not completed its Paint method. ControlIsPainting returns True when the Control has been -assigned (contains a non-Nil value) and its IsProcessingPaintMsg -method returns True. +assigned (contains a non-Nil value) and its +IsProcessingPaintMsg method returns True.

-ControlIsPainting is used in the implementation of the -CreateHandle method. +ControlIsPainting is used in the implementation of the CreateHandle +method.

@@ -4075,11 +4075,30 @@ Shift, Ctrl, or Alt modifier for the key up event. Aborts the dragging operation when the capture control has changed. - - + +

+CaptureChanged is an abstract virtual method in +TDragManager, and must be implemented in a descendent class. In the +default drag manager implementation, the DragMode and DragKind properties for +child controls are checked to determine if one of them has the mouse capture. +If none of them are active, the Parent control calls DragStop. +

+

+CaptureChanged is called from the CaptureChanged method in TControl when +the LM_CaptureChanged message is received by the control and the drag manager +is active. +

+ + + + + + - + +Control which has the mouse capture change message is handled for the control. + @@ -4197,7 +4216,9 @@ A docking operation never should start immediately. - + +Owner of the class instance. + @@ -4315,8 +4336,8 @@ specified control. CanStartDragging is an abstract virtual Boolean function used to determine if the mouse has been moved beyond the threshold that initiates a drag operation. The result is True when the mouse -coordinates in X and Y are located within the client rectangle and threshold -for the specified control in Site. +coordinates in X and Y are located within the client rectangle and within the +threshold for the specified control in Site.

CanStartDragging must be implemented in a descendent class, like the @@ -4460,8 +4481,8 @@ InsertControl determines the placement of the just docked control, forcing a repaint of the container control if necessary.

-When SetReplacingControl has been called with a non-Nil Control before, the -dropped control only should replace that control. +When SetReplacingControl has been called with a non-Nil Control before, +the dropped control only should replace that control.

An overloaded version passes the DragDockObject to the dockmanager, allowing @@ -5522,16 +5543,23 @@ object. -True when the specified spacing is the same as the current settings. +True when the specified spacing is the same as the current settings in +the class instance. - + +True when the specified spacing is the same as the current settings in +the class instance. + - + +TControlBorderSpacing instance with values compared to the current class +instance. + @@ -5540,11 +5568,15 @@ object. -Out parameter, initial contents are ignored! + +Output parameter; the initial contents are ignored. + -The space on a control side, including Around space. + +The space on a control side including Around space. + @@ -6380,10 +6412,10 @@ The return value is always True. The hint text for the client control. - + - + @@ -6401,10 +6433,10 @@ Help properties are assumed linked only when all these properties match. - + - + @@ -11189,10 +11221,20 @@ Signals the OnMouseWheelDown handler. -True if handled. + +True if the mouse wheel message is handled. + + + + +Shift, Ctrl or Alt modifier for the mouse wheel event notification. + + + + +Location for the mouse pointer when the wheel event was generated. + - - @@ -11202,8 +11244,8 @@ Signals the OnMouseWheelUp handler. True if handled. - - + + @@ -13764,7 +13806,9 @@ the list used to store the values. - + +Ordinal position for the anchored control in the property value. + @@ -14186,13 +14230,23 @@ resizing. - + +True if the BoundsRect is retrieved and used as the value in +BaseBounds. False if the existing value in BaseBounds is used. + - + +True if the ClientWidth and ClientHeight in the Parent control is +retrieved and used. False if the existing value in BaseParentClientSize +is used. + - + +True if the client size retrieved during LCL component streaming is +used in the BaseParentClientSize. False if the calculated value is used. + @@ -14291,19 +14345,34 @@ DoAutoAdjustLayout to apply the scaling factors or size changes. - + +Layout policy applied in the method. Controls the actions performed to scale +and / or position the control. + - + +Design-time Pixels per Inch setting. Used to derive scaling factors applied in +the method. + - + +Run-time Pixels per Inch setting for the current monitor. Used to derive +scaling factors applied in the method. + - + +Form width prior to applying the auto-adjustment policy. Used to calculate an +x-axis scaling factor applied in the method. + - + +Form width after the auto-adjustment policy is applied. Used to calculate an +x-axis scaling factor applied in the method. + @@ -14329,7 +14398,9 @@ property has not been enabled. -Corrects the font size for High-DPI-aware applications. + +Corrects the font size for High-DPI-aware applications. +

FixDesignFontsPPI is a method used to adjust the font size when the @@ -15270,6 +15341,12 @@ Screen coordinates converted to client coordinates in the method. Converts control-relative coordinates to absolute screen coordinates. + +

+Screen coordinates in the return value are determined by adding the values in +APoint and the ClientOrigin for the control. +

+ @@ -15278,10 +15355,15 @@ Converts control-relative coordinates to absolute screen coordinates. - + +TPoint instance with the Screen coordinates for the specified control coordinates. + - + +TPoint instance with the control-relative coordinates converted in the +method. + @@ -15462,22 +15544,30 @@ should be ignored. + + +TComponent.ComponentState - + +True if the control is visible and needs a handle object. + -Returns True if any parent is destroying its Handle (or handles for -its children). +Returns True if any parent control is destroying its Handle (or handles +for its children). - + +Returns True if any parent control is destroying its Handle (or handles +for its children). + @@ -15489,7 +15579,10 @@ destroyed. - + +Returns True if all Parents have allocated handles, and are not being +destroyed. + @@ -15721,10 +15814,16 @@ Adds or inserts the specified OnVisibleChanged event handler. - + +TNotifyEvent handler routine added in the method. + - + +True if the routine is inserted as the first handler in the list of +handlers for the chtOnVisibleChanged type. False if the routine is +appended to the list. + @@ -15735,7 +15834,10 @@ Removes the specified OnVisibleChanged event handler. - + +TNotifyEvent handler routine removed from the chtOnVisibleChanged handler +type. + @@ -15746,10 +15848,16 @@ Adds the specified OnEnabledChanging handler. - + +TNotifyEvent handler routine added in the method. + - + +True if the routine is inserted as the first handler in the list of +handlers for the chtOnVisibleChanging type. False if the routine is +appended to the list. + @@ -15760,7 +15868,10 @@ Removes the specified OnEnabledChanging event handler. - + +TNotifyEvent handler routine removed from the chtOnEnabledChanging handler +type. + @@ -15769,10 +15880,16 @@ Removes the specified OnEnabledChanging event handler. - + +TNotifyEvent handler routine added in the method. + - + +True if the routine is inserted as the first handler in the list of +handlers for the chtOnEnabledChanged type. False if the routine is +appended to the list. + @@ -15783,7 +15900,10 @@ Removes the specified OnEnabledChanged event handler. - + +TNotifyEvent handler routine removed from the chtOnEnabledChanged handler +type. + @@ -15792,10 +15912,16 @@ Removes the specified OnEnabledChanged event handler. - + +TKeyEvent handler routine added to the chtOnKeyDown handler type. + - + +True if the routine is inserted as the first handler in the list of +handlers for the chtOnKeyDown type. False if the routine is appended to +the list. + @@ -15804,7 +15930,10 @@ Removes the specified OnEnabledChanged event handler. - + +TKeyEvent handler routine removed from the list of handlers for the +chtOnKeyDown handler type. + @@ -15815,10 +15944,16 @@ Adds or inserts the specified OnBeforeDestruction event handler. - + +TNotifyEvent handler routine added to the list of handlers for the +chtOnBeforeDestruction handler type. + - + +True if the routine is inserted as the first handler in the list of +handlers. False if the routine is appended to the list. + @@ -15829,7 +15964,10 @@ Removes the specified OnBeforeDestruction event handler. - + +TNotifyEvent handler routine removed from the list for the +chtOnBeforeDestruction handler type. + @@ -15840,10 +15978,16 @@ Adds or inserts the specified OnMouseWheel event handler. - + +TMouseWheelEvent handler routine added to the list for the chtOnMouseWheel +handler type. + - + +True if the routine is inserted as the first handler in the list of +handlers. False if the routine is appended to the list. + @@ -15852,11 +15996,17 @@ Adds or inserts the specified OnMouseWheel event handler. - + +TMouseWheelEvent handler routine removed from the list for the chtOnMouseWheel +handler type. + -Contains the accessible name for the control. + +Contains the accessible name for the control, like the value for its Caption +or Name property. + @@ -16430,10 +16580,34 @@ preferred size is changed, and during scaling operations. -The top, left pixel of the control in screen coordinates. - + +The top, left pixel for the control in screen coordinates. + + +

+ControlOrigin is a read-only TPoint property with the +screen-relative coordinates where the control is located. +

+

+The X and Y members in the property represent the Left and Top coordinates for +the control after they are converted to screen coordinates. The values are +derived by adding the TPoint values for the Left and Top coordinates to the +ClientOrigin property for the Parent control. The return value contains the +unmodified values in Left and Top when a Parent control has not been assigned. +

+

+ControlOrigin is used to implement the ScreenToControl and ControlToScreen +methods. +

+ + + + + + + @@ -16924,7 +17098,7 @@ not docked. -The Width when last docked, with siblings to the left or right. +The Width when last docked with siblings to the left or right. @@ -16932,7 +17106,7 @@ The Width when last docked, with siblings to the left or right. -The Height when last docked, with siblings above or below. +The Height when last docked with siblings above or below. @@ -16956,7 +17130,7 @@ The Height when last docked, with siblings above or below. - +True when BiDiMode is bdRightToLeft. @@ -16965,7 +17139,7 @@ The Height when last docked, with siblings above or below. - +True when BiDiMode is not bdLeftToRight. @@ -16976,7 +17150,9 @@ The Height when last docked, with siblings above or below. - + +True when BiDiMode indicates right-to-left reading is in use. + @@ -16985,7 +17161,7 @@ The Height when last docked, with siblings above or below. - +True when BiDiMode is not bdLeftToRight. @@ -17606,7 +17782,7 @@ Arranges controls in columns, from top to bottom and then left to right.

TControlChildSizing is a TPersistent descendant which provides properties and methods used to layout, align, and resize child -controls relative to their parent. Properties are provide which define the +controls relative to their parent. Properties are provided which define the horizontal and vertical spacing between controls, the preferred direction controls are aligned, and whether controls are scaled to fit in the parent control. @@ -17635,35 +17811,25 @@ in the properties. - - + - - + - - + - - + - - + - - + - - + - - + - - + - - + @@ -17769,48 +17935,134 @@ class instance. -Set all spacing to the same value. + +Sets all spacing in the class instance to the specified value. + - + + + + + + - - + +Integer value applied to each of the spacing properties. + + -The Control to which childsizing applies. - - + +The Control where the class instance is used. + + +

+The value for the property is passed as an argument to the Create constructor. +

+ + + + -Number of controls per line. +The number of controls per line. -Various ways to fit controls into the available Width. - - + +Indicates how child controls are expanded or aligned horizontally in the +parent Control. + + +

+EnlargeHorizontal is a TChildControlResizeStyle property +which indicates how child controls are expanded or aligned horizontally in the +parent Control. +

+

+The default value for the property is crsAnchorAligning, and indicates that +Anchors and Align work like Delphi. +

+

+For example: when the Anchors property of the control is [akLeft] it means +fixed distance between left border of parent's client area. [akRight] means +fixed distance between right border of the control and the right border of the +parent's client area. When the parent is resized the child is moved to keep +the distance. [akLeft,akRight] means fixed distance to left border and fixed +distance to right border. When the parent is resized, the controls width is +changed (resized) to keep the left and right distance. +

+

+See for more information about the +values for the property and their meanings. +

+ + + + + + -Various ways to fit controls into the available Height. + +Indicates how child controls are expanded or aligned vertically in the parent +Control. + - + + + -Minimum space between children. + +Minimum space between children. + -Allows to also arrange the child controls in rows or columns. - - + +Indicates the layout direction when child controls are arranged into rows and +/ or columns. + + +

+Layout is a TControlChildrenLayout property which +indicates the layout behavior for adjacent controls in the parent Control. +Layout is used when methods in TControl (and descendent classes) need to +arrange their child controls into columns or rows. +

+

+The default value for the property is cclNone, and indicates that a layout +direction has not been specified. This causes the design-time positioning for +the child controls to be used. Use cclLeftToRightThenTopToBottom or +cclTopToBottomThenLeftToRight to layout child control in column / row order +using the BiDiMode settings for the Control. +

+

+Changing the value for the property causes the Change method to be called to +realign child controls and signal the OnChange event handler (when assigned). +

+

+Layout is used in TControl methods like WidthIsAnchored and HeightIsAnchored, and in the AlignControls method in TWinControl. +

+ + + + + + + + + + @@ -18164,12 +18416,16 @@ functions in TWinControl. -Gets the enumerator for the class. + +Returns the enumerator in the class instance (Self). + - + +Returns the enumerator in the class instance (Self). + @@ -18184,9 +18440,25 @@ Moves to the next value using the ordering in effect for the enumerator. -Gets the current value for the enumerator. - - + +Contains the TControl instance which is the current value in the enumerator. + + +

+Current is a read-only TControl property with the +current value in the enumerator. It represents one of the child controls in +the TWinControl instance passed as an argument to the Create constructor. +

+

+Use MoveNext to move the enumerator to the next control in the order used for +the enumerator. +

+ + + + + + @@ -18323,30 +18595,34 @@ Control which provides the relative position for the control and its children. Implements the storage specifier for the DoubleBuffered property. -

Contains True when a parent control has not enabled its -DoubleBuffered property.

+

Contains True when the Parent control has not enabled its +DoubleBuffered property. +

 - + +True when the Parent control has not enabled its DoubleBuffered +property. + - + - + - + - + - + - + - + @@ -18360,11 +18636,11 @@ DoubleBuffered property.

Value for the property. - + - + @@ -18378,21 +18654,17 @@ DoubleBuffered property.

New value for the DesignerDeleting property. - - - - - - + + + - - + - + - + @@ -18411,7 +18683,7 @@ controls in Parent to be re-sequenced as needed.

No actions are performed in the method when Parent is unassigned (contains -Nil). +Nil).

@@ -18550,10 +18822,14 @@ alignment and are visible. List all controls with this alignment. - + +TFPList instance populated in the method. + - + +TControl instance that is added as the first control in the align list. + @@ -18636,10 +18912,24 @@ client rectangle for subsequent access. Returns the adjusted logical ClientRect, using the cached value when available. - + +

+GetAdjustedLogicalClientRect is a method used to get the client +rectangle for the control, and adjust the values for any additional space +needed for the control. It calls the AdjustClientRectangle method to apply any +additional spacing required for borders, bevels, edges, indentation, etc. In +TWinControl, no additional space is required. Descendent classes may have +different requirements. +

+

+GetAdjustedLogicalClientRect is used to implement the CheckSidePosition method +in TAnchorSide. +

+ + @@ -18830,7 +19120,9 @@ parent form. - + +True if the control is eligible to receive input focus. + @@ -18951,7 +19243,7 @@ An empty implementation in the current LCL version. Class name for the control added as a subclass. - + Notifies the widgetset class instance when Constraints are changed. @@ -18981,8 +19273,14 @@ Updates the size and extent of the control as well as its ClientRect.

-Changing the ClientRect here, to the most probable size, reduces unnecessary -resize messages. +DoSetBounds is an overridden method in TWinControl. It +keeps a copy of the current Width and Height prior to calling the inherited +method to apply the argument values to the Left, Top, Width and Height +properties. +

+

+It performs actions to adjust the CachedClientWidth and CachedClientHeight if the control flags do not indicate they are being loading or have already been +loaded for the control. Changing the ClientRect here, to the most probable size, reduces unnecessary resize messages.

Normally, the ClientWidth / ClientHeight are adjusted automatically by the @@ -18995,19 +19293,31 @@ resize messages. + + + + - + +New value for the Left property in the control. + - + +New value for the Top property in the control. + - + +New value for the Width property in the control. + - + +New value for the Height property in the control. + @@ -19137,11 +19447,14 @@ is theme- dependent, so it is passed as a parameter to the widgetset. - + +Width used for new instances of the control. + - - + +Height used for new instances of the control. + Indicates if additional space is reserved for theme services. @@ -19565,7 +19878,9 @@ notifies the widgetset. - + +Control message handled in the method. + @@ -19577,7 +19892,9 @@ notifies all child controls. - + +Control message handled in the method. + @@ -19590,7 +19907,9 @@ Handler for changed Visible message. - + +Control message handled in the method. + @@ -19610,7 +19929,9 @@ Calls DoEnter to signal the OnEnter event handler (when assigned). -Message handled in the method. + +Control message handled in the method. + @@ -19630,7 +19951,9 @@ Calls DoExit to signal the OnExit event handler (when assigned). - + +Control message handled in the method. + @@ -19643,7 +19966,9 @@ eventually delegates handling to the affected child control. - + +Window message handled in the method. + @@ -19656,7 +19981,9 @@ Erases the background, when required. - + +Window message handled in the method. + @@ -19665,7 +19992,9 @@ Erases the background, when required. - + +Window message handled in the method. + @@ -19674,7 +20003,9 @@ Erases the background, when required. - + +Window message handled in the method. + @@ -19697,7 +20028,7 @@ being freed. -Message examined in the method. +Window message examined in the method. @@ -19706,7 +20037,9 @@ being freed. - + +Window message handled in the method. + @@ -19715,7 +20048,9 @@ being freed. -Message handled in the method. + +Window message handled in the method. + @@ -19724,31 +20059,37 @@ being freed. -Message handled in the method. + +Window message handled in the method. + Event handler for a key press not handled by the widget; Tries +id="TWinControl.DoRemainingKeyDown"/>. - + +Window message handled in the method. + Event handler for system key presses not handled by the widget; tries +id="TWinControl.DoRemainingKeyDown"/>. - + +Window message handled in the method. + @@ -19760,7 +20101,9 @@ id="TWinControl.DoRemainingKeyUp"/>. - + +Window message handled in the method. + @@ -19772,7 +20115,9 @@ id="TWinControl.DoRemainingKeyUp"/> - + +Window message handled in the method. + @@ -19784,7 +20129,9 @@ itself. - + +Window message handled in the method. + @@ -19796,7 +20143,9 @@ itself. - + +Window message handled in the method. + @@ -19807,7 +20156,10 @@ Manages paint requests, and handles double buffering. This topic needs more detail. -Which platforms define BUFFERED_WMPAINT? +BUFFERED_WMPAINT is defined for the Windows platform only. +Ensures that a valid device context is selected before calling the Windows API +routines like: CreateCompatibleBitmap and BitBlt. Ensures the device context +is freed after use. @@ -19844,7 +20196,9 @@ Handler for widget moved message; updates the Bounds. - + +Window message handled in the method. + @@ -19862,7 +20216,9 @@ BoundsRealized member to avoid sending a size message back to the interface. - + +Window message handled in the method. + @@ -19883,7 +20239,9 @@ interface. - + +Window message handled in the method. + @@ -19895,7 +20253,7 @@ DoKeyDownBeforeInterface by default. - +Message handled in the method. @@ -19907,7 +20265,7 @@ DoKeyDownBeforeInterface by default. - +Message handled in the method. @@ -19919,7 +20277,7 @@ DoKeyUpBeforeInterface by default. - +Message handled in the method. @@ -19931,7 +20289,7 @@ DoKeyUpBeforeInterface by default. - +Message handled in the method. @@ -19943,7 +20301,7 @@ it has handled the key press itself. - +Message handled in the method. @@ -20793,10 +21151,8 @@ When True only a control with Parent set to Self is found. - - - - + + Gets the value for the BorderStyle property. @@ -22640,10 +22996,8 @@ Scrolls the control (and all child controls) by the specified amounts. Increment for Top. - - - - + + @@ -22902,13 +23256,9 @@ AControl is stored, or -1 when not found or Controls has not been assigned. The child control to locate in the method. - - - - - - - + + + Checks whether the control has focus. @@ -22983,10 +23333,8 @@ When True, only select a control that can receive the focus. - - - - + + @@ -23056,10 +23404,8 @@ been handled. The message to process. - - - - + + Schedules a repaint request. @@ -23127,8 +23473,8 @@ Tells the widgetset to add a Handle object representing the current control. The TWinControlEnumerator instance. - - + + @@ -23698,7 +24044,7 @@ actual drawing operations for the control. - + Handles LM_PAINT messages for the control. @@ -23976,18 +24322,18 @@ class. - - - - - - - - - - - - + + + + + + + + + + + + @@ -24181,7 +24527,7 @@ DockManager can (and should) use its own class instead. New value for the Top property. - + Sets the value for the Width property. @@ -24634,10 +24980,10 @@ would be docked via InsertControl. - - + + - + Destroys the zone and its child zones. @@ -24648,12 +24994,10 @@ would be docked via InsertControl. - - - - + + - + @@ -24714,10 +25058,8 @@ UpdateAll is called from the EndUpdate method. - - - - + + Constructor for the class instance. @@ -24811,13 +25153,9 @@ and its properties immediately. - - - - - - - + + + @@ -24830,8 +25168,8 @@ specified by InsertAt. docked control, forcing a repaint of the container control if necessary.

-When SetReplacingControl has been called with a non-Nil Control -before, the dropped control only should replace that control. +When SetReplacingControl has been called with a non-Nil +Control before, the dropped control only should replace that control.

A tree docking manager organizes the docksite into layers of horizontal or @@ -24903,30 +25241,20 @@ the host docksite is not involved. - - - - + + - - - - + + - - - - + + - - - - + + - - - - + + Stores the layout in an file. @@ -24984,35 +25312,25 @@ Mouse global unit variable. - - + - - + - - + - - + - - + - - + - - + - - + - - + - - + @@ -25041,7 +25359,7 @@ The number of lines to scroll with every notch or unit on the mouse wheel -Does dragging start immediately (True), or only after a mouse move? +Does dragging start immediately (True), or only after a mouse move? @@ -25065,7 +25383,10 @@ The default value is 5 (pixels). AnchorAlign is an array constant that contains elements with TAnchors set values. Values in AnchorAlign are indexed by TAlign enumeration values. This allows the TAlign value to -retrieve the set of Anchors used for the specified align option. For example: +retrieve the set of Anchors used for the specified align option. +

+

+For example:

AControl.Align := AnchorAlign[alRight]; // contains [akRight, akTop, akBottom] @@ -25118,7 +25439,7 @@ Not used in the current LCL version. - + Gets the drag target at the specified screen position.

@@ -25126,7 +25447,9 @@ Disabled controls should be excluded, but are not due to an bug in FindControlAtPosition.

- + + + The control at Position; Nil if none. @@ -25208,7 +25531,7 @@ when a window is not found.

The result is very interface specific; use FindOwnerControl when Handle may -be a non-TWinControl handle +be a non-TWinControl handle.

@@ -25248,18 +25571,27 @@ the implementation (meaning) of a parent handle. -Returns the TControl that currently is visible at a screen position. +Returns the TControl currently visible at the specified screen position. +

The result is not reliable during resizing. +

 - + +Control visible at the specified screen coordinates. The active windowed +control (or form) is returned if a control is not found at the specified +position. + - + +TPoint instance with the screen coordinates for the control located in the +method. + @@ -25391,7 +25723,8 @@ capture. -TControl instance (or Nil) representing the control for the mouse capture. +TControl instance (or Nil) representing the control for the mouse +capture.