In order to tell Orocos how to display your type, you may overload the TemplateTypeInfo::write and TemplateTypeInfo::write functions or define operator<<() and operator>>() for your type.

  #include <rtt/TemplateTypeInfo.hpp>
  #include <ostream>
  #include <istream>

  // Displaying:
  std::ostream& operator<<(std::ostream& os, const ControlData& cd) {
     return os << '('<< cd.x << ',' << cd.y << ',' << cd.z << '): ' << cd.sample_nbr;
  }

  // Reading (not sufficient for scripting):
  std::istream& operator>>(std::istream& is, ControlData& cd) {
     char c;
     return is >> c >> cd.x >> c >> cd.y >> c >> cd.z >> c >> c >> cd.sample_nbr; // 'c' reads '(' ',' ',' ')' and ':'
  }
  // ...
  // The 'true' argument means:  it has operator<< and operator>>
  struct ControlDataTypeInfo
    : public RTT::TemplateTypeInfo<ControlData,true>
  {
     ControlDataTypeInfo()
        : RTT::TemplateTypeInfo<ControlData,true>("ControlData")
     {}
  };

  // Tell Orocos the name and type of this struct
  RTT::types()->addType( new ControlDataTypeInfo() );
	

If you use the above line of code to add the type, Orocos will be able to display it as well, for example in the TaskBrowser or in the ReportingComponent. Other subsystems may use your operators to exchange data in a text-based form. However, in order to 'construct' your type in a script or at the TaskBrowser prompt, you need to add a constructor as shown in Section 1.3.2, “Loading Constructors”.

In order to inform Orocos of the structure of your data type, it must be given a 'decompose' function: Of which primitive types does the struct consists ? Representing structured data is what Orocos Property objects do. Here is how to tell Orocos how the "ControlData" is structured:

  // ...
  struct ControlDataTypeInfo
    : public TemplateTypeInfo<ControlData,true>
  {
     // ... other functions omitted

     virtual bool decomposeTypeImpl(const ControlData& in, PropertyBag& targetbag ) const {
         targetbag.setType("ControlData");
         targetbag.add( new Property<double>("X", "X value of my Data", in.x ) );
         targetbag.add( new Property<double>("Y", "Y value of my Data", in.y ) );
         targetbag.add( new Property<double>("Z", "Z value of my Data", in.z ) );
         targetbag.add( new Property<int>("Sample", "The sample number of the Data", in.sample_nbr ) );
         return true;
     }
  }

That was easy ! For each member of your struct, add a Property of the correct type to the targetbag and you're done ! setType() can be used lateron to determine the version or type of your XML representation. Next, if Orocos tries to write an XML file with ControlData in it, it will look like:

  <struct name="MyData" type="ControlData">
    <simple name="X" type="double">
       <description>X value of my Data</description>
       <value>0.12</value>
    </simple>
    <simple name="Y" type="double">
       <description>Y value of my Data</description>
       <value>1.23</value>
    </simple>
    <simple name="Z" type="double">
       <description>Z value of my Data</description>
       <value>3.21</value>
    </simple>
    <simple name="Sample" type="short">
       <description>The sample number of the Data</description>
       <value>3123</value>
    </simple>
  </struct>
	

Orocos does not know yet how to convert an XML format back to the ControlData object. This operation is called 'composition' and is fairly simple as well: Here is how to tell Orocos how the "ControlData" is read:

  // ...
  struct ControlDataTypeInfo
    : public TemplateTypeInfo<ControlData,true>
  {

     // ... other functions omitted

     virtual bool composeTypeImpl(const PropertyBag& bag, ControlData& out ) const 
     {
        if ( bag.getType() == std::string("ControlData") ) // check the type
        {  
          Property<double>* x = targetbag.getProperty<double>("X");
          Property<double>* y = targetbag.getProperty<double>("Y");
          Property<double>* z = targetbag.getProperty<double>("Z");
          Property<int>* t = targetbag.getProperty<int>("Sample");

	  if ( !x || !y || !z || !t )
	     return false;

          out.x = x->get();
          out.y = y->get();
          out.z = z->get();
          out.sample_nbr = t->get();
          return true;
        }
        return false; // unknown type !
     }
  }

First the properties are located in the bag, it should look just like we stored them. If not, return false, otherwise, read the values and store them in the out variable.

In order to transfer your data between components over a network, Orocos requires that you provide the conversion from your type to a CORBA::Any type and back, quite similar to the 'composition' and 'decomposition' of your data. Look at the TemplateTypeInfo interface for the functions you need to implement.

The first step is describing your struct in IDL and generate the 'client' headers with 'Any' support. Next you create such a struct, fill it with your data type's data and next 'stream' it to an Any. The other way around is required as well.

In addition, you will need the CORBA support of Orocos enabled in your build configuration.

In order to add more complex types, take a look at the code of the RealTimeToolkit and the KDL Toolkit Plugin of Orocos.

Operator are stored in the class OperatorRepository in Operators.hpp. The list of supported operators is set by the toolkit and added to the OperatorRepository It looks something like this:

bool loadOperators() {
  OperatorRepository::shared_ptr oreg = RTT::operators();
  // boolean stuff:
  oreg->add( newUnaryOperator( "!", std::logical_not<bool>() ) );
  oreg->add( newBinaryOperator( "&&", std::logical_and<bool>() ) );
  oreg->add( newBinaryOperator( "||", std::logical_or<bool>() ) );
  oreg->add( newBinaryOperator( "==", std::equal_to<bool>() ) );
  oreg->add( newBinaryOperator( "!=", std::not_equal_to<bool>() ) );
  return true;
} 

Adding your own should not be terribly hard. The hardest part is that as the second argument to newUnaryOperator, newBinaryOperator or newTernaryOperator, you need to specify a STL Adaptable Functor, and even though the STL provides many predefined one's, it does not provide all possible combinations, and you might end up having to write your own. The STL does not at all provide any "ternary operators", so if you need one of those, you'll definitely have to write it yourself.

Note that this section is only about adding overloads for existing operators, if you want to add new operators to the scripting engine, the parsers need to be extended as well.

Constructors can only be added after a type has been loaded using addType. Say that the ControlData struct has a constructor:

  struct ControlData {
    // Don't forget to supply the default constructor
    // as well.
    ControlData() 
      : x(0), y(0), z(0), sample_nbr(0)
    {}
    ControlData(double a, double b, double c) 
      : x(a), y(b), z(c), sample_nbr(0)
    {}
    double x, y, z;
    int sample_nbr;
  }

This constructor is not automatically known to the type system. You need to write a constructor function and add that to the type info:

  // This 'factory' function constructs one object.
  ControlData createCD(double a, double b, double c) {
    return ControlData(a,b,c);
  }

  // Tell Orocos a constructor is available:
  // Attention: "ControlData" must have been added before with 'addType' !
  RTT::types()->type("ControlData")->addConstructor( newConstructor(&createCD) );
	

From now on, one can write in a script:

  var ControlData cd = ControlData(3.4, 5.0, 1.7);

Multiple constructors can be added for the same type. The first one that matches with the given arguments is then taken.

Orocos allows to call small functions on data types in order to extract meta data or individual elements. Say that the ControlData struct has a helper function to determine if the data is valid and a function for each data part:

  struct ControlData {

    // Returns true if the data corresponds to a measurement.
    bool isValid() { return sample_nbr >= 0; }

    // Returns x,y,z
    double getX() { return x; }
    double getY() { return y; }
    double getZ() { return z; }

    double x, y, z;
    int sample_nbr;
  }

The question is now how to access these values in scripting. The RTT calls this 'dot' operators. They allow you to write:

  var ControlData cd = ...;

  if ( cd.valid ) {
    double norm_square = cd.x*cd.x + cd.y*cd.y + cd.z*cd.z ;
    // ...
  }

In order to add the .x, .y, .z and .valid 'dot' operators to the 'ControlData' type you need to add these pieces of code to your toolkit:

  // These 'query' structs use ControlData
  struct get_cd_valid
     : public std::unary_function<ControlData, bool>
  {
      bool operator()(ControlData& data ) const
      {
          return data.isValid();
      }
  };

  // These 'query' structs use ControlData
  struct get_cd_x
     : public std::unary_function<ControlData, double>
  {
      double operator()(ControlData& data ) const
      {
          return data.getX();
      }
  };

  // These 'query' structs use ControlData
  struct get_cd_y
     : public std::unary_function<ControlData, double>
  {
      double operator()(ControlData& data ) const
      {
          return data.getY();
      }
  };

  // These 'query' structs use ControlData
  struct get_cd_z
     : public std::unary_function<ControlData, double>
  {
      double operator()(ControlData& data ) const
      {
          return data.getZ();
      }
  };

  // Finally, add these helper structs to the OperatorRepository:
  OperatorRepository::shared_ptr oreg = RTT::operators();
  oreg->add( newDotOperator( "valid",  get_cd_valid() ) );
  oreg->add( newDotOperator( "x",  get_cd_x() ) );
  oreg->add( newDotOperator( "y",  get_cd_y() ) );
  oreg->add( newDotOperator( "z",  get_cd_z() ) );

The dot operator (DotOp) is ONLY for reading. You can not use it to write to a data type. So this will not work:

  var ControlData cd = ControlData(3.4, 5.0, 1.7);

  cd.x = 0.0; // error!

The current work-around is to write:

  var ControlData cd = ControlData(3.4, 5.0, 1.7);
  cd = ControlData(0.0, cd.y, cd.z); // use its constructor !