TWinControl class

In unit Controls

Implements a windowed control which can contain other child controls.

Declaration

pascal

TWinControl = class(TControl)

Inheritance

Descends from it: TButtonControl TCustomCalendar TCustomComboBox TCustomControl TCustomEdit TCustomGroupBox TCustomListBox TCustomListView TCustomPage TCustomPairSplitter TCustomProgressBar TCustomRubberBand TCustomScrollBar TCustomStaticText TCustomTabControl TCustomTrackBar TPairSplitterSide TPreviewFileControl TStatusBar

Description

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.

Properties

`WindowHandle`	protected	For internal use; allows direct access to the Handle for the control, bypassing any getter/setter methods.
`BorderStyle`	protected	Indicates the border style displayed around the control.
`BorderWidth`	public	Width of the Border around the control; default is zero.
`BoundsLockCount`	public	A counter used to track updates to the BoundsRect for the control.
`Brush`	public	The Brush used to paint the background for the control.
`CachedClientHeight`	public	The intended ClientHeight, as sent to the widgetset class.
`CachedClientWidth`	public	The intended ClientWidth, as sent to the widgetset class.
`ChildSizing`	public	Provides a grid (table) layout for the children of this control.
`ControlCount`	public	The number of child controls in the Controls property.
`Controls`	public	Provides indexed access to the child controls for the class instance.
`DefWndProc`	public	The default WndProc on Windows widgetset and platforms.
`DockClientCount`	public	The number of clients docked into this control.
`DockClients`	public	The indexed list of controls docked into this control.
`DockManager`	public	The docking layout manager for this control.
`DockSite`	public	Allows controls to be drag-and-dock-ed into this control.
`DoubleBuffered`	public	When enabled, it reduces flicker when the control is painted.
`Handle`	public	A reference handle to the widgetset class instance associated with this control.
`IsFlipped`	public	Used in Carbon and Cocoa widgetsets
`IsResizing`	public	Indicates if the control is changing its size after the BeginUpdateBounds method has been called.
`TabOrder`	public	Indicates the navigation order for the control when the user presses the Tab or Shift+Tab key.
`TabStop`	public	Allows the user to navigate to / from the control by pressing the Tab or Shift+Tab keys.
`ParentDoubleBuffered`	public	Value for the DoubleBuffered property in a Parent control.
`ParentWindow`	public	The window Handle for the Parent widget.
`Showing`	public	Cached visibility for the widget. Not necessarily in sync with the widget.
`UseDockManager`	public	Determines whether a DockManager is used for this DockSite.
`DesignerDeleting`	public	Indicates whether the wcfDesignerDeleting flag is included in the flags for the control.
`IsSpecialSubControl`	public	Indicates if the control has the wcfSpecialSubControl control flag.
`VisibleDockClientCount`	public	The number of visible docked controls.

Methods

