User Tools

Site Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
guisys:guifiles [2011-06-20 21:46]
Carsten First step in big rewrite of page contents...
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"​*/
-^ FIXME ^ This page is currently work in progress(Carsten, 2011-06-20) ^ +
  
 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 8: Line 6:
 GUI files can be created with the GUI Editor, written by hand, or a combination of those: 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.   * 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 ​scripts ​that augment the part of the script ​code that has been generated ​with the GUI Editor.+  * 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.
  
-When you save a GUI in the GUI Editor, the editor creates or re-creates some of these files, updates others, and leaves alone the rest. +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, +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.
-but sometimes you may wish to hand-tune ​some 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. In such cases, it is very helpful to understand the files that belong to a GUI.
- 
-One key question addressed in this section is how we can add hand-written code to the script generated by saving a GUI in the GUI Editor, //without// losing the custom changes when the script is modified in the GUI Editor the next time. 
-/* Better: ... 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. */ 
  
 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. 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.
  
  
-====== Augmenting ​GUI Editor scripts with custom script code ======+===== One directory per GUI =====
  
-Assume that you're using the GUI Editor ​in order to create a "Call Lift" GUI. +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 ownThis
-Let's also assume ​that when doneyou want to access your new GUI under the file name ''​CallLift.cgui''​.+
  
-The trick is that when you save this GUI in the GUI Editoryou'd //not// save it under file name ''​CallLift.cgui''​. Instead, you save it under file name ''​CallLift_init.cgui''​. +  * explicitly groups all files that logically form and belong to the GUI, and 
-Next, create ​second file next to ''​CallLift_init.cgui'' ​with the name that you actually want''​CallLift.cgui''​.+  * makes packaging a complete GUI in a ''​my_GUI.zip'' ​archive possible, so that the GUI can easily and safely be distributedshipped and handled.
  
-The new ''​CallLift.cgui'' ​file will be the file that you actually use, and it will contain all hand-written custom codeFor this to work, it must include ​the GUI Editor created file, and therefore its content looks like this:+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''​).
  
-<code lua> +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.
-dofile("Games/​DeathMatch/​GUIs/​CallLift_init.cgui");    ​-- Include ​the GUI Editor generated file.+
  
--- Add your hand-written custom ​code below this line+/* Example: 
--- ... +<code dos> 
-</​code>​+d:​\Dev\Cafu\Games\DeathMatch\Models\Players>​ dir Trinity 
 +ChromeBuckle_diff.png 
 +ChromeGlass_diff.png 
 +Pants_diff.png 
 +Skin_diff.png 
 +Trinity.cmat 
 +Trinity.cmdl 
 +Trinity.cmdl_bak 
 +Trinity_editor.cmat 
 +</​code> ​*/
  
-In summary: 
-  * When you edit your GUI in the GUI Editor, you only load and save file ''​CallLift_init.cgui''​. 
-  * All hand-written code enters file ''​CallLift.cgui''​ instead. 
-  * The connection between the two files is made by the ''​dofile()''​ command. 
  
-\\ +===== cgui GUI definition ​files =====
-^ 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. |+
  
 +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.
  
-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 ====
  
-====== Definition of GUIs: The cgui File Format ======+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.
  
