The CComAPIHandler class implements a C++ wrapper for calling automation objects (scripting objects) or objects implemented using the Softimage Object Model (formerly called the COM API).
Automation objects can be created from C++ using CComAPIHandler::CreateInstance. The handler provides access to an automation object's methods and properties via CComAPIHandler::Call, CComAPIHandler::GetProperty, CComAPIHandler::PutProperty and CComAPIHandler::Invoke.
using namespace XSI; CStatus st; CComAPIHandler xsiuitoolkit; xsiuitoolkit.CreateInstance( L"XSI.UIToolkit"); CValue return = xsiuitoolkit.GetProperty( L"ProgressBar" ); // The return contains a pointer to the progressbar // that has had its reference count incremented, the destructor of CValue // takes care of dereferencing the pointer. CComAPIHandler progressbar( return ); // set min/max progressbar.PutProperty( L"Minimum", (LONG)1 ); progressbar.PutProperty( L"Maximum", (LONG)200 ); progressbar.PutProperty( L"Value", (LONG)195 ); progressbar.PutProperty( L"Caption", CValue(L"My Caption") ); return = progressbar.GetProperty( L"Value" ); // show the progress bar progressbar.PutProperty( L"Visible", true ); while ( (progressbar.GetProperty( L"CancelPressed" ) == false) && ((LONG)return < 200)) { // your code here progressbar.Call( L"Increment", return ); } // Just for good measure. If you put break points in the // code sometimes the progress dialog doesn't go away. progressbar.PutProperty( L"Visible", false );
#include <xsi_comapihandler.h>
Public Types | |
enum | InvokeFlag { Method, PropertyGet, PropertyPut, PropertyPutRef } |
Public Member Functions | |
CComAPIHandler () | |
virtual | ~CComAPIHandler () |
CComAPIHandler (const CValue &in_val) | |
CComAPIHandler (const CComAPIHandler &in_obj) | |
CComAPIHandler & | operator= (const CComAPIHandler &in_obj) |
CStatus | CreateInstance (const CString &in_name) |
CStatus | Attach (const CValue &in_val) |
CStatus | Detach (void) |
CValue | GetProperty (const CString &in_name) const |
CStatus | PutProperty (const CString &in_name, const CValue &in_newval) const |
CStatus | Call (const CString &in_name, CValue &io_return, const CValueArray &in_args=CValueArray()) const |
CStatus | Call (const CString &in_name, CValue &io_return, const CValue &in_arg) const |
CStatus | Call (const CString &in_name, CValue &io_return, const CValue &in_arg, const CValue &in_arg1) const |
CStatus | Call (const CString &in_name, CValue &io_return, const CValue &in_arg, const CValue &in_arg1, const CValue &in_arg2) const |
CStatus | Call (const CString &in_name, CValue &io_return, const CValue &in_arg, const CValue &in_arg1, const CValue &in_arg2, const CValue &in_arg3) const |
CStatus | Invoke (const CString &in_name, LONG in_flags, CValue &io_return, const CValueArray &in_args=CValueArray()) const |
CValue | GetRef (void) const |
enum InvokeFlag |
Flags to specify the context for the CComAPIHandler::Invoke function.
CComAPIHandler | ( | ) |
Default constructor.
virtual ~CComAPIHandler | ( | ) | [virtual] |
Default destructor.
CComAPIHandler | ( | const CValue & | in_val | ) |
Constructor.
in_val | Contains a reference to a Softimage Object Model object. |
using namespace XSI ; Application app ; Model root = app.GetActiveSceneRoot(); X3DObject arc; root.AddGeometry( L"Arc", L"NurbsCurve", L"AnArc", arc ) ; // Construct a CComAPIHandler representing the newly created arc object CComAPIHandler omArc( arc.GetRef() ); // Now we can use the object model to modify the object. // In this case we change the name property. omArc.PutProperty( L"Name", L"MyArc" ) ; // Retrieve the object name using the Name property CValue nameFromCOMAPI = omArc.GetProperty( L"Name" ) ; app.LogMessage( L"Softimage OM SIObject::Name property returns: " + nameFromCOMAPI.GetAsText() ) ; // In this case the same property is available directly from the C++ API // so we didn't really need to use CComAPIHandler CString nameFromCppAPI = arc.GetName() ; app.LogMessage( L"C++ API SIObject::GetName returns: " + nameFromCppAPI ) ; // Expected results: //'INFO : Softimage OM SIObject::Name property returns: MyArc //'INFO : C++ API SIObject::GetName returns: MyArc
CComAPIHandler | ( | const CComAPIHandler & | in_obj | ) |
Copy constructor.
in_obj | constant class object. |
CComAPIHandler& operator= | ( | const CComAPIHandler & | in_obj | ) |
Assignment operator
in_obj | CComAPIHandler to copy. |
Creates an automation object and attaches it to the CComAPIHandler object. If you try to create an automation object that doesn't exist an error (CStatus::Fail) occurs.
in_name | ProgID of the Softimage OM object to create. The ProgID is a string found in the Registry, that maps to the CLSID of the object. For example XSI.UIToolkit and Scripting.FileSystemObject . |
Attaches an automation object or Softimage object to the CComAPIHandler object. The CValue can be set either with a CRef object or with a pointer to an object model interface. CComAPIHandler takes care of handling the reference counting on the underlying Softimate OM object.
in_val | CValue to attach |
CStatus Detach | ( | void | ) |
Detaches an automation object pointer from the CComAPIHandler object.
Returns the property value.
in_name | The name of the property. |
Sets the property value. If you try to set a read-only property, an error (CStatus::AccessDenied) occurs. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.
in_name | The name of the property. |
in_newval | The new property value. |
CStatus Call | ( | const CString & | in_name, |
CValue & | io_return, | ||
const CValueArray & | in_args = CValueArray() |
||
) | const |
Calls the object method specified by name. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.
in_name | The name of the method. |
io_return | The return value. |
in_args | Array of arguments passed through to the method to call, |
Calls the object method specified by name. This version is convenient for calling a method that takes one argument. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.
in_name | The name of the property. |
io_return | The return value. |
in_arg | The argument passed through to the method. |
CStatus Call | ( | const CString & | in_name, |
CValue & | io_return, | ||
const CValue & | in_arg, | ||
const CValue & | in_arg1 | ||
) | const |
Calls the object method specified by name. This version is convenient for calling a method that takes two arguments. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.
in_name | The name of the property. |
io_return | The return value. |
in_arg | The first argument passed through to the method. |
in_arg1 | The second argument passed through to the method. |
CStatus Call | ( | const CString & | in_name, |
CValue & | io_return, | ||
const CValue & | in_arg, | ||
const CValue & | in_arg1, | ||
const CValue & | in_arg2 | ||
) | const |
Calls the object method specified by name. This version is convenient for calling a method that takes three arguments. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.
in_name | The name of the property. |
io_return | The return value. |
in_arg | The first argument passed through to the method. |
in_arg1 | The second argument passed through to the method. |
in_arg2 | The third argument passed through to the method. |
CStatus Call | ( | const CString & | in_name, |
CValue & | io_return, | ||
const CValue & | in_arg, | ||
const CValue & | in_arg1, | ||
const CValue & | in_arg2, | ||
const CValue & | in_arg3 | ||
) | const |
Calls the object method specified by name. This version is convenient for calling a method that takes four arguments. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.
in_name | The name of the property. |
io_return | The return value. |
in_arg | The first argument passed through to the method. |
in_arg1 | The second argument passed through to the method. |
in_arg2 | The third argument passed through to the method. |
in_arg3 | The fourth argument passed through to the method. |
CStatus Invoke | ( | const CString & | in_name, |
LONG | in_flags, | ||
CValue & | io_return, | ||
const CValueArray & | in_args = CValueArray() |
||
) | const |
Calls the object method or property specified by name, in the context specified by in_flags
. If you try to call a method or property that doesn't exist an error (CStatus::MemberNotFound) occurs.
// Make sure something is selected Selection sel = app.GetSelection(); LONG lCount = sel.GetCount(); app.LogMessage(L"Found " + CString(lCount) + L" selected items."); if ( lCount < LONG(1) ) { app.LogMessage( L"No components are selected" ); return CStatus::OK; } for ( LONG i=0; i<lCount; i++ ) { if ( sel.GetItem(i).GetClassIDName() == L"X3DObject" ) { X3DObject x3dobj(sel.GetItem(i)); app.LogMessage(L"\titem[" + CString(i) + L"]: " + x3dobj.GetName() ); } else { app.LogMessage(L"\titem[" + CString(i) + L"]: " + sel.GetItem(i).GetClassIDName() ); } } // The collection of selected components exists in the first member CComAPIHandler comCollItem( sel.GetItem(0) ); CComAPIHandler comSubComp( comCollItem.GetProperty(L"SubComponent") ); CValue subCompType = comSubComp.GetProperty( L"Type" ); app.LogMessage( L"Type of subcomponent: " + CString(subCompType) ); // Grab the component collection CComAPIHandler comCompColl( comSubComp.GetProperty(L"ComponentCollection") ); // Now we can iterate over the component collection's members LONG lCollCount( comCompColl.GetProperty(L"Count") ); app.LogMessage(L"Found " + CString(lCollCount) + L" selected components."); for ( LONG j=0; j<lCollCount; j++ ) { CValue rtn; // output from the Item property CValueArray idx; idx.Add(j); // set the index to use comCompColl.Invoke( L"Item", CComAPIHandler::PropertyGet, rtn, idx ); // From the CRef class, we can convert it to the actual class CRef itm(rtn); if ( itm.GetClassID() == siVertexID ) { Vertex vtx = Vertex(itm); app.LogMessage( L"Found a vertex at index " + CString(vtx.GetIndex()) ); } if ( itm.GetClassID() == siSampleID ) { Sample smp = Sample(itm); app.LogMessage( L"Found a sample at index " + CString(smp.GetIndex()) ); } if ( itm.GetClassID() == siEdgeID ) { Edge edg = Edge(itm); app.LogMessage( L"Found a edge at index " + CString(edg.GetIndex()) ); } if ( itm.GetClassID() == siControlPointID ) { ControlPoint ctrl = ControlPoint(itm); app.LogMessage( L"Found a control point at index " + CString(ctrl.GetIndex()) ); } // etc. }
in_name | The name of the property or method to invoke |
in_flags | Specify the context (whether it's calling a method, setting or getting a property). See CComAPIHandler::InvokeFlag. |
io_return | The return value. |
in_args | Array of arguments for the method to call. |
CValue GetRef | ( | void | ) | const |
Returns a reference to the automation object attached to the CComAPIHandler.