Class TCastleApplicationProperties

Unit

Declaration

type TCastleApplicationProperties = class(TObject)

Description

Events and properties of the Castle Game Engine application, usually accessed through the ApplicationProperties singleton.

These members work regardless if you use CastleWindow or CastleControl. For more fine-grained application control, see TCastleApplication (in case you use CastleWindow) or Lazarus (LCL) TApplication (in case you use CastleControl).

Hierarchy

Overview

Fields

Public nested const DefaultLimitFPS = 100.0;
Public nested const PlatformAllowsModalRoutines = true ;

Methods

Public constructor Create;
Public destructor Destroy; override;
Public procedure WriteWarningOnConsole(const Category, Message: String);
Public function Description: String;

Properties

Public property ApplicationName: String read GetApplicationName write SetApplicationName;
Public property Caption: String read FCaption write FCaption;
Public property Version: String read FVersion write FVersion;
Public property TouchDevice: boolean read FTouchDevice write FTouchDevice;
Public property ShowUserInterfaceToQuit: Boolean read FShowUserInterfaceToQuit write FShowUserInterfaceToQuit;
Public property LimitFPS: Single read FLimitFPS write FLimitFPS default DefaultLimitFPS ;
Public property OnGLContextOpen: TGLContextEventList read FOnGLContextOpen;
Public property OnGLContextOpenObject: TNotifyEventList read FOnGLContextOpenObject;
Public property OnGLContextClose: TGLContextEventList read FOnGLContextClose;
Public property OnGLContextCloseObject: TNotifyEventList read FOnGLContextCloseObject;
Public property IsGLContextOpen: boolean read FIsGLContextOpen;
Public property OnUpdate: TNotifyEventList read FOnUpdate;
Public property OnInitializeJavaActivity: TNotifyEventList read FOnInitializeJavaActivity;
Public property OnPause: TNotifyEventList read FOnPause;
Public property OnResume: TNotifyEventList read FOnResume;
Public property OnWarning: TWarningEventList read FOnWarning;
Public property OnLog: TLogEventList read FOnLog;

Description

Fields

Public nested const DefaultLimitFPS = 100.0;
 
Public nested const PlatformAllowsModalRoutines = true ;

Some platforms do not support Application.ProcessMessages, which means you cannot just write a function like MessageYesNo that waits until user clicks something. You *have* to implement modal boxes then using states, e.g. using CastleDialogStates or your own TUIState descendants.

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 
Public procedure WriteWarningOnConsole(const Category, Message: String);

Add this to OnWarning to output warnings to standard output (usually, console). Eventually, on GUI Windows programs, it will make a dialog box. This is handled by WarningWrite procedure.

Public function Description: String;

Print some common information about application, for example to use in –help command-line output. It shows application name, version, CGE version, compiler version, platform.

Includes the output of SCompilerDescription and SPlatformDescription.

Properties

Public property ApplicationName: String read GetApplicationName write SetApplicationName;

Application short name. Used e.g. by InitializeLog to name the log file.

When compiled with FPC, this returns and sets the same thing as standard SysUtils.ApplicationName. When setting this, we automatically set SysUtils.OnGetApplicationName.

Public property Caption: String read FCaption write FCaption;

Pretty application name, to show to user e.g. as a window caption.

Public property Version: String read FVersion write FVersion;

Version of this application. It may be used e.g. by InitializeLog and TCastleApplication.ParseStandardParameters.

Public property TouchDevice: boolean read FTouchDevice write FTouchDevice;

Initialized to True on touch devices (Android, iOS, Nintendo Switch).

A "touch device" means that:

As a debugging feature, you can set this to True to simulate touch devices on a desktop. The idea is that when an application shows a different input behavior on touch devices, it should always condition it depending on this boolean property. So an application may do this:

Viewport.WalkCamera.MouseLook := not ApplicationProperties.TouchDevice;

And to test on desktop whether everything behaves OK on mobile, you can just earlier call this:

if FakeTouchDeviceOnDesktop then
  ApplicationProperties.TouchDevice := true;

