Implementing an About box and a Help Manual - Part 1

Section 3.3.2 of the EULA:

Quote:
3.3.2. display in the "About" box or in the credits screen of the Product the text "Powered by Torque [Version]";

Hmm, so we need either an "About" dialog or a credits screen with the words "Powered by Torque [version]". I'm going to do both!

Somewhere inside of scripts/client/default.bind.cs you'll also find this:

Quote:
GlobalActionMap.bindCmd(keyboard, "F1", "", "contextHelp();");

This keybind is leftover from the days of TGE. For those of you who do not have access to or never experienced the venerable TGE, contextHelp was a built-in (scripted) help system that implemented an about screen, credits, and simple instruction pages on using the various editors. Somewhere along the evolution of TGE to Torque 3D this Help system was removed.

This Resource will re-implement it, covering the EULA stipulation above as well as demonstrating how to setup the various help pages. On an "About" dialog we'll be adding a link to the Help system where we will incorporate a "more information" page about the application, a "credits" page, and a page showing the default control setup that we'll be able to access directly instead of the current ControlsHelpDlg hud.

The About BoxFirst let's add a new folder to the art/gui directory, name it help. Inside of art/gui/help is where to place the required .gui and .cs script files, the help pages, and all relevant art assets.

Start with the "About" dialog which will contain a GuiWindowCtrl, a GuiMLTextCtrl, and two GuiButtonCtrls (one for opening a "more info" page of the manual, another for closing the dialog box. The important control here is the GuiMLTextCtrl which will be named 'aboutText'. You'll also need to add an "AboutButton" to the MainMenu which has this command:

command = "Canvas.pushDialog(aboutDlg);";

Create the aboutDlg.gui file in your preferred manner - here is the one I made if you're lazy:

//--- OBJECT WRITE BEGIN ---
%guiContent = new GuiControl(aboutDlg) {
   position = "0 0";
   extent = "1024 768";
   minExtent = "8 8";
   horizSizing = "right";
   vertSizing = "bottom";
   profile = "GuiDefaultProfile";
   visible = "1";
   active = "1";
   tooltipProfile = "GuiToolTipProfile";
   hovertime = "1000";
   isContainer = "1";
   canSave = "1";
   canSaveDynamicFields = "1";
      helpTag = "0";

   new GuiWindowCtrl() {
      text = "About...";
      resizeWidth = "0";
      resizeHeight = "0";
      canMove = "1";
      canClose = "1";
      canMinimize = "0";
      canMaximize = "0";
      canCollapse = "0";
      closeCommand = "Canvas.popDialog(aboutDlg);";
      edgeSnap = "1";
      margin = "0 0 0 0";
      padding = "0 0 0 0";
      anchorTop = "1";
      anchorBottom = "0";
      anchorLeft = "1";
      anchorRight = "0";
      position = "324 232";
      extent = "376 303";
      minExtent = "8 8";
      horizSizing = "center";
      vertSizing = "center";
      profile = "GuiWindowProfile";
      visible = "1";
      active = "1";
      tooltipProfile = "GuiToolTipProfile";
      hovertime = "1000";
      isContainer = "1";
      canSave = "1";
      canSaveDynamicFields = "0";

      new GuiMLTextCtrl(aboutText) {
         lineSpacing = "2";
         allowColorChars = "0";
         maxChars = "-1";
         text = "This is a test";
         useURLMouseCursor = "0";
         position = "19 36";
         extent = "336 223";
         minExtent = "8 8";
         horizSizing = "width";
         vertSizing = "relative";
         profile = "GuiMLTextProfile";
         visible = "1";
         active = "1";
         tooltipProfile = "GuiToolTipProfile";
         hovertime = "1000";
         isContainer = "0";
         canSave = "1";
         canSaveDynamicFields = "0";
      };
      new GuiButtonCtrl() {
         text = "OK";
         groupNum = "-1";
         buttonType = "PushButton";
         useMouseEvents = "0";
         position = "287 260";
         extent = "60 23";
         minExtent = "8 8";
         horizSizing = "right";
         vertSizing = "bottom";
         profile = "GuiButtonProfile";
         visible = "1";
         active = "1";
         command = "Canvas.popDialog(aboutDlg);";
         tooltipProfile = "GuiToolTipProfile";
         hovertime = "1000";
         isContainer = "0";
         canSave = "1";
         canSaveDynamicFields = "0";
      };
      new GuiButtonCtrl() {
         text = "More...";
         groupNum = "-1";
         buttonType = "PushButton";
         useMouseEvents = "0";
         position = "28 260";
         extent = "76 23";
         minExtent = "8 8";
         horizSizing = "right";
         vertSizing = "bottom";
         profile = "GuiButtonProfile";
         visible = "1";
         active = "1";
         command = "getHelp(\"About\");";
         tooltipProfile = "GuiToolTipProfile";
         hovertime = "1000";
         isContainer = "0";
         canSave = "1";
         canSaveDynamicFields = "0";
      };
   };
};
//--- OBJECT WRITE END ---

Now for the magic MLText stuff. Add the following to
the aboutDlg.gui:

function aboutDlg::onWake(%this)
{
   %text="<just:center><bitmap:art/gui/help/logoyours>\n\n\n<font:Arial Bold:20>THIS IS MY GAME!\n"@
         "<font:Arial:12>Copyright (c) 20XX by me.\n"@
         "Version: "@ getVersionNumber() @", "@ getVersionString() @", "@ getBuildString() @" Build\n"@
         "Compile time: "@ getCompileTimeString() @"\n\n"@
         "<font:Arial:16>Powered by Torque 3D\n"@
         "<bitmap:art/gui/help/logotorque><sbreak><a:www.garagegames.com>GarageGames.Com</a>";
   aboutText.setText(%text);   
}   

function aboutText::onURL(%this, %url)
{
   echo("\c4AboutText: "@ %this @" is opening url:"@ %url);
   gotoWebPage(%url);
}

Notice the MLText formatting. We'll be displaying a "company" logo, the name of the game, a copyright notice, version information, and our EULA required "powered by Torque [version] string. As a bonus we'll throw in a Torque logo as well as a link to GarageGames.com that will open the webpage in your internet browser. Take note of the text that reads "THIS IS MY GAME!" and the copyright information, as you'll most likely want to change this. The onWake() callback stuffs our formatted text string into the GuiMLTextCtrl of the "About" box. The onUrl() callback is what happens when a hyperlink is clicked, in this case a call to gotoWebPage(). For a listing of MLText commands available in TorqueScript visit the GUI/TorqueML page on the TDN wiki.

Add these two images to art/gui/help. Right-click, then save as:
logoyours.png:
logotorque.png:

Don't forget to exec the gui from scripts/client/init.cs in function initClient(), somewhere after the other guis are loaded:

exec("art/gui/help/aboutDlg.gui");

Now when you run the game you'll get something like this when you click your "About" button. If you didn't add an "About" button, simply access the aboutDlg through the GUI Editor:

Note that the "More..." button doesn't work, yet. It will work once the help system is in place.

Continued in Part 2