Class TUIContainer

Does setting MousePosition also causes Motion / OnMotion events. While we tried to make everything work reliably always, the mouse look logic just needs to know this.

It is easy to test it in practice. Just run examples/window/window_events.lpr, move mouse around, and press "5" (this does "MousePosition := window middle").

Get the default UI scale of controls. Useful only when GLInitialized, when we know that our size is sensible. Almost all UI code should rather be placed in TCastleUserInterface, and use TCastleUserInterface.UIScale, not directly accessing Container.DefaultUIScale or Container.FCalculatedUIScale.

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 TCastleWindowBase or TCastleControlBase. 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.

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.

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.

Is the OpenGL context initialized.

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.

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.

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.

Translucent status bar height in the container, in pixels. This is expressed in real device pixels. Prefer using StatusBarHeight instead of this.

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. TCastleUserInterface.Width is "unscaled" by we don't call it "UnscaledWidth"). 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.

Container height as seen by controls with UI scaling.

See also

UnscaledWidth

Container width as seen by controls with UI scaling.

Container rectangle as seen by controls with UI scaling.

See also

UnscaledWidth

Container width as seen by controls with UI scaling.

Translucent status bar height inside the container as seen by controls with UI scaling.

Status bar occupies the top part of the container height. Invisible status bar returns height equal zero.

See also

UnscaledWidth

Container width as seen by controls with UI scaling.

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

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

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

See also

Touches

Currently active touches on the screen.

Render a TCastleUserInterface (along with all it's children).

This method can be used to render UI control into an image, TDrawableImage, when it is surrounded by TDrawableImage.RenderToImageBegin and TDrawableImage.RenderToImageEnd. See example ../../../examples/3d_rendering_processing/render_3d_to_image.lpr.

It can also be used with more low-level TGLRenderToTexture. See example ../../../examples/3d_rendering_processing/render_3d_to_texture_and_use_as_quad.lpr.

This is a good method to render the UI control off-screen. It can render any UI control, including e.g. TCastleViewport with 3D stuff inside TCastleScene.

The contents of the Controls list doesn't matter for this method. In particular, it doesn't matter if the Control (given as a parameter) is present on the list of current Controls. This method explicitly renders the given Control parameter (and it's children), nothing more, nothing less.

More details what this method does:

• Temporarily sets Control.Container, if needed.

• Makes sure OpenGL resources of the control are initialized. If needed, it calls Control.GLContextOpen and Control.GLContextClose around. This is needed when you want to perform off-screen rendering, but the control's OpenGL resources are not initialized yet, e.g. because it is not present on the Controls list.

  Note that doing this repeatedly may be a slowdown (how much, it depends on the actual TCastleUserInterface – some controls do nothing in TCastleUserInterface.GLContextOpen, some controls do a lot). If you want to repeatedly call RenderControl on the same Control, it is more efficient to first explicitly create it's OpenGL resources, e.g. by calling Control.GLContextOpen explicitly. Or adding the control to the Controls list.

• Calls Control.Resize, which may be expected by some controls.

• Calls Control.BeforeRender, which may be expected by some controls.

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 TCastleWindowBase and TCastleControlBase) 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).

Capture the current container (window) contents to an image with alpha.

An example:

{ TUIContainer.SaveScreenRgba example.

  This example relies on OpenGL color buffer that can store alpha information,
  which you request by "Window.AlphaBits := 8".

  An alternative approach, without needing "Window.AlphaBits := xxx",
  is to initialize FBO with color framebuffer with alpha channel,
  and render using this Fbo, like this:

    Fbo := TGLRenderToTexture.Create(Window.Width, Window.Height);
    Fbo.Buffer := tbNone;
    Fbo.ColorBufferAlpha := true;
    Fbo.GLContextOpen;
    Fbo.RenderBegin;
    ...
    Fbo.RenderEnd;
}
uses SysUtils,
  CastleWindow, CastleLog, CastleVectors, CastleUIControls, CastleScene,
  CastleViewport, CastleKeysMouse, CastleImages;

procedure Press(Container: TUIContainer; const Event: TInputPressRelease);
var
  Image: TRGBAlphaImage;
begin
  if Event.IsKey(keyF5) then
  begin
    Image := Container.SaveScreenRgba;
    try
      SaveImage(Image, 'save_screen_rgba.png');
    finally FreeAndNil(Image) end;
  end;
end;

var
  Window: TCastleWindowBase;
  Viewport: TCastleViewport;
  Scene: TCastleScene;
begin
  Window := TCastleWindowBase.Create(Application);
  // We must have buffer that stores alpha information, not only RGB
  Window.AlphaBits := 8;
  // Initially fill buffer with transparent white.
  // When displaying, the window will be white, but it will be saved as transparent white.
  Window.Container.BackgroundColor := Vector4(1, 1, 1, 0);
  Window.OnPress := @Press;
  Window.Open;

  Viewport := TCastleViewport.Create(Application);
  Viewport.FullSize := true;
  Viewport.AutoCamera := true;
  Viewport.AutoNavigation := true;
  Viewport.Transparent := true; // do not fill parent with Viewport.BackgroundColor
  Window.Controls.InsertFront(Viewport);

  Scene := TCastleScene.Create(Application);
  Scene.Load('castle-data:/teapot.x3dv');
  Scene.Spatial := [ssRendering, ssDynamicCollisions];
  Scene.ProcessEvents := true;
  Viewport.Items.Add(Scene);
  Viewport.Items.MainScene := Scene;

  Application.Run;
