Class TCastleUserInterface

Unit

Declaration

type TCastleUserInterface = class(TInputListener)

Description

Basic user-interface class. All controls derive from this class, overriding chosen methods to react to some events.

Every control can have children controls, see Controls and ControlsCount. Parent control is recorded inside the Parent. A control may only be a child of one other control — that is, you cannot insert to the UI hierarchy the same control multiple times.

Control may handle mouse/keyboard input, see Press and Release methods.

Various methods return boolean saying if input event is handled. The idea is that not handled events are passed to the next control suitable. Handled events are generally not processed more — otherwise the same event could be handled by more than one listener, which is bad. Generally, return ExclusiveEvents if anything (possibly) was done (you changed any field value etc.) as a result of this, and only return False when you're absolutely sure that nothing was done by this control.

Every control also has a position and size and takes some rectangular space on the container.

The position is controlled using the Anchor methods or anchor properties, like HorizontalAnchorSelf, HorizontalAnchorParent, HorizontalAnchorDelta. The size is controlled using the Width, WidthFraction, Height, HeightFraction, FullSize, or AutoSizeToChildren properties.

The size (before UI scaling is applied) can be queried using EffectiveWidth and EffectiveHeight methods. The rectangle where the control is visible (during rendering, after applying UI scaling) can be queried using RenderRect and RenderRectWithBorder methods.

Note that some descendants perform auto-sizing, that is: their effective size follows some natural property of the control. For example, TCastleLabel size by default follows the TCastleLabel.Caption value, and ignores the explicit size set in Width and Height. You can turn off auto-sizing by TCastleLabel.AutoSize, to manually control the size using Width and Height.

All the coordinates passed here should follow the Castle Game Engine convention that (0, 0) is left-bottom window corner.

Hierarchy

Overview

Fields

Public nested const DefaultWidth = 100.0;
Public nested const DefaultHeight = 100.0;

Methods

Protected procedure DefineProperties(Filer: TFiler); override;
Protected procedure SetContainer(const Value: TUIContainer); override;
Protected procedure UIScaleChanged; virtual;
Protected procedure GetChildren(Proc: TGetChildProc; Root: TComponent); override;
Protected procedure PreferredSize(var PreferredWidth, PreferredHeight: Single); virtual;
Protected function EffectiveWidthForChildren: Single;
Protected function EffectiveHeightForChildren: Single;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure VisibleChange(const Changes: TCastleUserInterfaceChanges; const ChangeInitiatedByChildren: boolean = false); override;
Public procedure SetTransient;
Public function ControlsCount: Integer;
Public procedure InsertFront(const NewItem: TCastleUserInterface); overload;
Public procedure InsertFrontIfNotExists(const NewItem: TCastleUserInterface);
Public procedure InsertFront(const NewItems: TCastleUserInterfaceList); overload;
Public procedure InsertBack(const NewItem: TCastleUserInterface); overload;
Public procedure InsertBackIfNotExists(const NewItem: TCastleUserInterface);
Public procedure InsertBack(const NewItems: TCastleUserInterfaceList); overload;
Public procedure InsertControl(const Index: Integer; const NewItem: TCastleUserInterface);
Public procedure RemoveControl(const Item: TCastleUserInterface);
Public function IndexOfControl(const Item: TCastleUserInterface): Integer;
Public procedure ClearControls;
Public function GetExists: boolean; virtual;
Public function CapturesEventsAtPosition(const Position: TVector2): boolean; virtual;
Public procedure BeforeRender; virtual;
Public procedure Render; virtual;
Public procedure RenderOverChildren; virtual;
Public function TooltipExists: boolean; virtual;
Public procedure TooltipRender; virtual;
Public procedure GLContextOpen; virtual;
Public procedure GLContextClose; virtual;
Public procedure SetFocused(const Value: boolean); virtual;
Public function Rect: TFloatRectangle; virtual; deprecated 'instead of using this, use EffectiveRect or RenderRect depending on the situation; instead of overriding this, override PreferredSize';
Public function EffectiveRect: TFloatRectangle;
Public function EffectiveWidth: Single;
Public function EffectiveHeight: Single;
Public function CalculatedWidth: Cardinal; deprecated 'use EffectiveWidth';
Public function CalculatedHeight: Cardinal; deprecated 'use EffectiveHeight';
Public function CalculatedRect: TRectangle; deprecated 'use EffectiveRect';
Public function RenderRect: TFloatRectangle;
Public function RenderRectWithBorder: TFloatRectangle;
Public function ScreenRect: TRectangle; deprecated 'use RenderRect';
Public function LocalToScreenTranslation: TVector2;
Public function ParentRect: TFloatRectangle;
Public procedure Anchor(const AHorizontalAnchor: THorizontalPosition; const AHorizontalAnchorDelta: Single = 0); overload;
Public procedure Anchor( const AHorizontalAnchorSelf, AHorizontalAnchorParent: THorizontalPosition; const AHorizontalAnchorDelta: Single = 0); overload;
Public procedure Anchor(const AVerticalAnchor: TVerticalPosition; const AVerticalAnchorDelta: Single = 0); overload;
Public procedure Anchor( const AVerticalAnchorSelf, AVerticalAnchorParent: TVerticalPosition; const AVerticalAnchorDelta: Single = 0); overload;
Public procedure AlignHorizontal( const ControlPosition: TPositionRelative = prMiddle; const ContainerPosition: TPositionRelative = prMiddle; const X: Single = 0); deprecated 'use Align or Anchor';
Public procedure Align( const ControlPosition: THorizontalPosition; const ContainerPosition: THorizontalPosition; const X: Single = 0); overload;
Public procedure AlignVertical( const ControlPosition: TPositionRelative = prMiddle; const ContainerPosition: TPositionRelative = prMiddle; const Y: Single = 0); deprecated 'use Align or Anchor';
Public procedure Align( const ControlPosition: TVerticalPosition; const ContainerPosition: TVerticalPosition; const Y: Single = 0); overload;
Public procedure Center;
Public procedure EditorAllowResize(out ResizeWidth, ResizeHeight: Boolean; out Reason: String); virtual;

