Class TUIContainer

Unit

Declaration

type TUIContainer = class abstract(TComponent)

Description

Abstract user interface container. Connects OpenGL context management code with Castle Game Engine controls (TUIControl, that is the basis for all our 2D and 3D rendering). When you use TCastleWindowCustom (a window) or TCastleControlCustom (Lazarus component), they provide you a non-abstact implementation of TUIContainer.

Basically, this class manages a Controls list.

We pass our inputs (mouse / key / touch events) to the controls on this list. Input goes to the front-most (that is, last on the Controls list) control under the event position (or mouse position, or the appropriate touch position). We use TUIControl.CapturesEventsAtPosition to decide this (by default it simply checks control's TUIControl.ScreenRect vs the given position). As long as the event is not handled, we search for the next control that can handle this event and returns TUIControl.CapturesEventsAtPosition = True.

We also call various methods to every control. These include TInputListener.Update, TUIControl.Render, TInputListener.Resize.

Hierarchy

  • TComponent
  • TUIContainer

Overview

Methods

Protected procedure Notification(AComponent: TComponent; Operation: TOperation); override;
Protected procedure SetInternalCursor(const Value: TMouseCursor); virtual;
Protected function GetMousePosition: TVector2; virtual;
Protected procedure SetMousePosition(const Value: TVector2); virtual;
Protected function GetTouches(const Index: Integer): TTouch; virtual;
Protected function DefaultUIScale: Single;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure EventOpen(const OpenWindowsCount: Cardinal); virtual;
Public procedure EventClose(const OpenWindowsCount: Cardinal); virtual;
Public function EventPress(const Event: TInputPressRelease): boolean; virtual;
Public function EventRelease(const Event: TInputPressRelease): boolean; virtual;
Public procedure EventUpdate; virtual;
Public procedure EventMotion(const Event: TInputMotion); virtual;
Public function AllowSuspendForInput: boolean;
Public procedure EventBeforeRender; virtual;
Public procedure EventRender; virtual; abstract;
Public procedure EventResize; virtual;
Public function EventJoyAxisMove(const JoyID, Axis: Byte): boolean; virtual;
Public function EventJoyButtonPress(const JoyID, Button: Byte): boolean; virtual;
Public function EventSensorRotation(const X, Y, Z, Angle: Double; const SecondsPassed: Single): boolean; virtual;
Public function EventSensorTranslation(const X, Y, Z, Length: Double; const SecondsPassed: Single): boolean; virtual;
Public function Controls: TChildrenControls;
Public procedure Invalidate; virtual;
Public function GLInitialized: boolean; virtual;
Public function Width: Integer; virtual; abstract;
Public function Height: Integer; virtual; abstract;
Public function Rect: TRectangle; virtual;
Public function UnscaledWidth: Cardinal;
Public function UnscaledHeight: Cardinal;
Public function UnscaledRect: TRectangle;
Public function Dpi: Integer; virtual;
Public function Focused: boolean; virtual;
Public function TouchesCount: Integer; virtual;
Public procedure SaveScreen(const URL: string); overload;
Public function SaveScreen: TRGBImage; overload;
Public function SaveScreen(const SaveRect: TRectangle): TRGBImage; overload; virtual; abstract;
Public procedure UpdateFocusAndMouseCursor;
Public function IsMousePositionForMouseLook: boolean;
Public procedure MakeMousePositionForMouseLook;
Public procedure ReleaseCapture(const C: TUIControl);

Properties

Protected property OnOpen: TContainerEvent read FOnOpen write FOnOpen;
Protected property OnOpenObject: TContainerObjectEvent read FOnOpenObject write FOnOpenObject;
Protected property OnBeforeRender: TContainerEvent read FOnBeforeRender write FOnBeforeRender;
Protected property OnRender: TContainerEvent read FOnRender write FOnRender;
Protected property OnResize: TContainerEvent read FOnResize write FOnResize;
Protected property OnClose: TContainerEvent read FOnClose write FOnClose;
Protected property OnCloseObject: TContainerObjectEvent read FOnCloseObject write FOnCloseObject;
Protected property OnPress: TInputPressReleaseEvent read FOnPress write FOnPress;
Protected property OnRelease: TInputPressReleaseEvent read FOnRelease write FOnRelease;
Protected property OnMotion: TInputMotionEvent read FOnMotion write FOnMotion;
Protected property OnUpdate: TContainerEvent read FOnUpdate write FOnUpdate;
Protected property Cursor: TMouseCursor write SetInternalCursor; deprecated 'do not set this, engine will override this. Set TUIControl.Cursor of your UI controls to control the Cursor.';
Protected property InternalCursor: TMouseCursor write SetInternalCursor;
Public property Focus: TUIControlList read FFocus;
Public property TooltipVisible: boolean read FTooltipVisible;
Public property TooltipPosition: TVector2 read FTooltipPosition;
Public property MousePosition: TVector2 read GetMousePosition write SetMousePosition;
Public property MousePressed: TMouseButtons read FMousePressed write FMousePressed;
Public property Pressed: TKeysPressed read FPressed;
Public property Fps: TFramesPerSecond read FFps;
Public property Touches[Index:Integer]: TTouch read GetTouches;
Public property ForceCaptureInput: TUIControl read FForceCaptureInput write SetForceCaptureInput;
Published property RenderStyle: TRenderStyle read FRenderStyle write FRenderStyle default rs2D; deprecated 'do not use this to control front-back UI controls order, better to use controls order and TUIControl.KeepInFront';
Published property TooltipDelay: Single read FTooltipDelay write FTooltipDelay default DefaultTooltipDelay;
Published property TooltipDistance: Cardinal read FTooltipDistance write FTooltipDistance default DefaultTooltipDistance;
Published property UIScaling: TUIScaling read FUIScaling write SetUIScaling default usNone;
Published property UIReferenceWidth: Integer read FUIReferenceWidth write SetUIReferenceWidth default 0;
Published property UIReferenceHeight: Integer read FUIReferenceHeight write SetUIReferenceHeight default 0;
Published property UIExplicitScale: Single read FUIExplicitScale write SetUIExplicitScale default 1.0;

Description

Methods

Protected procedure Notification(AComponent: TComponent; Operation: TOperation); override;
 
Protected procedure SetInternalCursor(const Value: TMouseCursor); virtual;
 
Protected function GetMousePosition: TVector2; virtual;
 
Protected procedure SetMousePosition(const Value: TVector2); virtual;
 
Protected function GetTouches(const Index: Integer): TTouch; virtual;
 
Protected function DefaultUIScale: Single;

Get the default UI scale of controls. Useful only when GLInitialized, when we know that our size is sensible. Most UI code should rather be placed in TUIControl, and use TUIControl.UIScale.

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure EventOpen(const OpenWindowsCount: Cardinal); virtual;

Propagate the event to all the Controls and to our own OnXxx callbacks.

These methods are called automatically when necessary, so usually you don't call them. But in rare cases, it makes sense to "fake" some event by calling these methods.

Most of these methods are called automatically by the container owner, like TCastleWindow or TCastleControl. Some are called by EventUpdate, which is special in this regard, as EventUpdate is not only responsible for calling TInputListener.Update on all Controls, it also calls EventJoyAxisMove, EventJoyButtonPress, EventSensorRotation, EventSensorTranslation.

Public procedure EventClose(const OpenWindowsCount: Cardinal); virtual;
 
Public function EventPress(const Event: TInputPressRelease): boolean; virtual;
 
Public function EventRelease(const Event: TInputPressRelease): boolean; virtual;
 
Public procedure EventUpdate; virtual;
 
Public procedure EventMotion(const Event: TInputMotion); virtual;
 
Public function AllowSuspendForInput: boolean;
 
Public procedure EventBeforeRender; virtual;
 
Public procedure EventRender; virtual; abstract;
 
Public procedure EventResize; virtual;
 
Public function EventJoyAxisMove(const JoyID, Axis: Byte): boolean; virtual;
 
Public function EventJoyButtonPress(const JoyID, Button: Byte): boolean; virtual;
 
Public function EventSensorRotation(const X, Y, Z, Angle: Double; const SecondsPassed: Single): boolean; virtual;
 
Public function EventSensorTranslation(const X, Y, Z, Length: Double; const SecondsPassed: Single): boolean; virtual;
 
Public function Controls: TChildrenControls;

Controls listening for events (user input, resize, and such) of this container.

Usually you explicitly add / remove controls to this list using the Controls.InsertFront or Controls.InsertBack methods. Freeing any control that is on this list automatically removes it from this list (we use the TComponent.Notification mechanism).

Controls on the list should be specified in back-to-front order. That is, controls at the beginning of this list are rendered first, and are last to catch some events, since the rest of controls cover them.

Public procedure Invalidate; virtual;

Redraw the contents of of this window, at the nearest suitable time. This method does not redraw immediately (it does not call EventBeforeRender and EventRender inside), it only makes sure that they will be called very soon. Calling this on a closed container (with GLInitialized = False) is allowed and ignored.

Public function GLInitialized: boolean; virtual;

Is the OpenGL context initialized.

Public function Width: Integer; virtual; abstract;

Container size, in pixels. This is expressed in real device pixels. Prefer using UnscaledWidth instead of this. UnscaledWidth is more natural when you use UI scaling (UIScaling), and it's simply equal to Width when UI scaling is not used.

Public function Height: Integer; virtual; abstract;

Container size, in pixels. This is expressed in real device pixels. Prefer using UnscaledHeight instead of this. UnscaledHeight is more natural when you use UI scaling (UIScaling), and it's simply equal to Height when UI scaling is not used.

Public function Rect: TRectangle; virtual;

Container size, in pixels. This is expressed in real device pixels, using Width and Height. Prefer using UnscaledRect instead of this. UnscaledRect is more natural when you use UI scaling (UIScaling), and it's simply equal to Rect when UI scaling is not used.

Public function UnscaledWidth: Cardinal;

Container width as seen by controls with UI scaling. In other words, this is the real Width with UI scaling reversed (divided). Suitable to adjust size of your UI controls to container, when UI scaling is used.

This is equivalent to just Width when UIScaling is usNone (default).

Note: the name "unscaled" may seem a little unintuitive, but it's consistent. We call UI sizes "scaled" when they are expressed in real device pixels, because they are usually calculated as "desired size * UIScaling". So the UI size is "unscaled" when it's expressed in your "desired size". We usually don't use the prefix "unscaled" (e.g. TCastleButton.Width is "unscaled" by we don't call it "UnscaledWidth"; every property inside TCastleButton is actually "unscaled"). But here, we use prefix "unscaled", because the TUIContainer.Width is (for historic reasons) the "real" size.

