Add Task Example

The Add Task example adds a new kind of task - retreat - to the list of entity tasks. The method of doing so is to add a new task and controller which will receive and implement the new DtRetreatTask. The front-end component of the example inserts a "retreat" task menu item tied to a small dialog and ties it to the back-end components of Add Task.

The Add Task example is intended to demonstrate the following:

• How to add a new item to the task menu
• How to create and register a new task command
• How to send the task command from the front to the back-end

The VRF Front End Developers Guide has a more complete treatment of VR Forces menu manipulation and architecture, especially in section 3.1 as it pertains to our example. Additionally, common patterns used in this example are described in sections 9.3-9.5 (the Signaler, Factory and Creator patterns).

Adding an Item to the Task Menu

The fundamental unit of VR Forces menu items are described by objects of the DtMenuItem class - in the case of Set and Task menu items, the makVrf::DtVrfTaskSetMenuItem class. The DtMenuItem object in this example - called vrfAddTaskExample::DtTaskRetreatMenuItem - instantiates and registers a unique dialog ID with makVrf::DtTaskDialogCreator in its constructor. The class also configures the pure virtual createAction() to register the text and icon of the menu with its id number.

The menu item itself is registered with makVrf::DtTaskMenu in the plugin function initDeModule (in addTask/addTaskGui/addTaskPlugin.cxx). This requires:

1. Inserting the DtTaskRetreatAction menu item - in this case after the DtVrfTaskRotaryWingLandAction menu item.

2. Registering the DtTaskRetreatAction menu item with the menu assembler

   Additionally, the task creator function (vrfAddTaskExample::DtRetreatTask::creator()) is registered with makVrf::DtVrfSimMessager in the initialization function so that the front-end can communicate with the back-end (see the Add Task Back-end example )

Creating and Registering the New Task Dialog

1. a Dialog class - DtTaskRetreatDialog - deriving ultimately from DtTaskSetDialogInterface - that defines the dialog box, creates accessors & mutators, and communicates with the back-end
2. a Dialog Creator Class - DtTaskRetreatDialogCreator - deriving from DtVrfTaskSetDialogCreator - that simply creates the dialog object and is registered with the DtVrfTaskSetDialogManager

Since this example is loaded as a plugin, it can be used in conjunction with the released VR-Forces 3D application

Select Settings, Plugins... and on the Plugins Editor page, use the combo box at the top of the page to select the plug-in. Then enable the Load Plugin checkbox and re-start VR-Forces.

To view the new behavior, load the scenario data\scenarios\developer_toolkit_examples\addTask\retreat.scn Entities tasked to "retreat immediately" will move at full speed in the opposite direction from enemy entities Entities tasked to "hold ground" will stay still until they determine themselves to be "under fire," at which point they will retreat at full speed in the opposite direction from enemy entities

If the retreat command is to be enabled in any scenario, the addTask.sms file must be added to the scenario configuration. In the "New Scenario" window, under Simulation Model Sets, click the "..." button to open the Simulation Model Set Files dialog. Add the sms file .sms

Classes

DtTaskRetreatAction	menu item that is registered with the task menu from the plugin code.
DtTaskRetreatDialog	The widget that is used to select the retreat mechanism.
DtRetreatTask	The subclass of DtSimTask that is used to communicate the new task request.

---

Plugin Entry Points

/*******************************************************************************
** Copyright (c) 2011 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/

//\file addTaskPlugin.cxx
//\brief Contains registrations of the customized classes

//This file defines the generic DT_DLL_VRF_PLUGIN_EXPORT_MACRO.  Use that macro when
//you want to export symbols.  Also, in your CMakeLists.txt file, make sure to
//define the VRFPLUGIN_EXPORTS define to tell the compiler to define the macro as an
//export
#include <vrfGuiCore/vrfGuiExportPlugin.h>
#include "DtTaskRetreatMenuItem.h"
#include "../addTaskSim/retreatTask.h"

#include <vrfGuiCoreQt/DtTaskMenu.h>
#include <vrfGuiCore/DtGuiThreadVrfRemoteController.h>

//VR-Vantage includes
#include <vrvCore/DtDe.h>
#include <vrvCoreQt/DtQtMenuAssembler.h>

using namespace makVrf;

bool initDeModule(makVrv::DtDe* de)
{
   //Statically access the DtTaskMenu via the "de" provided by initDeModule
   DtTaskMenu& taskMenu = DtTaskMenu::instance(*de);

   //Inserts the DtTaskRetreatAction object name as the menu item into a 
   //specific point of the DtTaskMenu after the menu entry corresponding to 
   //"DtVrfTaskRotaryWingLandAction"
   taskMenu.menuConfiguration().addMenuPathBefore(
      makVrv::DtMenuPath::mainMenu(DtTaskMenuId).item("DtTaskRetreatAction"),
      makVrv::DtMenuPath::mainMenu(DtTaskMenuId).item(DtVrfTaskRotaryWingLandActionId));

   //Registers DtTaskRetreatAction with the task menu. The action specifies
   //what text to put in the menu and what dialog to show when it is selected.
   taskMenu.registerMenuItem(
      new vrfAddTaskExample::DtTaskRetreatAction(*de));

   DtGuiThreadVrfRemoteController::instance(*de).addTaskCreatorFcn(
      DtRetreatTaskTypeString, DtRetreatTaskType, DtRetreatTask::creator);

   return true;
}

//Fill out the information to be shown in the Plugin dialog (from the settings
//menu)
void DtPluginInformation(DtVrfPluginInformation& info)
{
   info.pluginName = "Add Task Gui";
   info.pluginVersion = "1.00";
   info.pluginDescription = "Front-end plugin addition to add new Retreat Task command";
   info.pluginCreator = "MAK Technologies";
   info.pluginCreatorEmail = "sales@mak.com";
   info.pluginContactWebPage = "www.mak.com";
   info.pluginContactMailingAddress = "68 Moulton Street - Cambridge, MA 02138";
   info.pluginContactPhone = "(617) 876 8085";
}