Castle Game Engine: CastleWindow

# Unit CastleWindow
Description | Uses | Classes, Interfaces, Objects and Records | Functions and Procedures | Types | Constants | Variables
5. ## Description Window with OpenGL context suitable for 2D and 3D rendering of "Castle Game Engine". Provides a window with OpenGL context that can contain 2D controls and 3D objects defined by our engine. TCastleWindowCustom is the base window class, and TCastleWindow is a comfortable class that adds a ready scene manager. Application object (instance of class TCastleApplication) is a central manager of all open TCastleWindowCustom windows. Using this unit: Declare and create TCastleWindowCustom instance. (Or a descendant like TCastleWindow.) Assign Window properties and callbacks like OnRender, OnResize, Width, Height, Caption. To initialize your game, you usually want to use Application.OnInitialize. If you only care about standalone programs (for normal OSes like Linux, Windows, MacOSX, but not Android) you may also just initialize your game in the main program block, although using Application.OnInitialize is still often comfortable. Call Window.Open, this will actually show the window and it's associated OpenGL context. The first window open calls Application.OnInitialize. It also calls OnOpen and OnResize callbacks. Call Application.Run. This will enter message loop that will call appropriate windows' callbacks at appropriate times (OnRender, OnPress, OnRelease, OnResize, OnUpdate and many more). There are also some Application callbacks, like Application.OnUpdate. For more advanced needs you can use something like
         while Application.ProcessMessage do <something>;
instead of Application.Run. You can also call Window.OpenAndRun, this is just a shortcut for Window.Open + Application.Run. Application.Run ends when you call Application.Quit or when you close last visible window using Close(true). User is also allowed to close a window using WindowManager facilities (clicking on "X" button in the frame corner, pressing Alt+F4 or something like that). By default, such user action will make window close (but you can freely customize what your program does when user tries to close the window using callback OnCloseQuery). So the simplest example of using this unit can look like this:
      uses CastleWindow;

      var
        Window: TCastleWindowCustom;

      procedure Render(Sender: TUIContainer);
      begin  ...  end;

      procedure Resize(Sender: TUIContainer);
      begin  ...  end;

      begin
        Window := TCastleWindowCustom.Create(Application);
        Window.OnResize := @Resize;
        Window.OnRender := @Render;
        Window.Caption := 'Simplest CastleWindow example';
        Window.OpenAndRun;
      end.
More component-like approach: For larger programs, it makes more sense to divide functionality into controls, which are classes descending from TUIControl. You can override TUIControl methods to render, capture input and so on (see e.g. TUIControl.Render, TInputListener.Press, TInputListener.Update.) You can then add your control to the TCastleWindowCustom.Controls list. Some features list: TCastleApplication.ProcessMessage method. This allows you to reimplement event loop handling, which is crucial for implementing things like MessageInputQuery function that does modal GUI dialog box. TCastleWindowCustom.Pressed to easily and reliably check which keys are pressed. Frames per second measuring, see TCastleWindowCustom.Fps, A menu bar under WinAPI and GTK backends. 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 TCastleWindowCustom.MainMenu property. When `CastleWindow` is implemented on top of GTK_2 or WINAPI or LCL we will show this menu and call TCastleWindowCustom.OnMenuClick when user clicks some menu item. Other backends (XLIB for now) ignore MainMenu. See `castle_game_engine/examples/window/window_menu.lpr` for an example how to use the menu. Changing screen resolution and bit depth, see TCastleApplication.VideoChange. You can request OpenGL context properties: color buffer with alpha channel (AlphaBits), stencil buffer (StencilBits), double buffer (DoubleBuffer), multisampling (full-screen antialiasing) buffers (by MultiSampling or higher-level AntiAliasing) You can use native modal dialogs for things such as file selection. GTK backend will use GTK dialogs, WinAPI backend will use Windows dialog boxes, XLib backend will fall back on CastleMessages text input. See TCastleWindowCustom.FileDialog (for opening and saving files) and TCastleWindowCustom.ColorDialog (for choosing RGB colors). TCastleWindowCustom.ParseParameters method allows you to easily initialize TCastleWindowCustom properties like initial size and position using command-line parameters like `--geometry WIDTHxHEIGHT`, `--display` etc. ## Uses Glib2 Gdk2 Gtk2 GdkGLExt GtkGLExt CastleDynLib Gdk2X X Xlib SysUtils Classes CastleVectors GL GLU GLExt CastleRectangles CastleColors CastleUtils CastleClassUtils CastleGLUtils CastleImages CastleGLImages CastleKeysMouse CastleStringUtils CastleFilesUtils CastleTimeUtils CastleFileFilters CastleUIControls CastleGLContainer CastleCameras FGL pk3DConnexion X3DNodes CastleScene CastleSceneManager CastleLevels ## 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 TCastleWindowCustom.FullScreen.
Class `EGLContextNotPossible` |
Class `TCastleWindowCustom` | Window with an OpenGL context.
Class `TCastleWindow` | Window with an OpenGL context, most comfortable to render 3D worlds with 2D controls above.
Class `TWindowList` |
Class `TCastleApplication` | Application, managing all open TCastleWindowCustom (OpenGL windows).
Class `TCastleClipboard` | Clipboard for cut / copy / paste of text.
### Functions and Procedures
`function Application: TCastleApplication;`
`function Clipboard: TCastleClipboard;`
`procedure Resize2D(Container: TUIContainer);`
`function KeyString(const CharKey: char; const Key: TKey; const Modifiers: TModifierKeys; out S: string): boolean;`
`function MenuItemFromSmallId(SearchSmallId: Integer): TMenuItem;`
`function SRemoveMnemonics(const S: string): string;`
`function SQuoteMenuEntryCaption(const S: string): string;`
### Types
`TWindowParseOption = (...);`
`TWindowParseOptions = set of TWindowParseOption;`
`PWindowParseOptions = ˆTWindowParseOptions;`
`TAntiAliasing = (...);`
`TUIContainer = CastleUIControls.TUIContainer;`
`TMenuEntryList = specialize TFPGObjectList<TMenuEntry>;`
`TWindowMessageType = (...);`
`TUpdateFunc = procedure;`
`TMenuClickFunc = procedure (Container: TUIContainer; Item: TMenuItem);`
`TDropFilesFunc = procedure (Container: TUIContainer; const FileNames: array of string);`
`TGLContextRetryOpenFunc = function (Window: TCastleWindowCustom): boolean;`
`TResizeAllowed = (...);`
`PGtkGLArea = PGtkWidget;`
`TCastleWindowBase = TUIContainer deprecated;`
`TGLApplication = TCastleApplication deprecated;`
### Constants
`WindowPositionCenter = -1000000;`
`WindowDefaultSize = -1000000;`
`StandardParseOptions = [poGeometry, poScreenGeometry, poDisplay, poMacOsXProcessSerialNumber];`
`DefaultDepthBits = 16;`
`DefaultFpsCaptionUpdateInterval = 5000;`
`DefaultLimitFPS = 100.0;`
`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 Clipboard: TCastleClipboard;`
Single global instance of TCastleClipboard. Automatically created / destroyed by CastleWindow unit.
`procedure Resize2D(Container: TUIContainer);`
A simple TCastleWindowCustom.OnResize callback implementation, that sets 2D projection. You can use it like `Window.OnResize := `Resize2D`;` or just by calling it directly from your OnResize callback. It does
      glViewport(Window.Rect);
      OrthoProjection(0, Window.Width, 0, Window.Height);