Properties

Public property Controls [Index:Integer]: TCastleUserInterface read GetControls write SetControls;
Public property GLInitialized: boolean read FGLInitialized default false;
Public property DisableContextOpenClose: Cardinal read FDisableContextOpenClose write FDisableContextOpenClose;
Public property Focused: boolean read FFocused write SetFocused;
Public property Parent: TCastleUserInterface read FParent;
Public property UIScale: Single read FLastSeenUIScale;
Public property FloatWidth: Single read FWidth write SetWidth stored false; deprecated 'use Width';
Public property FloatHeight: Single read FHeight write SetHeight stored false; deprecated 'use Height';
Public property KeepInFront: boolean read FKeepInFront write FKeepInFront default false;
Public property BorderColor: TCastleColor read FBorderColor write SetBorderColor;
Public property HasHorizontalAnchor: boolean read FHasHorizontalAnchor write FHasHorizontalAnchor stored false; deprecated 'this property does not do anything anymore, anchors are always active';
Public property HasVerticalAnchor: boolean read FHasVerticalAnchor write FHasVerticalAnchor stored false; deprecated 'this property does not do anything anymore, anchors are always active';
Public property Visible: Boolean read FVisible;
Published property OnRender: TUiNotifyEvent read FOnRender write FOnRender;
Published property Exists: boolean read FExists write SetExists default true;
Published property Left: Single read FLeft write SetLeft stored false default 0;
Published property Bottom: Single read FBottom write SetBottom default 0;
Published property FullSize: boolean read FFullSize write SetFullSize default false;
Published property Width: Single read FWidth write SetWidth default DefaultWidth;
Published property Height: Single read FHeight write SetHeight default DefaultHeight;
Published property WidthFraction: Single read FWidthFraction write SetWidthFraction default 0.0;
Published property HeightFraction: Single read FHeightFraction write SetHeightFraction default 0.0;
Published property AutoSizeToChildren: Boolean read FAutoSizeToChildren write SetAutoSizeToChildren default false;
Published property AutoSizeToChildrenPaddingRight: Single read FAutoSizeToChildrenPaddingRight write SetAutoSizeToChildrenPaddingRight default 0;
Published property AutoSizeToChildrenPaddingTop: Single read FAutoSizeToChildrenPaddingTop write SetAutoSizeToChildrenPaddingTop default 0;
Published property HorizontalAnchorSelf: THorizontalPosition read FHorizontalAnchorSelf write SetHorizontalAnchorSelf default hpLeft;
Published property HorizontalAnchorParent: THorizontalPosition read FHorizontalAnchorParent write SetHorizontalAnchorParent default hpLeft;
Published property HorizontalAnchorDelta: Single read FHorizontalAnchorDelta write SetHorizontalAnchorDelta default 0;
Published property VerticalAnchorSelf: TVerticalPosition read FVerticalAnchorSelf write SetVerticalAnchorSelf default vpBottom;
Published property VerticalAnchorParent: TVerticalPosition read FVerticalAnchorParent write SetVerticalAnchorParent default vpBottom;
Published property VerticalAnchorDelta: Single read FVerticalAnchorDelta write SetVerticalAnchorDelta default 0;
Published property EnableUIScaling: boolean read FEnableUIScaling write SetEnableUIScaling default true;
Published property CapturesEvents: boolean read FCapturesEvents write FCapturesEvents default true;
Published property Culling: Boolean read FCulling write SetCulling default false;
Published property ClipChildren: Boolean read FClipChildren write SetClipChildren default false;
Published property Border: TBorder read FBorder;
Published property BorderColorPersistent: TCastleColorPersistent read FBorderColorPersistent;

