Cafu Engine
WindowT Class Reference

A window is the basic element of a graphical user interface. More...

Public Member Functions

 AddChild (window child)
 This method adds the given window to the children of this window. More...
 
 RemoveChild (window child)
 This method removes the given window from the children of this window. More...
 
window GetParent ()
 This method returns the parent of this window (or nil if there is no parent). More...
 
table GetChildren ()
 This method returns an array of the children of this window. More...
 
number GetTime ()
 This method returns the windows local time (starting from 0.0). More...
 
ComponentBasicsT GetBasics ()
 This method returns the "Basics" component of this window. More...
 
ComponentTransformT GetTransform ()
 This method returns the "Transform" component of this window. More...
 
 AddComponent (ComponentBaseT component)
 This method adds a component to this window. More...
 
 RemoveComponent (ComponentBaseT component)
 This method removes a component from this window. More...
 
table GetComponents ()
 This method returns an array of the components of this window. More...
 
ComponentBaseT GetComponent (string type_name, number n)
 This method returns the (n-th) component of the given (type) name. More...
 

Event Handlers (Callbacks)

See the Event Handlers (Callbacks) overview page for additional information about the methods in this group.

 OnActivate ()
 Called for each window when the GUI is activated (i.e. switched on for rendering). More...
 
 OnDeactivate ()
 Called for each window when the GUI is deactivated. More...
 
 OnFocusGain ()
 This method is called when this window gains the keyboard input focus. More...
 
 OnFocusLose ()
 This method is called when this window loses the keyboard input focus. More...
 
 OnFrame ()
 Called on each frame that is rendered by the Cafu engine. More...
 
 OnInit ()
 This is the first method that is called for each window after a GUI has been loaded. More...
 
 OnInit2 ()
 This method is very much like OnInit(), but intended for your own custom use in the _main.cgui file. More...
 
boolean OnKeyPress (number Key)
 This method is called if a key was pressed and the window has the keyboard input focus. More...
 
boolean OnKeyRelease (number Key)
 Like OnKeyPress(), but for key releases. More...
 
boolean OnChar (number ch)
 This method is called when a character event occurred and the window has the keyboard input focus. More...
 
boolean OnMouseButtonDown (number button)
 This method is called when a mouse button went down (was pressed). More...
 
boolean OnMouseButtonUp (number button)
 This method is called when a mouse button went up (was released). More...
 
 OnMouseEnter ()
 This method is called when the mouse cursor enters the rectangle of the window. More...
 
 OnMouseLeave ()
 This method is called when the mouse cursor leaves the rectangle of the window. More...
 

Detailed Description

A window is the basic element of a graphical user interface.

Windows are hierarchically arranged in parent/child relationships to form complex user interfaces.

Each window essentially represents a rectangular shape, but only has very little features of its own. Instead, a window contains a set of components, each of which implements a specific feature for the window.

If you would like to create a new window explicitly (those defined in the CaWE GUI Editor are instantiated automatically), use GuiT::new():

local win = gui:new("WindowT", "my_window")
Implementing C++ Class:
cf::GuiSys::WindowT

Member Function Documentation

AddChild ( window  child)

This method adds the given window to the children of this window.

AddComponent ( ComponentBaseT  component)

This method adds a component to this window.

ComponentBasicsT GetBasics ( )

This method returns the "Basics" component of this window.

table GetChildren ( )

This method returns an array of the children of this window.

ComponentBaseT GetComponent ( string  type_name,
number  n 
)

This method returns the (n-th) component of the given (type) name.

Covers the "custom" components as well as the application components, "Basics" and "Transform". That is, GetComponent("Basics") == GetBasics() and GetComponent("Transform") == GetTransform().

Parameters
type_nameThe (type) name of the component to get, e.g. "Image".
nThis parameter is optional, it defaults to 0 if not given.
table GetComponents ( )

This method returns an array of the components of this window.

window GetParent ( )

This method returns the parent of this window (or nil if there is no parent).

number GetTime ( )

This method returns the windows local time (starting from 0.0).

ComponentTransformT GetTransform ( )

This method returns the "Transform" component of this window.

OnActivate ( )

Called for each window when the GUI is activated (i.e. switched on for rendering).

For example, when the user toggles the in-game console, this method is called every time the console GUI comes up.

boolean OnChar ( number  ch)

