Castle Game Engine: CastleUIControls: Class TUIControl

# Class TUIControl
Description | Hierarchy | Fields | Methods | Properties
## 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 TComponent TInputListener TUIControl ## Overview ### Methods
| `constructor Create(AOwner: TComponent); override;`
| `destructor Destroy; override;`
| `function PositionInside(const X, Y: Integer): boolean; virtual;`
| `procedure BeforeDraw; virtual;`
| `procedure Draw; virtual;`
| `function DrawStyle: TUIControlDrawStyle; virtual;`
| `function TooltipStyle: TUIControlDrawStyle; virtual;`
| `procedure DrawTooltip; virtual;`
| `procedure GLContextOpen; virtual;`
| `procedure GLContextClose; virtual;`
| `procedure SetFocused(const Value: boolean); virtual;`
### 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). This is (0, 0) in window coordinates, see SetWindowPos. 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 DrawStyle: TUIControlDrawStyle; virtual;`
| `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, so e.g. you can safely assume that modelview matrix is identity and (for 2D) raster is zero. 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.13.0 on 2013-08-17 21:27:14