This page is currently work in progress.

Each GUI comprises several files on disk, such as the GUI scripts, material definition files, and texture images.

GUI files can be created with the GUI Editor, written by hand, or a combination of those:

• The GUI Editor allows users to define and design the contents and layout of the windows that compose a GUI. However, the work in the GUI Editor is focused mainly on static aspects like window position and size, texts, colors, borders, etc.
• Everything “dynamic” and all sorts of effects can, by their nature, not be added by means of the GUI Editor, but must be written as custom, hand-crafted script code that augments the script that is auto-generated by the GUI Editor each time the “static” part of the GUI is saved.

One key question addressed in this section is how we can combine hand-crafted script code and editor-edited script code, while keeping both separated so that they don't overwrite each other.

In general, when you save a GUI in the GUI Editor, the editor creates or re-creates some of the files it is composed of, updates others, and leaves alone the rest. The result is normally exactly what you want and expect, but sometimes you may wish to or must hand-tune the details (such as the GUI scripts or material definitions) without and independently of the GUI Editor. In such cases, it is very helpful to understand the files that belong to a GUI.

This section explains the files that together form a GUI, how they relate to each other, and how hand-crafted and editor-created scripts can peacefully coexist.

Although not a technical requirement and not enforced by the Cafu GUI code (and in fact, at the time of this writing, not yet implemented by the example GUIs that ship with Cafu), it is highly recommended to save each GUI in a directory of its own. This

• explicitly groups all files that logically form and belong to the GUI, and
• makes packaging a complete GUI in a my_GUI.zip archive possible, so that the GUI can easily and safely be distributed, shipped and handled.

The name of the directory should match the file name of the GUI. That is, if your GUI's name is CallLift_init.cgui and CallLift_main.cgui, it should be stored in a directory with the same name CallLift/ (or in a zip archive with the same base name CallLift.zip).

Note that when you are saving a new GUI that does not yet have a separate directory, you can use the “New Folder” button (or right-click context menu) of the “Save” dialog to create such new directories as required.

The cgui files are the core files of the GUI: They contain the definitions for the positions, sizes, colors, texts, effects, animations, hierarchy and other properties of the windows that form the GUI.

For one GUI there is usually a pair of cgui files, one suffixed _init.cgui and one suffixed _main.cgui. For example:

d:\Dev\Cafu\Games\DeathMatch\GUIs> dir Teleporter\*.cgui
Teleporter_init.cgui
Teleporter_main.cgui

The _main.cgui file is for your hand-written GUI script code, if any, and is never touched or overwritten by the GUI Editor (with one exception, see below).

The GUI Editor also writes a secondary cgui file whose name ends with _init.cgui. This file is written anew each time the GUI is saved, and contains GUI window definitions whose script code was not hand-crafted, but who were created or edited in the GUI Editor.

The two cgui files are linked as follows: When the Cafu code loads a GUI, it opens the _main.cgui file (Teleporter_main.cgui). This file contains a statement like

-- Include the GUI Editor generated file.
dofile("Games/DeathMatch/GUIs/Teleporter/Teleporter_init.cgui");
 
-- Add your hand-written custom code below this line.
-- ...

in order to include and process the secondary _init.cgui along with the main file.

The only exception when the GUI Editor touches the main Teleporter_main.cmat file is when the file does not yet exist, or doesn't contain the dofile() reference to the init file. In this case, the _main.cgui would not be loaded at all, and thus the GUI Editor inserts the dofile() line into the _main.cgui file.

In summary, the goal of keeping two separate cgui files that are linked as described above is to keep your hand-crafted GUI script code and the GUI Editor edited window definitions cleanly separated, without any danger of one overwriting the other:

• When you edit your GUI in the GUI Editor, you only load and save file Teleporter_init.cgui.
• All hand-written code enters file Teleporter_main.cgui instead.
• The connection between the two files is made by the dofile() statement.

Future versions of the GUI Editor may even mildly enforce the two-files approach, where one file has the normal file name and its “twin” gets the _init suffix automatically appended. This helps e.g. to prevent accidental overwrites when you happen to load CallLift.cgui into the GUI Editor instead of CallLift_init.cgui.

The Cafu Engine and the Model Editor load cmdl files as Lua scripts, and as such they can be inspected or edited in a text editor.

As the GUI Editor is usually used to create and edit the static aspects of GUI windows, and dynamic aspects like animations or other kinds of effects typically require custom script code, editing cgui files (usually the _main.cgui file) is what you likely want to do often.

See the GUI Scripting Reference Documentation for more details.

The initialization consists of the following steps:

1. Most of the Lua Standard Libraries are loaded, namely the basic, package, table, io, os, string and math libraries. Please refer to the Lua documentation for details, online resources are at http://www.lua.org/pil/18.html and http://www.lua.org/manual/5.1/manual.html#5. With these libraries, you can for example use expressions like

       a = math.sin(3.1415926);

   in your scripts.

2. The Cafu Console library is loaded. This is a table with name Console that in fact provides an interface to the internal Cafu console. Please see the reference documentation at console for details. Example use:

       Console.Print("Hello!\n");

3. The Cafu command manager library is loaded. This is a table with name ccm that provides access to the related Cafu interface. Please see the reference documentation at ccm for details. Example use:

       Command="show";
       ccm.ExecuteCommand("list " .. Command);

4. Meta-tables for GUIs and GUI windows are created. They are used with the GUI and window objects below, and are not intended for direct use by the scripts.
5. The global variable gui is added. The gui variable is in fact a table that represents the GUI object itself. It has methods that are relevant not for an individual window of the GUI, but for the entire GUI. See gui for details. Example use:

       gui:setFocus(ConsoleInput);
       gui:close();

6. Most importantly, for each window in the GUI, a table with the name of the window is created that represents that very window. In the above example, window objects (tables) with the names Background, ReallyQuit, ButtonYes and ButtonNo are created. Contrary to the above tables however, you're not just supposed to access and call existing, predefined methods and variables, but you can (and in fact should) provide your own! Typical example for a frames-per-second window with name FPS:

       FPS.oldTime=FPS:get("time");
    
       function FPS:OnInit()
           -- ...
       end
    
       function FPS:OnFrame()
           local newTime=FPS:get("time");
           local deltaTime=newTime-self.oldTime;
    
           if (deltaTime<0.000000001) then
               self:set("text", string.format("FPS\nINF\n(%.4f sec)", deltaTime));
           else
               self:set("text", string.format("FPS\n%.2f\n(%.4f sec)", 1/deltaTime, deltaTime));
           end
    
           FPS.oldTime=newTime;
       end

   For a list of the predefined methods of each window that are available to you (e.g. the set() and get() methods above), please refer to section predefined_methods. For a list of methods that the GuiSys expects you to override for customization (e.g. the OnInit() method above), please refer to section called_methods.

Only after these steps is the initialization of a GUI script complete. The GuiSys then compiles each script and calls the OnInit() method for each window. That is, in the above example, it calls the methods Background:OnInit(), ReallyQuit:OnInit(), ButtonYes:OnInit() and ButtonNo:OnInit(). (Only if definitions have been provided in the script, of course. Otherwise, the corresponding call is just skipped.)

The cmat files contain the material definitions for the graphical elements of this GUI.

At the time of this writing, the materials for GUIs are still defined in the “global” material scripts for the MOD, but for the future we intend to have separate material scripts for each GUI that work analogous to cmat material definition files for models.

The texture images are referenced from the material definition scripts. See the documentation about the Cafu Material System for more details.