Feedback on wiki "GUI Scripting Language" Series

[Geep]

On 11/3/2022 at 5:59 PM, stgatilov said:

In Precedence section, there is discussion about parentheses.
Yes, you can put parentheses in GUI expressions, and rely on normal evaluation order otherwise.

The discussion about macros here might be a bit confusing, because GUI engine has nothing to do with #defines, in fact it does not even see them. Just like in C language, all the directives starting with #sharp are handles by totally separate thing called preprocessor, the GUI parser will see all macro references replaced by whatever they point to, so for the GUI parser it would be just a gigantic expression with two levels of nested parentheses.

I would probably be better to stress this in tutorial, because this understanding of preprocessor as an entirely separate step can help on many occasions.

@stgatilov, just doing a last pass through the pages. For the record, I do need to mention here a concern I noticed earlier.

While the preprocessor directives are indeed best thought of as a separate pass that resolves (e.g., does text substitution) before the main parsing occurs, I don't think that's actually what the source code is doing. As far as I can tell (just static analysis), macros are being parsed and resolved intermixed with other GUI commands. So I've worded things carefully to not claim an actual preprocessor pass.

Edit: Oh, I see I already mentioned all that back in November. Nevermind.

Edited December 27, 2022 by Geep

[Geep]

OK, it's almost the end of the year, and I am officially SO DONE with the GUI Scripting series! Yeah!!! Thanks for all the help, and apologies if I neglected or mangled any points anyone raised.

I hope TDM readers will find it useful at times, and will improve it where it needs it.

[stgatilov]

21 hours ago, Geep said:

While the preprocessor directives are indeed best thought of as a separate pass that resolves (e.g., does text substitution) before the main parsing occurs, I don't think that's actually what the source code is doing. As far as I can tell (just static analysis), macros are being parsed and resolved intermixed with other GUI commands.

That can be considered an optimization: C/C++ compilers most likely do the same today, although the specification is defined in terms of having a separate preprocessing pass.

The main consequence is that the preprocessor does not know anything about GUI language, and GUI language does not know anything about preprocessor, and the information just cannot get from GUI language to preprocessor. The formulation of a separate pass make it obvious, while the exact description of implementation does not.

[datiswous]

I was looking into the documentation for creating a listdef, but there is not enough information in it. It shows how it is done for some sections of the main menu, but it doesn't show you how to list your own data.

Quote

The listDef GUI does not itself populate a list, but relies on associated C++ code to do so, typically with a dynamic list.

I don't see how this page is helpful apart from some sort of historical reference. Or for tdm devs.

[Geep]

1 hour ago, datiswous said:

I don't see how this page is helpful apart from some sort of historical reference. Or for tdm devs.

I agree that listdefs as they are now are not useful to FM authors, because alteration of the C++ source code is needed. If there was some data array that was useful across FMs, then it might justify a collaboration to have C++ support it. For instance, I could imagine a generic fm_data_string_array, with read/write access, that you could associated with any FM-specific listdef. Don't have a clear idea here.

[datiswous]

Ok well, I was looking at the options for having a list of choices, but I decided to look for something else. Choicedef is also not useful in this case.

[datiswous]

On wiki page:

https://wiki.thedarkmod.com/index.php?title=GUI_Scripting:_Commands#Examples_2

I see:

Quote

 

Another example, with a time_duration value #defined in tdm_gui01.pk4\guis\readables\readable.guicode, and frequently used in other .gui for page-flipping visuals in readables. Observe that in this case, the developer chose not to include double quotes around time_duration, accel, and decel values:

#define READABLE_FADE_TIME 200

transition "leftPageCurl::matcolor" "1 1 1 0" "1 1 1 1" READABLE_FADE_TIME 0.5 0;

 

I don't see this defined in tdm_gui01.pk4\guis\readables\readable.guicode

[Geep]

11 hours ago, datiswous said:

I don't see this defined in tdm_gui01.pk4\guis\readables\readable.guicode

??? I'm seeing READABLE_FADE_TIME on line 12 of readable.guicode for TDM 2.10 and 2.11, and also the version of 2.12dev I have installed (admittedly not the latest).

[datiswous]

Ok, but not

transition "leftPageCurl::matcolor" "1 1 1 0" "1 1 1 1" READABLE_FADE_TIME 0.5 0;

 

Edited November 2, 2023 by datiswous

[Geep]

Yeah, but that line is used in a zillion .gui's, for example:

tdm_gui01.pk4\guis\readables\sheets\sheet_paper_print_stone.gui(line 124):

transition "leftPageCurl::matcolor" "1 1 1 0" "1 1 1 1" READABLE_FADE_TIME 0.5 0;

What I said was accurate. But I'll rearrange the text to avoid future confusion.

[datiswous]

I was wondering if this still works because I see it a lot in console warnings.

"leftPageCurl" , is that a windowDef devined where?

Edited November 3, 2023 by datiswous

[Geep]

You will find

