View source for GUI Scripting: Parsing of Set 'Cmd'

''See [[GUI Scripting Language]] for a broader background article.''

==Overview of GUI Commands Invoked by Set "Cmd"==
''by Geep''

GUI scripts typically contain event handlers (like onTime, onAction, etc.). Within the body of an event handler, there can be "set" commands, one form of which sets the value of a property or variable.

Another form, discussed here, has "cmd" as its first parameter. It invokes a "GUI command", parsed and acted upon in the core C++ code. This is one way developers working on the source code and main menu system (and related systems like objectives) can tie a GUI to core functionality.

===Unavailable to Mappers===
[https://forums.thedarkmod.com/index.php?/topic/21464-gui-on-a-world-object/&do=findComment&comment=475054 ''from greebo:'']

The set "cmd" trickery applies only to the main menu system, and will not work in regular player or entity GUIs. The main menu GUI has special support in the C++ code, e.g., in idGameLocal::HandleMainMenuCommand.

In particular, the logging available through the set "cmd" command, crucial in the past for debugging main menus, is not available to the mapper.

===Syntax===
 set "cmd" "value";
where ''value'' contains a GUI command and any parameters it takes.

===Examples===
The most frequently used GUI commands are "play" and "log", each of which takes one parameter:
 set "cmd" "log 'BriefingStateEnd called.'";
 set "cmd" "play sound/meta/menu/mnu_select;";

See the Note by Tels below about usage of "log" for main menu system testing.

Extending the above syntax, it is possible to list a sequence of commands, separated by semicolons:
 set "cmd" "play sound/meta/menu/mnu_select; saveGame 1";

Other commands tend to be used in the context of a particular GUI. A survey follows.

==TDM’s Specialized GUI Commands==
''by Geep''

This listing is "specialized" in the sense that it excludes 'log' and 'play'. Some commands shown are from Doom 3 days, but most have been added since. Be aware that there are additional GUI commands defined in the C++ code, but those shown here are in actual use (as of TDM 2.10) by each .gui file mentioned. A few take parameters (not always indicated here), but more typical is to set a state variable (e.g., in the GUI event handler) and have the function body retrieve it by name.

===Within GUIs of the Main Menu System===
* ''mainmenu_briefing.gui'': briefing_show, briefing_scroll_down_request, briefing_scroll_up_request
* ''mainmenu_briefing_video.gui'': briefingVideoHeartBeat, loadVideoDefinitions, prepareBriefingVideo, startBriefingVideo
* ''mainmenu_debriefing_video.gui'': debriefingVideoHeartBeat, prepareDebriefingVideo, startDebriefngVideo
* ''mainmenu_download.gui'': refreshAvailableMissionList, onDownloadableMissionSelected, onSelectMissionForDownload, onSelectallmissionsfordownload, onDeselectMissionForDownload, onStartDownload, onDownloadableMissionShowDetails, onGetNextScreenshotForAvailableMission, onGetPrevScreenshotForAvailbleMission
* ''mainmenu_failure.gui'': restart, exec tdm_restart_gui_update_objectives
* ''mainmenu_loadsave.gui'': loadsavemenu_init, updateSaveGameInfo, loadGame, close
* ''mainmenu_main.gui'': onStartMissionClicked, check_tdm_version, uninstallMod, mainmenu_init, refreshMissionList
* ''mainmenu_main_ingame.gui'': restart, mainmenuingame_init
* ''mainmenu_message.gui'': $gui::MsgBoxMiddleButtonCmd, $gui::MsgBoxLeftButtonCmd, $gui::MsgBoxRightButtonCmd
* ''mainmenu_music.gui'': $gui::BriefingVideoSoundCmd, $gui::DebriefingVideoSoundCmd, music nosound. Also, a number of #defines for various "MM_..._SOUND_CMD" music commands [Note 1].
* ''mainmenu_newgame.gui'': installSelectedMission, onClickInstallSelectedMission, onMissionSelected, loadModNotes, darkModRestart, eraseSelectedModFromDisk
* ''mainmenu_objectives.gui'': objective_open_request, diffSelect, close, objective_scroll_down_request, objective_scroll_up_request
* ''mainmenu_quit.gui'': quit
* ''mainmenu_settings.gui'': loadSettings
* ''mainmenu_settings_audio.gui'': sound, sound eax
* ''mainmenu_settings_gameplay.gui'': updateAIVision, updateAIHearing, setLPDifficulty, updateMeleeDifficulty
* ''mainmenu_settings_gamma.gui'': resetBrightness, resetGamma
* ''mainmenu_settings_guisize.gui'': resethud
* ''mainmenu_settings_language.gui'': setLang '<language>'
* ''mainmenu_settings_video.gui'': aspectRatioChanged, setVideoResWideScreen, updateCookedMathData, shadowimplchanged
* ''mainmenu_shop.gui'': shopLoad, shopDone, shopBuy, shopSold, shopMore, shopDropUndrop
* ''mainmenu_success.gui'': loadStatistics, onSuccessScreenContinueClicked
* ''mainmenu_utils.gui'': mainMenuStartup, loadCustomVideoResolution, loadVideoDefinitions, close, mainmenu_heartbeat

===Within Other Core GUIs===
* ''msg.gui'': left, mid, right
* ''tdm_invgrid.gui , tdm_invgrid_brown.gui , tdm_invgrid_parchment.gui'': updateInventoryGrid
* ''tdm_objectives.gui'': updateObjectives
* ''tdm_objectives_core.gui'': exec tdm_restart_gui_objectives_scrollup, exec tdm_restart_gui_objectives_scrolldown [Note 2] 
* ''tdm_waituntilready.gui'': playerIsReady
* ''readables\test\book<n>page.gui'': close

[Note 1] Uses #defines for MM_..._SOUND_CMD commands (for MENU, INGAME, CREDITS, MISSION_SUCCESS, BRIEFING, and BRIEFING_VIDEO) which are of form "music <sound>;". Default sounds are #defined in ''mainmenu_custom_defaults.gui''  These can be redefined by the mapper in ''mainmenu_custom_defs.gui''. For 2.08, defaults were defined in ''mainmenu_defs.gui''.

[Note 2] Via #defines OBJECTIVE_SCROLL_DOWN_CMD, OBJECTIVE_SCROLL_UP_CMD. In 2.10, these were defined in ''mainmenu_failure.gui''. In 2.08, in ''restart.gui''. (Maybe still earlier in ''tdm_objectives_defs.gui'').

===Changes in this List Between 2.08 and 2.10===

Probably most changes happened during the major menu revision of TDM 2.09. See also [Note 1][Note 2] above.

In 2.10, not 2.08:
* ''mainmenu_failure.gui'' - which was not in previous list; see above for calls.
* ''mainmenu_utils.gui'': mainmenumodeselect

Calls moved from ''mainmenu_newgame.gui'' in 2.08 to ''mainmenu_main.gui'' in 2.10:

onStartMissionClicked, uninstallMod, refreshMissionList

In 2.08, not 2.10:
* ''mainmenu_main_ingame.gui'': exec disconnect
* ''mainmenu_objectives.gui'': gui::mapStartCmd
* ''mainmenu_objectives_core.gui'': exec tdm_restart_gui_update_objectives
* ''mainmenu_restart.gui'': exec tdm_restart_gui_update_objectives
* ''mainmenu_settings.gui'': darkmodRestart
* ''mainmenu_settings_audio.gui'': settings_controls.gui
* ''mainmenu_shop.gui'': gui::mapStartCmd
* ''restart.gui'': restart, exec disconnect, exec tdm_restart_gui_update_objectives


== Early Implementation Note - When Parsing GUI Commands ==
''By Tels''

Commands in the main menu GUI with "cmd" as first parameter

 set "cmd" "mycommand argument1 argument2;"

are handled in <tt>idGameLocal::HandleMainMenuCommands()</tt> in ''game/game_local.cpp''.

''Geep adds: See that function for details of buffering, parsing, and dispatching or executing the GUI commands listed above. Code was further improved in TDM 2.09; see source code comments by stgatilov.''

=== Original Problem ===

For each of the parts "mycommand", "argument1", "argument2" and sometimes the final ";", the routine is called again. 

One special case is just using "set" "cmd" "mycommand", this will call <tt>HandleMainMenuCommands()</tt> twice, once with "mycommand" and once with ";" as the ''menuCommand'' parameter. 

Commands like "play" or "music" are special cases, too, only the first part ("play" or "music") is relayed to the routine, but the argument is not. Thus it seems impossible to recover what sound shader is to be played.

=== Implemented Solution ===

The routine therefore predicts how many arguments the current command takes, accumulating them on a stack. And when it has seen enough arguments, handles the command and clears the stack before returning. 

Any stray ";" as command is silently skipped.

The routine will also complain if you don't give enough arguments to a command.

=== Examples ===

 set "cmd" "play sound/meta/menu/mnu_hover";  // will result in "play", and potentially ";"
 set "cmd" "log 'Some text here';";           // will result in "log", "Some text here" and ";" - written to the console
 set "cmd" "mainmenu_heartbeat";              // will result in "mainmenu_heartbeat" and ";"
 set "cmd" "mainmenu_heartbeat;";             // will result in "mainmenu_heartbeat", ";" and ";"

Note: The "log" command only works on MainMenu guis, and only if the executable has been built with the cvar "tdm_debug_mainmenu" set to "1".

== See also ==

* [https://iddevnet.dhewm3.org/doom3/guis Introduction to Doom3 GUIs]
* [https://modwiki.dhewm3.org/GUI_scripting GUI Scripting] on modwiki
* For a look at available GUI Commands in the Doom 3 era, see [https://modwiki.dhewm3.org/Set_(GUI_command) The "set" command] on modiwiki.

{{GUI|sort=Set 'Cmd'}}