From 4cb0e26bbfac7c3bf90572c3dbd742ba13218f6b Mon Sep 17 00:00:00 2001 From: dsiders Date: Mon, 21 Feb 2022 02:43:05 +0000 Subject: [PATCH] Docs: LCL/controls. Updates topic content and links. * Mostly topics in TWinControl. (cherry picked from commit 86f222952fa2ad27cd7f57149a9a4ceb2c96ac92) --- docs/xml/lcl/controls.xml | 1461 +++++++++++++++++++++++++++++-------- 1 file changed, 1140 insertions(+), 321 deletions(-) diff --git a/docs/xml/lcl/controls.xml b/docs/xml/lcl/controls.xml index d87eecd65e..96d26f679c 100644 --- a/docs/xml/lcl/controls.xml +++ b/docs/xml/lcl/controls.xml @@ -1003,7 +1003,7 @@ The form is used as a Splash form.

- Signifies that the form cannot become the main form in an application. Implies that the form responds to fewer messages; generally, paint messages and little else. May affect the border style and even the window class used for the form on some widget sets. + Signifies that the form cannot become the main form in an application. Implies that the form responds to fewer messages; generally, paint messages and little else. May affect the border style and even the window class used for the form on some widgetsets.

@@ -3220,7 +3220,7 @@ HasOnDrawImage is a Boolean function used to determine if an event handler has been assigned to the OnDrawDockImage property. The return value is True if a routine has been assigned to the property. If an event handler has not been supplied, the HintDockImage routine is assigned to the event handler, and the return value is set to True.

- For platforms where the Alpha blending is not enabled for Forms, the return value is always False (determined by calling GetSystemMetrics for the SM_LCLHasFormAlphaBlend metric in the widget set class). + For platforms where the Alpha blending is not enabled for Forms, the return value is always False (determined by calling GetSystemMetrics for the SM_LCLHasFormAlphaBlend metric in the widgetset class).

HasOnDrawImage is used in methods like ShowDockImage, HideDockImage, and MoveDockImage. @@ -3289,7 +3289,7 @@ EraseDockRect is a TRect property that represents the area to be erased when redrawing the docking rectangle. The value in EraseDockRect is assigned in InitDock, and updated to contain the value from DockRect when the docking rectangle has been altered in methods like ShowDockImage, HideDockImage, and MoveDockImage.

- EraseDockRect is passed as an argument to OnDrawDockImage, and to the underlying widget set class. + EraseDockRect is passed as an argument to OnDrawDockImage, and to the underlying widgetset class.

@@ -10241,7 +10241,7 @@ - Returns True if auto-sizing must be has been delayed, until some other process is complete. + Returns True if auto-sizing has been delayed until some other process is complete. @@ -12620,7 +12620,9 @@ ALabel.Caption := '&Notes && Comments'; Button1.Caption := 'Click me'; // parent is not set, so it does not update the whole form Button1.Parent := Form1; // set parent as last, the LCL now applies all properties -

Delphi/VCL: Parent must be set first under Delphi, because many properties work differently if they are set before or after Handle creation. The LCL applies the properties when the Handle is created.

+

+ Delphi/VCL: Parent must be set first under Delphi, because many properties work differently if they are set before or after Handle creation. The LCL applies the properties when the Handle is created. +

@@ -12649,14 +12651,14 @@ ALabel.Caption := '&Notes && Comments'; Use the Hint property to set the text displayed in the pop-up hint window when ShowHint is enabled. Use the OnShowHint event handler to provide custom text uses in the Hint display.

- Use the ShowHint property in a TForm instance to enable or disable pop-up hint display for all controls on the form. Use the ShowHint property in TApplication to enable or disable pop-up hint display for all form and controls in an application. + Use the ShowHint property in a TForm instance to enable or disable pop-up hint display for all controls on a given form. Use the ShowHint property in TApplication to enable or disable pop-up hint display for all forms and controls in an application.

- TCustomForm.ShowHint + TForm.ShowHint TApplication.ShowHint @@ -12965,9 +12967,34 @@ ALabel.Caption := '&Notes && Comments'; - The vertical size for the control. + +

+ Height is an Integer property with the vertical size for the control in pixels. +

+

+ Setting a negative value in Height is not allowed, and the property defaults to 0 (zero). At design-time, setting Height to a value not in the range 0..9999 causes an ELayoutException to be raised (and handled in the IDE). +

+

+ Setting a new value for the property causes SetBounds and ChangeBounds to be called. This ensures that the new value is is the range allowed in Constraints, and that the control is aligned on its Parent using the Anchors for the control. +

+

+ A value assigned to Height is ignored when AutoSize is set to True; the control is automatically adjusted to the size needed for its aligned content. +

+

+ Values in Top, Left, Width, and Height are used to calculate the display area for the control in GetClientRect. They determine the clipping rectangle used when the control is drawn on its Parent. +

+ + + + + + + + + + @@ -13003,58 +13030,158 @@ ALabel.Caption := '&Notes && Comments'; - The client coordinate of the top edge of the control. + The client coordinate for the top edge of the control. + +

+ Top is an Integer property with the coordinate for the top edge of the control relative to its Parent. Changing the value for the property causes SetBounds to be called to apply the new value for the property along with the existing values in Left, Width, and Height. +

+ + + + + + + + + The horizontal size for the control.

- Width is an Integer property with the width for the control in pixels. Setting a new value for the property causes SetBounds and ChangeBounds to be called. This ensures that the new value is is the range allowed in Constraints, and that the control is aligned on its Parent using the Anchors for the control. + Width is an Integer property with the horizontal size for the control in pixels.

- Setting a negative value in Width is not allowed, and the property defaults to 0. + Setting a negative value in Width is not allowed, and the property defaults to 0 (zero). At design-time, setting Width to a value not in the range 0..9999 causes an ELayoutException to be raised (and handled in the IDE). +

+

+ Setting a new value for the property causes SetBounds and ChangeBounds to be called. This ensures that the new value is is the range allowed in Constraints, and that the control is aligned on its Parent using the Anchors for the control.

A value assigned to Width is ignored when AutoSize is set to True; the control is automatically adjusted to the size needed for its aligned content.

- Values in Top, Left, Width, and Height are used to calculate the display area for the control in GetClientRect. They also determine the clipping rectangle used when the control is drawn on its Parent. + Values in Top, Left, Width, and Height are used to calculate the display area for the control in GetClientRect. They determine the clipping rectangle used when the control is drawn on its Parent.

+ + + + + + + + + - Determines whether context-sensitive Help is selected by numeric ID or keyword. - + Indicates whether context-sensitive Help is selected by numeric ID or keyword. + +

+ HelpType is a THelpType property which indicates the mechanism used to locate and display a help topic for the control. +

+
+
htKeyword
+
+ Uses the value in HelpKeyword to locate help content for the control. +
+
htContext
+
+ Uses the numeric identifier in the HelpContext property to locate help content for the control. +
+
+

+ The default value for the property is htContext. +

+

+ The value in HelpType is updated when an explicit value is assigned to the HelpKeyword or HelpContext properties. +

+

+ HelpType is used in the ShowHelp method to select the TApplication method called to display the help content. When set to htContext, the HelpContext method in Application is called. When set to htKeyword, the HelpKeyword method in Application is called. If the help request cannot be handled using the values assigned to the control, the ShowHelp method in Parent is called (when assigned). +

+ + TApplication.HelpContext + TApplication.HelpKeyword + TApplicationProperties.HelpFile + TCustomForm.HelpFile + THelpType The context-sensitive Help keyword for the control. - + +

+ HelpKeyword is a String type with the context-sensitive keyword used to locate and display a help topic for the control. When an value is assigned to the property, the HelpType property is set to htKeyword. +

+

+ HelpKeyword is used in the ShowHelp method, and passed as an argument to the HelpKeyword method in the Application singleton. +

+

+ Use HelpContext to specify a numeric context identifier for the help topic displayed for the control. +

+

+ Use the HelpFile property, found on the parent form or in a TApplicationProperties instance, to set the help file with the content for the help topic. +

+ + + + TApplication.HelpKeyword + TApplicationProperties.HelpFile + TCustomForm.HelpFile - The context-sensitive Help identifier for the control. - + The numeric context-sensitive Help identifier for the control. + +

+ HelpContext is an Integer property with the numeric identifier used to locate and display a context-sensitive help topic for the control. The default value for the property is 0 (zero). +

+

+ Setting a new value for the property causes HelpType to be changed to htContext. +

+

+ HelpContext is used in the ShowHelp method, and passed as an argument to the HelpContext method in the Application singleton. +

+

+ Use HelpKeyword to specify a string value with the help topic displayed for the control. +

+

