This shows you the differences between two versions of the page.
Both sides previous revision Previous revision | Next revision Both sides next revision | ||
guisys:guifiles [2011-06-23 20:38] Carsten Augmented the text |
guisys:guifiles [2011-06-25 11:53] Carsten Augmented the 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 ==== | + | 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 | |
- | 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: | + | |
<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''. | ||
+ | |||
+ | |||
+ | ==== 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 if desired. | ||