Unit CastleUIControls

Description

Uses

Classes, Interfaces, Objects and Records

Functions and Procedures

Types

Constants

Variables

Description

User interface basic classes: TCastleUserInterface, TUIContainer.

Uses

Overview

Classes, Interfaces, Objects and Records

Name	Description
Object `TTouch`	Tracking of a touch by a single finger, used by TTouchList.
Class `TTouchList`	Tracking of multi-touch, a position of each finger on the screen.
Class `TUIContainer`	Abstract user interface container.
Class `TInputListener`	Base class for things that listen to user input.
Class `TCastleUserInterface`	Basic user-interface class.
Class `TCastleUserInterfaceList`	Simple list of TCastleUserInterface instances.
Class `TChildrenControls`	List of UI controls, with a parent control and container.

Functions and Procedures

function OnGLContextOpen: TGLContextEventList; deprecated 'use ApplicationProperties.OnGLContextOpen';

function OnGLContextClose: TGLContextEventList; deprecated 'use ApplicationProperties.OnGLContextClose';

function IsGLContextOpen: boolean; deprecated 'use ApplicationProperties.IsGLContextOpen';

function RenderControlToImage(const Container: TUIContainer; const Control: TCastleUserInterface; const ViewportRect: TRectangle; const BackgroundColor: TCastleColor): TRGBAlphaImage; overload;

procedure UserInterfaceSave(const C: TCastleUserInterface; const Url: String);

function UserInterfaceLoad(const Url: String; const Owner: TComponent): TCastleUserInterface;

Types

TBorder = CastleVectors.TBorder;

TContainerEvent = procedure (Container: TUIContainer);

TContainerObjectEvent = procedure (Container: TUIContainer) of object;

TInputPressReleaseEvent = procedure (Container: TUIContainer; const Event: TInputPressRelease);

TInputMotionEvent = procedure (Container: TUIContainer; const Event: TInputMotion);

TUiNotifyEvent = procedure (const Sender: TCastleUserInterface) of object;

TUiUpdateEvent = procedure (const Sender: TInputListener; const SecondsPassed: Single; var HandleInput: Boolean) of object;

TUiPressReleaseEvent = procedure (const Sender: TInputListener; const Event: TInputPressRelease; var Handled: Boolean) of object;

TUiMotionEvent = procedure (const Sender: TInputListener; const Event: TInputMotion; var Handled: Boolean) of object;

PTouch = ˆTTouch;

TUIScaling = (...);

TCastleUserInterfaceChange = (...);

TCastleUserInterfaceChanges = set of TCastleUserInterfaceChange;

TCastleUserInterfaceChangeEvent = procedure(const Sender: TInputListener; const Changes: TCastleUserInterfaceChanges; const ChangeInitiatedByChildren: boolean) of object;

TPositionRelative = (...) deprecated;

TCastleUserInterfaceClass = class of TCastleUserInterface;

TUIControlPos = TCastleUserInterface deprecated 'use TCastleUserInterface';

TUIRectangularControl = TCastleUserInterface deprecated 'use TCastleUserInterface';

TUIControl = TCastleUserInterface deprecated 'use TCastleUserInterface';

TUIControlSizeable = TCastleUserInterface deprecated 'use TCastleUserInterface';

TCastleUserInterfaceRect = TCastleUserInterface deprecated 'use TCastleUserInterface';

TUIControlChange = TCastleUserInterfaceChange;

TUIControlChanges = TCastleUserInterfaceChanges;

TUIControlList = TCastleUserInterfaceList;

TUIControlChangeEvent = TCastleUserInterfaceChangeEvent;

Constants

DefaultDpi = 96.0;

DefaultTooltipDelay = 1.0;

DefaultTooltipDistance = 10;

prLeft = prLow deprecated;

prRight = prHigh deprecated;

prBottom = prLow deprecated;

prTop = prHigh deprecated;

hpLeft = CastleRectangles.hpLeft ;

hpMiddle = CastleRectangles.hpMiddle;

hpRight = CastleRectangles.hpRight ;

vpBottom = CastleRectangles.vpBottom;

vpMiddle = CastleRectangles.vpMiddle;

vpTop = CastleRectangles.vpTop ;

Description

Functions and Procedures

function OnGLContextOpen: TGLContextEventList; deprecated 'use ApplicationProperties.OnGLContextOpen';

Warning: this symbol is deprecated: use ApplicationProperties.OnGLContextOpen

function OnGLContextClose: TGLContextEventList; deprecated 'use ApplicationProperties.OnGLContextClose';

Warning: this symbol is deprecated: use ApplicationProperties.OnGLContextClose

function IsGLContextOpen: boolean; deprecated 'use ApplicationProperties.IsGLContextOpen';

Warning: this symbol is deprecated: use ApplicationProperties.IsGLContextOpen

function RenderControlToImage(const Container: TUIContainer; const Control: TCastleUserInterface; const ViewportRect: TRectangle; const BackgroundColor: TCastleColor): TRGBAlphaImage; overload;

Render control contents to an RGBA image, using off-screen rendering. The background behind the control is filled with BackgroundColor (which may be transparent, e.g. with alpha = 0).

The rendering is done using off-screen FBO. Which means that you can request any size, you are not limited to your current window / control size.

