This is an old revision of the document!
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.
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.
Name | Type | Description |
---|---|---|
b | boolean | Whether the GUI is to be activated (true ) or deactivated (false ). |
Nothing (nil).
true
(the GUI is active).
Please see the example at the close()
method.
Same as calling activate(false)
.
None.
Nothing (nil).
-- The next two lines are equivalent: gui:close(); gui:activate(false);
Sets whether the GUI is interactive or not.
Name | Type | Description |
---|---|---|
b | boolean | true if the GUI is to be set interactive, false otherwise. |
Nothing (nil).
true
(the GUI is interactive).A typical example for a non-interactive GUI is the local players HUD, or any static world GUI that just displays some information.
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.
Name | Type | Description |
---|---|---|
b | boolean | true if this GUI is fullscreen and fully opaque, false otherwise. |
Nothing (nil).
false
(other GUIs beneath this one are rendered).
Sets the position of the mouse cursor to the point at (x, y)
(in virtual screen coordinates).
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. |
Nothing (nil).
Sets the MatSys material that is to be used for the mouse cursor.
Name | Type | Description |
---|---|---|
matName | string | The name of the MatSys material that is to be used for the mouse cursor. |
Nothing (nil).
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.
Name | Type | Description |
---|---|---|
b | boolean | When true , the mouse cursor is shown. When false , then not. |
Nothing (nil).
true
(mouse cursor is shown).
Sets the keyboard input focus (the default receiver for keyboard events) to window win
.
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 window_classes. |
Nothing (nil).
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.-- previousWin and myWin are some windows of this GUIs window hierarchy. previousWin:OnFocusLose(); gui:setFocus(myWin); myWin:OnFocusGain();
Returns a short string that describes the GUI.
None.
A string that briefly describes the GUI.
tostring()
method that allows the conversion of a GUI into a string.This method makes the following examples work:
s=tostring(gui); print(s); print(gui); -- Same as: print(tostring(gui));