See also
UnscaledHeight
Container height as seen by controls with UI scaling.
Public function UnscaledHeight: Cardinal;

Container height as seen by controls with UI scaling.

See also
UnscaledWidth
Container width as seen by controls with UI scaling.
Public function UnscaledRect: TRectangle;

Container rectangle as seen by controls with UI scaling.

See also
UnscaledWidth
Container width as seen by controls with UI scaling.
Public function Dpi: Integer; virtual;

Dots per inch, specifying the relation of screen pixels to physical size.

Public function Focused: boolean; virtual;

Is the window focused now, which means that keys/mouse events are directed to this window.

Public function TouchesCount: Integer; virtual;

Count of currently active touches (mouse or fingers pressed) on the screen.

See also
Touches
Currently active touches on the screen.
Public procedure SaveScreen(const URL: string); overload;

Capture the current container (window) contents to an image (or straight to an image file, like png).

Note that only capturing from the double-buffered OpenGL windows (which the default for our TCastleWindow and TCastleControl) is reliable. Internally, these methods may need to redraw the screen to the back buffer, because that's the only guaranteed way to capture OpenGL drawing (you have to capture the back buffer, before swap).

Public function SaveScreen: TRGBImage; overload;
 
Public function SaveScreen(const SaveRect: TRectangle): TRGBImage; overload; virtual; abstract;
 
