Custom Control Object

Table of Contents

• Adding a New Control Object to the Create Menu
• 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 to use during creation and editing of this new control object.

The new control object and its dialogs are area-type objects and its classes are derived from the Area control object. Two custom 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 Create Menu

Construction of the Create Menu or Palette is specified by the entity.mst file in vrforces\data\simulationModelSets\default\gui\entity.mst. Each entry specifies certain attributes of the entity or object, including its submenu - in our case "Control Objects" - and its entity type - in our case (1 18 0 0 1 0 0 101). Please note that the entity type value must correspond to a value defined in vrforces\data\simulationModelSets\default\vrfSim.opd and in an associated OPE file. The custom control object in this example is sufficiently described and handled by the the general Area control object type (1 18 -1 -1 -1 -1 -1 -1) for the purposes of its behavior and parameterization, so there is no need to introduce a unique OPD entry or OPE file.

Please note that additional entries into the Create Menu via the entity.mst file does not in and of itself add or specify a custom dialog. it simply adds an additional menu item. For creating and linking a custom dialog, see the next section.

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 expidite 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 (called "parameter one" and "parameter two," 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. Create a new scenario.
2. In the "New Scenario" specification window, select VR-Forces\data\simulationModelSets\developer_toolkit_examples\customControlObject.sms as an "Additional SMS File".
3. Create a Custom Control Object. It will be located under "Control Objects" in the create menu or palette
4. Click open the autoHide dialog tab
5. Specify at least three vertices and key in values for the two custom parameters. Complete the area by right-clicking the final vertex on the map.

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/DtGuiThreadVrfRemoteController.h>
#include <vrfExtProtocol/objType.h>

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

using namespace makVrf;

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

//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 initPluginMenus(makVrv::DtVrvApplication& app, 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 ));
}

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";
}