Interactor
[The interaction protocol]

Collaboration diagram for Interactor:

TO DO . More...

Classes
class	OMK::Iii::InteractiveExtension
	The extension to make an object interactive. More...
class	OMK::Iii::InteractorExtension
	Ancestor of every interactive, interactor or inspector objects. More...
class	OMK::Iii::InteractorOutput
	This class defines informations about interactor output. More...
class	OMK::Iii::SessionPrm
	Define a session of interaction between an interactor and an interactive object. More...

---

Detailed Description

TO DO .

How to define an interactor object ?

To define an interactor object you have to:

• define a new class, child of ExtensibleSimulatedObject
• add to it the attribute which will become the interactor outputs
• add to it an extension child of the InteractorExtension

Create interactor extension

To define your own interactor you have to define a new interactor extension. By using InteractorExtension as base class you don't have to create the interactor outputs, they will be automatically created with the informations find in the configuration parameters of the extension.

The main job to do in your extension is to create a state machine call by the postComputeParameters. The state of the machine will evolve according to events that the object will receive, so you will need to define some listeners and associated call back methods to update the internal state of your states machine.

Example of interactor

The following example shows a code that define an interactor object based on the SimplePoint which define a position in the space. To convert this simple object in an interactor we have to define a interactor extension and add this one to it.

• First we declared the extension, a son of InteractorExtension

  class MyInteractorExtension : public OM::Iii::InteractorExtension
  {
    DECLARE_EXTENSION_FACTORY( MyInteractorExtension ) ;
    ...
  

• then we declare a states machine

    // states of state machine 
    enum States{ EWaitingState,
                 EStartInteraction,
                 EControlTakeOver,
                 EControlState,
                 EControlRelease,
                 EFinishInteraction } ;
    // Current state
    States _state ;
  

• an id for the associated attribute which will be the output of the interactor

    // Associated attribute
    PsName _attributeId ;
  

• an id to identify the interactive object which will be controled

    // The id of the interactive object to control
    OM::AttributeTypeT< PsName > _interactiveObject ;
  

• Then the call back to take and release the control

    bool startInteraction( PsEvent* e ) ;
    bool stopInteraction( PsEvent* e ) ;
  

• and the redefined methods of the extension

    bool loadExtensionParameters( const PsConfigurationParameterDescriptor * node ) ;
    void postComputeParameters() ;
  } ;
  

In the code, we found

• The registration of the extension in the factory

  REGISTER_EXTENSION_FACTORY( MyInteractorExtension, "MyInteractorExtension" ) ;
  

• The constructor which adds an attribute to retrieve the id of the interactive object

  MyInteractorExtension::MyInteractorExtension( OM::ExtensibleSimulatedObject *owner, const PsName &id )
    : OM::Iii::InteractorExtension( owner, id ),
      _interactiveObject( "interactiveObject", "unknow" ),
      _state( EWaitingState ),
      _attributeId( "Position" )
  {
    owner->addAttribute( _interactiveObject ) ;
  }
  

• The destructor which has nothing to do

  MyInteractorExtension::~MyInteractorExtension()
  {
  }
  

• The loader of the configuration parameters which initialise the call back methods associated to a key of the keyboard

  bool MyInteractorExtension::loadExtensionParameters( const PsConfigurationParameterDescriptor * node )
  {
    // The extension need to know the name of the visualisation object to add the keyboard call back methods
    std::string visuName  ;
    if( PsParametersAccessor::get( node, "VisuName", visuName, _owner ) )
    {
      // The call back for take control of the interactive object
      std::string key = "T" ;
      PsParametersAccessor::get( node, "TakeControlKey", key ) ; // optional
      new PsEventListenerCallBack< MyInteractorExtension >
        ( *_owner, this, &MyInteractorExtension::startInteraction, OM::Inp::KeyListener::getKeyReleaseCode( key ) ) ;
      _owner->sendValuedEvent( visuName, OM::Inp::InputExtension::ADD_KEY, OM::Inp::AddInputKeyPrm( key, _owner->getName() ) ) ;
      // The call back for release the control of the interactive object
      std::string key = "R" ;
      PsParametersAccessor::get( node, "ReleaseKey", key ) ; // optional
      new PsEventListenerCallBack< MyInteractorExtension >
        ( *_owner, this, &MyInteractorExtension::stopInteraction, OM::Inp::KeyListener::getKeyReleaseCode( key ) ) ;
      _owner->sendValuedEvent( visuName, OM::Inp::InputExtension::ADD_KEY, OM::Inp::AddInputKeyPrm( key, _owner->getName() ) ) ;
    }  
    // the following attribute should declare an associated output, 
    // optional because set to the "Position" attribute of the object
    PsParametersAccessor::get( node, "AttributeId", _attributeId ) ;
    
    // will retrieve the optional parameter to set the _interactiveObject
    return InteractorExtension::loadExtensionParameters( node ) ;
  }
  

• The call back method to change the state of the machine to control the interactive object

  bool MyInteractorExtension::startInteraction( PsEvent* e )
  {
    if( _state == EWaitingState )
    {
      _state = EStartInteraction ;
    }
  }
  

• The call back method to change the state of the machine to release the interactive object

  bool MyInteractorExtension::stopInteraction( PsEvent* e )
  {
    if( _state == EControlState )
    {
      _state = EControlRelease ;
    }
  }
  

• And the compute method which define the behavior of the state machine

  void MyInteractorExtension::postComputeParameters()
  {
    switch( _state )
    {
      // Waiting for the call of the startInteraction call back
      case EWaitingState :
        break;
      // Starts the session with the interactive object and goes to the next state
      case EStartInteraction :
      {
        OMMESSAGE( "I am going to start with " << _interactiveObject ) ;
        startSessionWith( _interactiveObject ) ;
        _state = EControlTakeOver ;
      }
      break ;
      // Send the messages to take the control and to retrieve the current position of the interactive object 
      // then goes to the next state
      case EControlTakeOver :
      {
        OMMESSAGE( "I am taking control of " << _interactiveObject ) ;
        (*getSessionWith( _interactiveObject )).c( _attributeId ).c( OM::Iii::controlTakeOver ) ;
        (*getSessionWith( _interactiveObject )).c( _attributeId ).c( OM::Iii::getCurrentValues ) ;
        _state = EControlState ;
      }
      break ;
      // The objetc is under control 
      // Waiting for the call of the stopInteraction call back
      case EControlState :
        break;
      // Stops the session with interactive object then goes to the next state
      case EControlRelease :
      {
        OMMESSAGE( "I am releasing " << _interactiveObject ) ;
        (*getSessionWith( _interactiveObject )).c( _attributeId ).c( OM::Iii::controlRelease ) ;
        _state = EFinishInteraction ;
      }
      break;
      // Closes the session then returns to the waiting state
      case EFinishInteraction :
      {
        OMMESSAGE( "Session closed with " << _interactiveObject ) ;
        closeSessionWith( _interactiveObject ) ;
        _state = EWaitingState ;
      }
      break;
      default:
        OMASSERTM( false, "Forbidden state" ) ;
    }
  }
  

To use the extension you have to add it to the object in the configuration file

interactor
{
  Class SimplePoint
  Scheduling
  {
    Frequency 60
  }
  Extensions
  {
    interactor
    {
      Class MyInteractorExtension
      Level 0                       // The access level of the interactor
      Outputs                       // Define the interactor outputs
      {
        Position                    // for the attribute "Position"
        {
          Category "absolute"       // The category of the output
        }
      }
      VisuName visuOgre             // Specific parameter of MyInteractorExtension to activate the keyboard
    }
  }
}

Example of session

Written like this, the interactor cannot control anything. We must add to it some features to get the id of an interactive object. This id can be gotten by picking in a scene or by an event sent to the interactor,...
Once this is done, it can start the interaction. To do this part of its job, it can use the session object. This object is designed to manage the communication through events of the protocol between the interactor and an interactive object.
First it must start the session with a simulated object indicated by its id.

startSessionWith( _interactiveObject ) ;

This command creates a session and send the "parameters ?" event to the simulated object. If this one is an interactive one, it is answering with the list of its interactive parameters according to the access level of the interactor and those of its parameters. When the listener of the interactor receives this list it is mapping the type and category of the each parameters to those of the interactor outputs. Once this is done, the session is initialized and a list of the parameters controllable is established. Now the session object knows which parameter can be controlled and by which output.
The next step can be to retrieve the current values of the parameters. This is useful to initialize the output values to avoid difference between the output which will take the control of a parameter and the current value of this one. The answer calls indirectly the call back method associated to each interactor output.
To ask for all available parameters associable to an interactor output, the call is:

(*getSessionWith( _interactiveObject )).c( OM::Iii::getCurrentValues ) ;

If only some parameters are wanted, you must specify the output you want to use, the call becomes:

(*getSessionWith( _interactiveObject )).c( Prm::integerValue ).c( OM::Iii::getCurrentValues ) ;

The same syntax is used for 'control take over', 'control release', 'control freeze' and 'control unfreeze'

How to extend the behavior ?

As shown in How to extend the behavior ? the accessors can do few more things than only accessed the parameters, they can define new behaviors. The other way to extend the behavior is to define new kind of session with more functionalities.

By creating a new kind of session

This example shows a session object, which uses id to indicate if the interactive parameter will be frozen when its control is taken over. This example cannot be used as this, it is not functional.

• First we declare the new session class with is constructor, creator and destructor

  class SessionPrmBis : public OM::Iii::SessionPrm
  {
  protected:
    // Constructor
    SessionPrmBis( OM::Iii::IEventInteractiveObjectListener* listener, const PsName& interactiveObject ) 
    : OM::Iii::SessionPrm( listener, interactiveObject ) 
    {
    }
  public:
    // Creator
    static SessionPrmBis* create( OM::Iii::IEventInteractiveObjectListener* listener, const PsName& interactiveObject ) 
    {
      return new SessionPrmBis( listener, interactiveObject ) ;
    }
    // Destructor
    virtual ~SessionPrmBis() {}
  

• We declare the two internal ids to freeze or not freeze the interactive parameters

  protected:
    static PsName freezeId ;
    static PsName unfreezeId ;
  

• To store the freeze flag we store it in the _ids vector. So we overwrite the flow operator to add two ids at once, the first is the id of the interactor output, the second the freeze flag, by default, this one is set to freeze

  public:
    // Overwrite the flow operator to add two ids at once
    virtual OM::Iii::SessionPrm& c ( const OMK::Name& interactiveObjectId ) 
    { 
      _ids.push_back( interactiveObjectId ) ;
      _ids.push_back( freezeId ) ;
      return *this; 
    }
  

• We declare a protected method to set the flag, two friend functions which work with the flow operator

  protected:
    // To set the freeze flag 
    void selfFreeze( bool freeze ) 
  { // Should test the size !
      _ids[_ids.size()-1] = freeze ? freezeId : unfreezeId ;
    }
  public:
    inline friend OM::Iii::SessionPrm& frozen( OM::Iii::SessionPrm & s ) 
    {
      // Must cast the object to access to inner method
      dynamic_cast<SessionPrmBis&>(s).selfFreeze( true ) ;
      return s ;
    }
    inline friend OM::Iii::SessionPrm& notFrozen( OM::Iii::SessionPrm & s ) 
    {
      // Must cast the object to access to inner method
      dynamic_cast<SessionPrmBis&>(s).selfFreeze( false ) ;
      return s ;
    }
  

• Then we overwrite the selfControlTakeOver method to take into account the frozen flag. To work fine, the other inner methods "self*" should do the same.

  protected:
    // Overwrite the "control take over" to take into account the frozen flag 
    void selfControlTakeOver() 
    { 
      OM::Type::AccessTakeOverPrm connectorsToControl( _listener->getAccessLevel() ) ;   
      if( !_ids.empty() )
      {
        // loop with a step of 2, the first "_ids[ i ]" is the parameter id, the second  "_ids[ i + 1 ]" the freeze flag
        for ( int i = 0 ; i < _ids.size() ; i += 2 )
        {
          std::map< PsName, SessionPrm::Link >::const_iterator link = _links.find( _ids[ i ] ) ;
          if( link != _links.end() )
          {
            connectorsToControl.addItem( OM::Iii::ControlTakeOverPrm( link->second.connector, link->first, _ids[ i + 1 ] == freezeId ) ) ;
          }
          else
          {
            OMTRACE( "the id \"" << _ids[ i ] << "\" is not available" ) ;
          }
        }
      }
      else
      {
        OMTRACE( "cannot use an empty list" ) ;
      }
      if( !connectorsToControl.getItems().empty() )
      {
        _listener->getInteractor()->sendValuedEvent( _interactiveObject, EventId::controlTakeOver, AccessTakeOverType( connectorsToControl ) ) ;
      }
      _ids.clear() ;
    }
  } ;
  

This new session object will be created like this by the interactor:

class MyInteractorObject : public OM::Iii::InteractiveSimulatedObject
{
  //...  
  // Overwrites the startSessionWith method to use the new session object instead of the old one 
  virtual void startSessionWith( const PsName& interactiveObject ) 
  {
    OMASSERT( _eventInteractiveObjectListener && "cannot be null, must be an initialized interactor object" ) ;
    _eventInteractiveObjectListener->addSession( SessionPrmBis::create( _eventInteractiveObjectListener, interactiveObject ) ) ;
  } 
  //...
} ;

The startSessionWith method can be overwritten by the EventInteractiveObjectListener, which can also extend the behavior. It can offer different session types.
So there is no change to start a session in the interactor methods:

startSessionWith( _interactiveObject ) ;

And it will be used like this with the 'control take over' operation:

(*getSessionWith( _interactiveObject ))).c( Prm::integerValue  ).c( frozen )
                                        .c( Prm::floatingValue ).c( notFrozen )
                                        .c( OM::Iii::controlTakeOver ) ;

---