Custom Control Object (customControlObject)

Table of Contents

• Adding a New Control Object to the Tactical Graphics Palette
• Deriving, Modifying and Registering a Functional Create/ Edit Dialog
• Using UserData to Store and Retrieve Custom Parameters
• How to Run the Example
  • Classes
  • Plugin Entry Points

The Custom Control Object example adds a new control object to the create menus and creates and associates a new dialog box to use during creation and editing of this new control object.

The new control object and its dialog boxes are area-type objects and its classes are derived from the Area control object. Two custom numeric parameters are associated with the new control object.

The front-end example demonstrates the following:

• How to add a new control object to the Create menu
• How to derive and modify a functional create/ edit dialog
• How to use the UserData element of control objects to store and retrieve custom parameters

Adding a New Control Object to the Tactical Graphics Palette

Objects get assigned to the object creation palettes based on information in their .entity file. The information comes from the settings chosen in the Simulation Object Editor. Specifically, objects get placed on a palette based on the gui-on-palettes parameter. If this parameter is not specified, objects get placed on a palette based on their entity type enumeration. Objects with a kind value >= 16 get placed on the Tactical Graphics palette. The custom control object has a kind value of 18. Within a particular palette, objects get organized based on the gui-categories parameter. An object can be in more than one category.

Deriving, Modifying and Registering a Functional Create/ Edit Dialog

The Custom Control Object example inherits the dialog class structure used by Area control objects (DtShapeObjectDefinitionDialog, DtShapeObjectDefinitionDialogLogic and DtShapeObjectDefinitionDialogCreator), makes certain modifications and additions, and then registers the new dialog creator with the appropriate dialog manager (DtVrfObjectModifierDialogManager), associating it with the specific entity ID associated with the new control object.

DtCustomControlObjectDefinitionDialog, derived from DtShapeObjectDefinitionDialog, is ultimately derived from the Qt class QDockWidget. As such, it must be registered with Qt as a Q_OBJECT during compilation. Its specific role is to handle the placement and registration of GUI elements and transportation of data to and from these GUI elements. The Dialog class intantiates its own Logic class, DtCustomControlObjectDefinitionDialogLogic upon intialization.

DtCustomControlObjectDefinitionDialogLogic, derived from DtShapeObjectDefinitionDialogLogic, mostly acts as the interface between data from the DtCustomControlObjectDefinitionDialog and data in the rest of VR-Forces. In particular in this example, the Logic class translates betwen Parameter One and Parameter Two (an int and double, respectively) and userData, the std::string that they are stored in.

DtCustomControlObjectDefinitionDialogCreator is a class consisting only of a simple creator and initialization function that is registered with the Dialog Manager and called when the user invokes the creation or edit of the custom control object.

Using UserData to Store and Retrieve Custom Parameters

Adding an attribute to an entity is a fairly involved process (described and demonstrated in detail in the AddAttribute example). In order to expedite the process of adding attributes or parameters to control objects in VR-Forces, all control objects have a field of string type referred to as userData. This field is fully implemented but not used by stock VR-Forces.

The custom control object example introduces two custom parameters to the control object type, an int and a double (labeled as "Integer" and "Double" respectively). These parameters are transformed to and from a token-separated string by the Logic class and sent on to be stored in the control object's userdata field.

Naturally, extensive use of userdata must be carefully monitored to ensure that different implementations of userdata do not interfere with each other.

How to Run the Example

To view the new behavior:

1. Run VR-Forces.
2. Enable the Custom Control Object plug-in.
3. Restart VR-Forces.
4. Load the scenario userData\scenarios\developer_toolkit_examples\customControlObject\customControlObject.scn. This scenario includes the customControlObject.sms.
5. In the Control Objects category on the Tactical Graphics palette, select Custom Control Object.
6. Open the Create Custom Control Object dialog box.
7. Input boxes for the new parameters are above the window that lists the vertices for the control object.

Classes

The code for the three classes referenced in the table are here: Custom Control Object Dialog.

DtCustomControlObjectDefinitionDialog	The Qt-derived dialog class.
DtCustomControlObjectDefinitionDialogLogic	The logic class providing processing and transport of data to and from the dialog class.
DtCustomControlObjectDefinitionDialogCreator	The creator function for the dialog class, registered with the entity modification manager (DtVrfObjectModifierDialogManager).

---

Plugin Entry Points

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

//\file customControlObjectPlugin.cxx
//\brief Contains plugin function

//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 "customControlObjectDefinitionDialog.h"

#include <vrfGuiCoreQt/vrfObjectModifierDialogManager.h>
#include <vrfGuiCore/guiThreadVrfRemoteController.h>
#include <vrfExtProtocol/objectType.h>

#include <vrvCore/DtDe.h>
#include <vrvCoreQt/DtQtMenuAssembler.h>
#include "vrfGuiCoreQt/createMenu.h"
#include "vrvCore/DtMenuPath.h"
#include "vrvCore/DtVrvApplication.h"
#include "vrfGuiCore/vrfObjectManipulationManager.h"

using namespace makVrf;

//We need to register a new Dialog creation function with the objectModifierDialogManager, 
//but this plugin function is called prior to the normal initialization of the various managers
//and handlers.
void postInitDeModule(makVrv::DtDe& de)
{
   using namespace vrfCustomControlObjectExample;
   //retrieve a reference to the current instance of the DtVrfObjectModifierDialogManager
   DtVrfObjectModifierDialogManager& objectModifierDialogManager=DtVrfObjectModifierDialogManager::instance(de );

   //Register our custom dialog creator class with the objectModifierDialogManager
   //This associates the entity Id of the custom control object (defined in the constant DtCustomControlObjectType) with the 
   //new object definition dialog class via its creator
   DtCustomControlObjectDefinitionDialogCreator* customControlObjectDefinitionDialogCreator = new DtCustomControlObjectDefinitionDialogCreator;

   objectModifierDialogManager.addDialogCreationFcnForKind(DtCustomControlObjectType, 
      new DtObjectDefinitionDialogCreationParameters(customControlObjectDefinitionDialogCreator, true ));
}

bool initDeModule(makVrv::DtDe* de)
{
   return true;
}

void DtPluginInformation(DtVrfPluginInformation& info)
{
   info.pluginName = "Custom Control Object";
   info.pluginDescription = "Front-end plugin addition to add new Custom Control Object with associated dialog";
   info.pluginVersion = "1.00";   
   info.pluginCreator = "MAK Technologies";
   info.pluginCreatorEmail = "sales@mak.com";
   info.pluginContactWebPage = "www.mak.com";
   info.pluginContactMailingAddress = "150 Cambridge Park Drive 3rd Floor - Cambridge, MA 02140 USA";
   info.pluginContactPhone = "(617) 876 8085";
}