[Overview][Constants][Types][Classes][Procedures and functions][Variables][Index] Reference for unit 'Controls' (#lcl)

TWinControl

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

The base class for controls which can contain other (child) controls.

Declaration

Source position: controls.pp line 2007

type TWinControl = class(TControl)

protected

  FDoubleBuffered: Boolean;

  

Allows to reduce flicker in the painting of the control.

  FWinControlFlags: TWinControlFlags;

  

Various window control state flags.

  class procedure WSRegisterClass; override;

  

Registers this component class with the current WidgetSet.

  procedure AdjustClientRect(); virtual;

  

Override this method when the ClientRect for a control differs from the default value.

  procedure GetAdjustedLogicalClientRect();

  

Returns the adjusted ClientRect, using the cached value if available.

  procedure AlignControls(); virtual;

  

Aligns all child controls.

  function CustomAlignInsertBefore(); virtual;

  

Returns the placement order of custom-aligned child controls, using the OnAlignInsertBefore handler.

  procedure CustomAlignPosition(); virtual;

  

Returns the aligned position for a custom-aligned child control, using the OnAlignPosition handler.

  function DoAlignChildControls(); virtual;

  

Override this method to position/align all given controls.

  procedure DoChildSizingChange(); virtual;

  

Called after a change in ChildSizing information to trigger further processing.

  procedure InvalidatePreferredChildSizes;

  

Flags the preferred sizes of all child controls as invalid (recursively).

  function CanTab; override;

  

Indicates whether the Tab key can be used for keyboard navigation in the control.

  function IsClientHeightStored; override;

  

Implements the storage specifier for the ClientHeight property.

  function IsClientWidthStored; override;

  

Implements the storage specifier for the ClientWidth property.

  procedure DoSendShowHideToInterface; virtual;

  

Sends the new Visible state to the widgetset.

  procedure ControlsAligned; virtual;

  

Called by AlignControls after aligning controls.

  procedure DoSendBoundsToInterface; virtual;

  

Sends the control's new bounds to the widget.

  procedure RealizeBounds; virtual;

  

Checks for changes in BoundsRect, and sends the new bounds to the widget using DoSendBoundsToInterface.

  procedure RealizeBoundsRecursive;

  

Sends changed BoundsRects to the widget, for this and all child controls.

  procedure InvalidateBoundsRealized;

  

Resets the bounds rectangle for the control.

  procedure CreateSubClass();

  

An empty implementation in the current LCL version.

  procedure DoConstraintsChange(); override;

  

Performs actions needed when value(s) in Constraints have been changed.

  procedure DoSetBounds(); override;

  

Updates the size and extent of the control and its ClientRect.

  procedure DoAutoSize; override;

  

Shrinks or enlarges the control to accommodate its children.

  procedure DoAllAutoSize; override;

  

Resizes and aligns the control and all of it children.

  procedure AllAutoSized; virtual;

  

Called by DoAllAutoSize after all bounds are computed.

  procedure CalculatePreferredSize(); override;

  

Override this method to return a different preferred height and/or width for auto-sizing.

  procedure GetPreferredSizeClientFrame(); virtual;

  

Calculates the width and height for the frame area around the control.

  procedure GetChildren(); override;

  

Calls the specified procedure for each child control owned by the control in Root.

  function ChildClassAllowed(); override;

  

Returns True if the specified class is allowed in child controls.

  procedure PaintControls();

  

Paints all child controls which do not have a Handle.

  procedure PaintHandler();

  

Handler for TLMPaint, manages the painting of child controls.

  procedure PaintWindow(); virtual;

  

Paints a clipped portion (child control) on the specified device context.

  procedure CreateBrush; virtual;

  

Creates the Brush, if not already created.

  procedure ScaleControls(); virtual;

  

Scales (resizes) all child controls.

  procedure ChangeScale(); override;

  

Scales (resizes) the control and all of its child controls.

  procedure CMBiDiModeChanged(); message;

  

Handler for a changed BiDiMode message; notifies the widget and all child controls.

  procedure CMBorderChanged(); message;

  

Handler for changed Border property messages; adjusts and invalidates the control.

  procedure CMDoubleBufferedChanged(); message;

  

Handler for changes to the DoubleBuffered property.

  procedure CMEnabledChanged(); message;

  

Handler for changed Enabled message; notifies the widgetset.

  procedure CMParentDoubleBufferedChanged(); message;

  

Handles the CM_PARENTDOUBLEBUFFEREDCHANGED control message for the control (when enabled).

  procedure CMShowingChanged(); message;

  

Handler for changed Showing message; notifies the widgetset.

  procedure CMShowHintChanged(); message;

  

Handler for changed ShowHint message; notifies all child controls.

  procedure CMVisibleChanged(); message;

  

Handles Focus changes, and forces UpdateControlState.

  procedure CMEnter(); message;

  

Handles the CM_ENTER control message for the control.

  procedure CMExit(); message;

  

Handles the CM_EXIT control message for the control.

  procedure WMContextMenu(); message;

  

Handler for an ContextMenu event; eventually delegates handling to the affected child control.

  procedure WMEraseBkgnd(); message;

  

Erases the background, when required.

  procedure WMNotify(); message;

  

Handles (dispatches) notification messages.

  procedure WMSetFocus(); message;

  

Handler for receiving Focus event.

  procedure WMKillFocus(); message;

  

Handles the LM_KILLFOCUS message for the control.

  procedure WMShowWindow(); message;

  

Handler for changed visibility notification.

  procedure WMEnter(); message;

  

Handles the LM_ENTER message for the control.

  procedure WMExit(); message;

  

Handles the LM_EXIT message for the control.

  procedure WMKeyDown(); message;

  

Event handler for a key press not handled by the widget; Tries TWinControl.DoRemainingKeyDown

  procedure WMSysKeyDown(); message;

  

Event handler for system key presses not handled by the widget; tries TWinControl.DoRemainingKeyDown

  procedure WMKeyUp(); message;

  

Event handler for key released, not handled by the widget. Tries TWinControl.DoRemainingKeyUp.

  procedure WMSysKeyUp(); message;

  

Event handler for system key releases not handled by the widget; tries TWinControl.DoRemainingKeyUp

  procedure WMChar(); message;

  

Handler for messages sent by the widget, after it has handled the key press itself.

  procedure WMSysChar(); message;

  

Handler for messages sent by the widget, after it has handled the key press itself.

  procedure WMPaint(); message;

  

Manages paint requests, and handles double buffering.

  procedure WMDestroy(); message;

  

Handler for widget destroyed message; clears the Handle.

  procedure WMMove(); message;

  

Handler for widget moved message; updates the Bounds.

  procedure WMSize(); message;

  

Event handler for size messages.

  procedure WMWindowPosChanged(); message;

  

Event handler for size/move messages.

  procedure CNKeyDown(); message;

  

Handler for a key pushed notification; the message is handled by DoKeyDownBeforeInterface by default.

  procedure CNSysKeyDown(); message;

  

Handler for a system key pushed notification; the message is handled by DoKeyDownBeforeInterface by default.

  procedure CNKeyUp(); message;

  

Handler for a key released notification; the message is handled by DoKeyUpBeforeInterface by default.

  procedure CNSysKeyUp(); message;

  

Handler for a system key released notification; the message is handled by DoKeyUpBeforeInterface by default.

  procedure CNChar(); message;

  

Handler for a key pressed notification; CNChar is sent by the widget before it has handled the key press itself.

  function DoDragMsg(); override;

  

Dispatches a drag message, sent by the DragManager.

  function DoDockClientMsg(); virtual;

  

Handles a dmDragDock message, when a control has been docked to this site.

  function DoUndockClientMsg(); virtual;

  

Notifies the DockManager of the undock of a client control.

  procedure DoAddDockClient(); virtual;

  

Adjust the Parent of a newly docked Client.

  procedure DockOver(); virtual;

  

Called to check whether this control allows docking and where.

  procedure DoDockOver(); virtual;

  

Invoke the OnDockOver handler.

  procedure DoRemoveDockClient(); virtual;

  

Override this method to take special actions on removal of an docked client.

  function DoUnDock(); virtual;

  

Notifies an OnUnDock handler and the DockManager of an undocked client control.

  procedure GetSiteInfo(); virtual;

  

Return information about this dock site (InfluenceRect).

  function GetParentHandle;

  

Gets the handle for the Parent control.

  function GetTopParentHandle;

  

Gets the window handle for the parent control at the top of the control hierarchy.

  procedure ReloadDockedControl(); virtual;

  

Returns the docked control of the specified name.

  function CreateDockManager; virtual;

  

Returns the DockManager for this control.

  procedure SetDockManager();

  

Sets the value for the DockManager property.

  procedure DoFloatMsg(); override;

  

Handler called when the control starts floating.

  procedure DoGetDockCaption(); virtual;

  

Returns the dock caption in AControl.

  procedure DoEnter; virtual;

  

Invokes the OnEnter event handler.

  procedure DoExit; virtual;

  

Invoke the OnExit event handler.

  function DoKeyDownBeforeInterface();

  

Handles a KeyDown event before the widget processes the key.

  function DoRemainingKeyDown();

  

Handles key down messages which are not handled by the widget.

  function DoRemainingKeyUp();

  

Handles key up messages which are not handled by the widget.

  function DoKeyPress();

  

Tries all OnKeyPress handlers; the Parent OnKeyPress handler is tried first.

  function DoUTF8KeyPress(); virtual;

  

Tries all OnUTF8KeyPress handlers; the Parent OnUTF8KeyPress handler is tried first.

  function DoKeyUpBeforeInterface();

  

Handles a KeyUp event before the widget processes the key.

  function ChildKey(); virtual;

  

Applies the key message using ChildKey in the parent control.

  function SendDialogChar();

  

Forwards the key message to the parent form to be handled as an accelerator (shortcut) key.

  function DialogChar(); override;

  

Performs actions needed to handle an accelerator key for the control.

  procedure ControlKeyDown(); virtual;

  

Lets the Application handle an navigation key.

  procedure ControlKeyUp(); virtual;

  

Lets the Application handle an navigation key.

  procedure KeyDown(); virtual;

  

Invokes the OnKeyDown handler.

  procedure KeyDownBeforeInterface(); virtual;

  

Invokes the OnKeyDown handler.

  procedure KeyDownAfterInterface(); virtual;

  

An empty implementation in the current LCL version.

  procedure KeyPress(); virtual;

  

Invokes the OnKeyPress handler.

  procedure KeyUp(); virtual;

  

Invokes the OnKeyUp handler.

  procedure KeyUpBeforeInterface(); virtual;

  

Invokes the OnKeyUp handler.

  procedure KeyUpAfterInterface(); virtual;

  

An empty implementation in the current LCL version.

  procedure UTF8KeyPress(); virtual;

  

Invokes the OnUTF8KeyPress handler.

  function FindNextControl();

  

Returns the preceding or next control in the tab order.

  procedure SelectFirst;

  

Returns the first control in tab order.

  function RealGetText; override;

  

Returns the Caption property.

  function GetBorderStyle;

  

Gets the value for the BorderStyle property.

  function GetClientOrigin; override;

  

Gets the top, left screen coordinates for the client area in the control.

  function GetClientRect; override;

  

Gets the value for the ClientRect property.

  function GetControlOrigin; override;

  

The screen coordinates for the control.

  function GetDeviceContext(); override;

  

Returns a device context handle for the control, from Parent.

  function GetParentBackground;

  

Gets the value for the ParentBackground property.

  function IsControlMouseMsg();

  

Sends the mouse message to a child control.

  procedure CreateHandle; virtual;

  

Creates the Handle for the widget, if not already created.

  procedure CreateParams(); virtual;

  

Initializes the window creation parameter record with the settings for the control.

  procedure CreateWnd; virtual;

  

Creates the interface object (widget) and assigns the value in Handle.

  procedure DestroyHandle; virtual;

  

Destroys the handle for the control and all child controls.

  procedure DestroyWnd; virtual;

  

Destroys the interface object (widget).

  procedure DoFlipChildren; virtual;

  

Flip children horizontally (mirrors the Left position).

  procedure FinalizeWnd; virtual;

  

Prepares to remove the window (called before the Handle is destroyed).

  procedure FixupTabList;

  

Assigns sequential TabOrder values to all child controls.

  procedure FontChanged(); override;

  

Implements the event handler signalled when the Font has been changed for the control.

  procedure InitializeWnd; virtual;

  

Copies cached control properties to the just created widget.

  procedure Loaded; override;

  

Called when the control has been loaded from a resource, transfers the loaded property values to the widget.

  procedure FormEndUpdated; override;

  

Realizes all cached changes after a bulk update of the form. Calls inherited FormEndUpdated, then informs each child control.

  procedure MainWndProc();

  

This method allows handling messages in Windows.

  procedure ParentFormHandleInitialized; override;

  

Called after all child handles for the ParentForm are created; notifies all children of the end of the handle creation phase.

  procedure ChildHandlesCreated; virtual;

  

Called after all child handles have been created; resets wcfCreatingChildHandles.

  function GetMouseCapture; override;

  

Gets the value for the MouseCapture property.

  procedure RealSetText(); override;

  

Sets the text / caption for the control.

  procedure RemoveFocus();

  

Notifies the parent when the control loses focus.

  procedure SendMoveSizeMessages(); override;

  

Sends Move and Size messages through the LCL message paths.

  procedure SetBorderStyle(); virtual;

  

Indicates if borders are displayed around the control.

  procedure SetColor(); override;

  

Sets the value for the Color property.

  procedure SetChildZPosition();

  

Updates the position of the child control in the Z plane (i.e. front-to-back).

  procedure SetParentBackground(); virtual;

  

Sets the value for the ParentBackground property.

  procedure ShowControl(); virtual;

  

Asks the parent to show itself.

  procedure UpdateControlState;

  

Updates the visible state for the control; updates the widget set class when already created.

  procedure UpdateShowing; virtual;

  

When the widget should be visible and has not yet been created, it's created along with all children.

  procedure WndProc(); override;

  

Adds special handling for focus and input messages, and notifies the DockManager.

  procedure WSSetText(); virtual;

  

Sends text to the widget (from WM_SETTEXT?).

  property WindowHandle: HWND; [rw]

  

For internal use; allows direct access to the Handle for the control, bypassing any getter/setter methods.

  property BorderStyle: TBorderStyle; [rw]

  

Indicates if borders are displayed around the control.

  property OnGetSiteInfo: TGetSiteInfoEvent; [rw]

  

Provides information about the DockSite for the control.

  property OnGetDockCaption: TGetDockCaptionEvent; [rw]

  

This handler can provide a special DockCaption, different than the Caption default.

  property ParentBackground: Boolean; [rw]

  

Indicates if the control uses the background for its Parent control.

public

  property BorderWidth: TBorderWidth; [rw]

  

Width of the Border around the control; default is zero.

  property BoundsLockCount: Integer; [r]

  

For internal use: When greater zero, updates of the BoundsRect are blocked.

  property Brush: TBrush; [r]

  

The Brush used to paint the background of the control.

  property CachedClientHeight: Integer; [r]

  

The intended ClientHeight, as sent to the widget set class.

  property CachedClientWidth: Integer; [r]

  

The intended ClientWidth, as sent to the widget set class.

  property ChildSizing: TControlChildSizing; [rw]

  

Parameters for child control arrangement and spacing.

  property ControlCount: Integer; [r]

  

The number of child controls in the Controls property.

  property Controls []: TControl; [r]

  

Provides indexed access to the child controls for the class instance.

  property DefWndProc: Pointer; [rw]

  

The default WndProc on Windows widgetset and platforms.

  property DockClientCount: Integer; [r]

  

The number of clients docked into this control.

  property DockClients []: TControl; [r]

  

The indexed list of controls docked into this control.

  property DockManager: TDockManager; [rw]

  

The docking layout manager for this control.

  property DockSite: Boolean; [rw]

  

Allows controls to be drag-dock'd into this control.

  property DoubleBuffered: Boolean; [rws]

  

Allows to reduce flicker in the painting of the control.

  property Handle: HWND; [rw]

  

A reference to the widgetset class instance associated with this control.

  property IsFlipped: Boolean; [r]

  

Used in Carbon and Cocoa widgetsets

  property IsResizing: Boolean; [r]

  

Check IsResizing and drop or delay changes to the control, until the new size has been determined.

  property TabOrder: TTabOrder; [rw]

  

Determines the sequence of control navigation when the user presses the Tab key.

  property TabStop: Boolean; [rw]

  

Allows the user to navigate to this control, by pressing the Tab key.

  property OnAlignInsertBefore: TAlignInsertBeforeEvent; [rw]

  

Handler for custom-aligned child controls; determines the order of control placement.

  property OnAlignPosition: TAlignPositionEvent; [rw]

  

Handler for custom-aligned child controls, determines the position of the child control.

  property OnDockDrop: TDockDropEvent; [rw]

  

Notification handler for the drop of a control to be docked.

  property OnDockOver: TDockOverEvent; [rw]

  

Event handler for moves of a control over this docksite; determines acceptance or rejection of an possible drop.

  property OnEnter: TNotifyEvent; [rw]

  

Handler for control receiving the focus.

  property OnExit: TNotifyEvent; [rw]

  

Handler for control loosing the focus; This is a good place for checking the finished user input.

  property OnKeyDown: TKeyEvent; [rw]

  

Handler for keyboard key pressed.

  property OnKeyPress: TKeyPressEvent; [rw]

  

Handler for a character entered by the user.

  property OnKeyUp: TKeyEvent; [rw]

  

Handler for keyboard key released.

  property OnUnDock: TUnDockEvent; [rw]

  

Event handler for control being undocked from this DockSite.

  property OnUTF8KeyPress: TUTF8KeyPressEvent; [rw]

  

Handler for a character entered by the user.

  property ParentDoubleBuffered: Boolean; [rw]

  

Value from the DoubleBuffered property in a Parent control.

  property ParentWindow: HWND; [rw]

  

The Handle for the parent widget.

  property Showing: Boolean; [r]

  

Cached widget visibility, not necessarily in sync with the widget.

  property UseDockManager: Boolean; [rw]

  

Determines whether a DockManager is used for this DockSite.

  property DesignerDeleting: Boolean; [w]

  

Indicates whether the wcfDesignerDeleting flag is included in the flags for the control.

  property IsSpecialSubControl: Boolean; [r]

  

Indicates if the control has the wcfSpecialSubControl control flag.

  property VisibleDockClientCount: Integer; [r]

  

The number of visible docked controls.

  function AutoSizePhases; override;

  

Translates state flags into AutoSizePhases.

  function AutoSizeDelayed; override;

  

Returns true if auto-sizing must be has been delayed, until some other process is complete.

  function AutoSizeDelayedReport; override;

  

Returns a string with a debugging message for delayed auto-size requests.

  function AutoSizeDelayedHandle; override;

  

Returns true if AutoSize should be skipped / delayed because of its handle.

  procedure BeginUpdateBounds;

  

Starts an update to the Bounds property; disables SetBounds by incrementing BoundsLockCount.

  procedure EndUpdateBounds;

  

Ends an update to the Bounds property; decrements BoundsLockCount and eventually calls SetBounds.

  procedure LockRealizeBounds;

  

Disables sending bounds to the widget, by incrementing the internal FRealizeBoundsLockCount.

  procedure UnlockRealizeBounds;

  

Enables sending bounds to the widget again, eventually updates the widget.

  function ControlAtPos();

  

Get the child control at the given client position.

  function ContainsControl();

  

Returns True if this is a parent for the given control.

  procedure DoAdjustClientRectChange();

  

Asks the widget if ClientRect has changed since the last AlignControl execution; calls AdjustSize on change.

  procedure InvalidateClientRectCache();

  

The ClientRect is cached; call this procedure to invalidate the cache, so that the next ClientRect value is fetched from the widget set class.

  function ClientRectNeedsInterfaceUpdate;

  

The ClientRect is cached - check if the cache is valid.

  procedure SetBounds(); override;

  

Sets the control bounds and adjusts child and docked controls.

  function GetChildrenRect(); override;

  

Returns the Client rectangle relative to the controls left, top.

  procedure DisableAlign;

  

Disables auto-sizing for the control and its parent.

  procedure EnableAlign;

  

Re-enables auto-sizing for the control and its parent.

  procedure ReAlign;

  

Adjusts the size and placement for the control and all of its children.

  procedure ScrollBy_WS();

  

Scrolls the control using the handle for the widget set class.

  procedure ScrollBy(); virtual;

  

Scrolls the control (and all child controls) by the specified amounts.

  procedure WriteLayoutDebugReport(); override;

  

Used for debugging.

  procedure AutoAdjustLayout(); override;

  

Automatically adjusts the size and layout for the control (and all of its children).

  procedure FixDesignFontsPPIWithChildren();

  

Fixes the design-time PPI settings for the control font, and applies the changes to child controls.

  constructor Create(); override;

  

Constructor for the class instance.

  constructor CreateParented();

  

Constructor for a control that is the child of the given widget.

  class function CreateParentedControl();

  

Constructor for a control that is the child of the given widget.

  destructor Destroy; override;

  

Destructor for the class instance.

  procedure DockDrop(); virtual;

  

Handler for a DragManager dmDragDrop message, sent when a dragged control has been dropped onto this docksite.

  function CanFocus; virtual;

  

Is this control allowed to receive the focus when parent form is visible?

  function CanSetFocus; virtual;

  

Is this control allowed to receive the focus?

  function GetControlIndex();

  

Finds the index value for the given control, in TWinControl.Controls

  procedure SetControlIndex();

  

Updates the position of the child control in the Z plane (i.e. front-to-back).

  function Focused; virtual;

  

Checks whether the control has focus.

  function PerformTab(); virtual;

  

Sets the focus to the next (or preceding) control.

  function FindChildControl();

  

Finds a child control by name.

  procedure SelectNext();

  

Transfers the focus to the next child control.

  procedure SetTempCursor(); override;

  

Changes the cursor shape temporarily, preserving the original TControl.Cursor

  procedure BroadCast();

  

Posts the specified message to all of the child controls.

  procedure NotifyControls();

  

Sends a message to all child controls.

  procedure DefaultHandler(); override;

  

Handles all messages that the control doesn't fully handle itself.

  function GetTextLen; override;

  

The length of Text, here: of Caption.

  procedure Invalidate; override;

  

Schedules a repaint request.

  procedure AddControl; virtual;

  

Tells the widgetset to add a Handle object to a parent Handle object.

  procedure InsertControl();

  

Inserts the specified control into the Controls property.

  procedure RemoveControl(); virtual;

  

Removes the specified control from the Controls property.

  function GetEnumeratorControls;

  

Gets an enumerator for the Controls property.

  function GetEnumeratorControlsReverse;

  

Gets a reverse-order enumerator for the Controls property.

  procedure Repaint; override;

  

Immediately redraws the control when visible, bypassing the message queue.

  procedure Update; override;

  

Redraw invalidated parts of the control immediately.

  procedure SetFocus; virtual;

  

Ensures that the control or window handle has focus.

  procedure FlipChildren(); virtual;

  

Flip children horizontally. That means mirroring the Left position and anchoring.

  procedure ScaleBy();

  

Scales (resizes) the control and all of its child controls.

  function GetDockCaption(); virtual;

  

Returns the caption for the docked control.

  procedure UpdateDockCaption(); virtual;

  

Updates the Caption to reflect the names of the docked clients.

  procedure GetTabOrderList(); virtual;

  

Fill the list with all TabStop controls, recursing into child controls.

  function HandleAllocated;

  

Check whether a widget has been assigned to this control.

  function ParentHandlesAllocated; override;

  

Returns True if all Parents have handles allocated, and are not being destroyed.

  procedure HandleNeeded;

  

Call this method when your code requires a valid Handle for this control.

  function BrushCreated;

  

Has a Brush been created for this control?

  procedure EraseBackground(); virtual;

  

Fills the display rectangle for the control with the color and pattern in Brush.

  function IntfUTF8KeyPress(); virtual;

  

Called by the interface after the navigation and specials keys are handled; i.e. after KeyDown but before KeyPress.

  function IntfGetDropFilesTarget; virtual;

  

Searches for a Parent form that can be used as a file drop target.

  procedure PaintTo();

  

Paints the control using the handle for the widget set class.

  procedure SetShape();

  

Specifies the non-rectangular shape of the widget.

end;

Inheritance

TWinControl

  

The base class for controls which can contain other (child) controls.

|

TControl

  

The base class for visible controls.

|

TLCLComponent

  

The base class for LCL components which have an associated widget.

|

TComponent

?

TObject

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.

The latest version of this document can be found at lazarus-ccr.sourceforge.net.