User Tools
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision | |||
|
guisys:called_methods [2011-02-26 14:30] Carsten Deleted page, contents has been migrated to http://api.cafu.de/scripting/classWindowT.html |
— (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 Cafu 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 Cafu 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. | ||
| - | |||
| - | |||
| - | ===== bool OnChar(ch) ===== | ||
| - | |||
| - | This method is called when a character event occurred and the window has the keyboard input focus. | ||
| - | |||
| - | === Parameters: === | ||
| - | ^ Name ^ Type ^ Description ^ | ||
| - | | ch | number | The integral number that represents the character. | | ||
| - | |||
| - | === Return Value: === | ||
| - | The method must return ''true'' if it handled this key press, and ''false'' otherwise. | ||
| - | |||
| - | === Notes: === | ||
| - | * The big difference to ''OnKeyPress()'' is that ''OnKeyPress()'' just deals with plain keys, which is very useful for example to work with the arrow keys. Cafu uses a similar concept internally for generating player movement input. ''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. 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''. | ||
| - | |||
| - | |||
| - | ===== 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. | ||
guisys/called_methods.1298727022.txt.gz ยท Last modified: 2013-01-07 12:07 (external edit)