Description

Fields

Public nested const DefaultWidth = 100.0;
 
Public nested const DefaultHeight = 100.0;
 

Methods

Protected procedure DefineProperties(Filer: TFiler); override;
 
Protected procedure SetContainer(const Value: TUIContainer); override;
 
Protected procedure UIScaleChanged; virtual;
 
Protected procedure GetChildren(Proc: TGetChildProc; Root: TComponent); override;

procedure DoCursorChange; override;

Protected procedure PreferredSize(var PreferredWidth, PreferredHeight: Single); virtual;

Controls that have a preferred size should override this. By default this contains values derived from Width, WidthFraction, Height, HeightFraction, with Border subtracted.

Note that the arguments should be already scaled, i.e. multiplied by UIScale, i.e. expressed in final device pixels.

Note that the returned PreferredWidth and PreferredHeight must not include the space for Border. Border size will be added later.

Protected function EffectiveWidthForChildren: Single;

EffectiveWidth without Border size.

Protected function EffectiveHeightForChildren: Single;

EffectiveHeight without Border size.

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure VisibleChange(const Changes: TCastleUserInterfaceChanges; const ChangeInitiatedByChildren: boolean = false); override;
 
Public procedure SetTransient;

Ignore this component when serializing parent's Controls list, and do not show this component in CGE editor. This simply sets csTransient flag in ComponentStyle.

This is useful for children that are automatically managed by the parent, and should not be modified by user code. For example, TCastleCheckbox is internally composed from TCastleImageControl and TCastleLabel children, but we don't want to serialize or even show these children to user.

Note that if you want to prevent this component from serializing as part of Controls list, but you still want it to be visible in CGE editor, then make it a "subcomponent" instead, by SetSubComponent(true).

In any case (csSubComponent and/or csTransient) the component is just not serialized as part of parent's Controls list. But if you will make the component published (which is normal for "subcomponents") then it will be published, just as part of it's own property (like TCastleScrollView.ScrollArea). So to really avoid serializing the component, make it csSubComponent and/or csTransient, and do not publish it.

Public function ControlsCount: Integer;
 
Public procedure InsertFront(const NewItem: TCastleUserInterface); overload;

Add child control, at the front of other children.

Public procedure InsertFrontIfNotExists(const NewItem: TCastleUserInterface);
 
Public procedure InsertFront(const NewItems: TCastleUserInterfaceList); overload;
 
Public procedure InsertBack(const NewItem: TCastleUserInterface); overload;

Add child control, at the back of other children.

Public procedure InsertBackIfNotExists(const NewItem: TCastleUserInterface);
 
Public procedure InsertBack(const NewItems: TCastleUserInterfaceList); overload;
 
Public procedure InsertControl(const Index: Integer; const NewItem: TCastleUserInterface);

Add child control at specified position. It is usually easier to use InsertFront or InsertBack, if possible.

Public procedure RemoveControl(const Item: TCastleUserInterface);

Remove control added by InsertFront or InsertBack.

Public function IndexOfControl(const Item: TCastleUserInterface): Integer;

Index of child control, or -1 if not present.

Public procedure ClearControls;

Remove all child controls added by InsertFront or InsertBack.

Public function GetExists: boolean; virtual;

Return whether item really exists, see Exists. Non-existing item does not receive any of the render or input or update calls. They only receive GLContextOpen, GLContextClose, Resize calls.

It TCastleUserInterface class, this returns the value of Exists property. May be overridden in descendants, to return something more complicated, but it should always be a logical "and" with the inherited GetExists implementation (so setting the Exists := false will always work), like

Result := (inherited GetExists) and MyComplicatedConditionForExists;

Public function CapturesEventsAtPosition(const Position: TVector2): boolean; virtual;