+ Use the HelpFile property, found on the parent form or in a TApplicationProperties instance, to set the help file with the content for the help topic. +

+ + + + TApplication.HelpKeyword + TApplicationProperties.HelpFile + TCustomForm.HelpFile - Integer type for + Integer type used for + +

+ TBorderWidth is an Integer type with the range of values that can be used as the width for a border on a control. TBorderWidth is the type used to implement the BorderWidth property in TWinControl and descendent classes. +

+ + + + - Type of a callback method, to be called for all children of a control. + Type used for a callback method, to be called for all children of a control. @@ -13065,21 +13192,76 @@ ALabel.Caption := '&Notes && Comments'; - Modes for resizing child controls. + Defines how child controls are resized / aligned. Using (Delphi compatible). + +

+ Anchors and Align work like Delphi. For example if 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. Same for akTop,akBottom. +

+

+ Align=alLeft for a control means set Left leftmost, Top topmost and maximize Height. The width is kept, if akRight is not set. If akRight is set in the Anchors property, then the right distance is kept and the control's width is resized. If there several controls with Align=alLeft, they will not overlap and be put side by side. Same for alRight, alTop, alBottom. (Always expand 3 sides). +

+

+ Align=alClient. The control will fill the whole remaining space. Setting two children to Align=alClient does only make sense, if you set maximum Constraints. +

+

+ Order: First all alTop children are resized, then alBottom, then alLeft, then alRight and finally alClient. +

+ Scale children, keep space between children fixed. + +

+ Scale children, keep space between them fixed. Children are resized to their normal / advised size. If there is some space left in the client area of the parent, then the children are scaled to fill the space. You can set maximum Constraints. Then the other children are scaled more. +

+

+ For example: 3 child controls A, B, C with A.Width=10, B.Width=20 and C.Width=30 (total=60). If the Parent's client area has a ClientWidth of 120, then the children are scaled with Factor 2. +

+

+ If B has a maximum constraint width of 30, then first the children will be scaled with 1.5 (A.Width=15, B.Width=30, C.Width=45). Then A and C (15+45=60 and 30 pixel space left) will be scaled by 1.5 again, to a final result of: A.Width=23, B.Width=30, C.Width=67 (23+30+67=120). +

+ Enlarge children equally, i.e. by the same amount of pixels. + +

+ Enlarge children equally. Children are resized to their normal/adviced size. If there is some space left in the client area of the parent, then the remaining space is distributed equally to each child. +

+

+ For example: 3 child controls A, B, C with A.Width=10, B.Width=20 and C.Width=30 (total=60). If the Parent's client area has a ClientWidth of 120, then 60/3=20 is added to each Child. +

+

+ If B has a maximum constraint width of 30, then first 10 is added to all children (A.Width=20, B.Width=30, C.Width=40). Then A and C (20+40=60 and 30 pixel space left) will get 30/2=15 additional, resulting in: A.Width=35, B.Width=30, C.Width=55 (35+30+55=120). +

+ Enlarge space between children equally. + +

+ Enlarge space between children equally. Children are resized to their normal/adviced size. If there is some space left in the client area of the parent, then the space between the children is expanded. +

+

+ For example: 3 child controls A, B, C with A.Width=10, B.Width=20 and C.Width=30 (total=60). If the Parent's client area has a ClientWidth of 120, then there will be 60/2=30 space between A and B and between B and C. +

+ + + + Each child gets the same size (maybe one pixel difference). + + + Not implemented in the current LCL version. + +

+ Set each child to the same size (maybe one pixel difference). The client area is divided by the number of controls and each control gets the same size. The remainder is distributed to the first children. +

+ @@ -13355,7 +13537,7 @@ ALabel.Caption := '&Notes && Comments'; Alias for the TControlActionLink type.

- Since HelpContext and HelpKeyword are properties of TControl, this class is obsolete. In order not to break existing code, its declaration is aliased to TControlActionLink. + Since HelpContext and HelpKeyword are properties of TControl, this class is obsolete. To maintain compatibility with existing code, its declaration is aliased to TControlActionLink.

@@ -13379,10 +13561,10 @@ ALabel.Caption := '&Notes && Comments'; - + Client rectangle has been invalidated and needs to be updated. - + The Color property in s control has been changed. Set when the font was changed before handle creation. @@ -13391,10 +13573,10 @@ ALabel.Caption := '&Notes && Comments'; Set during DoAllAutosize. - Set during + Set when the AlignControls method is called. - + Set in the method Paint before the LM_ERASEBKGND message is performed. Set while constructing the handle of this control. @@ -13414,10 +13596,10 @@ ALabel.Caption := '&Notes && Comments'; - + Set before a visible control and its children are updated during auto-sizing. - + Set when a control is visible and not obscured on its parent. Set when the adjusted ClientRect is valid. @@ -13426,7 +13608,9 @@ ALabel.Caption := '&Notes && Comments'; - + + Set when the LCL interface has already called SetBounds during size and move operations. Prevents a loop. + Only used for TCustomPairSplitter / TPairSplitter. @@ -13437,9 +13621,14 @@ ALabel.Caption := '&Notes && Comments'; Set of TWinControlFlag enumeration values. - + +

+ TWinControlFlags is a set type used to store zero (0) or more values from the TWinControlFlag enumeration. TWinControlFlags is the type used to implement an internal member in TWinControl. Values are added to and removed from the set as needed in TWinControl methods. +

+ + @@ -13451,20 +13640,6 @@ ALabel.Caption := '&Notes && Comments';

TControlAtPosFlag is an enumeration type with values that indicate the mechanism used to locate a control at a given client position.

-
-
capfAllowDisabled
-
Include disabled controls
-
capfAllowWinControls
-
Do not find WinControls if False
-
capfOnlyClientAreas
-
Hit client areas only
-
capfRecursive
-
Search in child controls
-
capfHasScrollOffset
-
Scroll offset is already included in the coordinates
-
capfOnlyWinControls
-
Include only TWinControl descendents (ignores TControl descendents)
-

Values from the enumeration are stored in the TControlAtPosFlags type.

@@ -13474,22 +13649,23 @@ ALabel.Caption := '&Notes && Comments'; + - If set: include disabled controls. + Include disabled controls when set. - If set: include TWinControls, in addition to TControls. + Include both TWinControls and TControl instances when set. - If set: hit client areas only. + Checks for hits are limited to the client area when set. - If set: recurse into grand children. + Recurse into grand-children controls when set. - If set: scroll offset is already included in the coordinates. + Scroll offset is already included in the coordinates when set. Include only TWinControls (and ignore TControls) when set. @@ -13497,16 +13673,24 @@ ALabel.Caption := '&Notes && Comments'; Set type used to store values from the TControlAtPosFlag enumeration. - + +

+ Passed as an argument to the ControlAtPos method in TWinControl. Used internally in the implementation of the FindControlAtPosition routine. +

+ + + Used in custom alignment (alCustom). - This record was added for compatibility with Delphi releases after Version 7. It is used in CustomInsertBefore and CustomAlignPosition methods and handlers. +

+ This record was added for compatibility with Delphi releases after Version 7. It is used in CustomInsertBefore and CustomAlignPosition methods and handlers. +

@@ -13516,26 +13700,18 @@ ALabel.Caption := '&Notes && Comments'; The list of controls currently being aligned. - - Index of current control. - - The kind of alignment currently processed (always alCustom). - - For internal use. - - @@ -13563,7 +13739,9 @@ ALabel.Caption := '&Notes && Comments'; Type of an OnAlignPosition handler. - Handler which positions the Control using the specified coordinates. +

+ Specified an event handler which positions the Control using the specified coordinates and alignment information. +

@@ -13671,14 +13849,31 @@ ALabel.Caption := '&Notes && Comments'; - The base class for controls which can contain other (child) controls. + Implements a windowed control which can contain other child controls.

TWinControl is a TControl descendant which implements a base class for controls that can contain child controls. The name reflects the fact that (on Windows platforms) the controls are based on OS-provided widgets, which have window Handles.

+

+ TWinControl extends the ancestor class with new properties, methods, and events which are specific to the windowed control. It also provides overridden methods which re-implement the functionality for some inherited methods. The properties, methods, and event fall into categories like: +

+
    +
  • Hi-DPI Awareness and Scaling
    • +
  • Control, Window, and Notification Message Handlers
    • +
  • Keyboard and Mouse Message Handlers
    • +
  • Drag and Drop, Drag and Dock
    • +
  • Sizing, Positioning, and Alignment
    • +
  • Alternate Constructors and Class Functions used to create TWinControl Instances
    • +
  • Forward and Reverse Enumerators for Child Controls
    • +
+

