User Tools

Site Tools


This is an old revision of the document!


Called Methods

For all window classes, the GuiSys (C++) code automatically calls the following script methods. These methods are intended to be provided (and thus “overridden”) by the GUI script author, and are the entry or “starting” point for customizing the GUIs behaviour.

Note that none of these methods is obligatory, i.e. you are not required to provide any of them. The GuiSys will realize automatically which methods you provide and which you don't, and just do nothing for methods that have not been defined.

OnAction()

Called when the user pressed the “action” button inside the window. This is normally the left mouse button, but could also be the appropriate joystick button etc.

No parameters are being passed and no return value is expected.

Notes:

  • When the GuiSys calls this method, it also calls to the OnFocusLose() and OnFocusGain() methods, if appropriate (that is, when the keyboard input focus changed as a result of the mouse click).

OnActivate()

Called for each window when the GUI is activated (i.e. switched on for rendering, e.g. when the user toggles the in-game console, this method is called every time the console GUI comes up).

No parameters are being passed and no return value is expected.

OnDeactivate()

Called for each window when the GUI is deactivated.

No parameters are being passed and no return value is expected.

Notes:

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

OnFocusGain()

Called when this window gains the keyboard input focus.

No parameters are being passed and no return value is expected.

Notes:

  • 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()

Called when this window gains the keyboard input focus.

No parameters are being passed and no return value is expected.

Notes:

  • 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 Ca3D-Engine.

No parameters are being passed and no return value is expected.

Notes:

  • Note that it does not get the frame time passed, but you can always learn the global time by calling get(“time”);.
  • Oviously, you may not do many expensive things in this method — it's called every frame, after all!

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.

No parameters are being passed and no return value is expected.

bool OnKeyPress(Key)

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

Parameters:

Name Type Description
Key number The integral number that represents the key that has been pressed.

Please refer to the CaKeyboardEventT structure that is declared in the Libs/OpenGL/OpenGLWindow.hpp file that comes with the Ca3DE SDK for 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 must return true if it handled this key press, and false otherwise.

bool OnKeyRelease(Key)

Like OnKeyPress(Key), but for key releases.

OnMouseEnter()

Called when the mouse cursor enters the rectangle of the window.

No parameters are being passed and no return value is expected.

Notes:

  • Note that 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()

Called when the mouse cursor leaves the rectangle of the window.

No parameters are being passed and no return value is expected.

Notes:

  • Note that 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.
guisys/called_methods.1158510964.txt.gz · Last modified: 2013-01-07 12:07 (external edit)