[Previous][Up] Reference for unit 'Controls' (#lcl)

AutoSize - boolean property that permits the size of a control to be adjusted automatically.

AutoSize is a boolean property found in many classes; it permits the size of a control to be adjusted automatically to accommodate differences in the text or graphic contained therein, and allows most efficient use of available space

Many controls call TControl.DoAutoSize to perform the actual auto-sizing.

IMPORTANT: Many Delphi controls override this method and many call this method directly after setting some properties.

During handle creation not all interfaces can create complete Device Contexts which are needed to calculate things like text size.

That's why you should always call AdjustSize instead of DoAutoSize.

TControl.AdjustSize calls DoAutoSize in a smart fashion.

During loading and handle creation the calls are delayed.

This method is essentially the same as TWinControl.DoAutoSize. But since DoAutoSize is commonly overridden in descendent components, it is not useful to perform all tests, which can result in too much overhead. To reduce the overhead, the LCL calls AdjustSize instead.

When setting AutoSize to True, the LCL auto-sizes the width and height for the control. This is one of the most complex parts of the LCL, because the result depends on nearly a hundred properties. Let's start with a simple scenario:

The LCL will only auto-size the Width or Height if it is free to resize. In other words, the width is not auto-sized if:

The new size is calculated by the protected method TControl.CalculatePreferredSize. This method asks the widgetset for an appropriate Width and Height. For example a TButton has preferred Width and Height. A TComboBox has only a preferred Height. The preferred Width is returned as 0 and so the LCL does not auto-size the Width - it keeps the width unaltered. Finally a TMemo has no preferred Width or Height. Therefore AutoSize has no effect on a TMemo.

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 widgetsets must override the GetPreferredSize method for each widget class that has a preferred size (Width or Height or both).

Parent.AutoSize

The above described the simple explanation. The real algorithm provides far more possibilities and is therefore far more complex.

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 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.

During resizing, or when moving, the Left and Top coordinates are not always in sync with the coordinates for the Handle object.

When Parent is unassigned (contains Nil), Left and Top depend on the widgetset and the window manager. Until Lazarus 0.9.25, this is typically the screen coordinate of the left, top of the client area for the form. This is Delphi incompatible. It is planned to change this to the Left, Top of the window.

Hint:

Each time you change Left and Top, the LCL starts the movement instantly. If you want to change both Left and Top, use the following instead:

with Button1 do
    SetBounds(NewLeft,NewTop,Width,Height);

Width and Height

The Size in pixels must not be negative; most widgetsets do not allow Width and/or Height to be Zero (0). Some controls (on some platforms )define a larger minimum constraint. Instead of sizing a control to Width=0 and/or Height=0, set Visible to False. During resizing and moving, Width and Height are not always in sync with the size of the Handle object.

BoundsRect

Same as Bounds(Left,Top,Width,Height).

Common newbie mistake:

BoundsRect.Left:=3; // WRONG: common newbie mistake

This has no effect, because reading BoundsRect is a function. It creates a temporary TRect on the stack.

ClientRect

Left and Top are always 0,0. Width and Height are the visible size in pixels of the client area. Remember the client area is without the frame and without scrollbars. In a scrollable client area the logical client area can be bigger than the visible.

ClientOrigin

Returns the screen coordinate of the top left coordinate 0,0 of the client area. 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 desired position and sends a move message to the interface. It is up to the interface to handle moves instantly or queued.

LCLIntf.GetClientBounds

Returns the client bounds of a control. Like ClientRect, but Left and Top are the pixel distances to the control's left, top. For example on a TGroupBox the Left, Top are the width and height of the left and top frame border. Scrolling has no effect on GetClientBounds.

LCLIntf.GetWindowRect

After the call, ARect will be the control area in screen coordinates. That means, Left and Top will be the screen coordinate of the TopLeft pixel of the Handle object and Right and Bottom will be the screen coordinate of the BottomRight pixel.

FBaseBoundsLock: integer

Increased/Decreased by LockBaseBounds/UnlockBaseBounds. Used to keep FBaseBounds during SetBounds calls.

FBaseParentClientSize: TPoint

The Parent.ClientRect size valid for the FBaseBounds. FBaseBounds and FBaseParentClientSize are used to calculate the distance for akRight (akBottom). When the parent is resized, the LCL knows what distance to keep.

FBoundsRectForNewParent: TRect

When changing the Parent of a control the Handle is recreated and many things can happen. Especially for docking forms the process is too unreliable. Therefore the BoundsRect is saved. The VCL uses a similar mechanism.

FLastDoChangeBounds: TRect

Used to avoid calling OnChangeBounds with the same coordinates. This reduces user defined auto-sizing.

FLastResizeClientHeight: integer
FLastResizeClientWidth: integer
FLastResizeHeight: integer
FLastResizeWidth: integer

Used to avoid calling OnResize with the same coordinates. This reduces user defined auto-sizing.

FLoadedClientSize: TPoint

During loading many things are delayed and many things are set and worse: in the wrong order. That's why SetClientWidth/SetClientHeight calls are stored and set at end of loading again. This way the LCL can restore the distances (e.g. akRight) used during designing.

FReadBounds: TRect

Same as FLoadedClientSize, but for SetLeft, SetTop, SetWidth, SetHeight.

SetBoundsRectForNewParent(const AValue: TRect);

Used to set FBoundsRectForNewParent. See above.

procedure SetInitialBounds(aLeft, aTop, aWidth, aHeight: integer); virtual;

A smart version of SetBounds, reducing overhead during creation and loading.

procedure UpdateBaseBounds(StoreBounds, StoreParentClientSize, UseLoadedValues: boolean); virtual;

Commit current bounds to base bounds.

procedure SetClientHeight(Value: Integer);
procedure SetClientSize(Value: TPoint);
procedure SetClientWidth(Value: Integer);

Exists for Delphi compatibility too. Resizes the control, to get the wanted ClientRect size.

procedure ChangeBounds(ALeft, ATop, AWidth, AHeight: integer); virtual;

This is the internal SetBounds. Applies constraints, updates base bounds, calls OnChangeBound, OnResize, locks bounds.

procedure DoSetBounds(ALeft, ATop, AWidth, AHeight: integer); virtual;

This really sets the FLeft, FTop, FWidth, FHeight private variables.

procedure SetBounds(aLeft, aTop, aWidth, aHeight: integer); virtual;

This is the standard procedure overridden by many Delphi controls. TWinControl overrides it too. Ignores calls when bounds are locked; lock the FBoundsRealized to avoid overhead to the interface during auto sizing. ChangeBounds is not locked this way.

Function GetClientOrigin: TPoint; virtual;

Screen coordinate of Left, Top of client area.

Function GetClientRect: TRect; virtual;

Size of client area. (always Left=0, Top=0)

Function GetScrolledClientRect: TRect; virtual;

Visible client area in ClientRect.

function GetChildsRect(Scrolled: boolean): TRect; virtual;

Returns the Client rectangle relative to the control's Left, Top. If Scrolled is True, the rectangle is moved by the current scrolling values (for an example see TScrollingWincontrol).

function GetClientScrollOffset: TPoint; virtual;

Returns the scrolling offset of the client area.

function GetControlOrigin: TPoint; virtual;

Returns the screen coordinate of the topleft coordinate 0,0 of the control area. (The topleft 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 queued.


Version 3.2 Generated 2024-02-25 Home