4.8 - Getting and Setting User-Created State Property Values

Table of Contents

• 4.8.1 Simple Properties
• 4.8.2 Structure Properties
• 4.8.3 List Properties
• 4.8.4 Map Properties

This section explains how to retrieve state property data from a C++ plugin to the VRF simulation engine.

The state properties that are available to an object are defined in its OPE file in the SMS. The code examples in this section use the following state properties as they might be defined in an OPE file.

(state-data
   (DtRwString TestString "testing123" publish)
   (DtRwInt TestInt 123 publish)
   (DtRwReal TestReal 1.23 publish)
   (DtRwStructure TestStruct
      (DtRwString Type "some type")
      (DtRwInt Count 123)
      publish
   )
   (DtRwList TestList
      (DtRwString Text)
      ("item1")         ;; This definition adds 3 default items
      ("item2")
      ("item3")
      publish
   )     
   (DtRwList TestMapB DtRwInt     ;; A simple map type
      (DtRwReal ItemValue)
   )
   (DtRwList TestMapB DtRwString  ;; A more complex map type
      (DtRwStructure Item 
         (DtRwString ItemName)
         (DtRwReal ItemAmount)
      )
      publish
   )
)

In the VR-Forces simulation engine, each object stores its properties in its object state repository. So if you have a pointer to the DtVrfObject you can look up its state and parameter properties with the following code.

DtRwProperties& stateProps = vrfObj->vrfState()->stateProperties();
DtRwProperties& paramProps = vrfObj->vrfState()->parameterProperties();

In the VR-Forces GUI you can access the state properties from the object state. This is the DtVrfObjectDataState for entities, the DtVrlinkSimulatedAggregateState for aggregates, and DtVrlinkSimulatedEnvironmentProcess for environmental processes and tactical graphics. If you have the DtSimEntry for an entity, you can look up its state properties as follows.

DtVrfObjectDataState* objectState = findStateFor<DtVrfObjectDataState*>(entry);
if (objectState)
{
   DtRwProperties& stateProps = objectState->myStateProperties;
}

4.8.1 Simple Properties

Simple properties are those that use basic types like DtRwBoolean, DtRwReal, DtRwInt, or DtRwString. To get the value of a simple property, use the findPropertyValue() function. This is a template function that returns a boost::optional. A boost::optional wraps the value in a data type that allows you to test if a value has been set. If the property could not be found or converted to the specified type, then the boost::optional will have a value of false.

boost::optional<int> testIntVal = 
   obj->vrfState()->stateProperties()->findPropertyValue<int>(“TestInt”);
if (testIntVal)
{
   int val = *testIntVal;
}

To immediately set the value of a simple state property, use the findAndSetPropertyValue() template function. It returns true if it is successful.

bool success = findAndSetPropertyValue<int>(
   obj->vrfState()->stateProperties(), “TestInt”, newValue);

4.8.2 Structure Properties

Properties can be structures consisting of multiple fields. Each field is itself a property, so fields can be simple types, structures, lists, or maps. Property structures are implemented using the DtRwPropertiesStructure class. DtRwProperties also has a function that finds and returns the specific ReaderWriter property class for any property rather than just the value. You can use it to find the DtRwPropertiesStructure object instance for the structure. Then each field in the structure can be accessed using findFieldValue() or findAndSetFieldValue().

DtRwPropertiesStructure* propStruct =
  obj->vrfState()->stateProperties()->findProperty<DtRwPropertiesStructure>(
   "TestStruct");
if (propStruct)
{
   // Lookup current values
   boost::optional<DtString> oldType = 
      propStruct->findFieldValue<DtString>(“Type”);      
   boost::optional<int> oldCount = 
      propStruct->findFieldValue<int>("Count");

   // Set new values
   propStruct->findAndSetFieldValue<DtString>(“Type”, newType);
   propStruct->findAndSetFieldValue<int>(“Count”, newCount);
}

It is also possible to directly access fields within a property using findPropertyValue() and findAndSetPropertyValue(). To specify a field within a structure, use the format <PropertyName>.<FieldName> in place of the property name in the function call.

boost::optional<int> testStructCount = 
   obj->vrfState()->stateProperties()->findPropertyValue<int>(“TestStruct.Count”);

4.8.3 List Properties

Properties can be lists. Each item in a list must have the same type. The item type can be a simple property type, a structure, or another list or map. The list maintains a prototype item that identifies the type of its items. It will not allow any new items to be added that do not match this prototype. Property lists are implemented using the DtRwPropertiesList class. This class has additional functions that can help in navigating lists and accessing their items.

Lists have iterators that function in a similar fashion to the iterators used in C++ STL containers. Each iterator allows access to the underlying DtPropertyInterface, which is the interface class from which all property classes are derived. You can extract the value from a DtPropertyInterface using the propertValue() template function.

const DtRwPropertiesList* testList = 
   obj->vrfState()->stateProperties()->findProperty<DtRwPropertiesList>(
   "TestList");

if(testList)
{
   DtRwPropertiesList::const_iterator iter = testList->begin();
   for (; iter != testList->end(); ++iter)
   {
      boost::optional<DtString> itemVal = iter->propertyValue<DtString>();
      if (itemVal)
      {
         DtWarn << “Item value: “ << *itemVal;
      }
   }
}

To add a new item to a list you can use the addItem() function. This function comes in two forms. The first takes a DtPropertyInterface*, though the item this pointer points to must be of the same type as the list’s prototype. The second form returns a DtPropertyInterface* that points to a new item of the same type as the prototype.

DtRwPropertiesList* testList = 
      obj->vrfState()->stateProperties()->findProperty<DtRwPropertiesList>(
      "TestList");

if (testList)
{
   // Add existing property as an item to the list
   DtRwPropertyString* newItemA = new DtRwPropertyString(“newItemA”, “value A”);
   bool success = testList->addItem(newItemA);

   // Add a new property as an item to the list
   DtPropertyInterface* newItemB = testList->addItem();
   newItemB->setPropertyValue<DtString>(“value B”);
    }

You can also remove properties from the list with the erase() function.

testList->erase(newItemB);

4.8.4 Map Properties

A map property is a specialized type of list property that can be indexed by a key. Map keys must be some type of integer, real, or string. Property maps are implemented using the DtRwPropertiesMap class. This class has iterators just as the list does, but it also adds additional functions that allow you to easily access items by their key value.

If you want to look up a specific item in a map by the key, you can use findItem() or findItemValue().

const DtRwPropertiesMap* testMapA = 
   obj->vrfState()->stateProperties()->findProperty<DtRwPropertiesMap>(
   "TestMapA");


if (testMapA)
{
   const DtPropertyInterface* item = testMapA->findItem(7);
   boost::optional<double> itemVal = testMapA->findItemValue<double>(3);
}

You can add new items using either insert() or addItem(). Use insert() to add a previously created item. This item must have the same type as the map prototype item. Use addItem() to have the map create a new item of the same type as its prototype.

DtRwPropertyReal* newRealItem = new DtRwPropertyReal(“”, 45.6);
testMapA->insert(23, newRealItem);

DtPropertyInterface* newItem = testMapA->addItem(50);
newItem->setPropertyValue<double>(12.34);

Maps also allow you to erase items by their key.

testMapA->erase(3);

A map allows you to use the operator[] to access an item by its key. This returns a reference to the item’s DtPropertyInterface. If the item does not exist, a new one is added.

(*testMapA)[8].setPropertyValue<double>(89.1);

[<< User-Created State Properties] [Home] [Top of Page] [Publishing User-Created State Properties >>]