User Tools
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
guisys:guifiles [2011-06-23 20:38] Carsten Augmented the text |
guisys:guifiles [2011-06-26 10:55] Carsten Removed now obsolete passages of text |
||
|---|---|---|---|
| Line 49: | Line 49: | ||
| 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. | ||
| + | |||
| + | |||
| + | ==== Augmenting GUI Editor scripts with custom script code ==== | ||
| For one GUI there is usually a //pair// of ''cgui'' files, one suffixed ''_init.cgui'' and one suffixed ''_main.cgui''. For example: | For one GUI there is usually a //pair// of ''cgui'' files, one suffixed ''_init.cgui'' and one suffixed ''_main.cgui''. For example: | ||
| Line 57: | Line 60: | ||
| </code> | </code> | ||
| - | ==== cgui files are Lua scripts ==== | + | 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 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 if desired. | + | 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. |
| - | + | /* TODO: Das stimmt so nicht ganz, im Ggs. zu cmat files, denn Windows werden "halb" im init, "halb" im main File definiert. */ | |
| - | + | ||
| - | ==== Augmenting GUI Editor scripts with custom script code ==== | + | |
| - | + | ||
| - | Assume that you're using the GUI Editor in order to create a "Call Lift" GUI. | + | |
| - | Let's also assume that when done, you want to access your new GUI under the file name ''CallLift.cgui''. | + | |
| - | + | ||
| - | The trick is that when you save this GUI in the GUI Editor, you'd //not// save it under file name ''CallLift.cgui''. Instead, you save it under file name ''CallLift_init.cgui''. | + | |
| - | Next, create a second file next to ''CallLift_init.cgui'' with the name that you actually want, ''CallLift.cgui''. | + | |
| - | + | ||
| - | The new ''CallLift.cgui'' file will be the file that you actually use, and it will contain all hand-written custom code. For this to work, it must include the GUI Editor created file, and therefore its content looks like this: | + | |
| + | 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 | ||
| <code lua> | <code lua> | ||
| - | dofile("Games/DeathMatch/GUIs/CallLift_init.cgui"); -- Include the GUI Editor generated file. | + | -- Include the GUI Editor generated file. |
| + | dofile("Games/DeathMatch/GUIs/Teleporter/Teleporter_init.cgui"); | ||
| -- Add your hand-written custom code below this line. | -- Add your hand-written custom code below this line. | ||
| -- ... | -- ... | ||
| </code> | </code> | ||
| + | in order to include and process the secondary ''_init.cgui'' along with the main file. | ||
| - | In summary: | + | 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 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. | + | 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: |
| - | * The connection between the two files is made by the ''dofile()'' command. | + | * 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. | ||
| \\ | \\ | ||
| ^ Tip by the Cafu development team: ^ | ^ 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 ''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''. | 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''. | ||
| - | ==== Definition of GUIs: The cgui File Format ==== | + | ==== cgui files are Lua scripts ==== |
| - | For each GUI that occurs in Cafu, its definition is stored in a ''.cgui'' file. | + | 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 if desired. |
| - | As many other Cafu related files (e.g. ''.cmat'' material definition files), these files are simple ASCII text files. | + | |
| - | 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]]. | + | |
| Line 154: | Line 148: | ||
| end | 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]]. | </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 complete. The GuiSys then compiles each script and calls the ''OnInit()'' method for each window. | 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. | ||
guisys/guifiles.txt · Last modified: 2017-02-21 11:42 by Carsten