+ TWinControl is often used as the ancestor for control classes defined in the LCL. For example: TButtonControl, TCustomCalendar, TCustomComboBox, TCustomControl, TCustomEdit, TCustomGroupBox, TCustomListBox, TCustomListView, TCustomPage, TCustomPairSplitter, TCustomProgressBar, TCustomRubberBand, TCustomScrollBar, TCustomStaticText, TCustomTabControl, TCustomTrackBar, TPreviewFileControl, and TStatusBar. +

- + + + @@ -13705,27 +13900,27 @@ ALabel.Caption := '&Notes && Comments'; - - - - - - - - - - - + + + + + + + + + + + - + - - + + - - - - + + + + Aligns the control and its child controls. @@ -13740,7 +13935,7 @@ ALabel.Caption := '&Notes && Comments'; No actions are performed in the method when the control is being freed (the value csDestroying is in ComponentState).

- AlignControl gets the client rectangle used to display the control, and calls AdjustClientRect to allocate border spacing when needed. AlignControls is called to align child controls relative to the control in AControl using the calculated client rectangle. Some widget sets update their client rectangle when the first child is positioned; a second call to AlignControls is made if the client rectangle is altered in the initial call to the method. + AlignControl gets the client rectangle used to display the control, and calls AdjustClientRect to allocate border spacing when needed. AlignControls is called to align child controls relative to the control in AControl using the calculated client rectangle. Some widgetsets update their client rectangle when the first child is positioned; a second call to AlignControls is made if the client rectangle is altered in the initial call to the method.

AlignControl is used in the implementation of the DoAllAutoSize method in TControl. @@ -13993,17 +14188,9 @@ ALabel.Caption := '&Notes && Comments'; Control removed from the list of child Controls in the class instance. - - - - - - - - - - - + + + @@ -14028,43 +14215,72 @@ ALabel.Caption := '&Notes && Comments'; - - - - - - - - + + - + + Member used to store the value for the DoubleBuffered property. + - Various window control state flags. + Contains various window control state flags. - + + Registers the class instance for use in the widgetset. + +

+ No actions are performed in the method when the class type has already been registered in the widgetset. +

+

+ Calls the inherited method on entry to ensure that the TControl class type has been registered in the widgetset. Calls the widgetset routine used to register the TWinControl class type. +

+

+ Registers properties in TWinControl which are ignored during LCL component streaming. These are Delphi / VCL compatibility properties like ParentDoubleBuffered, ImeMode, and ImeName. They are not used in the LCL. +

+ + + + TLCLComponent.WSRegisterClass + + Override this method when the ClientRect for a control differs from the default value. - It is called often, so don't use expensive code here, or cache the resulting client rectangle. +

+ In TWinControl, the virtual method has an empty implementation. It can be overridden in descendent classes to perform actions needed for the class type. Such as: +

+
    +
  • + Shrink or grow the client rectangle to account for added or removed borders or bezels. +
    • +
  • + Reserve space for companion controls or user interface elements. +
    • +
  • + Set state or configuration flags which affect the client rectangle for the class. +
    • +
+

+ AdjustClientRect can be called often, especially during auto-sizing and anchoring operations. Do not use expensive code here, or cache the resulting client rectangle for subsequent access. +

- + The client rectangle examined and updated in the method. - Returns the adjusted ClientRect, using the cached value if available. + Returns the adjusted logical ClientRect, using the cached value when available. @@ -14078,14 +14294,30 @@ ALabel.Caption := '&Notes && Comments'; - Aligns all child controls. - + Repositions and resizes the control and child controls. + +

+ AlignControls is a method used to reposition and resize the specified control and the children in its Controls property. This includes using the DockManager (when assigned and enabled) to reserve space for docked controls in the client rectangle. It uses settings in the Align, Anchor, BorderSpacing, ChildSizing, and Constraints properties to determine the actions needed in the method for each of the controls. +

+

+ AlignControls checks and updates the windowed control flags prior to starting the operation. No actions are performed in the method when wcfAligningControls is already included in the control flags. +

+

+ The ControlsAligned method is called when the method is completed, and the control flags are updated to remove the value wcfAligningControls. +

+

+ AlignControls is called from the private AlignControl method after the client rectangle has been adjusted and the logical display area for the control has been determined. AlignControl is the boss; AlignControls performs the heavy lifting. +

+ + + + - + Control examined and updated in the method. The available space, becomes remaining space on exit. @@ -14100,7 +14332,7 @@ ALabel.Caption := '&Notes && Comments'; - True if Control2 shall be placed before Control1 is placed. + True if Control2 should be placed before Control1. @@ -14111,7 +14343,7 @@ ALabel.Caption := '&Notes && Comments'; - Returns the aligned position for a custom-aligned child control, using the OnAlignPosition handler. + Returns the aligned position for a custom-aligned child control, using the OnAlignPosition event handler.

@@ -14151,9 +14383,13 @@ ALabel.Caption := '&Notes && Comments'; - Override this method to position/align all given controls. + Override this method to position / align all child controls for the specified control. - + +

+ DoAlignChildControls always returns False in TWinControl. It can be overridden in descendent classes to perform any actions needed, and to set the return value to True to avoid the default handling performed in AlignControls. +

+ @@ -14165,13 +14401,13 @@ ALabel.Caption := '&Notes && Comments'; The alignment of all given controls. - + Control with child controls and client rectangle used in the method. The controls to be placed. - + The unused client rectangle available for the child controls. @@ -14245,10 +14481,10 @@ ALabel.Caption := '&Notes && Comments'; - Sends the new Visible state to the widgetset. + Sends the new Visible state to the widgetset class instance.

- Called by the CMShowingChanged method. + Called from the CMShowingChanged method.

@@ -14257,14 +14493,20 @@ ALabel.Caption := '&Notes && Comments'; - Called by AlignControls after aligning controls. - + Called from AlignControls when alignment for the control is completed. + +

+ ControlsAligned has an empty implementation in the current LCL version. +

+ - Sends the control's new bounds to the widget. - Called by RealizeBounds. + Sends the new bounds for the control to the widgetset class instance. + + Called from RealizeBounds. + @@ -14272,15 +14514,19 @@ ALabel.Caption := '&Notes && Comments'; - Checks for changes in BoundsRect, and sends the new bounds to the widget using DoSendBoundsToInterface. + Checks for changes in BoundsRect, and sends the new bounds to the widget. - + +

+ Calls DoSendBoundsToInterface to update the widget. +

+ - Sends changed BoundsRects to the widget, for this and all child controls. + Sends changed BoundsRects to the widget, for both the control and all child controls. @@ -14290,7 +14536,7 @@ ALabel.Caption := '&Notes && Comments'; - Resets the bounds rectangle for the control. + Resets the realized bounds rectangle for the control.

Creates a new, empty TRect instance for the internal member passed to the widgetset class. Used in widgetset methods which apply changes to the Font for the control. @@ -14315,14 +14561,27 @@ ALabel.Caption := '&Notes && Comments'; Class name for the control added as a subclass. - + + Notifies the widgetset class instance when Constraints are changed. + +

+ DoConstraintsChange is an overridden method in TWinControl, and calls the inherited method on entry to size and position child controls to Constraints. Calls the ConstraintsChange method in the widgetset class instance when its Handle has been allocated. +

+

+ DoConstraintsChange is called from the TSizeConstraints.Change method before it signals the OnChange event handler in the constraints class instance. +

+ + + TControl.DoConstraintsChange + + - + Object (TWinControl) instance for the change notification. - Updates the size and extent of the control and its ClientRect. + Updates the size and extent of the control as well as its ClientRect.

@@ -14358,11 +14617,11 @@ ALabel.Caption := '&Notes && Comments'; Because this method is frequently overridden, the LCL calls the method instead; it checks whether DoAutoSize really should be called right now.

