orxCommand_Register

Comments

• iarwain

  June 2014 edited June 2014

  Hi lightman and welcome here!
  
  Commands can take an arbitrary number of required parameters followed by an arbitrary number of optional ones, however their order cannot be altered. All commands must have a return value.
  
  In addition to the examples you can find in orx's code itself, here are a couple of examples:
  
  - No parameters, returning a bool
  

  orxCOMMAND_VAR_DEF stResult;
  
  stResult.eType = orxCOMMAND_VAR_TYPE_BOOL;
  stResult.zName = "ReturnName";
  
  orxCommand_Register("Module.Command1", &CommandFunction1, 0, 0, orxNULL, &stResult);
  

  
  Note it's not mandatory to have a command formatted as "Module.Command", but it's more consistent with all the commands already shipping with orx.
  
  - 2 required string parameters, 1 optional float one, returning a string
  

  orxCOMMAND_VAR_DEF stResult = {"ReturnName", orxCOMMAND_VAR_TYPE_STRING};
  orxCOMAND_VAR_DEF astParamList[] =
  {
    {"StringParam1", orxCOMMAND_VAR_TYPE_STRING},
    {"StringParam2", orxCOMMAND_VAR_TYPE_STRING},
    {"OptionalFloatParam", orxCOMMAND_VAR_TYPE_FLOAT}
  };
  
  orxCommand_Register("Module.Command2", &CommandFunction2, 2, 1, astParamList, &stResult);
  

  
  And here are examples for the functions themselves:
  

  void orxFASTCALL CommandFunction1(orxU32 _u32ArgNumber, const orxCOMMAND_VAR *_astArgList, orxCOMMAND_VAR *_pstResult)
  {
    orxLOG("Command1 executed!")
  
    // Updating result
    _pstResult->bValue = orxTRUE;
  }
  
  void orxFASTCALL CommandFunction2(orxU32 _u32ArgNumber, const orxCOMMAND_VAR *_astArgList, orxCOMMAND_VAR *_pstResult)
  {
    static orxCHAR sacBuffer[4096] = {};
  
    orxLOG("Command2 executed!")
  
    orxLOG("Param1: %s", _astArgList[0].zValue);
    orxLOG("Param2: %s", _astArgList[1].zValue);
  
    if(_u32ArgNumber > 2)
    {
      orxLOG("Optional Param: %f", _astArgList[2].fValue);
    }
  
    // Concatenates first two params in static buffer
    orxString_NPrint(acBuffer, sizeof(acBuffer) - 1, "%s%s", _astArgList[0].zValue, _astArgList[1].zValue);
  
    // Updating result
    _pstResult->zValue = sacBuffer;
  }
  
• iarwain

  June 2014 edited June 2014

  Also note that the example with no params, as written above, would trigger an assert in debug versions. I just fixed that in orx tonight.
  You can either sync to the latest code (or get the next nightly build), or pass a dummy non-NULL value for the parameter list (it won't be read anyway).
• lightman

  June 2014 edited June 2014

  Hi!
  
  Thanks so much for the quick reply.
  
  Your examples were just what I needed to understand how to define the functions.
• iarwain

  June 2014 edited June 2014

  Glad I could help!
  
  Don't hesitate if you have any other questions.