Castle Game Engine: CastleWindow: Class TCastleApplication

# Class TCastleApplication
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleWindow ## Declaration `type TCastleApplication = class(TComponent)` ## Description Application, managing all open TCastleWindowCustom (OpenGL windows). This tracks all open instances of TCastleWindowCustom and implements message loop. It also handles some global tasks like managing the screen (changing current screen resolution and/or bit depth etc.) The only instance of this class should be in Application variable. Don't create any other instances of class `TCastleApplication`, there's no point in doing that. ## Hierarchy TComponent TCastleApplication ## Overview ### Fields
| `VideoResize: boolean;`
| `VideoResizeWidth: integer;`
| `VideoResizeheight: integer;`
### Methods
| `procedure Notification(AComponent: TComponent; Operation: TOperation); override;`
| `function VideoSettingsDescribe: string;`
| `function TryVideoChange: boolean;`
| `procedure VideoChange(OnErrorWarnUserAndContinue: boolean);`
| `procedure VideoReset;`
| `function ScreenHeight: integer;`
| `function ScreenWidth: integer;`
| `function OpenWindowsCount: integer;`
| `function ProcessMessage(WaitForMessage, WaitToLimitFPS: boolean): boolean;`
| `function ProcessAllMessages: boolean;`
| `procedure Quit;`
| `procedure Run;`
| `function BackendName: string;`
| `constructor Create(AOwner: TComponent); override;`
| `destructor Destroy; override;`
### Properties
| `property XDisplayName: string read FXDisplayName write FXDisplayName;`
| `property VideoColorBits: integer read FVideoColorBits write FVideoColorBits default 0;`
| `property VideoFrequency: Cardinal read FVideoFrequency write FVideoFrequency default 0;`
| `property OpenWindows[Index:integer]: TCastleWindowCustom read GetOpenWindows;`
| `property OnInitialize: TProcedure read FOnInitialize write FOnInitialize;`
| `property OnUpdate: TUpdateFunc read FOnUpdate write FOnUpdate;`
| `property OnIdle: TUpdateFunc read FOnUpdate write FOnUpdate; deprecated;`
| `property OnTimer: TProcedure read FOnTimer write FOnTimer;`
| `property TimerMilisec: Cardinal read FTimerMilisec write FTimerMilisec default 1000;`
| `property MainWindow: TCastleWindowCustom read FMainWindow write SetMainWindow;`
| `property LimitFPS: Single read FLimitFPS write FLimitFPS default DefaultLimitFPS;`
## Description ### Fields
| `VideoResize: boolean;`
If `VideoResize`, then next VideoChange call will try to resize the screen to given VideoResizeWidth / VideoResizeHeight. Otherwise, next TryVideoChange and VideoChange will use default screen size.
| `VideoResizeWidth: integer;`
| `VideoResizeheight: integer;`
### Methods
| `procedure Notification(AComponent: TComponent; Operation: TOperation); override;`
| `function VideoSettingsDescribe: string;`
Describe the changes recorded in variables VideoXxx, used by VideoChange and TryVideoChange. This is a multiline string, each line is indented by 2 spaces, always ends with CastleUtils.NL.
| `function TryVideoChange: boolean;`
Change the screen size, color bits and such, following the directions you set in VideoColorBits, VideoResize, VideoResizeWidth / VideoResizeHeight, and VideoFrequency variables. Returns `True` if success.
| `procedure VideoChange(OnErrorWarnUserAndContinue: boolean);`
Change the screen size, color bits and such, following the directions you set in VideoColorBits, VideoResize, VideoResizeWidth / VideoResizeHeight, and VideoFrequency variables. This actually just calls TryVideoChange and checks the result. If not success: if OnErrorWarnUserAndContinue then we'll display a warning and continue. If not OnErrorWarnUserAndContinue then we'll raise an Exception. ###### Exceptions raised `Exception` If video mode change failed, and OnErrorWarnUserAndContinue = false.
| `procedure VideoReset;`
Return default screen video mode. If you never called TryVideoChange (with success), then this does nothing. This is automatically called in Application.Destroy, so at finalization of this unit. This way your game nicely restores screen resolution for user.
| `function ScreenHeight: integer;`
| `function ScreenWidth: integer;`
| `function OpenWindowsCount: integer;`
List of all open windows.
| `function ProcessMessage(WaitForMessage, WaitToLimitFPS: boolean): boolean;`
Process messages from the window system. You have to call this repeatedly to process key presses, mouse events, redraws and everything else. Messages are processed and appropriate window callbacks are called, like TCastleWindowCustom.OnRender, TCastleWindowCustom.OnUpdate, TCastleWindowCustom.OnKeyPress and many others. For simple programs calling the Run method is usually the best solution, Run just calls `ProcessMessage` in a loop. Manually using the `ProcessMessage` method allows you to implement modal dialog boxes (generally any kind of "display something until something happens" behavior). Make your own event loop like this:
      while not SomethingHappened do
        Application.ProcessMessages(...);
Often this is used together with TGLMode, TGLModeFrozenScreen and similar utilities from CastleWindowModes unit. They allow you to temporarily replace window callbacks with new ones, and later restore the original ones. This is useful for behavior similar to modal dialog boxes. Returns `True` if we should continue, that is if Quit method was not called (directly or by closing the last window). If you want to check it (if you allow the user at all to close the application during modal box or such) you can do:
      while not SomethingHappened do
        if not Application.ProcessMessage(...) then
          Break;
Do not assume too much about message processing internals. For example, not all `ProcessMessage` calls cause redraw, even if redraw is requested by Invalidate. When we have messages to process, we generally don't call redraw or even OnUpdate. ###### Parameters WaitForMessage If `True` (and some other conditions are met, for example we do not have to call OnUpdate continuosly) then we can block, waiting for an event to process. Set this to `True` whenever you can, that is whenever your program only responds to user inputs (as opposed to making some operations, like animation or loading or ray-tracing something). Generally, when `SomethingHappened` from the example pseudo-code above can only be changed by user events (e.g. user has to click something; nothing happens if user doesn't click for 5 minutes or 5 hours). This allows to let OS and CPU have some rest, and spend time on other applications, or just sleep and conserve laptop battery power. WaitToLimitFPS If `True`, then we have backup mechanism for limiting CPU usage. When WaitForMessage mechanism cannot be used (becasue WaitForMessage is `False` or some other conditions disallow it), and user doesn't throw events at us (we don't want to sleep when user produces many events e.g. by mouse move), then we can do a small sleep to stabilize number of `ProcessMessage` calls at LimitFPS per second. Set this to `True` whenever you can, that is whenever you don't need `ProcessMessage` to return as fast as it can. For example, when you're displaying some animation, then displaying LimitFPS frames should be enough. OTOH, if you really do something that should be done as fast as possible (like loading some file or ray-tracing) you probably have to set this to `False`.
| `function ProcessAllMessages: boolean;`
Processes all pending messages. Do not wait for anything. Contrast this with ProcessMessage method, that processes only a single event. Or no event at all (when no events were pending and AllowSuspend = `False`). This means that after calling ProcessMessage once, you may have many messages left in the queue (especially mouse move together with key presses typically makes a lot of events). So it's not good to use if you want to react timely to some user requests, e.g. when you do something time-consuming and allow user to break the task with Escape key. `ProcessAllMessages` is like calling in a loop ProcessMessage(false, false), ends when ProcessMessage(false, false) didn't process any message or when quit was called (or last window closed). So `ProcessAllMessages` makes sure we have processed all pending events, thus we are up-to-date with window system requests.
| `procedure Quit;`
Close all open windows, make ProcessMessage return `False`, finish the Run method (if working), and thus finish the application work.
| `procedure Run;`
Run the program using TCastleWindowCustom, by doing the event loop. Think of it as just a shortcut for "while ProcessMessage do ;". Note that this does nothing if OpenWindowsCount = 0, that is there are no open windows. Besides the obvious reason (you didn't call TCastleWindowCustom.Open on any window...) this may also happen if you called Close (or Application.Quit) from your window OnOpen / OnResize callback. In such case no event would probably reach our program, and user would have no chance to quit, so Run just refuses to work and exits immediately without any error.
| `function BackendName: string;`
| `constructor Create(AOwner: TComponent); override;`
| `destructor Destroy; override;`
### Properties
| `property XDisplayName: string read FXDisplayName write FXDisplayName;`
Set XDisplay name, this will be used for all TCastleWindowCustom that will be subsequently initialized by TCastleWindowCustom.Open. Note that this is exposed by GTK even for non-XWindows platforms, but I don't know what it does there.
| `property VideoColorBits: integer read FVideoColorBits write FVideoColorBits default 0;`
Color bits per pixel that will be set by next VideoChange call, and that are tried to be used at TCastleWindowCustom.Open. Zero means that system default is used.
| `property VideoFrequency: Cardinal read FVideoFrequency write FVideoFrequency default 0;`
Video frequency to set in next VideoChange call. Leave as 0 to use system default.
| `property OpenWindows[Index:integer]: TCastleWindowCustom read GetOpenWindows;`
| `property OnInitialize: TProcedure read FOnInitialize write FOnInitialize;`
The backend is initialized. Called only once, at the very beginning of the game, when we're ready to load everything and the first OpenGL context is initialized (right before calling TCastleWindowCustom.OnOpen). For targets like Android or iOS or browser plugin, you should not do anything (even reading files) before this callback occurs. Only when this occurs, we know that external process told us "Ok, you're ready". So you should put all the game initialization in an Application.OnInitialize callback. It will be automatically called by CastleWindow backend when we're really ready (actually, a little later — when OpenGL context is active, to allow you to display progress bars etc. when loading).
| `property OnUpdate: TUpdateFunc read FOnUpdate write FOnUpdate;`
Continously occuring event. ###### See also TCastleWindowCustom.OnUpdate. Continously occuring event, called for all open windows.
| `property OnIdle: TUpdateFunc read FOnUpdate write FOnUpdate; deprecated;`
Warning: this symbol is deprecated. Deprecated name for OnUpdate.
| `property OnTimer: TProcedure read FOnTimer write FOnTimer;`
Event called approximately after each TimerMilisec miliseconds. The actual delay may be larger than TimerMilisec miliseconds, depending on how the program (and OS) is busy. You can of course change TimerMilisec (and `OnTimer`) even when some windows are already open.
| `property TimerMilisec: Cardinal read FTimerMilisec write FTimerMilisec default 1000;`
| `property MainWindow: TCastleWindowCustom read FMainWindow write SetMainWindow;`
Main window used for various purposes. On targets when only one TCastleWindowCustom instance makes sense (like Android), set this to the reference of that window. It is also used by TWindowProgressInterface to display progress bar.
| `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. To be more precise, this limits the number of TCastleApplication.ProcessMessage calls per second, in situations when we do not have to process any user input. So we limit not only rendering (TCastleWindowCustom.OnRender) but also other animation processing (TCastleWindowCustom.OnUpdate) calls per second. See TCastleApplication.ProcessMessage. In case of CastleWindow backends when we have to fight with event clogging (right now only LCL backend, used by default only on Mac OS X) this is also the "desired number of FPS": we make sure that even when application is clogged with events (like when dragging with mouse), we call update (TCastleWindowCustom.OnUpdate) and (if necessary) draw (TCastleWindowCustom.OnRender and related) at least as often. When `LimitFPS` is used for this purpose ("desired number of FPS"), it is also capped (by MaxDesiredFPS = 100.0).
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:13