User Tools
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
guisys:guifiles [2011-06-26 15:40] Carsten Removed more obsolete passages of text |
guisys:guifiles [2017-02-21 11:42] (current) Carsten remove obsolete reference to Trac |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== GUI Files Explained ====== | ====== GUI Files Explained ====== | ||
| /* This text has been derived from and is similar to "Model Files Explained". */ | /* This text has been derived from and is similar to "Model Files Explained". */ | ||
| - | |||
| - | ^ FIXME ^ 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. | Each GUI comprises several files on disk, such as the GUI scripts, material definition files, and texture images. | ||
| Line 27: | Line 24: | ||
| * 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. | * 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''). | + | The name of the directory should match the file name of the GUI. That is, if your GUI's file names are ''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. | 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. | ||
| Line 49: | Line 46: | ||
| The ''cgui'' files are the core files of the GUI: | 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. | They contain the definitions for the positions, sizes, colors, texts, effects, animations, hierarchy and other properties of the windows that form the GUI. | ||
| + | |||
| + | |||
| + | ==== cgui files are Lua scripts ==== | ||
| + | |||
| + | The Cafu Engine and the GUI Editor load ''cgui'' files as [[http://www.lua.org/|Lua]] scripts, and as such they can be inspected or edited in a text editor. | ||
| + | |||
| + | The GUI Editor is usually used to create and edit the static aspects of GUI windows, automatically generating the related script code when saving the file. | ||
| + | Dynamic aspects like animations or other kinds of effects typically require adding custom script code, so editing ''cgui'' files (usually the ''_main.cgui'' file) is something that you'll likely want to do often. | ||
| + | |||
| + | See the [[http://api.cafu.de/lua/|Lua Scripting Overview]] and the [[http://api.cafu.de/lua/group__GUI.html|GUI Scripting Reference Documentation]] for more details. | ||
| Line 82: | Line 89: | ||
| * All hand-written code enters file ''Teleporter_main.cgui'' instead. | * All hand-written code enters file ''Teleporter_main.cgui'' instead. | ||
| * The connection between the two files is made by the ''dofile()'' statement. | * The connection between the two files is made by the ''dofile()'' statement. | ||
| - | |||
| - | \\ | ||
| - | ^ Tip by the Cafu development team: ^ | ||
| - | | The ''Games/DeathMatch/GUIs/MainMenu/MainMenu(_init).cgui'' files that are natively included with Cafu are prime examples of this technique. | | ||
| - | |||
| - | 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''. | ||
| - | |||
| - | |||
| - | ==== cgui files are Lua scripts ==== | ||
| - | |||
| - | The Cafu Engine and the Model Editor load ''cmdl'' files as [[http://www.lua.org/|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 [[http://api.cafu.de/scripting/group__GUI.html|GUI Scripting Reference Documentation]] for more details. | ||
| - | |||
| - | === How cgui files are loaded === | ||
| - | |||
| - | The initialization consists of the following steps: | ||
| - | |||
| - | - 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 <code=lua> | ||
| - | a = math.sin(3.1415926); | ||
| - | </code> in your scripts. | ||
| - | - 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 [[scripting:console]] for details. Example use: <code=lua> | ||
| - | Console.Print("Hello!\n"); | ||
| - | </code> | ||
| - | - 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 [[scripting:ccm]] for details. Example use: <code=lua> | ||
| - | Command="show"; | ||
| - | ccm.ExecuteCommand("list " .. Command); | ||
| - | </code> | ||
| - | - 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. | ||
| - | - 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 [[scripting:gui]] for details. Example use: <code=lua> | ||
| - | gui:setFocus(ConsoleInput); | ||
| - | gui:close(); | ||
| - | </code> | ||
| - | - 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'': <code=lua> | ||
| - | 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 | ||
| - | </code> 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 [[guisys: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 [[guisys: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.) | ||
| Line 146: | Line 95: | ||
| The ''cmat'' files contain the material definitions for the graphical elements of this GUI. | 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 [[http://www.cafu.de/wiki/modeleditor:modelfiles#cmat_material_definition_files|cmat material definition files]] for models. | + | 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 [[http://docs.cafu.de/modeleditor:modelfiles#cmat_material_definition_files|cmat material definition files]] for models. |
| Line 152: | Line 101: | ||
| The texture images are referenced from the material definition scripts. | The texture images are referenced from the material definition scripts. | ||
| - | See the documentation about [[http://www.cafu.de/wiki/#the_cafu_material_system|the Cafu Material System]] for more details. | + | See the documentation about [[http://docs.cafu.de/#the_cafu_material_system|the Cafu Material System]] for more details. |
| /* Example: | /* Example: | ||
guisys/guifiles.1309095651.txt.gz ยท Last modified: 2013-01-07 12:07 (external edit)