Does this control capture events under this screen position. The default implementation simply checks whether Position is inside RenderRect. It also checks whether CapturesEvents is True.

Always treated like False when GetExists returns False, so the implementation of this method only needs to make checks assuming that GetExists = True.

Public procedure BeforeRender; virtual;

Prepare your resources, right before drawing. Called only when GetExists and GLInitialized.

Do not explicitly call this method. Instead, render controls by adding them to the TUIContainer.Controls list, or render them explicitly (for off-screen rendering) by TUIContainer.RenderControl.

Public procedure Render; virtual;

Render a control. Called only when GetExists and GLInitialized, you can depend on it in the implementation of this method.

Do not explicitly call this method. Instead, render controls by adding them to the TUIContainer.Controls list, or render them explicitly (for off-screen rendering) by TUIContainer.RenderControl. This is method should only be overridden in your own code.

Before calling this method we always set some OpenGL state, and you can depend on it (and you can carelessly change it, as it will be reset again before rendering other control).

OpenGL state always set:

  • Viewport is set to include whole container.

  • Depth test is off.

  • (For fixed-function pipeline:) The 2D orthographic projection is always set at the beginning. Useful for 2D controls, 3D controls can just override projection matrix, e.g. use CastleGLUtils.PerspectiveProjection.

  • (For fixed-function pipeline:) The modelview matrix is set to identity. The matrix mode is always modelview.

  • (For fixed-function pipeline:) The raster position is set to (0,0). The (deprecated) WindowPos is also set to (0,0).

  • (For fixed-function pipeline:) Texturing, lighting, fog is off.

Beware that GLSL TGLSLProgram.Current has undefined value when this is called. You should always set it, before making direct OpenGL drawing calls (all the engine drawing routines of course do it already, this is only a concern if you make direct OpenGL / OpenGLES calls).

Public procedure RenderOverChildren; virtual;

Render a control contents over the children controls. This is analogous to Render, but it executes after children are drawn. You should usually prefer to override Render instead of this method, as the convention is that the parent is underneath children.

Public function TooltipExists: boolean; virtual;

Render a tooltip of this control. If you want to have tooltip for this control detected, you have to override TooltipExists. Then the TCastleWindowCustom.TooltipVisible will be detected, and your TooltipRender will be called.

TooltipRender is called in the same way as Render, so e.g. you can safely assume that modelview matrix is identity and (for 2D) WindowPos is zero. TooltipRender is always called as a last (front-most) control.

Public procedure TooltipRender; virtual;
 
Public procedure GLContextOpen; virtual;

Initialize your OpenGL resources.

This is called when OpenGL context of the container is created, or when the control is added to the already existing context. In other words, this is the moment when you can initialize OpenGL resources, like display lists, VBOs, OpenGL texture names, etc.

As an exception, this is called regardless of the GetExists value. This way a control can prepare it's resources, regardless if it exists now.

Public procedure GLContextClose; virtual;

Destroy your OpenGL resources.

Called when OpenGL context of the container is destroyed. Also called when controls is removed from the container Controls list. Also called from the destructor.

You should release here any resources that are tied to the OpenGL context. In particular, the ones created in GLContextOpen.

As an exception, this is called regardless of the GetExists value. This way a control can release it's resources, regardless if it exists now.

Public procedure SetFocused(const Value: boolean); virtual;

Called when this control becomes or stops being focused, that is: under the mouse cursor and will receive events. In this class, they simply update Focused property. You can override this to react to mouse enter / mouse exit events.

Public function Rect: TFloatRectangle; virtual; deprecated 'instead of using this, use EffectiveRect or RenderRect depending on the situation; instead of overriding this, override PreferredSize';

Warning: this symbol is deprecated: instead of using this, use EffectiveRect or RenderRect depending on the situation; instead of overriding this, override PreferredSize

 
Public function EffectiveRect: TFloatRectangle;

Control position and size. Use this to base other controls size/position on this control's calculated size/position.

The algorithm that determines control position and size is like this:

The above describes the size of the content and border, summed. The content itself may be a little smaller, when the Border is used. The size of the "content itself" is returned only by RenderRect (in already-scaled coordinates, i.e. using final device pixels).

The anchors (see Anchor) also affect the final position of the control.

Note that some descendants do auto-sizing by default. This means that some of these properties may be ignored, and instead the calculated size (EffectiveWidth, EffectiveHeight) depends on some core values of the control.

For example:

Consult the documentation of each descendant for the exact specification of the size behavior.

