This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
guisys:called_methods [2006-09-24 16:29] Carsten Added proper section heading for Params and Return Values |
— (current) | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== 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. <clear> | ||
- | |||
- | |||
- | ===== 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. | ||
- | |||
- | === Parameters and Return Value: === | ||
- | 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). | ||
- | For example, when the user toggles the in-game console, this method is called every time the console GUI comes up. | ||
- | |||
- | === Parameters and Return Value: === | ||
- | No parameters are being passed and no return value is expected. | ||
- | |||
- | |||
- | ===== OnDeactivate() ===== | ||
- | |||
- | Called for each window when the GUI is deactivated. | ||
- | |||
- | === Parameters and Return Value: === | ||
- | 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. | ||
- | |||
- | === Parameters and Return Value: === | ||
- | 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. | ||
- | |||
- | === Parameters and Return Value: === | ||
- | 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. | ||
- | |||
- | === Parameters and Return Value: === | ||
- | 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. | ||
- | |||
- | === Parameters and Return Value: === | ||
- | 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 | | ||
- | |||
- | === Return Value: === | ||
- | 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. | ||
- | |||
- | === Parameters and Return Value: === | ||
- | 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. | ||
- | |||
- | === Parameters and Return Value: === | ||
- | 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. | ||