Public procedure UpdateFocusAndMouseCursor;

Called by controls within this container when something could change the container focused control (in TUIContainer.Focus) (or it's cursor) or TUIContainer.Focused or MouseLook. In practice, called when TUIControl.Cursor or TUIControl.CapturesEventsAtPosition (and so also TUIControl.ScreenRect) results change.

This recalculates the focused control and the final cursor of the container, looking at Container's Controls, testing TUIControl.CapturesEventsAtPosition with current mouse position, and looking at Cursor property of various controls.

When you add / remove some control from the Controls list, or when you move mouse (focused changes) this will also be automatically called (since focused control or final container cursor may also change then).

Public function IsMousePositionForMouseLook: boolean;

Internal for implementing mouse look in cameras.

Public procedure MakeMousePositionForMouseLook;

Internal for implementing mouse look in cameras.

Public procedure ReleaseCapture(const C: TUIControl);

When the control accepts the "press" event, it automatically captures the following motion and release events, hijacking them from other controls, regardless of the mouse cursor position. This is usually desirable, to allow the control to handle the dragging. But sometimes you want to cancel the dragging, and allow other controls to handle the following motion and release events, in which case calling this method helps.

Properties

Protected property OnOpen: TContainerEvent read FOnOpen write FOnOpen;

These should only be get/set by a container provider, like TCastleWindow or TCastleControl.

Protected property OnOpenObject: TContainerObjectEvent read FOnOpenObject write FOnOpenObject;
 
Protected property OnBeforeRender: TContainerEvent read FOnBeforeRender write FOnBeforeRender;
 
Protected property OnRender: TContainerEvent read FOnRender write FOnRender;
 
Protected property OnResize: TContainerEvent read FOnResize write FOnResize;
 
Protected property OnClose: TContainerEvent read FOnClose write FOnClose;
 
Protected property OnCloseObject: TContainerObjectEvent read FOnCloseObject write FOnCloseObject;
 
Protected property OnPress: TInputPressReleaseEvent read FOnPress write FOnPress;
 
Protected property OnRelease: TInputPressReleaseEvent read FOnRelease write FOnRelease;
 
Protected property OnMotion: TInputMotionEvent read FOnMotion write FOnMotion;
 
Protected property OnUpdate: TContainerEvent read FOnUpdate write FOnUpdate;
 
Protected property Cursor: TMouseCursor write SetInternalCursor; deprecated 'do not set this, engine will override this. Set TUIControl.Cursor of your UI controls to control the Cursor.';

Warning: this symbol is deprecated: do not set this, engine will override this. Set TUIControl.Cursor of your UI controls to control the Cursor.

 
Protected property InternalCursor: TMouseCursor write SetInternalCursor;
 
Public property Focus: TUIControlList read FFocus;

Returns the controls that should receive input events, from back to front. So the front-most control, that should receive events first, is last on this list.

Public property TooltipVisible: boolean read FTooltipVisible;

When the tooltip should be shown (mouse hovers over a control with a tooltip) then the TooltipVisible is set to True, and TooltipPosition indicate left-bottom (in screen space, regardless of UIScaling) suggested position of the tooltip.

The tooltip is only detected when TUIControl.TooltipExists. See TUIControl.TooltipExists and TUIControl.TooltipStyle and TUIControl.TooltipRender. For simple purposes just set TUIControlFont.Tooltip to something non-empty.

Public property TooltipPosition: TVector2 read FTooltipPosition;
 
Public property MousePosition: TVector2 read GetMousePosition write SetMousePosition;

Current mouse position. See TTouch.Position for a documentation how this is expressed.

Public property MousePressed: TMouseButtons read FMousePressed write FMousePressed;

Currently pressed mouse buttons. When this changes, you're always notified by OnPress or OnRelease events.

This value is always current, in particular it's already updated before we call events OnPress or OnRelease.

Public property Pressed: TKeysPressed read FPressed;

Keys currently pressed.

Public property Fps: TFramesPerSecond read FFps;

Measures application speed.

Public property Touches[Index:Integer]: TTouch read GetTouches;

Currently active touches on the screen. This tracks currently pressed fingers, in case of touch devices (mobile, like Android and iOS). In case of desktops, it tracks the current mouse position, regardless if any mouse button is currently pressed.

Indexed from 0 to TouchesCount - 1.

See also
TouchesCount
Count of currently active touches (mouse or fingers pressed) on the screen.
TTouch
Tracking of a touch by a single finger, used by TTouchList.
Public property ForceCaptureInput: TUIControl read FForceCaptureInput write SetForceCaptureInput;

Force passing events to given control first, regardless if this control is under mouse cursor. This control also always has focus.

An example when this is useful is when you use camera MouseLook, and the associated viewport does not fill the full window (TCastleAbstractViewport.FullSize is False, and actual sizes are smaller than window, and may not include window center). In this case you want to make sure that motion events get passed to this control, and that this control has focus (to keep mouse cursor hidden).

Published property RenderStyle: TRenderStyle read FRenderStyle write FRenderStyle default rs2D; deprecated 'do not use this to control front-back UI controls order, better to use controls order and TUIControl.KeepInFront';

Warning: this symbol is deprecated: do not use this to control front-back UI controls order, better to use controls order and TUIControl.KeepInFront

How OnRender callback fits within various Render methods of our Controls.

  • rs2D means that OnRender is called at the end, after all our Controls (3D and 2D) are drawn.

  • rs3D means that OnRender is called after all other Controls with rs3D draw style, but before any 2D controls.

    This is suitable if you want to draw something 3D, that may be later covered by 2D controls.

Do not use this to control the order of rendering, better to use proper InsertFront or InsertBack or KeepInFront.

Published property TooltipDelay: Single read FTooltipDelay write FTooltipDelay default DefaultTooltipDelay;

Delay in seconds before showing the tooltip.

Published property TooltipDistance: Cardinal read FTooltipDistance write FTooltipDistance default DefaultTooltipDistance;
 
Published property UIScaling: TUIScaling read FUIScaling write SetUIScaling default usNone;

Enable automatic scaling of the UI. This is great when the container size may vary widly (for example, on mobile devices, although it becomes more and more sensible for desktops too). See TUIScaling values for precise description how it works.

Published property UIReferenceWidth: Integer read FUIReferenceWidth write SetUIReferenceWidth default 0;

Reference width and height to which we fit the container size (as seen by TUIControl implementations) when UIScaling is usEncloseReferenceSize or usFitReferenceSize. See usEncloseReferenceSize and usFitReferenceSize for precise description how this works. Set both these properties, or set only one (and leave the other as zero).

Published property UIReferenceHeight: Integer read FUIReferenceHeight write SetUIReferenceHeight default 0;
 
Published property UIExplicitScale: Single read FUIExplicitScale write SetUIExplicitScale default 1.0;

Scale of the container size (as seen by TUIControl implementations) when UIScaling is usExplicitScale. See usExplicitScale for precise description how this works.


Generated by PasDoc 0.15.0.