This method is called when a character event occurred and the window has the keyboard input focus.

The difference to OnKeyPress() and OnKeyRelease() is that these two just deals with plain keys, which is useful for example to work with the arrow keys. OnChar() however deals with entered characters, which for example take the state of the SHIFT key into account, language specific keyboard settings and layout, etc. Therefore, OnChar() is the preferred choice for text input.

  • Characters are represented as ASCII codes. That is, the integer values that ch may assume match the ASCII table.
  • You can use the string.char(ch) Lua library function in order to obtain a string that consist of the character that corresponds to the numeric value of ch.
Parameters
chThe integer number that represents the character.
Returns
The method should return true if it handled ("consumed") this event, false otherwise.
OnDeactivate ( )

Called for each window when the GUI is deactivated.

  • This method mainly exists for symmetry with OnActivate(), it has little practical use.
OnFocusGain ( )

This method is called when this window gains the keyboard input focus.

  • This not called when the focus change was triggered by the script, i.e. by a call to gui:setFocus(myWin). That is, this method is only called when the user triggered the focus change by a mouse click. If you use gui:setFocus(myWin) and want this method called, just call it yourself immediately after the call.
OnFocusLose ( )

This method is called when this window loses the keyboard input focus.

  • This not called when the focus change was triggered by the script, i.e. by a call to gui:setFocus(myWin). That is, this method is only called when the user triggered the focus change by a mouse click.
  • Currently, losing the focus cannot be vetoed.
OnFrame ( )

Called on each frame that is rendered by the Cafu engine.

  • Note that it does not get the frame time passed, but you can always learn the global time by calling get() with parameter "time", e.g.
    t = self:get("time")
  • Obviously, expensive computations cannot be run in this method — they would directly impact the framerate!
OnInit ( )

This is the first method that is called for each window after a GUI has been loaded.

It is only called once for each window.

Note that OnInit() callbacks are special: They're automatically written by the CaWE GUI Editor as part of the _init.cgui file whenever it saves a file. That is, you can normally not write an OnInit() callback yourself, because it has been used already in the normal init code of the GUI. See OnInit2() for a callback with the same purpose that is available for your customizations.

OnInit2 ( )

This method is very much like OnInit(), but intended for your own custom use in the _main.cgui file.

It is only called once for each window.

boolean OnKeyPress ( number  Key)

This method is called if a key was pressed and the window has the keyboard input focus.

Parameters
KeyThe integer number that represents the key that has been pressed. See OpenGLWindow.hpp for a list of possible values for Key. Here is a list of the most frequently used values and their meaning:
Key Value Key Name
1 ESC (Escape)
2...11 1 ... 9, 0
14 Backspace
15 TAB (Tabulator)
28 Return (on main keyboard)
41 Accent Grave
156 Enter (on numpad)
200 Arrow Up
208 Arrow Down
Returns
The method should return true if it handled ("consumed") this event, false otherwise.
boolean OnKeyRelease ( number  Key)

Like OnKeyPress(), but for key releases.

boolean OnMouseButtonDown ( number  button)

This method is called when a mouse button went down (was pressed).

Parameters
buttonThe number of the mouse button that went down. (Typically 0 for the left, 1 for the right, 2 for the middle, and 3 for extra mouse button.)
Returns
The method should return true if it handled ("consumed") this event, false otherwise.
boolean OnMouseButtonUp ( number  button)

This method is called when a mouse button went up (was released).

Parameters
buttonThe number of the mouse button that went up. (Typically 0 for the left, 1 for the right, 2 for the middle, and 3 for extra mouse button.)
Returns
The method should return true if it handled ("consumed") this event, false otherwise.
OnMouseEnter ( )

This method is called when the mouse cursor enters the rectangle of the window.

Note
This does currently not take rotation into account, i.e. it acts as if the rotation was always 0, even if the window rectangle is actually rotating.
OnMouseLeave ( )

This method is called when the mouse cursor leaves the rectangle of the window.

Note
This does currently not take rotation into account, i.e. it acts as if the rotation was always 0, even if the window rectangle is actually rotating.
RemoveChild ( window  child)

This method removes the given window from the children of this window.

Parameters
childThe window that is to be removed from the children of this window.
RemoveComponent ( ComponentBaseT  component)

This method removes a component from this window.