- DoAutoSize does roughly this: + DoAutoSize performs the following:

    -
  • Checks whether Autosize is in fact permitted
    • -
  • Checks for unaligned child components and fits them in as best it can
    • +
  • Checks whether Autosize is permitted
    • +
  • Checks for unaligned child components and aligns them as best it can
  • Moves the constrained (aligned) child components to the correct position
  • Adjusts the size of the client rectangle
  • Adjusts the bounds of the whole control
    • @@ -14373,10 +14632,44 @@ ALabel.Caption := '&Notes && Comments'; - + + + Performs actions to resize and align the control and all of its children. + + +

    + DoAllAutoSize is an overridden method in TWinControl. +

    +

    + No actions are performed in the method when wcfAllAutoSizing has already been included in the window control flags; in other words, the method has already been called. No actions are performed when AutoSizeDelayed returns True. +

    +

    + DoAllAutoSize checks to ensure that a Handle has been allocated for the control, and that it and its Parent are Visible. If AutoSizing is not possible, the flag is removed from the control and its children and the method is exited. +

    +

    + DoAllAutoSize calls the inherited method to change the bounds, invalidate the preferred size, and update flags for the control. RealizeBoundsRecursive is called to update the bounds for the all child controls. The child controls are made visible first, and then the current control instance. +

    +

    + DoAllAutoSize is called from the AdjustSize and EnableAutoSizing methods. +

    +     + +

    + The inherited method raises an EInvalidOperation exception if Parent has not been assigned for the control. +

    +

    + Raises a catchable exception when cfAutoSizeNeeded is already included in the control flags when the method is called. +

    +     + + + + + +     - Called by DoAllAutoSize after all bounds are computed. + Called from DoAllAutoSize after all bounds are computed for the control. TCustomForm.AllAutoSized @@ -14406,7 +14699,7 @@ ALabel.Caption := '&Notes && Comments'; This value is independent of constraints and siblings, only the inner parts are relevant for the calculates values.

    - WithThemeSpace adds space for stacking when set to True. For example: TRadioButton has a minimum size. But for stacking multiple TRadioButtons there should be space around each control. This space is theme- dependent, so it is passed as a parameter to the widget set. + WithThemeSpace adds space for stacking when set to True. For example: TRadioButton has a minimum size. But for stacking multiple TRadioButtons there should be space around each control. This space is theme- dependent, so it is passed as a parameter to the widgetset.

    @@ -14449,9 +14742,13 @@ ALabel.Caption := '&Notes && Comments'; - Calls the specified procedure for each child control owned by the control in Root. + 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 instance as an argument. An application must implement an object procedure using the signature in TGetChildProc, and pass the procedure in the Proc argument. +

    +     @@ -14459,27 +14756,59 @@ ALabel.Caption := '&Notes && Comments'; The callback procedure.     - Owner of the affected controls. + Owner of the controls passed to the procedure. - Returns True if the specified class is allowed in child controls. - - + 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. +

    +

    + In TWinControl, the return value is True when ChildClass has been assigned (not Nil) and the class type is derived from TControl. +

    +

    + ChildClassAllowed does not call the inherited method which always returns False. +

    +

    + ChildClassAllowed is called from the CheckChildClassAllowed method in TControl. +

    +     + + + + +     - True when allowed. + True when ChildClass is allowed in Controls. Class type examined in the method. - Paints all child controls which do not have a Handle. + Paints all child controls which do not have a Handle as part of their Parent.

    Controls which do not descend from TWinControl have no handle of their own; they are repainted when the parent control is redrawn.

    +

    + No actions are performed in the method when the device context in DC is unassigned (0), the Handle has not been allocated for the control, or an internal TFPList has not been created to store the child controls in the Controls property. +

    +

    + PaintControls tries to locate and paint controls (starting with the control in First) not derived from TWinControl. When First is omitted (Nil) or not found in the internal list, all child controls in the list are examined. The control must be Visible and within the visible client area on the Parent to be painted. +

    +

    + Each eligible control is positioned on the device context using the Left and Top properties for the control. Its clipping rectangle is copied to the device context, and an LM_PAINT message is performed on the DC to redraw the parent control. +

    +

    + The ControlState property is updated prior to and following the paint operation for each child control to include or exclude the csPaintCopy value. +

    +

    + PaintControls is called from the PaintHandler method, and occurs when the WMPaint method handles an LM_PAINT message for a control. +

    @@ -14492,78 +14821,156 @@ ALabel.Caption := '&Notes && Comments'; Handler for TLMPaint, manages the painting of child controls. - + +

    + PaintHandler is a method used to apply the LM_PAINT window message in TheMessage to the client rectangle for the control. The device context in TheMessage is used as the target for the paint operation. If the device context is unassigned on entry, the BeginPaint routine in the LCL interface is called to get a device context for the Handle in the control. +

    +

    + PaintHandler checks the list of child controls if any of the items are visible, opaque TControl class instances which need to be drawn using the Handle for the control. When found, a clipping rectangle for the child control is calculated on the device context. +

    +

    + PaintHandler calls the PaintSite method in the DockManager (when assigned and enabled) to paint the DockSite to the device context. The PaintControls method is called to force the all child controls to be painted to the device context. +

    +

    + PaintHandler calls the EndPaint routine in the LCL interface to free the device context prior to exiting from the method. +

    +

    + PaintHandler is called when the WMPaint method receives an LM_PAINT message for the control. +

    +     - + LM_PAINT window message handled in the method. - Paints a clipped portion (child control) on the specified device context. - + Paints a clipping region for the control on the specified device context. + +

    + PaintWindow is a method used to paint a clipping region for the control (or a child control) to the device context in DC. +

    +

    + PaintWindow creates a TLMessage instance using the LM_PAINT window message and the specified device context. The DefaultHandler method is called to pass the message to the widgetset class instance (and ultimately its message processing loop). +

    +

    + No actions are performed in the method when DC is unassigned (0), the Handle for the control has not been allocated, or the control is being freed. +

    +

    + PaintWindow is called from the PaintHandler method. +

    +     - + Device context with the requested clipping region. Creates the Brush, if not already created. - - + +

    + Creates and assigns a TBrush instance used in the Brush property. The brush Color is updated using the resolved value in the Color property. clDefault in Color causes the default brush color value from the widgetset to be used. +

    +

    + CreateBrush is called when the value for the Brush property is read, and the member has not yet been assigned. +

    +     + + + + + TBrush +     - Scales (resizes) all child controls. - + Scales values for all child controls. + +

    + ScaleControls is a method used to scale the child controls in the Controls property using the specified multiplier and divisor. ScaleControls visits each of the class instances in Controls and calls its ChangeScale method using Multiplier and Divider as arguments. +

    +

    + ScaleControls is called from the overridden ChangeScale method. This causes all controls in the hierarchy to apply the scaling factor to values in their Constraints, Font, Left, Top, Right and Bottom properties. For top-level Forms, the values in Left and Top are not scaled. +

    +     + +     - + Multiplier applied to a value to achieve a scaling factor. - + Divisor applied to a value to achieve a scaling factor. 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 extends the inherited method by calling DisableAlign before applying the scaling factor. It calls the ScaleControls method to apply Multiplier and Divider to the child controls. It calls the inherited method to apply scaling to the Bounds, Constraints, and Font in the control. +

    +

    + ChangeScale visits each of the control instances in Controls, and calls their UpdateAnchorRules method to update the BaseBounds in the control as needed. +

    +

    + EnableAlign is called prior to exiting from the method. +

    +     - + Multiplier applied to a value to achieve a scaling factor. - + Divisor applied to a value to achieve a scaling factor. - Handler for a changed BiDiMode message; notifies the widget and all child controls. + 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 CM_PARENTBIDIMODECHANGED message. +

    +

    + If a handle has been allocated in the widgetset class instance, its SetBiDiMode method is called to reflect the values from UseRightToLeftAlignment, UseRightToLeftReading, and UseRightToLeftScrollBar. +

    +

    + AdjustSize is called to update the sizes for parent and child controls after the property value has been changed. +

    +     - + Control message examined and handled in the method. - Handler for changed Border property messages; adjusts and invalidates the control. + Handles a CM_BORDERCHANGED message received for the control. + +

    + CMBorderChanged ensures that the size and client rectangle are adjusted when a border is added to or removed from the control. It calls DoAdjustClientRectChange and AdjustSize to update values in the control. It calls Invalidate to force the control to be redrawn with the new size and client rectangle. +

    +     - Message examined in the method. + Control message examined and applied in the method. @@ -14573,7 +14980,7 @@ ALabel.Caption := '&Notes && Comments'; CMDoubleBufferedChanged is the handler used to process CM_PARENTDOUBLEBUFFEREDCHANGED messages when the value in DoubleBuffered has been been changed.

    - CMDoubleBufferedChanged calls NotifyControls to apply the message in the widget set class; the value in the Message argument is ignored. + CMDoubleBufferedChanged calls NotifyControls to apply the message in the widgetset class; the value in the Message argument is ignored.

    CMDoubleBufferedChanged calls Invalidate to cause the control to be redrawn. @@ -15241,7 +15648,9 @@ ALabel.Caption := '&Notes && Comments'; Handler called when the control starts floating. - TWinControls can float for themselves, unless they request a special FloatingDockSiteClass. +

    + A TWinControl can be floated as a stand-alone window, unless they request a special FloatingDockSiteClass. +

    @@ -15271,11 +15680,33 @@ ALabel.Caption := '&Notes && Comments';     - Invokes the OnEnter event handler. + Signals the OnEnter event handler (when assigned) when the control receives focus. + +

    + DoEnter is called from the CMEnter method when a CM_ENTER message is received for the control. The event handler allows actions to be performed when the control receives focus, either by using keyboard navigation or by mouse click in the client area for the control. +

    +     + + + + + +     - Invoke the OnExit event handler. + Signals the OnExit event handler (when assigned) when the control loses focus. + +

    + DoExit is called from the CMExit method when a CM_EXIT message is received for the control. The event handler allows actions to be performed when the control loses focus, either by using keyboard navigation or by mouse click in the client area for another control. +

    +     + + + + + +     @@ -15298,7 +15729,7 @@ ALabel.Caption := '&Notes && Comments'; Finally, the user handler is invoked.

    - If none of the handlers accept / respond to the key, the widget set class is used to process the key. + If none of the handlers accept / respond to the key, the widgetset class is used to process the key.

    @@ -15347,26 +15778,72 @@ ALabel.Caption := '&Notes && Comments'; - Tries all OnKeyPress handlers; the Parent OnKeyPress handler is tried first. + Performs actions needed to handle a key press message for the control. - + +

    + DoKeyPress is a Boolean function used to handle a key press event received for the control. The return value is True if the character code in the specified Message is handled for the control. +

    +

    + DoKeyPress allows a TCustomForm instance in Parent with KeyPreview enabled to handle the notification message using its DoKeyPress method. If the character code is handled, the return value is set and no further actions are performed in the method. +

    +

    + The return value is False when standard events have been disabled by including csNoStdEvents in the ControlStyle property. +

    +

    + When not disabled, the KeyPress method is called using the character code in Message as an argument. If the character was handled in the OnKeyPress event handler, the return value is True. +

    +

    + DoKeyPress is called from the CNChar method when a CN_CHAR control notification message is received for the control. +

    +     + + + +     - True if the key was handled. + True if the key press was handled for the control. - + Control Notification message handled in the method. - Tries all OnUTF8KeyPress handlers; the Parent OnUTF8KeyPress handler is tried first. + Performs actions needed to handle a UTF-8-encoded key press message for the control. - - + +

    + DoUTF8KeyPress is a Boolean function used to handle a key press event for a UTF-8-encoded value received for the control. The return value is True if the character code in the specified Message is handled for the control. +

    +

    + DoUTF8KeyPress allows a TCustomForm instance in Parent with KeyPreview enabled to handle the notification message using its DoUTF8KeyPress method. If the character code is handled, the return value is set and no further actions are performed in the method. +

    +

    + The return value is False when standard events have been disabled by including csNoStdEvents in the ControlStyle property. +

    +

    + When not disabled, the UTF8KeyPress method is called using the character code in Message as an argument. If the character was handled in the OnUTF8KeyPress event handler, the return value is True. +

    +

    + At design-time, DoUTF8KeyPress redirects the key event to the active design surface in the Lazarus IDE. +

    +

    + DoUTF8KeyPress is called from the IntfUTF8KeyPress method when a CN_CHAR control notification message is received for the control. DoUTF8KeyPress is called after KeyDown has been executed. +

    +     + + + + + + + +     True if the key was handled. @@ -15394,15 +15871,22 @@ ALabel.Caption := '&Notes && Comments'; - Applies the key message using ChildKey in the parent control. - - + Allows a parent form to process a keyboard message in one of its child controls. + + + WantChildKey in TCustomForm always returns False. + + + + + + - True if the key was handled. + True if the key message was handled. - + Child key message handled in the method. @@ -15423,64 +15907,106 @@ ALabel.Caption := '&Notes && Comments'; - + + Handles the specified key in Message as an accelerator or shortcut key. + +

    + DialogChar is an overridden Boolean function in TWinControl used to handle a character code in Message as an accelerator (or shortcut) key for a control. It re-implements the inherited method which always returns False. In TWinControl, the Message is sent to each of the children in Controls until one of them indicates that it responds to the accelerator key. +

    +

    + DialogChar is overridden in descendent classes to perform actions needed when the shortcut key is handled in the method. These classes allow the accelerator key to be defined using the Caption or Shortcut properties. Some examples include: +

    +
      +
    • TCustomGrid / TGrid
      • +
    • TCustomButton / TButton
      • +
    • TCustomLabel / TLabel
      • +
    • TCustomStaticText / TStaticText
      • +
    • TCustomSpeedButton / TSpeedButton
      • +
    +     + + TControl.DialogChar + +     True if the key was handled. - + Message with the character examined in the method. - Lets the Application handle an navigation key. - - + Handles key down events for special navigation keys used in a control. + +

    + ControlKeyDown is a method used to detect and handle key down events for navigation keys used in the control. ControlKeyDown calls the corresponding method in TApplication to determine the actions needed for the key and modifier. The application handles Tab and cursor keys which may affect control or form focus. +

    +

    + ControlKeyDown is called from the DoRemainingKeyDown method to handle keys not otherwise handled by a control or its parent forms. +

    +     + + + TApplication.ControlKeyDown + TApplication.DoTabKey + TApplication.DoArrowKey +     - + Numeric key code examined in the method. - + Shift, Ctrl, or Alt modifier for the key. - Lets the Application handle an navigation key. - - + Handles key up events for special navigation keys. + +

    + ControlKeyUp is a method used to detect and handle key up events for navigation keys used in the control. ControlKeyUp calls the corresponding method in TApplication to determine the actions needed for the key and modifier. The application handles Return (Enter) and Escape keys which may affect control or form focus. +

    +

    + ControlKeyUp is called from the DoRemainingKeyUp method to handle keys not otherwise handled by a control or its parent forms. +

    +     + + + TApplication.ControlKeyUp + TApplication.DoReturnKey + TApplication.DoEscapeKey +     - + Numeric key code examined in the method. - + Shift, Ctrl, or Alt modifier for the key. - - Invokes the OnKeyDown handler. - + Signals the OnKeyDown event handler (when assigned). - + Numeric key code examined in the method. - + Shift, Ctrl, or Alt modifier for the key. - Invokes the OnKeyDown handler. + Lets the application, parent forms, or control handle key preview before the LCL interface. - + Numeric key code examined in the method. - + Shift, Ctrl, or Alt modifier for the key. @@ -15500,28 +16026,24 @@ ALabel.Caption := '&Notes && Comments'; - - Invokes the OnKeyPress handler. - + Signals the OnKeyPress event handler (when assigned). - + Character value for the key press event. - - Invokes the OnKeyUp handler. - + Signals the OnKeyUp event handler (when assigned). - + Numeric key code for the key up event. - + Shift, Ctrl, or Alt modifier for the key. @@ -15555,14 +16077,12 @@ ALabel.Caption := '&Notes && Comments'; - - Invokes the OnUTF8KeyPress handler. - + Signals the OnUTF8KeyPress event handler (when assigned). - + UTF-8-encoded character value for the key press event. @@ -15593,7 +16113,7 @@ ALabel.Caption := '&Notes && Comments'; - Returns the first control in tab order. + Returns the first control in the tab order for the parent form. @@ -15632,10 +16152,10 @@ ALabel.Caption := '&Notes && Comments'; Gets the value for the ClientRect property.

    - GetClientRect is an overridden method in TWinControl used to get the value for the ClientRect property. ClientRect contains the visual client area for the control. + GetClientRect is an overridden method in TWinControl used to get the value for the ClientRect property. ClientRect contains the visual client area for the control.

    - GetClientRect extends the ancestor method to synchronize values in the control and its widgetset class using the Handle for the control. It uses values in ComponentState and the control flags for the TWinControl instance to determine the actions needed in the method. If an action cannot be determined, or the handle is not available, values in ClientWidth and ClientHeight are used as the Width and Height in the TRect instance. + GetClientRect extends the inherited method to synchronize values in the control with its widgetset class instance using the Handle for the control. It uses values in ComponentState and the control flags for the TWinControl instance to determine the actions needed in the method. If an action cannot be determined, or the handle is not available, values in ClientWidth and ClientHeight are used as the Width and Height in the TRect instance.

    @@ -15647,23 +16167,49 @@ ALabel.Caption := '&Notes && Comments';     - The screen coordinates for the control. + Gets the value for the ControlOrigin property. +

    + GetControlOrigin is overridden in TWinControl to get a window rectangle from the LCL interface. If the Handle for the control has not been allocated, the inherited method is called. +

    +

    + Returns the screen coordinates for the Top and Left coordinate 0,0 of the control area. (The top / left pixel of the control on the screen). Note that this value is the position as stored in the interface and is not always in sync with the LCL. When a control is moved, the LCL sets the bounds to the wanted position and sends a move message to the interface. It is up to the interface to handle moves instantly or to queue them. +

    TControl.GetControlOrigin     - + TPoint instance with the screen coordinates for the Top and Left properties. - + + Gets the device context for the control. + +

    + GetDeviceContext is an overridden HDC function in TWinControl used to get the device context used for the control. +

    +

    + The device context provides a Handle (yes another one) with information about the drawing region on a display or printer. In the LCL, this essentially identifies a clipping rectangle for a given window handle. In TControl, the device context for the WindowHandle in the Parent control is used (because it does not have its own handle). In TWinControl, the Handle for the control is used. +

    +

    + GetDevice context calls the GetDC routine in the LCL interface to get a device context for the value in its Handle property. On successful completion of the routine, the return value is also assigned to the WindowHandle argument (which is the member for the WindowHandle property for display purposes). +

    +

    + An EOutOfResources exception is raised when GetDC returns an unassigned device context (0). +

    +

    + GetDeviceContext re-implements the inherited method. +

    +     + +     - + Device context created for the control, or 0 when unavailable. - + Handle for the control represented in the device context. Updated in the method. @@ -15835,9 +16381,19 @@ ALabel.Caption := '&Notes && Comments'; - Called when the control has been loaded from a resource, transfers the loaded property values to the widget. + 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 calls the inherited method to update the BaseBounds for control, and to apply property values dependent on the Parent control. +

    +

    + Loaded calls FixupTabList to populate an internal list with child Controls ordered by their TabOrder property. +

    +     @@ -15845,7 +16401,7 @@ ALabel.Caption := '&Notes && Comments'; - Realizes all cached changes after a bulk update of the form. Calls inherited FormEndUpdated, then informs each child control. + Realizes all cached changes after a bulk update of the form. Calls the inherited FormEndUpdated method, then informs each child control. @@ -15854,13 +16410,18 @@ ALabel.Caption := '&Notes && Comments'; - This method allows handling messages in Windows. + The message handler for the control. +

    + Used for controls which need features not yet supported by the LCL. MainWndProc has an empty implementation in TWinControl. +

    - + + TApplication +     - + Message handled in the method. @@ -15919,15 +16480,40 @@ ALabel.Caption := '&Notes && Comments'; - Notifies the parent when the control loses focus. - - + Notifies the parent Form when the control cannot be focused. + +

    + RemoveFocus is a method used to notify the parent form when the control cannot be focused. RemoveFocus is called from methods like Destroy and RemoveControl, where the control will no longer exist on the parent form. It is also called from methods like CMEnabledChanged and CMVisibleChanged, where the parent form should no longer allow the control to be focused. +

    +

    + RemoveFocus calls GetParentForm to get the parent form instance, and calls its DefocusControl method to ensure that the control is removed as the ActiveControl (when assigned). +

    +     + + + + + + TCustomForm.DefocusControl + TCustomForm.ActiveControl + GetParentForm +     - + True if the control is being freed, False when it is not enabled or not visible. - + + Sends Move or Size messages using the window message processing loop. + +

    + Send Move and Size messages through the LCL message paths. This simulates the VCL behavior and has no real effect. +

    +     + + TControl.SendMoveSizeMessages + +     @@ -15935,9 +16521,13 @@ ALabel.Caption := '&Notes && Comments';     - + Sets the value for the BorderStyle property. - + +

    + Notifies the widgetset class instance of the new property value when its handle has been allocated. +

    +     @@ -15976,10 +16566,10 @@ ALabel.Caption := '&Notes && Comments';     - + Control to locate and move in the method. - + New ordinal position for the control in the Controls property. @@ -15994,28 +16584,61 @@ ALabel.Caption := '&Notes && Comments'; - Asks the parent to show itself. - - + Displays the control on its Parent. + +

    + ShowControl is a method used to display the control on its Parent. When Parent has been assigned, its ShowControl is called. This is repeated until a control without an assigned Parent is encountered. +

    +

    + ShowControl is called from the Show method in a control instance. It occurs before the Visible property is set to True, and forces each of the parent controls to become visible before setting the value in the control. +

    +     + + + +     - The control to show, here: ignored! + A control to display. Ignored in this method. - Updates the visible state for the control; updates the widget set class when already created. + Updates the visible state for the control, and notifies the widgetset class when available. - + +

    + Calls AdjustSize when the Handle has been allocated for the control and the control is logically visible in the client area for the parent. This causes DoAllAutoSize and UpdateShowing to be called. If the control is not visible, UpdateShowing is called to hide the control. +

    +

    + Called from the SetParentWindow method. +

    +     - When the widget should be visible and has not yet been created, it's created along with all children. + Updates the Showing property with the visibility for the control, its Parents, and its child controls. - - + +

    + UpdateShowing is a method used to determine the visibility for the Handle in the control. It calls HandleObjectShouldBeVisible to check the handle state and visibility for both the control and each of its Parent controls. If the control should be showing and Handle has not already been allocated, CreateHandle is called. +

    +

    + When child controls exist in the Controls property, they are visited to call the UpdatingShowing method for each of the TWinControl instances. +

    +

    + If an auto-sizing request is not active, a CM_SHOWINGCHANGED message is performed to apply the new visibility for the control(s). The Showing property is updated prior to exiting from the method. +

    +     + + + + + + +     @@ -16187,7 +16810,7 @@ ALabel.Caption := '&Notes && Comments'; - The intended ClientHeight, as sent to the widget set class. + The intended ClientHeight, as sent to the widgetset class. @@ -16195,7 +16818,7 @@ ALabel.Caption := '&Notes && Comments'; - The intended ClientWidth, as sent to the widget set class. + The intended ClientWidth, as sent to the widgetset class. @@ -16343,17 +16966,37 @@ ALabel.Caption := '&Notes && Comments'; - A reference to the widgetset class instance associated with this control. + A reference handle to the widgetset class instance associated with this control. - - + +

    + Handle is a HWND property which represents the handle to the widgetset class instance for the control. It provides a bi-directional communication mechanism between an LCL component and the native control on a given platform or widgetset. Handle has a non-zero value when it has been allocated for the widget. +

    +

    + Read access to the property value calls the HandleNeeded method to create the handle if it does not already exist in the control (and its Parent controls). When the property value is changed, the InvalidatePreferredSize method is called to update control flags and clear the cached size for the control. +

    +

    + Use HandleAllocated to check Handle for a non-zero value. Use HandleNeeded when the LCL component needs to ensure that the control and Parent controls have an assigned Handle. Or call CreateHandle. +

    +

    + Use WindowHandle to access the unique identifier for a device context used in drawing operations for the widgetset class. +

    +     + + + + + + + +     Used in Carbon and Cocoa widgetsets

    - IsFlipped is a read-only Boolean property. It is used in the Carbon and Cocoa widgetsets for these Mac platforms. + IsFlipped is a read-only Boolean property. It is used in the Carbon and Cocoa widgetsets for the macOS platforms.

    @@ -16381,9 +17024,19 @@ ALabel.Caption := '&Notes && Comments'; - Determines the navigation order for the control when the user presses the Tab or Shift+Tab key. + Indicates the navigation order for the control when the user presses the Tab or Shift+Tab key. - + +

    + TabOrder is a TTabOrder with a numeric value which indicates the navigation order for the control when the user presses the Tab or Shift+Tab key. The default value for the property is -1 and indicates that an explicit value has not been assigned. +

    +

    + Each TWinControl has an internal list used to maintain the tab order for its child Controls. When TabOrder is -1 for a given child control, it added to the end of the tab order list. A non-zero value forces the control to be stored at that ordinal position in the tab order list. Setting a new value for the property causes the private UpdateTabOrder method to be called to maintain the sequence for the child controls. +

    +

    + Use TabStop to indicate if the control can be focused using tab order navigation request. +

    +     @@ -16391,17 +17044,36 @@ ALabel.Caption := '&Notes && Comments'; - Allows the user to navigate to this control, by pressing the Tab key. + Allows the user to navigate to / from the control by pressing the Tab or Shift+Tab keys. - + +

    + TabStop is a TabStop property which indicates if the control can be focused when using the Tab or Shift+Tab keys to navigate between controls on a form. The default value for the property is False. At design-time, the Lazarus IDE sets the value to True in newly created control instances. +

    +

    + When set to True, the windows style flags are updated to include the value WS_TABSTOP in the CreateParams method. +

    +

    + Changing the value for the property causes the internal tab order list to be updated, and a CM_TABSTOPCHANGED control message is performed for the control. +

    +

    + TabStop is used in methods like FindNextControl, and may be updated in methods like Insert. +

    +     + + + + + +     - Handler for custom-aligned child controls; determines the order of control placement. + Event handler signalled to determine the order and placement for custom-aligned child controls. @@ -16409,7 +17081,7 @@ ALabel.Caption := '&Notes && Comments'; - Handler for custom-aligned child controls, determines the position of the child control. + Event handler signalled to determines the position for custom-aligned child controls. @@ -16480,9 +17152,7 @@ ALabel.Caption := '&Notes && Comments'; - - Handler for keyboard key released. - + Event handler signalled when a key up event has occurred for the control.

    Unlike OnKeyDown, this event occurs only once for auto-repeated keys. @@ -16498,12 +17168,21 @@ ALabel.Caption := '&Notes && Comments'; - Event handler for control being undocked from this DockSite. + Event handler signalled before a control is undocked from its DockSite.

    - The handler can be used to disallow undocking. + OnUnDock is a TUnDockEvent property with the event handler signalled before a control is undocked from its DockSite. The event handler arguments identify the control with the DockSite, the client control which will become undocked, the control that has the new dock site, and a Boolean which indicates if the operation is allowed. +

    +

    + The event handler can be used to disallow undocking by setting the Boolean argument to False in the handler routine. +

    +

    + OnUnDock is signalled from the DoUnDock method.

    + + +     @@ -16525,23 +17204,67 @@ ALabel.Caption := '&Notes && Comments'; - Value from the DoubleBuffered property in a Parent control. - - + Value for the DoubleBuffered property in a Parent control. + +

    + ParentDoubleBuffered is a Boolean property which indicates the value for the DoubleBuffered property in the Parent control. The default value for the property is True. Changing the value for the property causes a CM_PARENTDOUBLEBUFFEREDCHANGED message to be performed (for the control) when Parent has been assigned. +

    +

    + To disable double buffering for a single control, make sure both DoubleBuffered and ParentDoubleBuffered are set to False. +

    +

    + Double buffering is a technique used to reduce screen flicker when controls are redrawn. It uses an additional off-screen buffer to perform drawing operations, and transfers the content to the on-screen buffer when completed. +

    +

    + DoubleBuffered and ParentDoubleBuffered are implemented for the Win32 platform/widgetset. It is implemented for TWinControl (and descendants) and TApplication. In TApplication, the setting is applied to all forms and controls when assigned before the forms and controls are created. +

    +     + + + +     - The Handle for the parent widget. - - + The window Handle for the Parent widget. + +

    + ParentWindow is a HWND property with the window Handle for the Parent widget. A new value assigned to the property is ignored when Parent has already been assigned. +

    +

    + The property value is assigned when the CreateParented constructor or the CreateParentedControl class function is used to create a new TWinControl instance. Setting the property to 0 (zero) causes the handle to be destroyed. 0 is the unassigned handle value. +

    +

    + ParentWindow is used in the the CreateWnd method to form an association between the Handle in the widgetset class instance and the window handle value for a control. +

    +     + + + + + + + +     - Cached widget visibility, not necessarily in sync with the widget. + Cached visibility for the widget. Not necessarily in sync with the widget. - - + +

    + Showing is a read-only Boolean property with the visibility for the Handle in a control or its Parent. The value for the property is assigned in the UpdateShowing method when the control hierarchy is checked for valid and Visible window handles for the control or its Parents. Showing may be updated when the DoAllAutoSize or UpdateControlState methods are called. +

    +     + + + + + + + +     @@ -16593,17 +17316,55 @@ ALabel.Caption := '&Notes && Comments'; - Translates state flags into AutoSizePhases. - - + Translates control state flags into AutoSizePhases. + +

    + The return value is a TControlAutoSizePhases set type. It is populated with values from the TControlAutoSizePhase enumeration based on window control flags and other internal members in the class instance. When Parent has been assigned, the values are derived by calling AutoSizePhases in Parent. +

    +

    + AutoSizePhases is called from methods like DoAutoSize and UpdateShowing. It is also called from window messgae handlers like WMMove, WMSize, and WMWindowPosChanged. +

    +     + + + + + + + + + +     - + Set withe auto-size phase values enabled for the control. - + + + Returns True if auto-sizing has been delayed until some other process is completed. + + +

    + AutoSizeDelayed is an overridden Boolean function in TWinControl. It returns True when auto-sizing cannot or should not be performed at the current time, or when the value in Showing cannot be changed. +

    +

    + In TWinControl, it checks the ControlState flags for the value csDestroyingHandle when determining the return value for the method. AutoSizeDelayed calls the inherited method, and sets the return value to True if either condition is True. +

    +

    + The value from AutoSizeDelayed is used in methods like DoAllAutoSize and UpdateShowing. +

    +     + + + + + + + +     - + True if auto-sizing cannot be performed at the current time. @@ -16613,6 +17374,8 @@ ALabel.Caption := '&Notes && Comments'; Returns True if AutoSize should be skipped / delayed because of its handle. + + @@ -16683,7 +17446,7 @@ ALabel.Caption := '&Notes && Comments'; - Returns True if this is a parent for the given control. + Returns True if the control is a parent for the specified control. @@ -16708,7 +17471,7 @@ ALabel.Caption := '&Notes && Comments'; - The ClientRect is cached; call this procedure to invalidate the cache, so that the next ClientRect value is fetched from the widget set class. + The ClientRect is cached; call this procedure to invalidate the cache, so that the next ClientRect value is fetched from the widgetset class. @@ -16730,21 +17493,46 @@ ALabel.Caption := '&Notes && Comments'; Sets the control bounds and adjusts child and docked controls. + +

    + SetBounds is an overridden method in TWinControl. used to set the bounds for the control to the values in the ALeft, ATop, AWidth, and AHeight arguments. +

    +

    + No actions are performed in the method when the internal BoundsLockCount member has a non-zero value. In other words, when BeginUpdateBounds has been called and EndUpdateBounds has not been called. +

    +

    + At design-time, SetBounds checks to ensure that negative is not present in the Width or Height properties when the user has changed the bounds for the control. +

    +

    + SetBounds calls DisableAutoSizing to reduce the overhead for recomputing/moving/resizing when the bounds are changed. The inherited method is called to apply the new values in ALeft, ATop, AWidth, and AHeight. EnableAutoSizing is called to re-enable auto-sizing when the operation has been completed. +

    +

    + SetBounds is called when any one of these Left, Top, Width or Height properties, or the BoundsRect property has been changed. +

    +

    + Keep in mind that the given aLeft, aTop, aWidth, aHeight might not be valid and will be changed by the LCL before applied. +

    +     + + + + +     - + The X coordinate for the left side of the control. - + The Y coordinate for the left side of the control. - + The width for the control. - + The height for the control. @@ -16769,13 +17557,13 @@ ALabel.Caption := '&Notes && Comments'; - Disables auto-sizing for the control and its parent. + Disables auto-sizing when aligning the control and its parent. - Re-enables auto-sizing for the control and its parent. + Re-enables auto-sizing after aligning the control and its parent. @@ -16793,10 +17581,10 @@ ALabel.Caption := '&Notes && Comments';     - Scrolls the control using the handle for the widget set class. + Scrolls the control using the handle for the widgetset class. - Raises an Exception if the handle has not been allocated for the widget set class instance. Raised with the message 'TWinControl.ScrollBy_WS: Handle not allocated'. + Raises an Exception if the handle has not been allocated for the widgetset class instance. Raised with the message 'TWinControl.ScrollBy_WS: Handle not allocated'. @@ -17012,7 +17800,7 @@ if FormFoo.EditBar.CanFocus then

    A possible usage:

    if MyControl.CanSetFocus then - MyControl.SetFocus; + MyControl.SetFocus;

    CanSetFocus should be preferred over CanFocus if used in CanSetFocus/SetFocus combination because it checks also if the parent form can receive focus and thus prevents the "cannot focus an invisible window" LCL exception. @@ -17029,10 +17817,17 @@ if MyControl.CanSetFocus then - Finds the index value for the given control, in + Finds the position for the specified control in the Controls property. - - + +

    + Calls the IndexOf method in Controls to find the child control in AControl. The return value contains the ordinal position in Controls where AControl is stored, or -1 when not found or Controls has not been assigned. +

    +     + + + TFPList.IndexOf +     The ordinal position in Controls, -1 if not found. @@ -17051,15 +17846,22 @@ if MyControl.CanSetFocus then Checks whether the control has focus. - - + +

    + Focused is a Boolean function which indicates whether the control can be and is the currently focused control. The return value is True when the control can become focused during tab order navigation, has a valid Handle, and is the currently focused control in the widgetset class instance. +

    +     + + + +     True when the control has focus. - Sets the focus to the next (or preceding) control. + Changes the focus to the next (or preceding) control. @@ -17073,9 +17875,7 @@ if MyControl.CanSetFocus then     - - Finds a child control by name. - + Finds a child control with the specified name. @@ -17116,6 +17916,17 @@ if MyControl.CanSetFocus then Posts the specified message to all of the child controls. + +

    + Allows the specified method to be handled by one of the child Controls. The ToAllMessage argument is untyped; any TLMessage descendant can be passed as the value for the argument. +

    +

    + The method name is a misnomer. Broadcast implies delivery of the message simultaneously to all of the recipients. Actually, it is more like a telegraph. The message is posted sequentially to child controls until one of them handles the message using its WindowProc method. +

    +

    + Use NotifyControls to post a message with a specific message identifier constant to child Controls in the class instance. +

    +     @@ -17126,7 +17937,11 @@ if MyControl.CanSetFocus then Sends a message to all child controls. - + +

    + Calls the BroadCast method to deliver a TLMessage instance with the identifier in Msg. +

    +     @@ -17162,15 +17977,18 @@ if MyControl.CanSetFocus then Schedules a repaint request.

    - This implementation calls the Invalidate method for the widgetset class instance. + Invalidate is an overridden method in TWinControl. It re-implements the inherited method to call the Invalidate method in the widgetset class instance when its Handle has been allocated. It does not call the inherited method.

    - + + +     - Tells the widgetset to add a Handle object to a parent Handle object. - + Tells the widgetset to add a Handle object representing the current control. + + @@ -17252,23 +18070,25 @@ if MyControl.CanSetFocus then - Returns the caption for the docked control. + Returns the docking caption for the specified control. + + - + String the docking caption for the control. - + Control instance examined in the method. - Updates the Caption to reflect the names of the docked clients. + Updates the Caption to reflect the names for the docked clients.

    - Called when this is a hostdocksite and either the list of docked clients have changed, or one of their captions. + Called when this is a HostDockSite and either the list of docked clients have changed, or one of their captions has changed.

    - When a control is currently being undocked, but still is in the DockClients list, Exclude is set to this control. + If the control is being undocked, but still is in the DockClients list, it is excluded from the docking caption and the Exclude argument is set to True.

    @@ -17288,13 +18108,13 @@ if MyControl.CanSetFocus then - Check whether a widget has been assigned to this control. + Checks whether a handle for the widget has been allocated for the control. - True when a widget exists (Handle is not Nil). + True when a widget exists and its Handle is not Nil. @@ -17338,7 +18158,7 @@ if MyControl.CanSetFocus then - Has a Brush been created for this control? + Indicates whether a Brush has been created for the control. @@ -17406,10 +18226,10 @@ if MyControl.CanSetFocus then - Paints the control using the handle for the widget set class. + Paints the control using the handle for the widgetset class.

    - PaintTo is a procedure used to draw the control using the handle for the widget set class. An overloaded variant is provided which uses the handle in a TCanvas instance as the target for the drawing operation. + PaintTo is a procedure used to draw the control using the handle for the widgetset class. An overloaded variant is provided which uses the handle in a TCanvas instance as the target for the drawing operation.

    @@ -17434,7 +18254,7 @@ if MyControl.CanSetFocus then SetShape is an overloaded procedure used to set the shape for the control to the non-rectangular value in AShape. The overloaded methods allow AShape to be either a TBitmap or a TRegion value.

    - When TBitmap is used, the widget set class calls its SetShape method to apply the TBitmap handle to the handle for the widget. No actions are performed in the method when a handle has not been allocated for the widget set class. + When TBitmap is used, the widgetset class calls its SetShape method to apply the TBitmap handle to the handle for the widget. No actions are performed in the method when a handle has not been allocated for the widgetset class.

    When TRegion is used, SetWindowRgn in the LCL interface is called to apply the region in AShape to the handle for the control. @@ -17485,7 +18305,7 @@ if MyControl.CanSetFocus then Performs actions needed when the Font for the control has been changed.

    - FontChanged is an overridden method in TGraphicControl used to perform actions needed when the Font for the control has been changed. It is the routine used as the OnChange event handler for the Font property, and is assigned in the inherited constructor for the class instance. + FontChanged is an overridden method in TGraphicControl used to perform actions needed when the Font for the control has been changed. It is the routine used as the OnChange event handler for the Font property, and is assigned in the inherited constructor for the class instance.

    Sender contains the object instance for the event notification, and is provided to maintain compatibility with the TNotifyEvent signature for the event handler. It is not used in TGraphicControl, but is passed as an argument to the inherited method. @@ -17511,7 +18331,7 @@ if MyControl.CanSetFocus then

    - Paint is a method which causes the control to be drawn using the drawing mechanism for the control. In TGraphicControl, like TCustomControl, the OnPaint event handler is used (when assigned). Assign a routine to the OnPaint handler to perform the drawing operations needed for the control. + Paint is a method which causes the control to be drawn using the drawing mechanism for the control. In TGraphicControl, like TCustomControl, the OnPaint event handler is used (when assigned). Assign a routine to the OnPaint handler to perform the drawing operations needed for the control.

    @@ -17523,7 +18343,7 @@ if MyControl.CanSetFocus then Performs action needed when the bounds for the control have been changed.

    - DoOnChangeBounds is an overridden method in TGraphicControl. It calls the inherited method on entry to update control flags and signal OnChangeBounds event handlers for the control. The Handle in Canvas is freed prior to exiting from the method. The handle is re-allocated the next time it is accessed. + DoOnChangeBounds is an overridden method in TGraphicControl. It calls the inherited method on entry to update control flags and signal OnChangeBounds event handlers for the control. The Handle in Canvas is freed prior to exiting from the method. The handle is re-allocated the next time it is accessed.

    DoOnChangeBounds is called when the component is loaded using the LCL streaming mechanism, and from the ChangeBounds method when the control is resized. @@ -19125,7 +19945,7 @@ AControl.Align := AnchorAlign[alRight]; // contains [akRight, akTop, akBottom] - (Re-)Creates the widget set class instance for a TWinControl. + (Re-)Creates the widgetset class instance for a TWinControl.

    This function was originally a member of TWinControl. @@ -19134,7 +19954,7 @@ AControl.Align := AnchorAlign[alRight]; // contains [akRight, akTop, akBottom] From a VCL point of view, that made perfectly sense since the VCL knows when a Win32 widget has to be recreated when properties have changed.

    - The LCL, however, does not know when properties values are changed. But the widget set does. To avoid the old VCL behavior, and to provide a central function for use in the widget set, it has been moved here. + The LCL, however, does not know when properties values are changed. But the widgetset does. To avoid the old VCL behavior, and to provide a central function for use in the widgetset, it has been moved here.

    @@ -19159,7 +19979,7 @@ AControl.Align := AnchorAlign[alRight]; // contains [akRight, akTop, akBottom] CancelDrag is a procedure used to cancel an active drag operation. CancelDrag calls the DragStop method in the currently active DragManager.

    - No actions are performed in the routine when DragManager has been assigned (contains Nil), or when DragManager returns False from its IsDragging method. + No actions are performed in the routine when DragManager has not been assigned (contains Nil), or when DragManager returns False from its IsDragging method.     @@ -19415,7 +20235,7 @@ AControl.Align := AnchorAlign[alRight]; // contains [akRight, akTop, akBottom] Determines if the color for the control is the system default (GTK).

    - Used by GTK-based widget set classes to determine if the color in a control needs to be compares to the SYS_COLOR_BASE value used in the widget set. + Used by GTK-based widgetset classes to determine if the color in a control needs to be compares to the SYS_COLOR_BASE value used in the widgetset.

    @@ -19652,7 +20472,7 @@ var Some controls override this method. For example the TGraphicControl descendants like TLabel have no window handle and so cannot query the widgetset. They must calculate their preferred Width and Height themselves.

    - The widget sets must override the GetPreferredSize method for each widget class that has a preferred size (Width or Height or both). + The widgetsets must override the GetPreferredSize method for each widget class that has a preferred size (Width or Height or both).

    Parent.AutoSize

    @@ -19661,7 +20481,7 @@ var

    Properties / Methods

    Left and Top

    - If Parent is not Nil then Left, Top are the pixel distance to the top, left pixel of the parent's client area (not scrolled). Remember the client area is always without the frame and scrollbars of the parent. For Delphi users, some VCL controls like TGroupbox define the client area as the whole control including the frame. Others do not. The LCL is more consistent, and therefore Delphi incompatible. Left and Top can be negative or bigger than the client area. Some widget sets define a minimum, and maximum somewhere around 10,000 pixels or more. + If Parent is not Nil then Left, Top are the pixel distance to the top, left pixel of the parent's client area (not scrolled). Remember the client area is always without the frame and scrollbars of the parent. For Delphi users, some VCL controls like TGroupbox define the client area as the whole control including the frame. Others do not. The LCL is more consistent, and therefore Delphi incompatible. Left and Top can be negative or bigger than the client area. Some widgetsets define a minimum, and maximum somewhere around 10,000 pixels or more.

    When the client area is scrolled the Left and Top are kept unchanged. @@ -19916,7 +20736,6 @@ B.AnchorSide[akTop].Side:=asrTop; | | +---+ +-------+ -

    use: