API Reference

Unit CastleWindow

Description
Uses
Classes, Interfaces, Objects and Records
Functions and Procedures
Types
Constants
Variables

Description

Defines TCastleWindow class: a window for rendering, processing of inputs, and generally the primary way to display your "Castle Game Engine" application.

Technically speaking, most of the TCastleWindow job is to initialize rendering context (like OpenGL, OpenGLES context) and to manage a hierarchy of user interface controls (TCastleUserInterface). When necessary, it calls the proper methods of these controls to render, process inputs, and so on.

Usage:

You usually do not need to write code to create an instance of this class yourself. Just create a new project (using "New Project" in CGE editor, or using castle-engine create NEW-PROJECT-NAME command-line). The recommended code to create and initialize a single TCastleWindow instance will be already there. It basically

Most of the code you write will be inside a "view", see https://castle-engine.io/view_events . This view is just a TCastleUserInterface instance inside a TCastleWindow, and that's where you can override methods like TCastleUserInterface.Render, TCastleUserInterface.Press, TCastleUserInterface.Update.

Application singleton:

This unit also defines a singleton Application object (instance of class TCastleApplication), which is a central manager of all open TCastleWindow windows.

You don't need to use the Application object directly in most cases. The new projects will contain a unit GameInitialize that performs the initialization of your application in a routine called ApplicationInitialize, assigned to the Application.OnInitialize. This is the place to do a global initialization (that doesn't fit to be put in any view's Start method).

Multiple windows:

Desktop applications are generally free to create and open as many TCastleWindow instances as they want. Mobile and console applications are limited to a single TCastleWindow instance which shall be assigned to the Application.MainWindow property.

Window features:

Features of TCastleWindow and TCastleApplication include:

  • Each window has its own rendering context. OpenGL and OpenGLES context can be initialized by each window.

  • Window handles system events like key presses, mouse presses and movement, touch events on mobile.

  • Window sends events when it needs to be redrawn and when it has been resized.

  • TCastleWindow.Pressed information is available to always check which keys re pressed.

  • Application speed is automatically measured, see TCastleWindow.Fps,

  • On desktops you can create multiple windows, each with its own rendering context. All the windows share rendering resources (like textures).

  • On desktops (and Android) you can use TCastleApplication.ProcessMessage to implement modal dialog boxes as routines that block the event loop until the dialog is closed. To do this, you can run a loop like this: 

    while Application.ProcessMessage do <something>;

  • Multiple backends are available (WinAPI, GTK 2, Cocoa, LCL, FMX, Xlib...), see CastleWindow Backends. There's also a special backend CASTLE_WINDOW_LIBRARY that allows to use existing OpenGL(ES) context created by some other code (e.g. Objective-C code on iOS).

  • Some backends support a menu bar. Consult CastleWindow Backends to learn which backends support menus.

    You can attach a menu to a window. Menu structure is constructed using various descendants of TMenuEntry class. Then you have to assign such menu structure to TCastleWindow.MainMenu property. Assign TCastleWindow.OnMenuItemClick to handle what happens when the user clicks some menu item.

    See examples/window/window_menu/ for an example how to use the menu.

  • Changing screen resolution and bit depth is possible on some platforms, see TCastleApplication.VideoChange. Consult CastleWindow Backends to learn which backends support this feature.

  • You can request OpenGL(ES) context properties:

  • You can use native modal dialogs for things such as file selection. Consult CastleWindow Backends to learn which backends support this feature.

    We will use native dialogs,like GTK or WinAPI dialogs, if available. So these dialogs look and behave good on all platforms.

    See TCastleWindow.FileDialog (for opening and saving files) and TCastleWindow.ColorDialog (for choosing RGB colors).

  • TCastleWindow.ParseParameters method allows you to easily initialize TCastleWindow properties like initial size and position using command-line parameters like --geometry WIDTHxHEIGHT, --display etc.

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class TMenuEntry A basic class representing basic menu building block.
Class TMenuEntryWithCaption  
Class TMenu TMenuEntry that contains a list of menu entries.
Class TMenuItem TMenuEntry that is a simple, clickable menu item.
Class TMenuSeparator TMenuEntry that acts as a visual separator (horizontal line or something like that) between menu items.
Class TMenuItemChecked TMenuItem that should visualize Checked state somehow to the user.
Class TMenuItemRadio Menu radio item.
Class TMenuItemRadioGroup A group of radio buttons.
Class TMenuItemToggleFullScreen Menu item that toggles TCastleWindow.FullScreen.
Class EGLContextNotPossible  
Class TWindowContainer Container suitable to be used in TCastleWindow.
Class TCastleWindow Window to render everything (3D or 2D) with Castle Game Engine.
Class TWindowList  
Class TCastleApplication Application, managing all open TCastleWindow (OpenGL windows).