Make sure that the control is nicely positioned to fill the ViewportRect. Usually you want to adjust control size and position, and disable UI scaling (set TCastleUserInterface.EnableUIScaling = False if you use TUIContainer.UIScaling).

This is the easiest way to make off-screen rendering, i.e. to render 3D things (like TCastleScene in TCastleViewport) into an image. This is not the fastest way, as it creates new TGLRenderToTexture instance each time, and it grabs the image contents to CPU. If you want a faster approach, use TUIContainer.RenderControl and render into TDrawableImage using TDrawableImage.RenderToImageBegin and TDrawableImage.RenderToImageEnd.

procedure UserInterfaceSave(const C: TCastleUserInterface; const Url: String);

Save / load TCastleUserInterface (or descendant) to a .castle-user-interface file.

function UserInterfaceLoad(const Url: String; const Owner: TComponent): TCastleUserInterface;

Types

TBorder = CastleVectors.TBorder;

TContainerEvent = procedure (Container: TUIContainer);

TContainerObjectEvent = procedure (Container: TUIContainer) of object;

TInputPressReleaseEvent = procedure (Container: TUIContainer; const Event: TInputPressRelease);

TInputMotionEvent = procedure (Container: TUIContainer; const Event: TInputMotion);

TUiNotifyEvent = procedure (const Sender: TCastleUserInterface) of object;

TUiUpdateEvent = procedure (const Sender: TInputListener; const SecondsPassed: Single; var HandleInput: Boolean) of object;

TUiPressReleaseEvent = procedure (const Sender: TInputListener; const Event: TInputPressRelease; var Handled: Boolean) of object;

TUiMotionEvent = procedure (const Sender: TInputListener; const Event: TInputMotion; var Handled: Boolean) of object;

PTouch = ˆTTouch;

TUIScaling = (...);

Possible values for TUIContainer.UIScaling.

Values

usNone: Do not scale UI.
usEncloseReferenceSize: Scale to fake that the container sizes enclose TUIContainer.UIReferenceWidth and TUIContainer.UIReferenceHeight. So one size will be equal to reference size, and the other will be equal or larger to reference.
Controls that look at TCastleUserInterface.UIScale will be affected by this. Together with anchors (see TCastleUserInterface.Anchor), this allows to easily design a scalable UI.
usFitReferenceSize: Scale to fake that the container sizes fit inside TUIContainer.UIReferenceWidth and TUIContainer.UIReferenceHeight. So one size will be equal to reference size, and the other will be equal or smaller to reference.
Controls that look at TCastleUserInterface.UIScale will be affected by this. Together with anchors (see TCastleUserInterface.Anchor), this allows to easily design a scalable UI.
usExplicitScale: Scale to fake that the container sizes are smaller/larger by an explicit factor TUIContainer.UIExplicitScale. Controls that look at TCastleUserInterface.UIScale will be affected by this.
Like usEncloseReferenceSize or usFitReferenceSize, this allows to design a scalable UI. In this case, the scale factor has to be calculated by your code (by default TUIContainer.UIExplicitScale is 1.0 and the engine will not modify it automatically in any way), which allows customizing the scale to your requirements.
usDpiScale: Scale to pretend that the container size is smaller/larger by a factor derived from TUIContainer.Dpi.
This allows to adjust controls to:
- The physical size (TUIContainer.Dpi on iOS and Android really reflects physical size).
- Or at least to follow user preferred UI scaling (TUIContainer.Dpi desktop is often more like "configurable way to scale UI" than derived from actual monitor physical size).
This is the same scaling done by normal desktop applications, e.g. using Lazarus LCL. Using this scaling is best if your user interface using CGE should match (the size of) the user interface done by Lazarus LCL.

TCastleUserInterfaceChange = (...);

Things that can cause TInputListener.VisibleChange notification.

Values

chRender: The look of this control changed. This concerns all the things that affect what TCastleUserInterface.Render does.
Note that changing chRectangle implies that the look changed too. So when chRectangle is in Changes, you should always behave like chRender is also in Changes, regardless if it's there or not.
chRectangle: The rectangle (size or position) of the control changed. This concerns all the things that affect TCastleUserInterface.Rect or our position inside parent (anchors).
Note that this is not (necessarily) called when the screen position changed just because the parent screen position changed. We only notify when the size or position changed with respect to the parent.
Note that changing chRectangle implies that the look changed too. So when chRectangle is in Changes, you should always behave like chRender is also in Changes, regardless if it's there or not.
chCursor
chExists
chChildren: A (direct) child control was added or removed.
chChildrenExists: A (direct) child control TCastleUserInterface.Exists value changed.

TCastleUserInterfaceChanges = set of TCastleUserInterfaceChange;

TCastleUserInterfaceChangeEvent = procedure(const Sender: TInputListener; const Changes: TCastleUserInterfaceChanges; const ChangeInitiatedByChildren: boolean) of object;

TPositionRelative = (...) deprecated;

Warning: this symbol is deprecated.

Position for relative layout of one control in respect to another. Deprecated, rather use cleaner THorizontalPosition and TVerticalPosition.

Values

prLow
prMiddle
prHigh

TCastleUserInterfaceClass = class of TCastleUserInterface;

TUIControlPos = TCastleUserInterface deprecated 'use TCastleUserInterface';

Warning: this symbol is deprecated: use TCastleUserInterface