#include <xsi_comapihandler.h>

Class Description

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.

See also:: ConvertObject

Example:

                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 );

List of all members.

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

Member Enumeration Documentation

enum InvokeFlag

Search for all occurrences

Flags to specify the context for the CComAPIHandler::Invoke function.

Enumerator:

Method	Invokes a Method Search for all occurrences
PropertyGet	Invokes getting a Property Search for all occurrences
PropertyPut	Invokes setting a Property Search for all occurrences
PropertyPutRef	Invokes setting a Property with a pointer Search for all occurrences

Constructor & Destructor Documentation

CComAPIHandler ( )

Default constructor.

virtual ~CComAPIHandler ( ) [virtual]

Default destructor.

CComAPIHandler ( const CValue & in_val )

Constructor.

Parameters:

in_val Contains a reference to a Softimage Object Model object.

Example:: Demonstrates how it is possible to access properties exposed on Softimage objects using the object model interface rather than the C++ API. This approach is important for accessing any method or property that is available in the object model but not the C++ API.

                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.

Parameters:

in_obj constant class object.

Member Function Documentation

CComAPIHandler& operator= ( const CComAPIHandler & in_obj )

Assignment operator

Parameters:

in_obj CComAPIHandler to copy.

CStatus CreateInstance ( const CString & in_name )

Search for all occurrences

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.

Parameters:

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.

Returns:: CStatus::OK success; CStatus::Fail other failure

CStatus Attach ( const CValue & in_val )

Search for all occurrences

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.

Parameters:

in_val CValue to attach

Returns:: CStatus::OK Success; CStatus::InvalidArgument Invalid referance object; CStatus::Fail Other failure

CStatus Detach ( void )

Search for all occurrences

Detaches an automation object pointer from the CComAPIHandler object.

Returns:: CStatus::OK Success; CStatus::Fail Other failure

CValue GetProperty ( const CString & in_name ) const

Search for all occurrences

Returns the property value.

Parameters:

in_name The name of the property.

Returns:: The property value.

CStatus PutProperty	(	const CString &	in_name,
		const CValue &	in_newval
	)		const

Search for all occurrences

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.

Parameters:

in_name	The name of the property.
in_newval	The new property value.

Returns:: CStatus::OK Success; CStatus::Fail Other failure; CStatus::AccessDenied Trying to set a read-only parameter.; CStatus::MemberNotFound Property does not exist.

CStatus Call	(	const CString &	in_name,
		CValue &	io_return,
		const CValueArray &	in_args = `CValueArray()`
	)		const

Search for all occurrences

Calls the object method specified by name. If you try to call a method that doesn't exist an error (CStatus::MemberNotFound) occurs.

Parameters:

in_name	The name of the method.
io_return	The return value.
in_args	Array of arguments passed through to the method to call,

Returns:: CStatus::OK Success; CStatus::Fail Other failure; CStatus::AccessDenied Trying to set a read-only parameter.; CStatus::MemberNotFound Method does not exist.

CStatus Call	(	const CString &	in_name,
		CValue &	io_return,
		const CValue &	in_arg
	)		const

Search for all occurrences

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.

Parameters:

in_name	The name of the property.
io_return	The return value.
in_arg	The argument passed through to the method.

Returns:: CStatus::OK Success; CStatus::Fail Other failure; CStatus::AccessDenied Trying to set a read-only parameter.; CStatus::MemberNotFound Method does not exist.

CStatus Call	(	const CString &	in_name,
		CValue &	io_return,
		const CValue &	in_arg,
		const CValue &	in_arg1
	)		const

Search for all occurrences

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.

Parameters:

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.

Returns:: CStatus::OK Success; CStatus::Fail Other failure; CStatus::AccessDenied Trying to set a read-only parameter.; CStatus::MemberNotFound Method does not exist.

CStatus Call	(	const CString &	in_name,
		CValue &	io_return,
		const CValue &	in_arg,
		const CValue &	in_arg1,
		const CValue &	in_arg2
	)		const

Search for all occurrences

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.

Parameters:

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.

Returns:: CStatus::OK Success; CStatus::Fail Other failure; CStatus::AccessDenied Trying to set a read-only parameter.; CStatus::MemberNotFound Method does not exist.

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

Search for all occurrences

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.

Parameters:

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.

Returns:: CStatus::OK Success; CStatus::Fail Other failure; CStatus::AccessDenied Trying to set a read-only parameter.; CStatus::MemberNotFound Method does not exist.

CStatus Invoke	(	const CString &	in_name,
		LONG	in_flags,
		CValue &	io_return,
		const CValueArray &	in_args = `CValueArray()`
	)		const

Search for all occurrences

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.

Note:: A common use of this function is to get a property that uses input parameters; for example, the 'Item' property on a collection that needs to specify the index or name of the item to retrieve from the collection.

Example:: This example demonstrates how to use the CComAPIHandler to browse the list of selected components (since the SubComponent class is not fully implemented in the C++ API).

                // 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.
                }

Parameters:

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.

Returns:: CStatus::OK Success; CStatus::Fail Other failure; CStatus::AccessDenied Trying to set a read-only parameter.; CStatus::MemberNotFound Method or property does not exist.

CValue GetRef ( void ) const

Search for all occurrences

Returns a reference to the automation object attached to the CComAPIHandler.

Returns:: A reference to an automation object.

The documentation for this class was generated from the following file:

xsi_comapihandler.h

Class Description

Public Types

Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation