TorqueGameEngines/Torque3D
1
0
Fork 0
mirror of https://github.com/TorqueGameEngines/Torque3D.git synced 2026-03-18 20:00:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

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

Browse source
This commit is contained in:
JeffR 2022-05-09 16:17:22 -05:00
parent 41add628ad
commit 07b3e2789e
6 changed files with 260 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

51
Templates/BaseGame/game/data/UI/guis/MainMenuButtons.tscript
View file

@ -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);
}

2
Templates/BaseGame/game/data/UI/guis/chooseLevelDlg.tscript
View file

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

29
Templates/BaseGame/game/data/UI/guis/mainMenu.tscript
View file

@ -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();

12
Templates/BaseGame/game/data/UI/guis/optionsMenu.tscript
View file

@ -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?",

108
Templates/BaseGame/game/data/UI/scripts/menuInputHandling.tscript
View file

@ -26,18 +26,30 @@ btn_start = Start
btn_back = Back/Select
*/
//==============================================================================
/// Summary:
/// This is used with the main UI menu lists, when a non-axis input event is called
/// such as pressing a button
/// It is called from the engine
///
/// \param %device (string) The name of the device the input event is coming fromt
/// \param %action (string) The specific key/input action
/// \param %state (bool) The down/up state of the event sent
function UIMenuButtonList::onInputEvent(%this, %device, %action, %state)
{
if(%state)
$activeMenuButtonContainer.processInputs(%device, %action);
}
//==============================================================================
/// Summary:
/// This is used with the main UI menu lists, when an axis input event is called
/// such as moving a joystick
/// It is called from the engine
///
/// \param %device (string) The name of the device the input event is coming fromt
/// \param %action (string) The specific key/input action
/// \param %axisVal (float) The float value of the axis event
function UIMenuButtonList::onAxisEvent(%this, %device, %action, %axisVal)
{
//Skip out of the value is too low as it could just be noise or miscalibrated defaults
@ -47,6 +59,8 @@ function UIMenuButtonList::onAxisEvent(%this, %device, %action, %axisVal)
$activeMenuButtonContainer.processAxisEvent(%device, %action);
}
//==============================================================================
/// Summary:
/// Sets the command and text for the specified button. If %text and %command
/// are left empty, the button will be disabled and hidden.
///
@ -83,6 +97,9 @@ function MenuInputButton::set(%this, %gamepadButton, %keyboardButton, %text, %co
%this.refresh();
}
//==============================================================================
/// Summary:
/// Disables the MenuInputButton, marking it as not to consume inputs or display
function MenuInputButton::disable(%this)
{
%this.setText("");
@ -91,6 +108,8 @@ function MenuInputButton::disable(%this)
%this.setVisible(false);
}
//==============================================================================
/// Summary:
/// Refreshes the specific button, updating it's visbility status and the displayed input image
function MenuInputButton::refresh(%this)
{
@ -203,6 +222,8 @@ function MenuInputButton::refresh(%this)
return true;
}
//==============================================================================
/// Summary:
/// Refreshes a menu input container, updating the buttons inside it
function MenuInputButtonContainer::refresh(%this)
{
@ -215,6 +236,8 @@ function MenuInputButtonContainer::refresh(%this)
}
}
//==============================================================================
/// Summary:
/// Sets the given MenuInputButtonContainer as the active one. This directs input events
/// to it's buttons, ensures it's visible, and auto-hides the old active container if it was set
function MenuInputButtonContainer::setActive(%this)
@ -227,6 +250,8 @@ function MenuInputButtonContainer::setActive(%this)
$activeMenuButtonContainer.refresh();
}
//==============================================================================
/// Summary:
/// Checks the input manager for if we have a gamepad active and gets it's name
/// If we have one, also sets the active input type to gamepad
function MenuInputButtonContainer::checkGamepad(%this)
@ -241,12 +266,17 @@ function MenuInputButtonContainer::checkGamepad(%this)
$activeControllerType = "gamepad";
}
//==============================================================================
/// Summary:
/// This is called by the earlier inputs callback that comes from the menu list
/// this allows us to first check what the input type is, and if the device is different
/// (such as going from keyboard and mouse to gamepad) we can refresh the buttons to update
/// the display
/// Then we process the input to see if it matches to any of the button maps for our
/// MenuInputButtons. If we have a match, we execute it's command.
///
/// \param %device (string) The device that is causing the input event
/// \param %action (string) The name of the input action
function MenuInputButtonContainer::processInputs(%this, %device, %action)
{
//check to see if our status has changed
@ -305,10 +335,16 @@ function MenuInputButtonContainer::processInputs(%this, %device, %action)
}
}
//==============================================================================
/// Summary:
/// This is called by the earlier inputs callback that comes from the menu list
/// this allows us to first check what the input type is, and if the device is different
/// (such as going from keyboard and mouse to gamepad) we can refresh the buttons to update
/// the display
///
/// \param %device (string) The name of the device the input event is coming fromt
/// \param %action (string) The specific key/input action
/// \param %axisVal (float) The float value of the axis event
function MenuInputButtonContainer::processAxisEvent(%this, %device, %action, %axisVal)
{
//check to see if our status has changed
@ -367,6 +403,15 @@ function onSDLDeviceDisconnected(%sdlIndex)
// This'll let the active menu list be navigated, as well as buttons be processed
// and ultimately handled by the Input Buttons above
//==============================================================================
//==============================================================================
/// Summary:
/// This is used with the main UI menu lists, when an axis input event is called
/// such as moving a joystick
/// It is called from the engine
///
/// \param %device (string) The name of the device the input event is coming fromt
/// \param %action (string) The specific key/input action
/// \param %axisVal (float) The float value of the axis event
function MenuInputHandler::onAxisEvent(%this, %device, %action, %value)
{
//this is to force a refresh of the menu
@ -416,6 +461,15 @@ function MenuInputHandler::onAxisEvent(%this, %device, %action, %value)
}
}
//==============================================================================
/// Summary:
/// This is used with the main UI menu lists, when a non-axis input event is called
/// such as pressing a button
/// It is called from the engine
///
/// \param %device (string) The name of the device the input event is coming fromt
/// \param %action (string) The specific key/input action
/// \param %state (bool) The down/up state of the event sent
function MenuInputHandler::onInputEvent(%this, %device, %action, %state)
{
if(%action $= "upov" || %action $= "dpov" || %action $= "lpov" || %action $= "rpov")
@ -432,6 +486,10 @@ function MenuInputHandler::onInputEvent(%this, %device, %action, %state)
// Menu List processing
// These functions manage the navigation and activation of the Menu Lists
//==============================================================================
//==============================================================================
/// Summary:
/// Is the GUIContainer with this MenuList namespace the 'active' menulist as far
/// as UI interfaces is concerned?
function MenuList::isActiveMenuList(%this)
{
if($activeMenuList == %this)
@ -440,6 +498,14 @@ function MenuList::isActiveMenuList(%this)
return false;
}
//==============================================================================
/// Summary:
/// Sets the GUIContainer with this MenuList namespace as the active menulist.
/// This means that any input events caught in MenuInputHandlers is directed at
/// this menu list to navigate it
///
/// \param %startPosition (Point2F) The X and Y starting positions of the selection for this menuList
/// \param %menuMode (string) Indicates the mode/type of menuList, allowing for special behaviors depending on type
function MenuList::setAsActiveMenuList(%this, %startPosition, %menuMode)
{
if(%startPosition $= "")
@ -456,7 +522,9 @@ function MenuList::setAsActiveMenuList(%this, %startPosition, %menuMode)
%this.refresh();
}
//==============================================================================
/// Summary:
/// Activates the currently highlighted child object
function MenuList::activate(%this)
{
//check for a highlighted element
@ -467,6 +535,11 @@ function MenuList::activate(%this)
}
}
//==============================================================================
/// Summary:
/// refreshes the menuList, updating children highlight status and if there is
/// a button pointer control defined on our list, we update it's position as
/// needed
function MenuList::refresh(%this)
{
%selectedObject = -1;
@ -516,6 +589,10 @@ function MenuList::refresh(%this)
}
}
//==============================================================================
/// Summary:
/// Selects the next 'up' child item in the menuList. If the current is the topmost
/// then nothing happens
function MenuList::navigateUp(%this)
{
$activeMenuList.ListPosition.y -= 1;
@ -525,6 +602,10 @@ function MenuList::navigateUp(%this)
%this.refresh();
}
//==============================================================================
/// Summary:
/// Selects the next 'down' child item in the menuList. If the current is the bottommost
/// then nothing happens
function MenuList::navigateDown(%this)
{
$activeMenuList.ListPosition.y += 1;
@ -534,6 +615,10 @@ function MenuList::navigateDown(%this)
%this.refresh();
}
//==============================================================================
/// Summary:
/// Selects the next 'left' child item in the menuList. If the current item is the leftmost
/// then nothing happens
function MenuList::navigateLeft()
{
//Atm, we're only handling specific control types, namely options entries, but
@ -564,6 +649,10 @@ function MenuList::navigateLeft()
}
}
//==============================================================================
/// Summary:
/// Selects the next 'right' child item in the menuList. If the current item is the rightmost
/// then nothing happens
function MenuList::navigateRight()
{
%btn = $activeMenuList.getObject($activeMenuList.ListPosition.y);
@ -590,13 +679,24 @@ function MenuList::navigateRight()
}
}
//==============================================================================
/// Summary:
/// Gets the current vertical positionally selected child object
function MenuList::getActiveRow(%this)
{
return $activeMenuList.ListPosition.y;
}
//==============================================================================
/// Summary:
/// Called from the engine when a GUIButtonBase-derived class with MenuListButton namespace class
/// has its highlighting status changed. Allows us to react to this change of state and trigger refreshse
/// or other events to keep the navigation tracking up to date
///
/// \param %state (bool) The on/off state of the button being highlighted
function MenuListButton::onHighlighted(%this, %state)
{
echo("MenuListButton::onHighlighted() - " @ %this.internalName @ " was " @ %state @ " highlighted");
%parentContainer = %this.getParent();
if(%parentContainer.class $= "MenuList" || %parentContainer.superClass $= "MenuList")
{
@ -607,6 +707,7 @@ function MenuListButton::onHighlighted(%this, %state)
%parentContainer.buttonPointerCtrl.setHidden(false);
%buttonCenter = %this.getGlobalCenter();
echo(" - button center:" @ %buttonCenter);
if(%parentContainer.centerButtonPointerCtrl)
{
@ -617,7 +718,12 @@ function MenuListButton::onHighlighted(%this, %state)
//if we're not centering, then left-justify
%parentContainer.buttonPointerCtrl.setGlobalCenter(%buttonCenter.x - %this.extent.x / 2, %buttonCenter.y);
}
echo(" - pointer position:" @ %parentContainer.buttonPointerCtrl.getPosition());
}
/*else
{
%parentContainer.buttonPointerCtrl.setHidden(true);
}*/
}
}
}