`WSRegisterClass`	protected	Registers the class instance for use in the widgetset.
`AdjustClientRect`	protected	Override this method when the ClientRect for a control differs from the default value.
`GetAdjustedLogicalClientRect`	protected	Returns the adjusted logical ClientRect, using the cached value when available.
`AlignControls`	protected	Repositions and resizes the control and child controls.
`CustomAlignInsertBefore`	protected	Indicates whether the specified controls were custom-aligned using the OnAlignInsertBefore handler.
`CustomAlignPosition`	protected	Returns the aligned position for a custom-aligned child control, using the OnAlignPosition event handler.
`DoAlignChildControls`	protected	Override this method to position / align all child controls for the specified control.
`DoChildSizingChange`	protected	Called after a change in ChildSizing information to trigger further processing.
`InvalidatePreferredChildSizes`	protected	Flags the preferred sizes of all child controls as invalid (recursively).
`CanTab`	protected	Indicates whether the Tab key can be used for keyboard navigation in the control.
`IsClientHeightStored`	protected	Implements the storage specifier for the ClientHeight property.
`IsClientWidthStored`	protected	Implements the storage specifier for the ClientWidth property.
`DoSendShowHideToInterface`	protected	Sends the new Visible state to the widgetset class instance.
`ControlsAligned`	protected	Called from AlignControls when alignment for the control is completed.
`DoSendBoundsToInterface`	protected	Sends the new bounds for the control to the widgetset class instance.
`RealizeBounds`	protected	Checks for changes in BoundsRect, and sends the new bounds to the widget.
`RealizeBoundsRecursive`	protected	Sends changed BoundsRects to the widget, for both the control and all child controls.
`InvalidateBoundsRealized`	protected	Resets the realized bounds rectangle for the control.
`CreateSubClass`	protected	An empty implementation in the current LCL version.
`DoConstraintsChange`	protected	Notifies the widgetset class instance when Constraints are changed.
`DoSetBounds`	protected	Updates the size and extent of the control as well as its ClientRect.
`DoAutoSize`	protected	Shrinks or enlarges the control to accommodate its children.
`DoAllAutoSize`	protected	Performs actions to resize and align the control and all of its children.
`AllAutoSized`	protected	Called from DoAllAutoSize after all bounds have been computed for the control.
`CalculatePreferredSize`	protected	Override this method to return a different preferred height and/or width for auto-sizing.
`GetPreferredSizeClientFrame`	protected	Calculates the width and height for the frame area around the control.
`GetChildren`	protected	Calls the specified procedure for each child control with Root as the Owner.
`ChildClassAllowed`	protected	Checks whether the specified class type is allowed as a child control.
`PaintControls`	protected	Paints all child controls which do not have a Handle.
`PaintHandler`	protected	Handler for TLMPaint, manages the painting of child controls.
`PaintWindow`	protected	Paints a clipping region for the control on the specified device context.
`CreateBrush`	protected	Creates the Brush, if not already created.
`ScaleControls`	protected	Scales values for all child controls.
`ChangeScale`	protected	Scales (resizes) the control and all of its child controls.
`CMBiDiModeChanged`	protected	Handles a CM_BIDIMODECHANGED control message for the control.
`CMBorderChanged`	protected	Handles a CM_BORDERCHANGED message received for the control.
`CMDoubleBufferedChanged`	protected	Handler for changes to the DoubleBuffered property.
`CMEnabledChanged`	protected	Handler signalled when the Enabled property has been changed.
`CMParentDoubleBufferedChanged`	protected	Handles the CM_PARENTDOUBLEBUFFEREDCHANGED control message for the control (when enabled).
`CMShowingChanged`	protected	Handler for changed Showing message; notifies the widgetset.
`CMShowHintChanged`	protected	Handler for changed ShowHint message; notifies all child controls.
`CMVisibleChanged`	protected	Handles Focus changes, and forces UpdateControlState.
`CMEnter`	protected	Handles the CM_ENTER control message for the control.
`CMExit`	protected	Handles the CM_EXIT control message for the control.
`WMContextMenu`	protected	Handler for an ContextMenu event; eventually delegates handling to the affected child control.
`WMEraseBkgnd`	protected	Erases the background, when required.
`WMNotify`	protected	Handles (dispatches) notification messages.
`WMSetFocus`	protected	Handler for receiving Focus event.
`WMKillFocus`	protected	Handles the LM_KILLFOCUS message for the control.
`WMShowWindow`	protected	Handler for changed visibility notification.
`WMEnter`	protected	Handles the LM_ENTER message for the control.
`WMExit`	protected	Handles the LM_EXIT message for the control.
`WMKeyDown`	protected	Event handler for a key press not handled by the widget; Tries .
`WMSysKeyDown`	protected	Event handler for system key presses not handled by the widget; tries .
`WMKeyUp`	protected	Event handler for key released, not handled by the widget. Tries .
`WMSysKeyUp`	protected	Event handler for system key releases not handled by the widget; tries
`WMChar`	protected	Handler for messages sent by the widget, after it has handled the key press itself.
`WMSysChar`	protected	Handler for messages sent by the widget, after it has handled the key press itself.
`WMPaint`	protected	Manages paint requests, and handles double buffering.
`WMDestroy`	protected	Handler for widget destroyed message; clears the Handle.
`WMMove`	protected	Handler for widget moved message; updates the Bounds.
`WMSize`	protected	Event handler for size messages.
`WMWindowPosChanged`	protected	Event handler for size/move messages.
`CNKeyDown`	protected	Handler for a key pushed notification; the message is handled by DoKeyDownBeforeInterface by default.
`CNSysKeyDown`	protected	Handler for a system key pushed notification; the message is handled by DoKeyDownBeforeInterface by default.
`CNKeyUp`	protected	Handler for a key released notification; the message is handled by DoKeyUpBeforeInterface by default.
`CNSysKeyUp`	protected	Handler for a system key released notification; the message is handled by DoKeyUpBeforeInterface by default.
`CNChar`	protected	Handler for a key pressed notification; CNChar is sent by the widget before it has handled the key press itself.
`DoDragMsg`	protected	Dispatches a drag message, sent by the DragManager.
`DoDockClientMsg`	protected	Handles a dmDragDock message, when a control has been docked to this site.
`DoUndockClientMsg`	protected	Notifies the DockManager of the undock of a client control.
`DoAddDockClient`	protected	Adjust the Parent of a newly docked Client.
`DockOver`	protected	Called to check whether this control allows docking and where.
`DoDockOver`	protected	Invoke the OnDockOver handler.
`DoRemoveDockClient`	protected	Override this method to take special actions on removal of an docked client.
`DoUnDock`	protected	Notifies an OnUnDock handler and the DockManager of an undocked client control.
`GetSiteInfo`	protected	Return information about this dock site (InfluenceRect).
`GetParentHandle`	protected	Gets the handle for the Parent control.
`GetTopParentHandle`	protected	Gets the window handle for the parent control at the top of the control hierarchy.
`ReloadDockedControl`	protected	Returns the docked control of the specified name.
`CreateDockManager`	protected	Returns the DockManager for this control.
`SetDockManager`	protected	Sets the value for the DockManager property.
`DoFloatMsg`	protected	Handler called when the control starts floating.
`DoGetDockCaption`	protected	Returns the dock caption in AControl.
`DoEnter`	protected	Signals the OnEnter event handler (when assigned) when the control receives focus.
`DoExit`	protected	Signals the OnExit event handler (when assigned) when the control loses focus.
`DoKeyDownBeforeInterface`	protected	Handles a KeyDown event before the widget processes the key.
`DoRemainingKeyDown`	protected	Handles key down messages which are not handled by the widget.
`DoRemainingKeyUp`	protected	Handles key up messages not already handled by the widget.
`DoKeyPress`	protected	Performs actions needed to handle a key press message for the control.
`DoUTF8KeyPress`	protected	Performs actions needed to handle a UTF-8-encoded key press message for the control.
`DoKeyUpBeforeInterface`	protected	Handles a KeyUp event before the widget processes the key.
`ChildKey`	protected	Allows a parent form to process a keyboard message in one of its child controls.
`SendDialogChar`	protected	Forwards the key message to the parent form to be handled as an accelerator (shortcut) key.
`DialogChar`	protected	Handles the specified key in Message as an accelerator or shortcut key.
`ControlKeyDown`	protected	Handles key down events for special navigation keys used in a control.
`ControlKeyUp`	protected	Handles key up events for special navigation keys.
`KeyDown`	protected	Signals OnKeyDown event handlers (when assigned).
`KeyDownBeforeInterface`	protected	Allows the application, parent forms, or control to handle key preview before the LCL interface.
`KeyDownAfterInterface`	protected	An empty implementation in the current LCL version.
`KeyPress`	protected	Signals the OnKeyPress event handler (when assigned).
`KeyUp`	protected	Signals the OnKeyUp event handler (when assigned).
`KeyUpBeforeInterface`	protected	Signals the OnKeyUp handler (when assigned)) before calling the LCL interface.
`KeyUpAfterInterface`	protected	An empty implementation in the current LCL version.
`UTF8KeyPress`	protected	Signals the OnUTF8KeyPress event handler (when assigned).
`FindNextControl`	protected	Returns the preceding or next control in the tab order.
`SelectFirst`	protected	Returns the first control in the tab order for the parent form.
`RealGetText`	protected	Returns the Caption property.
`GetBorderStyle`	protected	Gets the value for the BorderStyle property.
`GetClientOrigin`	protected	Gets the top, left screen coordinates for the client area in the control.
`GetClientRect`	protected	Gets the value for the ClientRect property.
`GetControlOrigin`	protected	Gets the value for the ControlOrigin property.
`GetDeviceContext`	protected	Gets the device context for the control.
`IsControlMouseMsg`	protected	Sends the specified mouse message to a child control.
`CreateHandle`	protected	Creates the Handle for the widget, if not already created.
`CreateParams`	protected	Initializes the window creation parameter record with the settings for the control.
`CreateWnd`	protected	Creates the interface object (widget) and assigns the value in Handle.
`DestroyHandle`	protected	Destroys the handle for the control and all child controls.
`DestroyWnd`	protected	Destroys the interface object (widget).
`DoFlipChildren`	protected	Flip children horizontally (mirrors the Left position).
`FinalizeWnd`	protected	Prepares to remove the window (called before the Handle is destroyed).
`FixupTabList`	protected	Assigns sequential TabOrder values to child controls.
`FontChanged`	protected	Implements the event handler signalled when the Font has been changed for the control.
`InitializeWnd`	protected	Copies cached control properties to the newly created widget.
`Loaded`	protected	Performs actions when a component has been loaded during LCL streaming.
`FormEndUpdated`	protected	Realizes all cached changes after a bulk update to a form. Calls the inherited FormEndUpdated method, then informs each child control.
`MainWndProc`	protected	The message handler loop for the control.
`ParentFormHandleInitialized`	protected	Called after all child handles for the ParentForm are created; notifies all children of the end of the handle creation phase.
`ChildHandlesCreated`	protected	Called after all child handles have been created; resets wcfCreatingChildHandles.
`GetMouseCapture`	protected	Gets the value for the MouseCapture property.
`RealSetText`	protected	Sets the text / caption for the control.
`RemoveFocus`	protected	Notifies the parent Form when the control cannot be focused.
`SendMoveSizeMessages`	protected	Sends Move or Size messages using the window message processing loop.
`SetBorderStyle`	protected	Sets the value for the BorderStyle property.
`SetColor`	protected	Sets the value for the Color property.
`SetChildZPosition`	protected	Updates the position of the child control in the Z plane (i.e. front-to-back).
`ShowControl`	protected	Displays the control on its Parent.
`UpdateControlState`	protected	Updates the visible state for the control, and notifies the widgetset class when available.
`UpdateShowing`	protected	Updates the Showing property with the visibility for the control, its Parents, and its child controls.
`WndProc`	protected	Adds special handling for focus and input messages, and notifies the DockManager.
`WSSetText`	protected	Sets the value for the Text property in the widgetset class.
`AutoSizePhases`	public	Translates control state flags into AutoSizePhases.
`AutoSizeDelayed`	public	Returns True if auto-sizing has been delayed until some other process is completed.
`AutoSizeDelayedReport`	public	Returns a string with a debugging message for delayed auto-size requests.
`AutoSizeDelayedHandle`	public	Returns True if AutoSize should be skipped / delayed because of its handle.
`BeginUpdateBounds`	public	Starts an update to the Bounds property; disables SetBounds by incrementing BoundsLockCount.
`EndUpdateBounds`	public	Ends an update to the Bounds property; decrements BoundsLockCount and eventually calls SetBounds.
`LockRealizeBounds`	public	Disables sending bounds to the widget, by incrementing the internal FRealizeBoundsLockCount.
`UnlockRealizeBounds`	public	Enables sending bounds to the widget again, eventually updates the widget.
`ControlAtPos`	public	Get the child control at the given client position.
`ContainsControl`	public	Returns True if the control is a parent for the specified control.
`DoAdjustClientRectChange`	public	Asks the widget if ClientRect has changed since the last AlignControl execution; calls AdjustSize on change.
`InvalidateClientRectCache`	public	The ClientRect is cached; call this procedure to invalidate the cache, so that the next ClientRect value is fetched from the widgetset class.
`ClientRectNeedsInterfaceUpdate`	public	The ClientRect is cached - check if the cache is valid.
`SetBounds`	public	Sets the control bounds and adjusts child and docked controls.
`GetChildrenRect`	public	Returns the Client rectangle relative to the controls left, top.
`DisableAlign`	public	Disables auto-sizing when aligning the control and its parent.
`EnableAlign`	public	Re-enables auto-sizing after aligning the control and its parent.
`ReAlign`	public	Adjusts the size and placement for the control and all of its children.
`ScrollBy_WS`	public	Scrolls the control using the handle for the widgetset class.
`ScrollBy`	public	Scrolls child controls by the specified number of pixels.
`WriteLayoutDebugReport`	public	Used for debugging.
`AutoAdjustLayout`	public	Automatically adjusts the size and layout for the control (and all of its children).
`FixDesignFontsPPIWithChildren`	public	Fixes the design-time PPI settings for the control font, and applies the changes to child controls.
`Create`	public	Constructor for the class instance.
`CreateParented`	public	Constructor for a control that is the child of the given widget.
`CreateParentedControl`	public	Constructor for a control that is the child of the given widget.
`Destroy`	public	Destructor for the class instance.
`DockDrop`	public	Handler for a DragManager dmDragDrop message, sent when a dragged control has been dropped onto this docksite.
`CanFocus`	public	Is this control allowed to receive the focus when parent form is visible?
`CanSetFocus`	public	Is this control allowed to receive the focus?
`GetControlIndex`	public	Finds the position for the specified control in the Controls property.
`SetControlIndex`	public	Updates the position of the child control in the Z plane (i.e. front-to-back).
`Focused`	public	Checks whether the control has focus.
`PerformTab`	public	Changes the focus to the next (or preceding) control.
`FindChildControl`	public	Finds a child control with the specified name.
`SelectNext`	public	Transfers the focus to the next child control.
`SetTempCursor`	public	Changes the cursor shape temporarily, preserving the original
`BroadCast`	public	Posts the specified message to all of the child controls.
`NotifyControls`	public	Sends a message to all child controls.
`DefaultHandler`	public	Handles all messages that the control doesn't fully handle itself.
`GetTextLen`	public	The length of the Text for the control.
`Invalidate`	public	Schedules a repaint request.
`AddControl`	public	Tells the widgetset to add a Handle object representing the current control to the Parent handle.
`InsertControl`	public	Inserts the specified control into the Controls property.
`RemoveControl`	public	Removes the specified control from the Controls property.
`GetEnumeratorControls`	public	Gets an enumerator for the Controls property.
`GetEnumeratorControlsReverse`	public	Gets a reverse-order enumerator for the Controls property.
`Repaint`	public	Immediately redraws the control when visible, bypassing the message queue.
`Update`	public	Redraws invalidated parts of the control immediately.
`SetFocus`	public	Ensures that the control or window handle has focus.
`FlipChildren`	public	Flip children horizontally. That means mirroring the Left position and anchoring.
`ScaleBy`	public	Scales (resizes) the control and all of its child controls.
`GetDockCaption`	public	Returns the docking caption for the specified control.
`UpdateDockCaption`	public	Updates the Caption to reflect the names for the docked clients.
`GetTabOrderList`	public	Fill the list with all TabStop controls, recursing into child controls.
`HandleAllocated`	public	Checks whether a handle for the widget has been allocated for the control.
`ParentHandlesAllocated`	public	Returns True if all Parents have handles allocated, and are not being destroyed.
`HandleNeeded`	public	Call this method when your code requires a valid Handle for this control.
`BrushCreated`	public	Indicates whether a Brush has been created for the control.
`EraseBackground`	public	Fills the display rectangle for the control with the color and pattern in Brush.
`IntfUTF8KeyPress`	public	Called by the interface after the navigation and specials keys are handled; i.e. after KeyDown but before KeyPress.
`IntfGetDropFilesTarget`	public	Searches for a Parent form that can be used as a file drop target.
`PaintTo`	public	Paints the control using the handle for the widgetset class.
`SetShape`	public	Specifies the non-rectangular shape of the widget.

Events

`OnGetSiteInfo`	protected	Provides information about the DockSite for the control.
`OnGetDockCaption`	protected	This handler can provide a special DockCaption, different than the Caption default.
`OnAlignInsertBefore`	public	Event handler signalled to determine the order and placement for custom-aligned child controls.
`OnAlignPosition`	public	Event handler signalled to determines the position and size for custom-aligned child controls.
`OnDockDrop`	public	Event handler signalled for the drop of a control to be docked.
`OnDockOver`	public	Event handler signalled when a control is moved over a docksite; determines whether the drop event is accepted or rejected.
`OnEnter`	public	Event handler signalled when the control receives focus.
`OnExit`	public	Event handler signalled when the control loses focus.
`OnKeyDown`	public	Event handler signalled for key down keyboard events.
`OnKeyPress`	public	Event handler signalled for character data entered by the user.
`OnKeyUp`	public	Event handler signalled when a key up event has occurred for the control.
`OnUnDock`	public	Event handler signalled before a control is undocked from its DockSite.
`OnUTF8KeyPress`	public	Handler for a character entered by the user.

Fields

`FDoubleBuffered`	protected	Member used to store the value for the DoubleBuffered property.
`FWinControlFlags`	protected	Contains various window control state flags.