`function KeyString(const CharKey: char; const Key: TKey; const Modifiers: TModifierKeys; out S: string): boolean;`
Describe given key. Key is given as combination of character code (may be #0) and Key code (may be K_None), and additional required `Modifiers` (although some modifiers may be already implied by CharKey). See TMenuItem.Key and TMenuItem.CharKey and TMenuItem.Modifiers. Only when both CharKey = #0 and Key = K_None then this combination doesn't describe any key, and we return `False`. Otherwise we return `True` and set S.
`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
`TWindowParseOption = (...);`
###### Values poGeometry: poScreenGeometry: poDisplay: poMacOsXProcessSerialNumber:
`TWindowParseOptions = set of TWindowParseOption;`
`PWindowParseOptions = ˆTWindowParseOptions;`
`TAntiAliasing = (...);`
Anti-aliasing values for TCastleWindowCustom.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.TUIContainer;`
Expose `TUIContainer` type from CastleWindow unit, since almost all code using CastleWindow will need to use `TUIContainer` type for callback parameter type.
`TMenuEntryList = specialize TFPGObjectList<TMenuEntry>;`
`TWindowMessageType = (...);`
Type of message box, for TCastleWindowCustom.MessageOK and TCastleWindowCustom.MessageYesNo. ###### Values mtInfo: mtWarning: mtQuestion: mtError: mtOther:
`TUpdateFunc = procedure;`
`TMenuClickFunc = procedure (Container: TUIContainer; Item: TMenuItem);`
`TDropFilesFunc = procedure (Container: TUIContainer; const FileNames: array of string);`
`TGLContextRetryOpenFunc = function (Window: TCastleWindowCustom): boolean;`
`TResizeAllowed = (...);`
###### Values raNotAllowed: raOnlyAtOpen: raAllowed:
`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.
`TCastleWindowBase = TUIContainer deprecated;`
Warning: this symbol is deprecated. . In new programs, use TUIContainer as a parameter for callbacks, and TCastleWindowCustom or TCastleWindow as window class.
`TGLApplication = TCastleApplication deprecated;`
Warning: this symbol is deprecated. Deprecated name for TCastleApplication.
### Constants
`WindowPositionCenter = -1000000;`
`WindowDefaultSize = -1000000;`
`StandardParseOptions = [poGeometry, poScreenGeometry, poDisplay, poMacOsXProcessSerialNumber];`
All "normal" command-line options, that most programs using CastleWindow should be able to handle without any problems. In other words, most programs calling TCastleWindowCustom.ParseParameters method can safely pass as the 1st parameter this constant, `StandardParseOptions`. Or they can simply call overloaded version of TCastleWindowCustom.ParseParameters that doesn't take any parameters, it is always equivalent to calling TCastleWindowCustom.ParseParameters(`StandardParseOptions`).
`DefaultDepthBits = 16;`
`DefaultFpsCaptionUpdateInterval = 5000;`
`DefaultLimitFPS = 100.0;`
`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)' );`
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:13