User Tools
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
scripting:gui [2006-09-24 18:26] Carsten Revised the text |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== The gui Object ====== | ||
| - | |||
| - | The ''gui'' object represents the GUI of the current ''.cgui'' file. | ||
| - | It provides methods that affect the entire GUI as a whole, not just a single window of its window hierarchy. | ||
| - | |||
| - | |||
| - | ===== activate(b) ===== | ||
| - | |||
| - | Sets whether the GUI is active or not. | ||
| - | Active GUIs are drawn and receive device (mouse and keyboard) and clock-tick events. | ||
| - | Inactive GUIs aren't drawn and don't receive any events. | ||
| - | |||
| - | === Parameters: === | ||
| - | ^ Name ^ Type ^ Description ^ | ||
| - | | b | boolean | Whether the GUI is to be activated (''true'') or deactivated (''false''). | | ||
| - | |||
| - | === Returns: === | ||
| - | Nothing (nil). | ||
| - | |||
| - | === Notes: === | ||
| - | * The default setting is ''true'' (the GUI is active). | ||
| - | * In order for a GUI to receive device events, more requirements must be met (just being active is not enough). See [[#setInteractive_b|setInteractive()]] for more details. | ||
| - | |||
| - | === Example: === | ||
| - | Please see the example at the ''close()'' method. | ||
| - | |||
| - | |||
| - | ===== close() ===== | ||
| - | |||
| - | Same as calling ''activate(false)''. | ||
| - | |||
| - | === Parameters: === | ||
| - | None. | ||
| - | |||
| - | === Returns: === | ||
| - | Nothing (nil). | ||
| - | |||
| - | === Example: === | ||
| - | <code lua> | ||
| - | -- The next two lines are equivalent: | ||
| - | gui:close(); | ||
| - | gui:activate(false); | ||
| - | </code> | ||
| - | |||
| - | |||
| - | ===== setInteractive(b) ===== | ||
| - | |||
| - | Sets whether the GUI is interactive or not. | ||
| - | |||
| - | === Parameters: === | ||
| - | ^ Name ^ Type ^ Description ^ | ||
| - | | b | boolean | ''true'' if the GUI is to be set interactive, ''false'' otherwise. | | ||
| - | |||
| - | === Returns: === | ||
| - | Nothing (nil). | ||
| - | |||
| - | === Notes: === | ||
| - | * The default setting is ''true'' (the GUI is interactive). | ||
| - | * Only the top-most, interactive GUI receives device (mouse and keyboard) events. | ||
| - | * However, in order for a GUI to receive events, it must also be active, see [[#activate_b|activate()]] for more details. | ||
| - | |||
| - | === Example: === | ||
| - | A typical example for a non-interactive GUI is the local players HUD, or any static world GUI that just displays some information. | ||
| - | |||
| - | |||
| - | ===== setFullCover(b) ===== | ||
| - | |||
| - | Sets whether this GUI is fullscreen and fully opaque, that is, whether this GUI covers everything beneath it. | ||
| - | |||
| - | If ''b'' is ''true'', the GuiSys saves the rendering of the GUIs "below" this one, otherwise it doesn't. | ||
| - | This can improve the GUI performance significantly if e.g. the player is at a point in the game where the world rendering FPS is low. In this case, if ''gui.setFullCover(false)'' has been called, the world FPS also drags the GUI FPS down. If however ''setFullCover(true)'' has been called, the GuiSys omits the slow drawing of the world beneath this GUI, so that the GUIs FPS can be much higher. | ||
| - | |||
| - | === Parameters: === | ||
| - | ^ Name ^ Type ^ Description ^ | ||
| - | | b | boolean | ''true'' if this GUI is fullscreen and fully opaque, ''false'' otherwise. | | ||
| - | |||
| - | === Returns: === | ||
| - | Nothing (nil). | ||
| - | |||
| - | === Notes: === | ||
| - | * The default value is ''false'' (other GUIs beneath this one are rendered). | ||
| - | |||
| - | |||
| - | ===== setMousePos(x, y) ===== | ||
| - | |||
| - | Sets the position of the mouse cursor to the point at ''(x, y)'' (in virtual screen coordinates). | ||
| - | |||
| - | === Parameters: === | ||
| - | ^ Name ^ Type ^ Description ^ | ||
| - | | x | number | The x-coordinate in virtual screen coordinates (640*480) to set the mouse cursor to. | | ||
| - | | y | number | The y-coordinate in virtual screen coordinates (640*480) to set the mouse cursor to. | | ||
| - | |||
| - | === Returns: === | ||
| - | Nothing (nil). | ||
| - | |||
| - | |||
| - | ===== setMouseMat(matName) ===== | ||
| - | |||
| - | Sets the MatSys material that is to be used for the mouse cursor. | ||
| - | |||
| - | === Parameters: === | ||
| - | ^ Name ^ Type ^ Description ^ | ||
| - | | matName | string | The name of the MatSys material that is to be used for the mouse cursor. | | ||
| - | |||
| - | === Returns: === | ||
| - | Nothing (nil). | ||
| - | |||
| - | === Notes: === | ||
| - | * This is not yet implemented. Instead the GuiSys always draws a simple built-in default cursor. Sorry. | ||
| - | |||
| - | |||
| - | ===== showMouse(b) ===== | ||
| - | |||
| - | Sets whether the mouse cursor is shown at all. | ||
| - | |||
| - | Non-interactive GUIs normally don't show a mouse cursor whereas interactive GUIs do, but there also are exceptions, e.g. a GUI in which the user can control a 3D camera with the mouse is interactive but may not need a mouse cursor. (The clients main world rendering is an example for this.) Also fade-out or cinematic sequences can temporarily switch off the mouse-cursor with this method. | ||
| - | |||
| - | === Parameters: === | ||
| - | ^ Name ^ Type ^ Description ^ | ||
| - | | b | boolean | When ''true'', the mouse cursor is shown. When ''false'', then not. | | ||
| - | |||
| - | === Returns: === | ||
| - | Nothing (nil). | ||
| - | |||
| - | === Notes: === | ||
| - | * The default value is ''true'' (mouse cursor is shown). | ||
| - | |||
| - | |||
| - | ===== setFocus(win) ===== | ||
| - | |||
| - | Sets the keyboard input focus (the default receiver for keyboard events) to window ''win''. | ||
| - | |||
| - | === Parameters: === | ||
| - | ^ Name ^ Type ^ Description ^ | ||
| - | | win | window | The window that should receive the keyboard input focus. This must be an instance of one of the window classes described in section [[guisys:window_classes]]. | | ||
| - | |||
| - | === Returns: === | ||
| - | Nothing (nil). | ||
| - | |||
| - | === Notes: === | ||
| - | * By default, no window has the keyboard input focus. | ||
| - | * When the user clicks with the mouse into a new window, the GuiSys automatically calls the ''OnFocusLose()'' and ''OnFocusGain()'' methods for the old and new window respectively. However, when the ''setFocus(win)'' method is called, no such calls are implied! :!: If you call ''setFocus(win)'' and want the ''OnFocusLose()'' and ''OnFocusGain()'' methods to be called, you must do so yourself as demonstrated in the example. | ||
| - | |||
| - | === Example: === | ||
| - | <code lua> | ||
| - | -- previousWin and myWin are some windows of this GUIs window hierarchy. | ||
| - | previousWin:OnFocusLose(); | ||
| - | gui:setFocus(myWin); | ||
| - | myWin:OnFocusGain(); | ||
| - | </code> | ||
| - | |||
| - | |||
| - | ===== __tostring() ===== | ||
| - | |||
| - | Returns a short string that describes the GUI. | ||
| - | |||
| - | === Parameters: === | ||
| - | None. | ||
| - | |||
| - | === Returns: === | ||
| - | A string that briefly describes the GUI. | ||
| - | |||
| - | === Notes: === | ||
| - | * This method is not intended to be called directly. Rather, it’s the metamethod for Luas ''tostring()'' method that allows the conversion of a GUI into a string. | ||
| - | |||
| - | === Example: === | ||
| - | This method makes the following examples work: | ||
| - | <code=lua> | ||
| - | s=tostring(gui); | ||
| - | print(s); | ||
| - | |||
| - | print(gui); -- Same as: print(tostring(gui)); | ||
| - | </code> | ||
scripting/gui.1159115212.txt.gz · Last modified: 2013-01-07 12:07 (external edit)