Unit CastleUIControls

Theme that you can customize, used by default by all UI controls.

Fallback (do not change this, ever) theme. Default state of Theme.

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

Warning: this symbol is deprecated: use ApplicationProperties.OnGLContextOpen

Called when first OpenGL context opens.

Warning: this symbol is deprecated: use ApplicationProperties.OnGLContextClose

Called when last OpenGL context closes.

Warning: this symbol is deprecated: use ApplicationProperties.IsGLContextOpen

Is any OpenGL context open.

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 TCastleContainer.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 TCastleContainer.RenderControl and render into TDrawableImage using TDrawableImage.RenderToImageBegin and TDrawableImage.RenderToImageEnd.

type

Possible values for TCastleContainer.UIScaling.

Values

• usNone: Do not scale UI.
• usEncloseReferenceSize: Scale to fake that the container sizes enclose TCastleContainer.UIReferenceWidth and TCastleContainer.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.

• usEncloseReferenceSizeAutoOrientation: Similar to usEncloseReferenceSize, but automatically flips the reference width and height to adjust to what is currently bigger (width or height), to adjust to mobile orientation changes (portrait vs landscape).

  For example, when UIReferenceWidth = 1600 and UIReferenceHeight = 900, then it will adjust to 1600x900 when device is in landscape mode (width > height), and to 900x1600 when device is in portrait mode (width < height).

  In effect, in contrast to usEncloseReferenceSize:

  • Advantage: On mobile devices, if you allow user to switch between portrait and landscape, the UI will have the same physical size in both portrait and landscape modes. So it looks better on mobile.

  • Disadvantage: Designing for this is a bit harder than for usEncloseReferenceSize, as you need to test both portrait (width smaller than height) and landscape (width bigger than height), as they result in different calculations.

  This is different from usEncloseReferenceSize only when both TCastleContainer.UIReferenceWidth and TCastleContainer.UIReferenceHeight are set to non-zero values. When one of them is zero, then both usEncloseReferenceSize and usEncloseReferenceSizeAutoOrientation behave the same, they just adjust scaling based on this one non-zero reference size.

• usFitReferenceSize: Scale to fake that the container sizes fit inside TCastleContainer.UIReferenceWidth and TCastleContainer.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 TCastleContainer.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 TCastleContainer.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 TCastleContainer.Dpi.

  This allows to adjust controls to:

  • The physical size. TCastleContainer.Dpi on iOS and Android really reflects physical size.

  • Or at least to follow user preferred UI scaling. TCastleContainer.Dpi on desktops 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 or native applications.

Things that can cause TCastleUserInterface.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 size 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.

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

Warning: this symbol is deprecated: use TCastleUserInterface

Warning: this symbol is deprecated: use TCastleUserInterface

Warning: this symbol is deprecated: use TCastleUserInterface

Warning: this symbol is deprecated: use TCastleUserInterface

Warning: this symbol is deprecated: use TCastleUserInterface

Warning: this symbol is deprecated: use TCastleUserInterface

Warning: this symbol is deprecated: use TCastleUserInterfaceChange

Warning: this symbol is deprecated: use TCastleUserInterfaceChanges

Warning: this symbol is deprecated: use TCastleUserInterfaceList

Warning: this symbol is deprecated: use TCastleUserInterfaceChangeEvent

Warning: this symbol is deprecated: use TCastleContainer

Type of theme image, use of TCastleTheme.ImagesPersistent.

Values

• tiPanel
• tiPanelSeparator
• tiButtonPressed
• tiButtonDisabled
• tiButtonFocused
• tiButtonNormal
• tiWindow
• tiScrollbarFrame
• tiScrollbarSlider
• tiSliderBackground
• tiSliderThumb
• tiLabel
• tiGroup
• tiActiveFrame
• tiTooltip
• tiTouchCtlInner
• tiTouchCtlOuter
• tiTouchCtlFlyInner
• tiTouchCtlFlyOuter
• tiCrosshair1
• tiCrosshair2
• tiSquareEmpty
• tiSquareChecked
• tiSquarePressedBackground
• tiLoading: Image displayed when the application is initializing, during Application.OnInitialize and Window.OnOpen. And TCastleUserInterface.GLContextOpen for all initially present UI controls. This "loading image" is loaded and displayed first, so that user does not see a black screen while the resources are prepared.

  It is especially useful on Android, where we can lose the OpenGL context at any moment, as user may switch applications in the middle of the game. When getting back to the application, we need to initiailize some resources, and during this process we also show this image. So this serves as a universal "please wait, we're loading" screen.

  You can customize this image, by setting Theme.ImagesPersistent[tiLoading].Image, LoadingBackgroundColor, LoadingTextColor. See https://castle-engine.io/manual_2d_user_interface.php#section_theme for a sample code that sets a theme image.

  Note that the customization of this image should be done before Application.OnInitialize has started, so it has to be usually done from the "initialization" section of some unit. And in the "initialization" section of a unit, you cannot load files (doing LoadImage at this point may fail on some Android devices, as we cannot load assets before activity is started). So you can only assign images already available in code — use image-to-pascal tool to convert any image to a Pascal code for this purpose.

• tiEdit: TCastleEdit frame.

Default value for container's Dpi, as is usually set on desktops.

Warning: this symbol is deprecated: use tiSliderBackground

Warning: this symbol is deprecated: use tiSliderThumb

Warning: this symbol is deprecated.

Warning: this symbol is deprecated.

Warning: this symbol is deprecated.

Warning: this symbol is deprecated.