Adds proper documentation and explains some of the navigation/menu usage behavior via the BaseUI example menus

Templates/BaseGame/game/data/UI/guis/MainMenuButtons.tscript

@@ -6,19 +6,52 @@ function MainMenuButtons::onSleep(%this)
 {
 }
 
-//Optional, as the check defaults to true, but here as an example case
+//==============================================================================
+// This gets called by the MainMenuGUI beacuse it, being a UINavigation classed control
+// set MainMenuButtonList as it's root page. 
+// This is an optional function, but is called as part of the validation that the page
+// CAN be opened, so it's shown here as an example
 function MainMenuButtonList::canOpen(%this)
 {
    return true;
 }
 
+//==============================================================================
+// This gets called by the MainMenuGUI beacuse it, being a UINavigation classed control
+// set MainMenuButtonList as it's root page. 
+// Once the page is added to the MainMenuGUI's UINavigation page stack, onOpen here is called
+// Which allows us to actually do the work we need to do for display
 function MainMenuButtonList::onOpen(%this)
 {
+   //Here, we set the MainMenuButtonList - a GuiStackControl with the MenuList class
+   // to be the active menu list.
+   // This means that when the MainMenuGUI's MainMenuInputHandler receives an input
+   // or we have one of the buttons in the MainMenuButtonHolder be actioned, we know
+   // we're working/navigating this list of buttons specifically
+   // In practice, it sets the $activeMenuList global variable so the various menu class code
+   // can reference it consistently
    MainMenuButtonList.setAsActiveMenuList();
    
+   //Because MainMenuGUI set it's MainMenuButtonHolder as the active button container, we can reference it
+   //by $activeMenuButtonContainer and set the menu button/accelerator prompts we need for the MainMenuButtonList
+   //specifically.
+   //In particular, being a simple list of buttons, the only one we NEED is a simple activate, so we'll
+   //disable all the other ones to keep them clear in case they were set by other pages at some point
    $activeMenuButtonContainer-->button1.disable();
    $activeMenuButtonContainer-->button2.disable();
    $activeMenuButtonContainer-->button3.disable();
+   
+   //Here we set the 4th button in the container
+   //All the buttons have the MenuInputButton class, which, like the other classes
+   //help keep things accessible and consistent. Here we use that class's set function to
+   //configure the accelerator behavior
+   //The first parameter sets the gamepad button to the 'A' button
+   //The second sets the keyboard button to Enter or Return
+   //Third is what the displayed text will be
+   //And finally we set the command when the button is clicked, or either key inputs are caught by
+   //our MenuInputHandler
+   //The menu buttons automatically detect which input device you're using and swap the display between
+   //gamepad or keyboard for consistent behavior
    $activeMenuButtonContainer-->button4.set("btn_a", "Return", "Go", "MainMenuButtonList.activate();");
    $activeMenuButtonContainer-->button5.disable();
 }
@@ -34,6 +67,7 @@ function MainMenuButtonList::onClose(%this)
 {
 }
 