Public property ShowUserInterfaceToQuit: Boolean read FShowUserInterfaceToQuit write FShowUserInterfaceToQuit;

Is it common, on current platform, to show the "Quit" button in your application. E.g. it is normal to show "Quit" on PC (Windows, Linux etc.). But on mobile devices and consoles (like Nintendo Switch) you should not show "Quit", it is expected that user knows how to use OS-specific mechanism to just switch to a different application.

Just like the TouchDevice, you can change this at runtime for debug purposes (to e.g. easily test mobile UI on PC).

Public property LimitFPS: Single read FLimitFPS write FLimitFPS default DefaultLimitFPS ;

Limit the number of (real) frames per second, to not hog the CPU. Set to zero to not limit.

The mechanism is implemented by occasionally sleeping (when we see that we render way faster than we need to). So it's a global thing, not just a property of TCastleWindow or TCastleControl.

In some cases, this also means the "desired number of FPS". This happens when we may be clogged with events (which is especially possible in case of mouse look, when we use CastleControl, or when we use CastleWindow with LCL backend). In such cases we try hard to call "update" and (if necessary) "render" events at least as often as LimitFPS. When LimitFPS is used for this purpose ("desired number of FPS, not just a limit"), it is also capped (by 100.0).

Public property OnGLContextOpen: TGLContextEventList read FOnGLContextOpen;

Callbacks called when the OpenGL context is opened or closed. Use when you want to be notified about OpenGL context availability, but cannot refer to a particular instance of TCastleControl or TCastleWindow.

Note that we may have many OpenGL contexts (many TCastleWindow or TCastleControl instances) open simultaneously. They all share OpenGL resources. OnGLContextOpen is called when first OpenGL context is open, that is: no previous context was open. OnGLContextClose is called when last OpenGL context is closed, that is: no more contexts remain open. Note that this implies that they may be called many times: e.g. if you open one window, then close it, then open another window then close it.

Callbacks on OnGLContextOpen are called from first to last. Callbacks on OnGLContextClose are called in reverse order, so OnGLContextClose[0] is called last.

Public property OnGLContextOpenObject: TNotifyEventList read FOnGLContextOpenObject;
 
Public property OnGLContextClose: TGLContextEventList read FOnGLContextClose;
 
Public property OnGLContextCloseObject: TNotifyEventList read FOnGLContextCloseObject;
 
Public property IsGLContextOpen: boolean read FIsGLContextOpen;

Is the OpenGL context available. IOW, we are between the first OnGLContextOpen and last OnGLContextClose.

Public property OnUpdate: TNotifyEventList read FOnUpdate;

Callbacks called continuously when (at least one) window is open.

You can use this just like TCastleControl.OnUpdate or TCastleWindow.OnUpdate or TCastleApplication.OnUpdate.

Public property OnInitializeJavaActivity: TNotifyEventList read FOnInitializeJavaActivity;

Callbacks called when Android Java activity started. Called every time a Java activity is created.

  • For the first time, it's called right before TCastleApplication.OnInitialize.

  • Later this is called when Java activity died (and is restarting now), but the native code thread survived. So all native code memory is already cool (no need to call TCastleApplication.OnInitialize), but we need to reinitialize Java part.

    Note that this is different from TCastleWindow.OnOpen. We lose OpenGL context often, actually every time user switches to another app, without having neither Java nor native threads killed.

For non-Android applications, this is simply always called exactly once, exactly before calling TCastleApplication.OnInitialize.

Public property OnPause: TNotifyEventList read FOnPause;

Callbacks called when Android Java activity is paused or resumed. For now not called on non-Android, but this may change — consider these events somewhat internal for the time being.

Public property OnResume: TNotifyEventList read FOnResume;
 
Public property OnWarning: TWarningEventList read FOnWarning;

Events called upon WritelnWarning.

Public property OnLog: TLogEventList read FOnLog;

Events called upon any WritelnLog, including WritelnWarning.


Generated by PasDoc 0.16.0.