-For each GUI that occurs in Cafuits definition is stored in a ''​.cgui'' ​file. +The GUI Editor is usually used to create and edit the static aspects of GUI windowsautomatically generating the related script code when saving the file. 
-As many other Cafu related ​files (e.g. ''​.cmat'' ​material definition files), these files are simple ASCII text files. +Dynamic aspects like animations or other kinds of effects typically require adding custom script code, so editing ​''​cgui''​ files (usually the ''​_main.cgui'' ​fileis something that you'll likely want to do often.
-Therefore, ​you can not only conveniently create them with the [[guisys:​guieditor|GUI Editor]], but you can also edit or write them by hand, if necessary even from scratch.+
  
-The ability to edit GUIs in a text editor and the understanding of the related ''​.cgui''​ file format can be crucial. For example, at the time of writing this text, no graphical GUI Editor existed, and all early Cafu GUIs therefore had to be written by hand. It comes also in helpful if you ever come across a GUI that for some reasons doesn'​t work well or not at all with the [[guisys:guieditor|GUI Editor]]. More importantly,​ if you just want to make a few quick changes or fixes to a GUI, editing the ''​.cgui''​ files directly can be a lot faster ​and more convenient than using the [[guisys:guieditor|GUI Editor]].+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.
  
  
-{{ guisys:​reallyquit.jpg?​300}} ​===== General structure =====+==== Augmenting GUI Editor scripts with custom script code ====
  
-The most important insight is that each GUI is in fact //a hierarchy of windows//, just like a program dialog of a real OSEach window is basically just a rectangle with certain properties, like position, size, border color and thickness, text to display, etc.+For one GUI there is usually a //pair// of ''​cgui''​ filesone suffixed ''​_init.cgui'' ​and one suffixed ''​_main.cgui''​For example: 
 +<code dos> 
 +d:​\Dev\Cafu\Games\DeathMatch\GUIs>​ dir Teleporter\*.cgui 
 +Teleporter_init.cgui 
 +Teleporter_main.cgui 
 +</​code>​
  
-However, the most important statements that we have to provide in order to instantiate a new window are its //​class// ​(or //type//)and its //name//.+The ''​_main.cgui''​ file is for your hand-written GUI script codeif any, and is never touched or overwritten by the GUI Editor ​(with one exceptionsee below).
  
-The **class** of window determines the most crucial features of the window, e.gif it displays text, if the user can enter textif it shows a value as a slider controlif it presents a list of items to select from, etcSection [[guisys:window_classes]] shows a list of all available window classeshowever the most commonly used window class is just ''​windowClass''​which provides you with an all-purpose window with basic capabilities.+The GUI Editor also writes ​secondary ''​cgui''​ file whose name ends with ''​_init.cgui''​This file is written anew each time the GUI is savedand contains GUI window definitions whose script code was not hand-craftedbut who were created or edited in the GUI Editor. 
 +/* TODODas stimmt so nicht ganzim Ggs. zu cmat filesdenn Windows werden "​halb"​ im init, "​halb"​ im main File definiert*/
  
-The **name** of a window must be //unique// throughout ​the entire ​GUI -- no other window must have the same name. This is important because both scripts and engine code may refer to windows by name, and things tend to become very confusing if two or more windows have name in common.+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 ​statement like 
 +<code lua> 
 +-- Include the GUI Editor generated file. 
 +dofile("​Games/​DeathMatch/​GUIs/​Teleporter/​Teleporter_init.cgui"​);​
  
 +-- Add your hand-written custom code below this line.
 +-- ...
 +</​code>​
 +in order to include and process the secondary ''​_init.cgui''​ along with the main file.
  
-===== How cgui files are loaded ​=====+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.
  
-When a new Lua program for a GUI is createdit is initially empty. During initialization,​ the GuiSys then adds several Lua tables ​to the empty program in order to provide the subsequent ​script code something to work with. Note that in  Lua, tables are very general ​and very powerfuland they are used to express several independent concepts. For example, the functions ​of a library are all kept in a common table, or object-oriented programming behaviour is simulated by considering a table as an object, where the table entries correspond to member variables and member functions (methods). Several examples for these cases are included below, however ​you should also study the relevant concepts ​in the Lua documentatione.gonline at [[http://​www.lua.org/​pil/​11.html]].+In summarythe 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 separatedwithout any danger ​of one overwriting ​the other: 
 +  * When you edit your GUI in the GUI Editoryou 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.
  
-Only after the empty Lua program for a GUI has been initialized with several tables is the code from all the ''​script''​ blocks concatenated to the program and the initialization complete. 
-More precisely, 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> +===== cmat material definition files ===== 
-    a math.sin(3.1415926);​ + 
-</​code>​ in your scripts. +The ''​cmat'' ​files contain ​the material definitions ​for the graphical elements ​of this GUI.
-  - 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() +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.
-        -- ... +
-    end+
  
-    function FPS:​OnFrame() 
-        local newTime=FPS:​get("​time"​);​ 
-        local deltaTime=newTime-self.oldTime;​ 
  
-        if (deltaTime<​0.000000001) then +===== Texture images =====
-            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;​ +The texture images are referenced from the material definition scripts
-    end +See the documentation about [[http://docs.cafu.de/#​the_cafu_material_system|the Cafu Material System]] for more details.
-</​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]]+
-  - The final step is the addition of the contents of all the ''​script { ... }''​ blocks. The scripts may now access and use all of the above mentioned variables/​tables/​objects/​interfaces,​ and in fact they often look very much like the example snippet that I provided in the previous step.+
  
-Only after these steps is the initialization of a GUI script completeThe GuiSys then compiles each script and calls the ''​OnInit()''​ method for each window+/* Example: 
-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 courseOtherwise, the corresponding call is just skipped.)+<code dos> 
 +d:​\Dev\Cafu\Games\DeathMatch\Models\Players>​ dir Trinity\*.png Trinity\*.jpg 
 +ChromeBuckle_diff.png 
 +ChromeGlass_diff.png 
 +Pants_diff.png 
 +Skin_diff.png 
 +</​code>​ */
  
guisys/guifiles.1308599218.txt.gz · Last modified: 2013-01-07 12:07 (external edit)