Castle Game EngineIntroduction Units Class Hierarchy Classes, Interfaces, Objects and Records Types Variables Constants Functions and Procedures Identifiers |
Class TUIControl
Unit
CastleUIControls
Declaration
type TUIControl = class(TInputListener)
Description
Basic user interface control class. All controls derive from this class, overriding chosen methods to react to some events. Various user interface containers (things that directly receive messages from something outside, like operating system, windowing library etc.) implement support for such controls.
Control may handle mouse/keyboard input, see Press and Release methods.
Various methods return boolean saying if input event is handled. The idea is that not handled events are passed to the next control suitable. Handled events are generally not processed more — otherwise the same event could be handled by more than one listener, which is bad. Generally, return ExclusiveEvents if anything (possibly) was done (you changed any field value etc.) as a result of this, and only return False when you're absolutely sure that nothing was done by this control.
All screen (mouse etc.) coordinates passed here should be in the usual window system coordinates, that is (0, 0) is left-top window corner. (Note that this is contrary to the usual OpenGL 2D system, where (0, 0) is left-bottom window corner.)
Hierarchy
Overview
Methods
Properties
 |
property GLInitialized: boolean read FGLInitialized default false; |
 |
property DisableContextOpenClose: Cardinal
read FDisableContextOpenClose write FDisableContextOpenClose; |
 |
property Focused: boolean read FFocused write SetFocused; |
 |
property Exists: boolean read FExists write SetExists default true; |
Description
Methods
 |
constructor Create(AOwner: TComponent); override; |
|
 |
destructor Destroy; override; |
|
 |
function PositionInside(const X, Y: Integer): boolean; virtual; |
Is given position inside this control. Returns always False in this class.
|
 |
procedure BeforeDraw; virtual; |
Prepare your resources, right before drawing.
|
 |
procedure Draw; virtual; |
Draw a control. If you want your Draw called automatically by the window, return something <> dsNone from DrawStyle, and draw your control inside Draw.
Do's and don't's when implementing Draw:
All controls with DrawStyle = ds3D are drawn first, with projection that you set yourself. Usually you should use TCastleSceneManager, which sets projection automatically for you to something suitable, see TCastleSceneManager.ApplyProjection and TCastleScene.GLProjection.
Then all the controls with DrawStyle = ds2D are drawn. For them, OpenGL viewport and projection are guaranteed to be set to standard 2D that fills the whole screen, like by
glViewport(0, Container.Width, 0, Container.Height);
OrthoProjection(0, Container.Width, 0, Container.Height);
The only OpenGL state you can change carelessly is:
The modelview matrix value.
The raster position.
The color (glColor), material (glMaterial) values.
The line width, point size.
Every other change should be wrapped in appropriate glPushAttrib / glPopAttrib.
Things that are guaranteed about OpenGL state when Draw is called:
The current matrix is modelview, and it's value is identity.
Only for DrawStyle = ds2D: the raster position is at (0, 0).
Only for DrawStyle = ds2D: Texturing, depth test, lighting are turned off.
If you require anything else, set this yourself.
When GetExists is False , remember to do nothing in Draw, and return dsNone in DrawStyle.
|
 |
function TooltipStyle: TUIControlDrawStyle; virtual; |
Draw a tooltip of this control. If you want to have tooltip for this control detected, you have to override TooltipStyle to return something <> dsNone. Then the TCastleWindowBase.TooltipVisible will be detected, and your DrawTooltip will be called.
So you can draw your tooltip either in overridden DrawTooltip, and/or somewhere else when you see that TCastleWindowBase.TooltipVisible is True . (Tooltip is always drawn for TCastleWindowBase.Focus control.) But in both cases, make sure to override TooltipStyle to return something <> dsNone.
The values of ds2D and ds3D are interpreted in the same way as DrawStyle. And DrawTooltip is called in the same way as Draw. DrawTooltip is always called as a last (front-most) 2D or 3D control.
|
 |
procedure DrawTooltip; virtual; |
|
 |
procedure GLContextOpen; virtual; |
Initialize your OpenGL resources.
This is called when OpenGL context of the container is created. Also called when the control is added to the already existing context. In other words, this is the moment when you can initialize OpenGL resources, like display lists, VBOs, OpenGL texture names, etc.
|
 |
procedure GLContextClose; virtual; |
Destroy your OpenGL resources.
Called when OpenGL context of the container is destroyed. Also called when controls is removed from the container Controls list. Also called from the destructor.
You should release here any resources that are tied to the OpenGL context. In particular, the ones created in GLContextOpen.
|
 |
procedure SetFocused(const Value: boolean); virtual; |
Called when this control becomes or stops being focused. In this class, they simply update Focused property.
|
Properties
 |
property GLInitialized: boolean read FGLInitialized default false; |
|
 |
property DisableContextOpenClose: Cardinal
read FDisableContextOpenClose write FDisableContextOpenClose; |
When non-zero, container will not call GLContextOpen and GLContextClose (when control is added/removed to/from the Controls list).
This is useful, although should be used with much caution: you're expected to call controls GLContextOpen / GLContextClose on your own when this is non-zero. Example usage is when the same control is often added/removed to/from the Controls list, and the window (with it's OpenGL context) stays open for a longer time. In such case, default (when DisableContextOpenClose = 0) behavior will often release (only to be forced to reinitialize again) OpenGL resources of the control. Some controls have large OpenGL resources (for example TCastleScene keeps display lists, textures etc., and TCastlePrecalculatedAnimation keeps all the scenes) — so constantly reinitializing them may eat a noticeable time.
By using non-zero DisableContextOpenClose you can disable this behavior.
In particular, TGLMode uses this trick, to avoid releasing and reinitializing OpenGL resources for controls only temporarily removed from the TCastleWindowCustom.Controls list.
|
 |
property Focused: boolean read FFocused write SetFocused; |
|
 |
property Exists: boolean read FExists write SetExists default true; |
Not existing control is not visible, it doesn't receive input and generally doesn't exist from the point of view of user. You can also remove this from controls list (like TCastleWindowCustom.Controls), but often it's more comfortable to set this property to false.
|
Generated by PasDoc 0.12.1 on 2013-02-04 20:26:52
|