windowDef leftPageCurl {....

within each multipage .gui, for example:

tdm_gui01.pke\guis\readables\sheets\sheet_paper_print_stone.gui (line 20)

I was just using this as a syntax example. I am not responsible for the code itself.

As to newish more numerous console warnings: It is certainly possible that some syntax forms that were previously accepted without complaint (at the time I wrote this wiki series) are now causing warnings.

[datiswous]

4 hours ago, Geep said:

I was just using this as a syntax example. I am not responsible for the code itself.

As to newish more numerous console warnings: It is certainly possible that some syntax forms that were previously accepted without complaint (at the time I wrote this wiki series) are now causing warnings.

I'm sorry if I made it sound like you made an error. This is not the case. Thanks for updating the wiki page.

[datiswous]

9 hours ago, datiswous said:

I was wondering if this still works because I see it a lot in console warnings.

"leftPageCurl" , is that a windowDef devined where?

I think this and "rightPageCurl" are only used in multipage documents. But they are often still shown in single page gui files, which produces warnings in console.

[Geep]

Sounds plausible. Perhaps you could file a bug report?

[datiswous]

Source: https://wiki.thedarkmod.com/index.php?title=GUI_Scripting:_GUI::_Parameters

Quote

Another string example, from the mainmenu_briefing.gui:

background	"gui::BriefingVideoMaterial"

I think this should be:

Quote

Another string example, from the mainmenu_briefing_video.gui:

background	"gui::BriefingVideoMaterial"

 

I don't actually understand this. Where is it defined what BriefingVideoMaterial is?

Edited November 13, 2023 by datiswous

[Geep]

Good catch. I fixed the .gui name, and added afterwards this brief explanation:

The value here is a path to a custom video material shader. It is set at runtime by the engine, based on information the FM author provided in mainmenu_custom_defs.gui as, e.g.:

#define MM_BRIEFING_VIDEO_MATERIAL_1 "video/tdm_briefing_video"

(In older FMs, the video was chopped into parts, in which case the engine updates the value just-in-time. See comments in mainmenu_custom_defs.gui for details.)

FYI, there is a similar system for debriefing videos.

 

[datiswous]

So how it works is not defined in a script, but in this case in the engine code? How can I know that a GUI::Parameter is pointing at engine code instead of a script?

Is this the same for "gui::ModNotesText" on line 593 of mainmenu_newgame.gui ?

[Geep]

Yeah, there's nothing in the syntax that tells you if the gui parameter is set in a gui script or the engine. Sometimes there's a comment in the script that helps out by saying, for instance,  "// set by SDK".

If you really need to know - say, you're writing a wiki article - then typically you'd do a full-text search for the parameter name within and across files. Namely, the search scope may include:

1. FM-specific .gui files
2. Core .gui (and sometimes .guicode) files
3. Engine .cpp (and sometimes .h) files, of the source code retrieved from, for instance, github

I use TextPad to do this. In the case of (2), I have a local copy of the latest official TDM distribution (currently 2.11), where I have replaced every .pk4 with its unzipped equivalent. Because TextPad can't look inside .pk4 files.

In the case of "ModNotesText", method (2) found nothing except the line you indicated. Method (3) found this line in a version of the source code:

\darkmod_src-trunk\darkmod_src-trunk\game\ModMenu.cpp(81): gui->SetStateString("ModNotesText", info != NULL ? info->GetModNotes() : "");

So, yes, it's set by the engine.

 

[datiswous]

Thanks for the detailed answer @Geep. I thought I might ask too much, because it was getting a little over my head.

4 hours ago, Geep said:

use TextPad to do this. In the case of (2), I have a local copy of the latest official TDM distribution (currently 2.11), where I have replaced every .pk4 with its unzipped equivalent. Because TextPad can't look inside .pk4 files.

Good idea, although I think if you use 7zip for example, you can select "open in external editor" or something, and it will open in the default external editor. When I'm on a Windows pc it opens it in Notepad ++ . Maybe I should check out TextPad.

[Geep]

While Notepad++ does have a "Find in Files" feature, it's not well suited for this particular task (examining all the files of a particular type within a large directory tree). TextPad works well for Windows, but there's no doubt plenty of other ways to do it.

[datiswous]

On 11/15/2023 at 6:33 PM, Geep said:

While Notepad++ does have a "Find in Files" feature, it's not well suited for this particular task (examining all the files of a particular type within a large directory tree).

It has a plugin system, but if you are happy with textpad, then no reason to switch I guess.

Actually it doesn't matter, you still would have to open 7zip and then probably open every file seperatly. This isn't worable in your case. But I think you should be able to open seperate files in Textpad this way, because 7zip unzips it temporarly and passes the file to the default external editor (I think), so the editor (Textpad) doesn't need to read inside the pk4 file.

Edited November 17, 2023 by datiswous

[Geep]

With my method, you get the results for all the successful matches back in a convenient single temp file (i.e., tabbed pane); each match is a single line, that you can examine and, if of particular interest, click on to open the relevant file in a separate tab within Textpad.

I'm not sure that 7zip->Textpad would deliver the same convenient summary, even if it might spare having to pre-expand the .pk4 trees.