This method returns the rectangle in local coordinates (relative to the parent 2D control). The returned rectangle size includes the border size. The returned rectangle size uses "unscaled" coordinates, which means that they correspond to the sizes you set e.g. in TCastleUserInterface.Width, TCastleUserInterface.Height, and translation units you use with e.g. TCastleUserInterface.Anchor.

If you're looking for a way to query the size of the control in final scaled coordinates (in real device pixels), and not relative to the parent position, use RenderRect or RenderRectWithBorder instead.

This method ignores the current value of the GetExists method and Exists property, that is: the result of this function assumes that control does exist.

See also
TCastleUserInterface.EffectiveWidth
Calculated width of the control, without UI scaling.
TCastleUserInterface.EffectiveHeight
Calculated height of the control, without UI scaling.
Public function EffectiveWidth: Single;

Calculated width of the control, without UI scaling. Useful if you want to base other controls size/position on this control calculated size.

Unlike the Width property, this is the effective size, not the desired size. So this is already processed by any auto-sizing mechanism (e.g. TCastleImageControl may adjust it's own size to the underlying image, depending on settings), it is changed by FullSize and so on.

It is always equal to just EffectiveRect.Width. It is 0 when EffectiveRect is empty.

See also
EffectiveRect
Control position and size.
Public function EffectiveHeight: Single;

Calculated height of the control, without UI scaling. Useful if you want to base other controls size/position on this control calculated size.

Unlike the Height property, this is the effective size, not the desired size. So this is already processed by any auto-sizing mechanism (e.g. TCastleImageControl may adjust it's own size to the underlying image, depending on settings), it is changed by FullSize and so on.

It is always equal to just EffectiveRect.Height. It is 0 when EffectiveRect is empty.

See also
EffectiveRect
Control position and size.
Public function CalculatedWidth: Cardinal; deprecated 'use EffectiveWidth';

Warning: this symbol is deprecated: use EffectiveWidth

 
Public function CalculatedHeight: Cardinal; deprecated 'use EffectiveHeight';

Warning: this symbol is deprecated: use EffectiveHeight

 
Public function CalculatedRect: TRectangle; deprecated 'use EffectiveRect';

Warning: this symbol is deprecated: use EffectiveRect

 
Public function RenderRect: TFloatRectangle;

Position and size of this control, assuming it exists, in screen (container) coordinates. The primary use of this is inside Render. A proper UI control should adjust to draw precisely in this rectangle.

Public function RenderRectWithBorder: TFloatRectangle;
 
Public function ScreenRect: TRectangle; deprecated 'use RenderRect';

Warning: this symbol is deprecated: use RenderRect

 
Public function LocalToScreenTranslation: TVector2;

How to translate local coords to screen. If you use UI scaling, this works in final coordinates (after scaling, real pixels on screen).

Public function ParentRect: TFloatRectangle;

Rectangle filling the parent control (or container), in local coordinates. Since this is in local coordinates, the returned rectangle Left and Bottom are always zero, unless parent has Border (the returned rectangle is shrunk by Parent.Border). This is already scaled by UI scaling.

Public procedure Anchor(const AHorizontalAnchor: THorizontalPosition; const AHorizontalAnchorDelta: Single = 0); overload;

Quick way to enable horizontal anchor, to automatically keep this control aligned to parent. Sets HorizontalAnchorSelf, HorizontalAnchorParent, HorizontalAnchorDelta.

Public procedure Anchor( const AHorizontalAnchorSelf, AHorizontalAnchorParent: THorizontalPosition; const AHorizontalAnchorDelta: Single = 0); overload;

Quick way to enable horizontal anchor, to automatically keep this control aligned to parent. Sets HorizontalAnchorSelf, HorizontalAnchorParent, HorizontalAnchorDelta.

Public procedure Anchor(const AVerticalAnchor: TVerticalPosition; const AVerticalAnchorDelta: Single = 0); overload;

Quick way to enable vertical anchor, to automatically keep this control aligned to parent. Sets VerticalAnchorSelf, VerticalAnchorParent, VerticalAnchorDelta.

Public procedure Anchor( const AVerticalAnchorSelf, AVerticalAnchorParent: TVerticalPosition; const AVerticalAnchorDelta: Single = 0); overload;

Quick way to enable vertical anchor, to automatically keep this control aligned to parent. Sets VerticalAnchorSelf, VerticalAnchorParent, VerticalAnchorDelta.

Public procedure AlignHorizontal( const ControlPosition: TPositionRelative = prMiddle; const ContainerPosition: TPositionRelative = prMiddle; const X: Single = 0); deprecated 'use Align or Anchor';

Warning: this symbol is deprecated: use Align or Anchor

Immediately position the control with respect to the parent by adjusting Left. Deprecated, use Align with THorizontalPosition.

Public procedure Align( const ControlPosition: THorizontalPosition; const ContainerPosition: THorizontalPosition; const X: Single = 0); overload;

Immediately position the control with respect to the parent by adjusting Left.

Note that using Anchor is often more comfortable than this method, since you only need to set anchor once (for example, right after creating the control). In contract, adjusting position using this method will typically need to be repeated at each window on resize, like in TCastleWindowCustom.OnResize.

Public procedure AlignVertical( const ControlPosition: TPositionRelative = prMiddle; const ContainerPosition: TPositionRelative = prMiddle; const Y: Single = 0); deprecated 'use Align or Anchor';

Warning: this symbol is deprecated: use Align or Anchor

Immediately position the control with respect to the parent by adjusting Bottom. Deprecated, use Align with TVerticalPosition.

Public procedure Align( const ControlPosition: TVerticalPosition; const ContainerPosition: TVerticalPosition; const Y: Single = 0); overload;

Immediately position the control with respect to the parent by adjusting Bottom.

Note that using Anchor is often more comfortable than this method, since you only need to set anchor once (for example, right after creating the control). In contract, adjusting position using this method will typically need to be repeated at each window on resize, like in TCastleWindowCustom.OnResize.

Public procedure Center;

Immediately center the control within the parent, both horizontally and vertically.

Note that using Anchor is often more comfortable than this method, since you only need to set anchor once. For example, right after creating the control call Anchor(hpMiddle); Anchor(vpMiddle);. In contrast, adjusting position using this method will typically need to be repeated at each window on resize, like in TCastleWindowCustom.OnResize.

Public procedure EditorAllowResize(out ResizeWidth, ResizeHeight: Boolean; out Reason: String); virtual;

Override this to prevent resizing some dimension in CGE editor.

Properties

Public property Controls [Index:Integer]: TCastleUserInterface read GetControls write SetControls;
 
Public property GLInitialized: boolean read FGLInitialized default false;
 
Public property DisableContextOpenClose: Cardinal read FDisableContextOpenClose write FDisableContextOpenClose;

When non-zero, control will not receive GLContextOpen and GLContextClose events when it is added/removed from the TUIContainer.Controls list.

This can be useful as an optimization, to keep the OpenGL resources created even for controls that are not present on the TUIContainer.Controls list. This must used very, very carefully, as bad things will happen if the actual OpenGL context will be destroyed while the control keeps the OpenGL resources (because it had DisableContextOpenClose > 0). The control will then remain having incorrect OpenGL resource handles, and will try to use them, causing OpenGL errors or at least weird display artifacts.

Most of the time, when you think of using this, you should instead use the TCastleUserInterface.Exists property. This allows you to keep the control of the TUIContainer.Controls list, and it will be receive GLContextOpen and GLContextClose events as usual, but will not exist for all other purposes.

Using this mechanism is only sensible if you want to reliably hide a control, but also allow readding it to the TUIContainer.Controls list, and then you want to show it again. This is useful for CastleWindowModes, that must push (and then pop) the controls, but then allows the caller to modify the controls list. And some games, e.g. castle1, add back some (but not all) of the just-hidden controls. For example the TCastleNotifications instance is added back, to be visible even in the menu mode. This means that CastleWindowModes cannot just modify the TUIContainer.Exists value, leaving the control on the TUIContainer.Controls list: it would leave the TCastleUserInterface existing many times on the TUIContainer.Controls list, with the undefined TUIContainer.Exists value.

Public property Focused: boolean read FFocused write SetFocused;
 
Public property Parent: TCastleUserInterface read FParent;

Visual parent control. This control is rendered within the parent, and it's anchors and coordinates are relative to the parent. Parent may be Nil, which means that the Container (if set) is our direct parent.

Public property UIScale: Single read FLastSeenUIScale;

UI scale of this control, derived from container (see TUIContainer.UIScaling and EnableUIScaling).

Public property FloatWidth: Single read FWidth write SetWidth stored false; deprecated 'use Width';

Warning: this symbol is deprecated: use Width

 
Public property FloatHeight: Single read FHeight write SetHeight stored false; deprecated 'use Height';

Warning: this symbol is deprecated: use Height

 
Public property KeepInFront: boolean read FKeepInFront write FKeepInFront default false;

Keep the control in front of other controls (with KeepInFront=False) when inserting.

TODO: Do not change this property while the control is already a children of something.

Public property BorderColor: TCastleColor read FBorderColor write SetBorderColor;

Color of the Border, by default completely transparent black.

Public property HasHorizontalAnchor: boolean read FHasHorizontalAnchor write FHasHorizontalAnchor stored false; deprecated 'this property does not do anything anymore, anchors are always active';

Warning: this symbol is deprecated: this property does not do anything anymore, anchors are always active

 
Public property HasVerticalAnchor: boolean read FHasVerticalAnchor write FHasVerticalAnchor stored false; deprecated 'this property does not do anything anymore, anchors are always active';

Warning: this symbol is deprecated: this property does not do anything anymore, anchors are always active

 
Public property Visible: Boolean read FVisible;

Is the control possibly visible. This is always True when Culling is False (the default).

Published property OnRender: TUiNotifyEvent read FOnRender write FOnRender;

Control is being displayed. See Render for details. This event it called after the Render method of this control finished.

Published property Exists: boolean read FExists write SetExists default true;

Not existing control is not visible, it doesn't receive input and generally doesn't exist from the point of view of user. You can also remove this from controls list (like TCastleWindowCustom.Controls), but often it's more comfortable to set this property to false.

Published property Left: Single read FLeft write SetLeft stored false default 0;

Position from the left side of the parent control.

It's usually better to use anchors instead of this property. For example, instead of setting Control.Left := 10, you can call Control.Anchor(hpLeft, 10), or just change HorizontalAnchorDelta.

Note that the effects of this property and HorizontalAnchorDelta are summed, if you set both.

Published property Bottom: Single read FBottom write SetBottom default 0;

Position from the bottom side of the parent control.

It's usually better to use anchors instead of this property. For example, instead of setting Control.Bottom := 10, you can call Control.Anchor(vpBottom, 10), or just change VerticalAnchorDelta.

Note that the effects of this property and VerticalAnchorDelta are summed, if you set both.

Published property FullSize: boolean read FFullSize write SetFullSize default false;

When FullSize, the control will always fill the whole parent area.

See also
TCastleUserInterface.EffectiveRect
Control position and size.
TCastleUserInterface.EffectiveWidth
Calculated width of the control, without UI scaling.
TCastleUserInterface.EffectiveHeight
Calculated height of the control, without UI scaling.
Published property Width: Single read FWidth write SetWidth default DefaultWidth;

These properties determine the control size. See the EffectiveRect documentation for details how the size is calculated.

See also
TCastleUserInterface.EffectiveRect
Control position and size.
TCastleUserInterface.EffectiveWidth
Calculated width of the control, without UI scaling.
TCastleUserInterface.EffectiveHeight
Calculated height of the control, without UI scaling.
Published property Height: Single read FHeight write SetHeight default DefaultHeight;
 
Published property WidthFraction: Single read FWidthFraction write SetWidthFraction default 0.0;
 
Published property HeightFraction: Single read FHeightFraction write SetHeightFraction default 0.0;
 
Published property AutoSizeToChildren: Boolean read FAutoSizeToChildren write SetAutoSizeToChildren default false;

Adjust size to encompass all the children. The properties FullSize, Width, Height are ignored in this case. Our Left and Bottom still matter.

Our size is adjusted to all existing children sizes and positions.

Note that this works only for simple children anchors: the left edge of the child to the left edge of the parent, the bottom edge of the child to the bottom edge of the parent, and so on. It is impossible to adjust this calculation to all possible children anchors values, since the interpretation of anchors depends on the parent size.

On the right and top side, we add AutoSizeToChildrenPaddingTop and AutoSizeToChildrenPaddingRight. To make left/bottom padding, simply move all children away from the left/bottom edge.

Published property AutoSizeToChildrenPaddingRight: Single read FAutoSizeToChildrenPaddingRight write SetAutoSizeToChildrenPaddingRight default 0;

Padding added when AutoSizeToChildren is used.

Published property AutoSizeToChildrenPaddingTop: Single read FAutoSizeToChildrenPaddingTop write SetAutoSizeToChildrenPaddingTop default 0;

Padding added when AutoSizeToChildren is used.

Published property HorizontalAnchorSelf: THorizontalPosition read FHorizontalAnchorSelf write SetHorizontalAnchorSelf default hpLeft;

Adjust position to align us to the parent horizontally. The resulting EffectiveRect and RenderRect and RenderRectWithBorder will immediately reflect the new position.

Note that HorizontalAnchorDelta is summed with Left. It's usually most natural to leave Left as zero when using anchors.

Note that anchors (as well as Left and Bottom) are ignored when FullSize is set to true. In case of FullSize, the control fills the parent perfectly.

Anchor distance is automatically affected by TUIContainer.UIScaling.

Which our border to align (it's aligned to parent HorizontalAnchorParent border).

Published property HorizontalAnchorParent: THorizontalPosition read FHorizontalAnchorParent write SetHorizontalAnchorParent default hpLeft;

Which parent border is aligned to our HorizontalAnchorSelf border.

Published property HorizontalAnchorDelta: Single read FHorizontalAnchorDelta write SetHorizontalAnchorDelta default 0;

Delta between our border and parent.

Published property VerticalAnchorSelf: TVerticalPosition read FVerticalAnchorSelf write SetVerticalAnchorSelf default vpBottom;

Adjust position to align us to the parent vertically. The resulting EffectiveRect and RenderRect and RenderRectWithBorder will immediately reflect the new position.

Note that VerticalAnchorDelta is summed with Bottom. It's usually most natural to leave Bottom as zero when using anchors.

Note that anchors (as well as Left and Bottom) are ignored when FullSize is set to true. In case of FullSize, the control fills the parent perfectly.

Anchor distance is automatically affected by TUIContainer.UIScaling.

Which our border to align (it's aligned to parent VerticalAnchorParent border).

Published property VerticalAnchorParent: TVerticalPosition read FVerticalAnchorParent write SetVerticalAnchorParent default vpBottom;

Which parent border is aligned to our VerticalAnchorSelf border.

Published property VerticalAnchorDelta: Single read FVerticalAnchorDelta write SetVerticalAnchorDelta default 0;

Delta between our border and parent.

Published property EnableUIScaling: boolean read FEnableUIScaling write SetEnableUIScaling default true;

Enable or disable UI scaling for this particular control. See more about UI scaling on TUIContainer.UIScaling and TCastleUserInterface.UIScale. Setting this to False forces TCastleUserInterface.UIScale to always return 1.0.

Note that this does not work recursively, i.e. it does not affect the children of this control. Setting this to False does not prevent UI scaling on children (you have to turn it off explicitly for children too, if you need to disable UI scaling recursively).

Published property CapturesEvents: boolean read FCapturesEvents write FCapturesEvents default true;

Capture input events (keyboard, mouse, joystick). If False, then the methods like Press and Release will never be called, and Update will always be called with HandleInput = False. The control will never behave like focused.

The only exception is when this control is set as TUIContainer.ForceCaptureInput. In this case, the control will receive inputs. In other words, TUIContainer.ForceCaptureInput overrides the intent of this property.

Published property Culling: Boolean read FCulling write SetCulling default false;

Optimize rendering and event processing by checking whether the control can be visible. The visibility is checked by looking at container rectangle, and all possible clipping parents (set by TCastleScrollView, or any other control with ClipChildren).

This is useful for UI controls that have expensive rendering or other events (e.g. they do something non-trivial in Render or RenderOverChildren, or they include a lot of children controls). And they may be placed off-screen, or they may be outside of a parent with clipping, which is often the case when the parent is TCastleScrollView.

Published property ClipChildren: Boolean read FClipChildren write SetClipChildren default false;

Clip the rendering of children.

By default this is False and so the control can draw outside of it's designated rectangle (RenderRect). Although all the standard UI controls are carefully implemented such that their Render and RenderOverChildren draw only within their RenderRect. But it is easy to place children controls outside of this rectangle.

When this property is True, the rendering is clipped, so the "overflowing" parts are never visible. This affects both Render and RenderOverChildren of this control, as well as all children rendering.

Published property Border: TBorder read FBorder;

Border (by default transparent) of the control. Border adds a space from the control content (drawn within RenderRect) to the control rectangle (returned by RenderRectWithBorder) (scaled), or EffectiveRect (unscaled) and friends).

It is transparent by default, but you can change it by BorderColor.

Border works always, regardless of FullSize or AutoSizeToChildren.

One obvious use-case is to use this for visual space (empty space or a colorful frame, separating this control from the rest).

Another use-case is to reserve a predictable space for as additional (sibling) control within the same parent. E.g. you can set FullSize=true and Border.Top=100, and this way there is always a strip with Height=100 at the top of the parent, where you can insert another control (with Height=100, anchored to the top).

Published property BorderColorPersistent: TCastleColorPersistent read FBorderColorPersistent;

BorderColor that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write BorderColor directly.

See also
BorderColor
Color of the Border, by default completely transparent black.

Generated by PasDoc 0.15.0.