63
Templates/BaseGame/game/data/UI/scripts/menuNavigation.tscript
View file

@ -1,3 +1,12 @@
//==============================================================================
/// Summary:
/// This function sets the root page for the navigation stack. The root page is 'below'
/// all other normal pages and cannot be popped like a normal page.
/// When we set a new root page, we first check if we have an existing root page.
/// If we do, we run the usual canClose() then onClose() function pair, then we
/// set it and call the onOpen() for the new root page.
///
/// \param %rootPage (guiControl) The new guiControl that is being set as the root page of the navigation stack
function UINavigation::setRootPage(%this, %rootPage)
{
if(!isObject(%this.pageStack))
@ -36,6 +45,25 @@ function UINavigation::setRootPage(%this, %rootPage)
%rootPage.call("onOpen");
}
//==============================================================================
/// Summary:
/// This function pushes a page onto the given UINavigation-classed GUIContainer's stack
/// The order of operations is thus:
/// 1) check to see if the new page being pushed says it can open via the canOpen() function.
/// If this method is not defined, it defaults to true, as there's no impediment to continuing
/// If this check returns false, the pushPage event cancels.
/// 2) check to see if the current page on the stack says it can close. Similar to
/// the canOpen() check on the new page, we default to true
/// If this check returns false, the pushPage event cancels.
/// 3) Call - if defined - onClose() on the current top page of the stack
/// 4) Add the new page onto the stack
/// 5) Call - if defined - onOpen() on the new page
/// 6) Finally, if we defined a callback, call that.
/// With this all run, the previous top page has done any cleanup work it needed to
/// and the new top page has been opened successfully.
///
/// \param %newPage (guiControl) The new guiControl that is being added onto the page stack
/// \param %callback[optional]: (Evaluable string) A evalable statement to invoke when the push has been completed
function UINavigation::pushPage(%this, %newPage, %callback)
{
if(!isObject(%this.pageStack))
@ -80,6 +108,24 @@ function UINavigation::pushPage(%this, %newPage, %callback)
eval(%callback);
}
//==============================================================================
/// Summary:
/// This function pops the topmost page off the given UINavigation-classed GUIContainer's stack
/// The order of operations is thus:
/// 1) check to see if the top page being popped says it can close via the canClose() function.
/// If this method is not defined, it defaults to true, as there's no impediment to continuing
/// If this check returns false, the popPage event cancels.
/// 2) check to see if the previous page on the stack says it can open. Similar to
/// the canClose() check on the new page, we default to true
/// If this check returns false, the popPage event cancels.
/// 3) Call - if defined - onClose() on the current top page of the stack
/// 4) Remove the top page
/// 5) Call - if defined - onOpen() on the now topmost page
/// 6) Finally, if we defined a callback, call that.
/// With this all run, the previous top page has done any cleanup work it needed to
/// and the new top page has been opened successfully.
///
/// \param %callback[optional] (Evaluable string) A evalable statement to invoke when the pop has been completed
function UINavigation::popPage(%this, %callback)
{
if(%this.pageStack.count() == 0)
@ -128,6 +174,12 @@ function UINavigation::popPage(%this, %callback)
eval(%callback);
}
//==============================================================================
/// Summary:
/// In order tops the topmost page in a loop until it has closed the entire stack,
/// leaving only the root page
///
/// \param %callback[optional] (Evaluable String) A evalable statement to invoke when the pop has been completed
function UINavigation::popToRoot(%this, %callback)
{
%pageChanged = false;
@ -177,6 +229,10 @@ function UINavigation::popToRoot(%this, %callback)
eval(%callback);
}
//==============================================================================
/// Summary:
/// Gets the current, topmost page on the stack. If no non-root pages are on the stack
/// the root page is returned
function UINavigation::getCurrentPage(%this)
{
if(isObject(%this.pageStack) && %this.pageStack.count() != 0)
@ -192,6 +248,10 @@ function UINavigation::getCurrentPage(%this)
return 0;
}
//==============================================================================
/// Summary:
/// Gets the page just under the topmost page in the stack. If there is no previous page
/// then the root page is returned
function UINavigation::getPreviousPage(%this)
{
if(isObject(%this.pageStack) && %this.pageStack.count() > 1)
@ -207,6 +267,9 @@ function UINavigation::getPreviousPage(%this)
return 0;
}
//==============================================================================
/// Summary:
/// Gets the number of pages on the stack.
function UINavigation::getPageCount(%this)
{
%count = 0;