+//Our actual commands when we activate the buttons
 function openSinglePlayerMenu()
 {
    $pref::HostMultiPlayer=false;
@@ -43,16 +77,31 @@ function openSinglePlayerMenu()
 function openMultiPlayerMenu()
 {
    $pref::HostMultiPlayer=true;
+   
+   //Here, like the other commands, we add a new page onto the stack
+   //In this case, we'll push the ChooseLevelDlg control onto the stack. This will
+   //invoke the canClose() and then onClose() functions for MainMenuButtonList
+   //before calling the onOpen() for ChooseLevelDlg then displaying.
    MainMenuGui.pushPage(ChooseLevelDlg);
 }
 
 function openJoinServerMenu()
 {
+   //Here, like the other commands, we add a new page onto the stack
+   //In this case, we'll push the JoinServerMenu control onto the stack. This will
+   //invoke the canClose() and then onClose() functions for MainMenuButtonList
+   //before calling the onOpen() for JoinServerMenu then displaying.
    MainMenuGui.pushPage(JoinServerMenu);
 }
 
 function openOptionsMenu()
 {
+   //Here, like the other commands, we add a new page onto the stack
+   //In this case, we'll push the OptionsMenu control onto the stack. This will
+   //invoke the canClose() and then onClose() functions for MainMenuButtonList
+   //before calling the onOpen() for OptionsMenu then displaying.
+   //The options menu additionally has an example of why we may want to capitalize on the
+   //canClose() call.
    MainMenuGui.pushPage(OptionsMenu);
 }
 

Templates/BaseGame/game/data/UI/guis/chooseLevelDlg.tscript

@@ -102,8 +102,6 @@ function ChooseLevelDlg::onOpen(%this)
    else
       LevelSelectTitle.setText("CREATE SERVER");
    
-   ChooseLevelButtonHolder.setActive();
-
    $activeMenuButtonContainer-->button1.disable();
    $activeMenuButtonContainer-->button2.disable();
    $activeMenuButtonContainer-->button3.disable();

Templates/BaseGame/game/data/UI/guis/mainMenu.tscript

@@ -5,17 +5,44 @@ function MainMenuGui::onAdd(%this)
 
 function MainMenuGui::onWake(%this)
 {
+   //In the BaseUI example case, the MainMenuGUI acts as our background
+   //So it's a logical control to set as our UINavigation as well. So we 
+   //set the MainMenuGUI's superClass to UINavigation to integrate it into
+   //that namespace to open up page navigation
+   
+   //At the same time, the MainMenuGUI control has the button holder, set to
+   //the MenuInputButtonContainer class, allowing us to set it as the active button
+   //holder here, prepping it for catching any button inputs to active commands
+   //Specifically, it sets the $activeMenuButtonContainer to be this, which allows
+   //other controls to manage what the behavior of the buttons is consistently
+   //without needing to worry about hardcoded names
    MainMenuButtonHolder.setActive();
+   
+   //We also have the MainMenuInputHandler, a GuiInputCtrl with the MenuInputHandler class
+   //This allows us to catch any input/axis event and pass it along to the active menuList
+   //or button containers to navigate the menus
+   //We set up this catch by making said control our first responder, here
    MainMenuInputHandler.setFirstResponder();
    
+   //Lastly, we go ahead and display some actual navigable content up on our main menu here
+   //In this case, we set the MainMenuButtonList as our root page, so we always come back
+   //to having the main menu buttons on screen if every other page is closed.
+   //This will ultimately call MainMenuButtonList::onOpen(), so to see where the navigation
+   //chain continues, see that function.
    %this.setRootPage(MainMenuButtonList);
    
+   //We also go ahead and mark for any future pages being added to the UINavigation's page stack
+   //to be prompted to resize when added. This isn't required, but helps keep pages formated to 
+   //the current size of the UINavigation, which is useful when dealing with aspect ratio or resolution
+   //changes.
    %this.resizePages = true;
 }
 
 function MainMenuButtonHolder::onWake(%this)
 {
-   //clean slate
+   //Because the blan slate MainMenuGUI doesn't have anything we need to bother with inputs on
+   //we just go ahead and disable all the buttons in our MainMenuButtonHolder to have
+   // a clean slate
    %this-->button1.disable();
    %this-->button2.disable();
    %this-->button3.disable();

Templates/BaseGame/game/data/UI/guis/optionsMenu.tscript

@@ -116,8 +116,17 @@ function OptionsMenu::onOpen(%this)
    $activeMenuButtonContainer-->button5.set("btn_b", "Escape", "Back", %this @ ".navigation.popPage();");
 }
    
+//We capitalize on the canClose test here, because we want to prompt for unapplied options changes before
+//backing out. So when the UINavigation test canClose, we can see if we have unapplied settings and prompt
+//that via the message box and return false.
+//This gives the user a chance to choose how they wish to proceed before we allow the 
+//UINavigation to move away from the options menu
 function OptionsMenu::canClose(%this)
 {
+   //Another special case is us catching the 'back/pop' action by just shifting from one
+   //menu list to another. In this case, we check if we were on the settings list as our active MenuList
+   //if so, then the back/pop just moves us to the Category list as our active and we inform the 
+   //UINavigation to not close the page
    if(OptionsMenuSettingsList.isActiveMenuList())
    {
    OptionsMenuCategoryList.setAsActiveMenuList();
@@ -126,6 +135,9 @@ function OptionsMenu::canClose(%this)
    }
    else
    {
+      //Here, we're on the category list as our active, so we're actually trying to leae the page
+      //If we have unapplied changes, we want to prompt about them before closing the page and navigating away
+      //If we don't, then we can process the popPage as normal and let the OptionsMenu close
       if(%this.unappliedChanges.count() != 0)
       {
          MessageBoxOKCancel("Discard Changes?", "You have unapplied changes to your settings, do you wish to apply or discard them?",