Functions and Procedures

function Application: TCastleApplication;
function KeyToString(const KeyString: String; const Key: TKey; const Modifiers: TModifierKeys; out S: String): boolean;
function KeyString(const AKeyString: String; const Key: TKey; const Modifiers: TModifierKeys; out S: String): boolean; deprecated 'use KeyToString';
function MenuItemFromSmallId(SearchSmallId: Integer): TMenuItem;
function SRemoveMnemonics(const S: string): string;
function SQuoteMenuEntryCaption(const S: string): string;

Types

TAntiAliasing = (...);
TUIContainer = CastleUIControls.TCastleContainer deprecated 'use TCastleContainer';
TCastleContainer = CastleUIControls.TCastleContainer;
TMenuEntryList = specialize TObjectList<TMenuEntry>;
TWindowMessageType = (...);
TUpdateFunc = procedure;
TMenuClickFunc = procedure (Container: TCastleContainer; Item: TMenuItem);
TMenuItemClickEvent = procedure (const Item: TMenuItem) of object;
TDropFilesFunc = procedure (Container: TCastleContainer; const FileNames: array of string);
TGLContextRetryOpenFunc = function (Window: TCastleWindow): boolean;
TResizeAllowed = (...);
TCaptionPart = (...);
PGtkGLArea = PGtkWidget;
TCastleWindowCustom = TCastleWindow deprecated 'use TCastleWindow';
TCastleWindowBase = TCastleWindow deprecated 'use TCastleWindow';
TCastleWindowClass = class of TCastleWindow;
TGLApplication = TCastleApplication deprecated;

Constants

WindowPositionCenter = -1000000;
WindowDefaultSize = -1000000;
DefaultDepthBits = 24;
DepthBitsFallback = 16;
DefaultFpsCaptionUpdateDelay = 1.0;
DefaultLimitFPS = TCastleApplicationProperties.DefaultLimitFPS deprecated 'use TCastleApplicationProperties.DefaultLimitFPS';
DefaultAntiAliasing = aaNone;
AntiAliasingNames: array [TAntiAliasing] of string = ( 'None', '2 samples (faster)', '2 samples (nicer)', '4 samples (faster)', '4 samples (nicer)', '8 samples (faster) (only latest GPUs)', '8 samples (nicer) (only latest GPUs)', '16 samples (faster) (only latest GPUs)', '16 samples (nicer) (only latest GPUs)' );

Description

Functions and Procedures

function Application: TCastleApplication;

Single global instance of TCastleApplication. Automatically created / destroyed by CastleWindow unit.

function KeyToString(const KeyString: String; const Key: TKey; const Modifiers: TModifierKeys; out S: String): boolean;

Describe given key. Key is given as combination of character (UTF-8 character as String, may be '') and Key code (may be keyNone), and additional required Modifiers (although some modifiers may be already implied by KeyString, e.g. when it is CtrlA). See TMenuItem.Key and TMenuItem.KeyString and TMenuItem.Modifiers.

Only when Key = keyNone and KeyString = '' then this combination doesn't describe any key, and we return False. Otherwise we return True and set S.

function KeyString(const AKeyString: String; const Key: TKey; const Modifiers: TModifierKeys; out S: String): boolean; deprecated 'use KeyToString';

Warning: this symbol is deprecated: use KeyToString

This item has no description.

function MenuItemFromSmallId(SearchSmallId: Integer): TMenuItem;

Search for menu item with given SmallId. SearchSmallId must be a SmallId of some existing (i.e. created and not destroyed yet) TMenuItem. This function returns this TMenuItem.

function SRemoveMnemonics(const S: string): string;

Returns S with each '__' replaced with single '_', any other '_' removed.

In other words: with mnemonics (as defined by TMenuEntryWithCaption.Caption removed.

function SQuoteMenuEntryCaption(const S: string): string;

Returns S with each underscore '_' replaced by two underscores, '__'.

In other words: S will not contain any mnemonics. If you will assign S to TMenuEntryWithCaption.Caption, then this menu entry caption will display exactly S, without any mnemonics. Single '_' in S will be displayed exactly as single '_'.

Types

TAntiAliasing = (...);

Anti-aliasing values for TCastleWindow.AntiAliasing.

Values
  • aaNone
  • aa2SamplesFaster: 2 samples, "don't care" hint.
  • aa2SamplesNicer: 2 samples, "nicest" hint (quincunx (5 taps) for NVidia).
  • aa4SamplesFaster: 4 samples, "don't care" hint.
  • aa4SamplesNicer: 4 samples, "nicest" hint (9 taps for NVidia).
  • aa8SamplesFaster: 8 samples, "don't care" hint.
  • aa8SamplesNicer: 8 samples, "nicest" hint.
  • aa16SamplesFaster: 16 samples, "don't care" hint.
  • aa16SamplesNicer: 16 samples, "nicest" hint.
TUIContainer = CastleUIControls.TCastleContainer deprecated 'use TCastleContainer';

Warning: this symbol is deprecated: use TCastleContainer

This item has no description.

TCastleContainer = CastleUIControls.TCastleContainer;

This item has no description.

TMenuEntryList = specialize TObjectList<TMenuEntry>;

This item has no description.

TWindowMessageType = (...);

Type of message box, for TCastleWindow.MessageOK and TCastleWindow.MessageYesNo.

Values
  • mtInfo
  • mtWarning
  • mtQuestion
  • mtError
  • mtOther
TUpdateFunc = procedure;

This item has no description.

TMenuClickFunc = procedure (Container: TCastleContainer; Item: TMenuItem);

This item has no description.

TMenuItemClickEvent = procedure (const Item: TMenuItem) of object;

This item has no description.

TDropFilesFunc = procedure (Container: TCastleContainer; const FileNames: array of string);

This item has no description.

TGLContextRetryOpenFunc = function (Window: TCastleWindow): boolean;

This item has no description.

TResizeAllowed = (...);

This item has no description.

Values
  • raNotAllowed
  • raOnlyAtOpen
  • raAllowed
TCaptionPart = (...);

This item has no description.

Values
  • cpPublic
  • cpFps
PGtkGLArea = PGtkWidget;

For now I use GtkDrawingArea when CASTLE_WINDOW_GTK_2. But, really, GLAreaGtk could be any gtk widget with CASTLE_WINDOW_GTK_2.

TCastleWindowCustom = TCastleWindow deprecated 'use TCastleWindow';

Warning: this symbol is deprecated: use TCastleWindow

This item has no description.

TCastleWindowBase = TCastleWindow deprecated 'use TCastleWindow';

Warning: this symbol is deprecated: use TCastleWindow

This item has no description.

TCastleWindowClass = class of TCastleWindow;

This item has no description.

TGLApplication = TCastleApplication deprecated;

Warning: this symbol is deprecated.

Deprecated name for TCastleApplication.

Constants

WindowPositionCenter = -1000000;

This item has no description.

WindowDefaultSize = -1000000;

This item has no description.

DefaultDepthBits = 24;

This item has no description.

DepthBitsFallback = 16;

This item has no description.

DefaultFpsCaptionUpdateDelay = 1.0;

This item has no description.

DefaultLimitFPS = TCastleApplicationProperties.DefaultLimitFPS deprecated 'use TCastleApplicationProperties.DefaultLimitFPS';

Warning: this symbol is deprecated: use TCastleApplicationProperties.DefaultLimitFPS

This item has no description.

DefaultAntiAliasing = aaNone;

This item has no description.

AntiAliasingNames: array [TAntiAliasing] of string = ( 'None', '2 samples (faster)', '2 samples (nicer)', '4 samples (faster)', '4 samples (nicer)', '8 samples (faster) (only latest GPUs)', '8 samples (nicer) (only latest GPUs)', '16 samples (faster) (only latest GPUs)', '16 samples (nicer) (only latest GPUs)' );

This item has no description.

Generated by PasDoc 0.16.0-snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.