end.

Capture the current container (window) contents to an image and save it to file, following the current platform/user preferred directory to store screenshots.

On Windows, this saves files to user's "My Pictures" directory. On Unix (using freedesktop standard) this saves files to directory like ˜/Pictures . On macOS, this saves files to the home directory right now. On other platforms, it may follow the most established convention, or abort if no place (where we have permissions to store screenshots) exists.

You can use SaveScreenPath yourself to have more control over the target location.

Returns the saved file URL, so that you can e.g. show it to user.

For tracking mouse look. See MouseLookDelta.

For tracking mouse look. See MouseLookDelta.

Read mouse position delta from container middle, and try to set mouse position to container middle.

This can be used to perform "mouse look" or a similar effect, when user doesn't see the mouse cursor, but user can move something by dragging with mouse. Moreover, user should not notice any "bounds" to this dragging (that's why we try to keep mouse position in container middle, to avoid screen borders from acting as constrains on mouse movement).

This is automatically used by TCastleWalkNavigation.MouseLook. You can use it yourself for custom effects "like mouse look". The template to use this is below. See the CGE examples examples/user_interface/dragging_test/ for a working code demonstrating this.

function TMyState.Press(const Event: TInputPressRelease): Boolean;
begin
  Result := inherited;
  if Result then Exit;

  if Event.IsMouseButton(buttonLeft) then
  begin
    Drag := true;
    Cursor := mcForceNone;
    Container.MouseLookPress;
  end;
end;

function TMyState.Release(const Event: TInputPressRelease): Boolean;
begin
  Result := inherited;
  if Result then Exit;

  if Event.IsMouseButton(buttonLeft) then
  begin
    Drag := false;
    Cursor := mcDefault;
  end;
end;

procedure TMyState.Update(const SecondsPassed: Single;
  var HandleInput: Boolean);
begin
  inherited;
  if Drag then
    Container.MouseLookUpdate;
end;

function TNewFightUi.Motion(const Event: TInputMotion): Boolean;
var
  Delta: TVector2;
begin
  Result := inherited;
  if Result then Exit;

  if Drag then
  begin
    Delta := Container.MouseLookDelta(Event);
    // ...
    // Use Delta to perform any logic you want.
    // It may be zero if mouse was not positioned correctly yet,
    // just make sure that Delta=zero does nothing.
    // You can use Delta / UiScale to adjust to UI scale
    // (user will then have to move mouse by more pixels on a larger screen to achieve the same Delta).
    // ...
  end;
end;

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.

Load visual settings from an XML file. See https://castle-engine.io/manual_castle_settings.php for a documentation of the file format.

This loads UIScaling, UIReferenceWidth, UIReferenceHeight, DefaultFont. In the future, it may load more things configurable by the CGE editor and CastleSettings.xml file.

These should only be get/set by a container owner, like TCastleWindowBase or TCastleControlBase.

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

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.

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

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.

Keys currently pressed.

Measures application speed.

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.

Force passing events to the given control first, regardless if this control is under the mouse cursor. Before we even send events to the currently "capturing" control (for example, when you're dragging the slider, it is "capturing" mouse events until you release the mouse), they are send to this control.

The control given here will always have focus (that is, TCastleUserInterface.Focused will be set to true shortly after it becomes the ForceCaptureInput).

An example when this is useful is when you use camera MouseLook, and the associated viewport does not fill the full window (TCastleViewport.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).

The engine itself never automatically sets this property. It is up to your application code to set this, if you need.

When this is not mcDefault, it sets the cursor, regardless of cursor specified at the TInputListener.Cursor value of the focused control. It even takes precedence over any control using mcForceNone (so it can force the cursor to be visible anyway).

Delay in seconds before showing the tooltip.

Enable automatic scaling of the UI.

This allows your UI to look correctly on various window sizes (great both for mobile and desktop, where window size may vary wildly). The idea is that you can set UI controls sizes (like TCastleUserInterface.Width, TCastleUserInterface.Height) to a simple constant values. And you should also set appropriate anchors (choose wisely whether to anchor e.g. to left or right, as the simulated window size still has variable aspect ratio). And the result will look good on any actual window size. All the controls will be scaled to fill the same window part. The scaling is actually done by scaling the coordinates, so there's no quality loss, whole rendering just adjusts to the actual window size in a smart way.

See TUIScaling values for precise description how it works.

Reference width and height to which we fit the container size (as seen by TCastleUserInterface 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).

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

Default font (type, size) to be used by all user interface controls. Note that each UI control can customize the used font and/or size using properties TCastleUserInterfaceFont.CustomFont, TCastleUserInterfaceFont.FontSize.

If this is Nil, we use the global font UIFont that is always assigned.

Before rendering anything else, fill the color buffer with BackgroundColor. By default this is True.

You can set this to False to gain a little speed, if you know you always draw something that fills the whole container. For example:

• Use TCastleRectangleControl with FullSize = True and set TCastleRectangleControl.Color as desired,

• or use TCastleViewport with TCastleUserInterface.FullSize = True and TCastleViewport.Transparent = False and set TCastleViewport.BackgroundColor as desired,

• eventually you can also call RenderContext.Clear at the beginning of your rendering in OnRender. This is the least advised method, as OnRender is performed after drawing all other controls, so doing RenderContext.Clear there would force you to make all your drawing in OnRender.

If you set this to False, but do not draw something else over the entire container, then the screen contents at the beginning are undefined.

Color that fills the window by default. By default it is DefaultBackgroundColor, which is very dark gray.