This class holds the hierarchy of windows that together form a GUI. More...
Public Member Functions | |
activate (bool IsActive) | |
Sets the IsActive flag of this GUI. More... | |
close () | |
Same as calling gui:activate(false); Same as calling activate() with parameter false . More... | |
setInteractive (bool IsInteractive) | |
Sets the IsInteractive flag of this GUI. More... | |
setFullCover (bool IsFullCover) | |
Sets the IsFullCover flag of this GUI. More... | |
setMousePos (number x, number y) | |
Sets the position of the mouse cursor. More... | |
setMouseCursorSize (number size) | |
Sets the size of the mouse cursor. More... | |
setMouseMat (string MatName) | |
Sets the material that is used to render the mouse cursor. More... | |
showMouse (bool IsShown) | |
Determines whether the mouse cursor is shown at all. More... | |
object | new (string ClassName, string InstanceName="") |
This method creates new GUI windows or new GUI components. More... | |
setFocus (WindowT Window) | |
Sets the keyboard input focus to the given window. More... | |
setFocus (string winName) | |
Like setFocus(WindowT), but takes the name of the window to set to focus to. More... | |
WindowT | GetRootWindow () |
Returns the root window of this GUI as previously set by SetRootWindow(). More... | |
SetRootWindow (WindowT Window) | |
Sets the root window for this GUI. More... | |
Init () | |
Calls the OnInit() script methods of all windows. More... | |
This class holds the hierarchy of windows that together form a GUI.
This class represents the GUI that is defined in a .cgui
script file as a whole. It is quasi the top-level "desktop" object that contains all the windows that together form the user interface. Its methods affect the entire GUI, not just a single window of its window hierarchy. (The new() method described below is an exception: It is used to create new windows and new components.)
Note that you never create GuiT instances yourself: Instead, each GUI script accesses the global gui
variable that is automatically predefined. Thus, the methods of the GuiT class are always used like this:
activate | ( | bool | IsActive | ) |
Sets the IsActive flag of this GUI.
Sets whether the GUI is "active" or not. Active GUIs are drawn and receive device (mouse and keyboard) events and clock-tick events. Inactive GUIs aren't drawn and don't receive any events. (A newly created GuiT instance is active by default.)
A GUI that receives events forwards them also to its windows, that is, the event handler methods such as WindowT::OnKeyPress(), WindowT::OnFrame() etc. are called.
IsActive | Whether the GUI is to be activated (true ) or deactivated (false ). |
close | ( | ) |
Same as calling gui:activate(false);
Same as calling activate() with parameter false
.
WindowT GetRootWindow | ( | ) |
Returns the root window of this GUI as previously set by SetRootWindow().
Init | ( | ) |
Calls the OnInit() script methods of all windows.
This method calls the OnInit()
script methods of all windows.
Normally, the OnInit()
callback is automatically called for each window as soon as the _main.cgui
file has been read. That is, there is an automatic implicit call to Init() at the end of the _main.cgui
script. However, sometimes that's not enough, and you need all the window's OnInit()
methods already run e.g. at the top of the _main.cgui
script, e.g. in order to make sure that all components of all windows have been created, so that in _main.cgui
you can grab their instances and attach callback methods to them. In this case, call Init() manually at the top of _main.cgui
. (It automatically makes sure not to initialize things twice when called multiple times.) See DeathMatch/GUIs/MainMenu/MainMenu_main.cgui
for an example.
object new | ( | string | ClassName, |
string | InstanceName = "" |
||
) |
This method creates new GUI windows or new GUI components.
ClassName | The name of the class of which an object should be created. Use "WindowT" in order to create a new WindowT. Use any class name from the ComponentBaseT hierarchy in order to create a new component, for example "ComponentImageT" in order to create a new image component. |
InstanceName | The name that the newly created window instance is assigned. Specifying a name for a window is equivalent to setting the Name attribute of its Basics component; see the example above and ComponentBasicsT.Name for details. Setting a proper window instance name is important so that other script code can unambiguously find and identify the window by name later. The CaWE GUI Editor also uses it in order to automatically create the initialization script code in the .cgui files. This parameter is not used (and in fact ignored) for components, which have no individual object names. |
setFocus | ( | WindowT | Window | ) |
Sets the keyboard input focus to the given window.
Does not call the OnFocusLose() or OnFocusGain() callbacks! Instead of a window instance, it is also possible to pass the name of the window (a string). Sets the keyboard input focus to the given window.
By default, in a newly created GUI, no window has the keyboard input focus.
When the user clicks with the mouse into a new window, the GuiSys automatically calls the WindowT::OnFocusLose() event handler for the window that loses the focus, and the WindowT::OnFocusGain() event handler for the window that receives that focus.
However, when setFocus() is called, no such calls are implied! That is, if you call setFocus() and want the WindowT::OnFocusLose() and WindowT::OnFocusGain() event handlers to be called, you must do so yourself as demonstrated in the example.
Window | The window that should receive the keyboard input focus. |
setFocus | ( | string | winName | ) |
Like setFocus(WindowT), but takes the name of the window to set to focus to.
winName | Name of the window to set to focus to. |
setFullCover | ( | bool | IsFullCover | ) |
Sets the IsFullCover flag of this GUI.
Sets whether this GUI is fullscreen and fully opaque, that is, whether this GUI covers everything underneath it.
If the given boolean b
is true
, the Cafu GuiSys skips 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 setFullCover() has been called with parameter false
, the world FPS also drags the GUI FPS down. If however setFullCover() has been called with parameter true
, the GuiSys omits the slow drawing of the world beneath this GUI, so that the GUIs FPS can be much higher.
For newly created GUIs, the default value is false
(other GUIs beneath this one are rendered).
IsFullCover | true if this GUI is fullscreen and fully opaque, false otherwise. |
setInteractive | ( | bool | IsInteractive | ) |
Sets the IsInteractive flag of this GUI.
Sets whether the GUI is "interactive" or not. Only the top-most, interactive GUI receives device (mouse and keyboard) events. For example, if the games main menu is shown on screen and the console (a separate, independent GUI) is opened "on top" of it, the (interactive) console will receive all device events while it is in the foreground. (A newly created GuiT instance is interactive by default.)
A GUI that receives events forwards them also to its windows, that is, the event handler methods such as WindowT::OnKeyPress(), WindowT::OnFrame() etc. are called.
IsInteractive | true if the GUI is to be set interactive, false otherwise. |
setMouseCursorSize | ( | number | size | ) |
Sets the size of the mouse cursor.
This can be useful especially in 3D world GUIs, where the default size can be too hard to see.
setMouseMat | ( | string | MatName | ) |
Sets the material that is used to render the mouse cursor.
(This method is not yet implemented.) Sets the MatSys material that is used to render the mouse cursor.
MatName | The name of the MatSys material that is to be used for the mouse cursor. |
setMousePos | ( | number | x, |
number | y | ||
) |
Sets the position of the mouse cursor.
Sets the position of the mouse cursor to the point at (x, y)
(in virtual screen coordinates).
x | The x-coordinate in virtual screen coordinates (640*480) to set the mouse cursor to. |
y | The y-coordinate in virtual screen coordinates (640*480) to set the mouse cursor to. |
SetRootWindow | ( | WindowT | Window | ) |
Sets the root window for this GUI.
Sets the root window for this GUI. If you use the GUI Editor that is part of the CaWE application, a proper call to this method is automatically included in the generated files.
Window | The window that is set as the root window of this GUI. |
showMouse | ( | bool | IsShown | ) |
Determines whether the mouse cursor is shown at all.
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.
(The default value is true
, a newly created GuiT instance shows the mouse cursor by default.)
IsShown | When true , the mouse cursor is shown. When false , then not. |