# CRef Class Reference

This class is used to reference Softimage objects. Each instance of an CRef maintains a link with only one single object at a time, it cannot refer to multiple objects. CRef has no base or derived class hierarchy and only contains methods for accessing the type of the underlying Softimage object. More...

`#include <xsi_ref.h>`

List of all members.

## Public Member Functions
| CRef ()
| CRef (const CRef &in_xsiRef)
| ~CRef ()
siClassID | GetClassID () const
bool | IsA (siClassID in_classID) const
CString | GetClassIDName () const
bool | IsValid () const
| operator bool () const
bool | operator== (const CRef &in_ref) const
bool | operator!= (const CRef &in_ref) const
CRef & | operator= (const CRef &in_ref)
CStatus | Set (const CString &in_str)
CString | GetAsText () const
bool | operator< (const CRef &in_ref) const
bool | operator> (const CRef &in_ref) const

## Detailed Description

This class is used to reference Softimage objects. Each instance of an CRef maintains a link with only one single object at a time, it cannot refer to multiple objects. CRef has no base or derived class hierarchy and only contains methods for accessing the type of the underlying Softimage object.

CRef provides the core of the RTTI system to determine if an object is of a specific type; for example, to ensure that the compatibility between the reference and a given API class is valid by checking it against the siClassID enum. CRef instances are typically attached to API classes for manipulating Softimage objects.

A CRef object can be converted to its corresponding Softimage Object Model interface, and the resulting object can be used with the Softimage object model. The inverse is also possible: you can create a CRef object from an existing Softimage object model interface. See the XSI::ConvertObject function for more details.

See also:
  CRefArray, CBase

Example:
  Demonstrates how to use the work with CRefs

              using namespace XSI;

              // Forward declaration
              void GetSomeObjects( CRefArray& io_array, const Application& in_app );

              Application app;

              CRefArray array;
              GetSomeObjects( array, app );

              // Find all X3DObjects in the scene and add them to the ref array
              CStringArray emptyArray;
              Model root( app.GetActiveSceneRoot() );

              array += root.FindChildren( L"", L"", emptyArray, true );

              // Add grid's parameters to ref array
              X3DObject grid;
              root.AddGeometry( L"Grid", L"MeshSurface", L"", grid );

              array += grid.GetParameters();

              for (LONG i=0; i<array.GetCount(); ++i )
              {
                  app.LogMessage(L"");

                  CRef ref(array[i]);
                  app.LogMessage( CString(L">>Reference object class type: ") + ref.GetClassIDName() );

                  if ( ref.IsA( siSIObjectID ) )
                  {
                      SIObject siobj(ref);
                      app.LogMessage( CString(L"\tObject name: ") + siobj.GetName() );
                  }

                  if ( ref.IsA( siX3DObjectID ) )
                  {
                      X3DObject xobj(ref);
                      app.LogMessage( CString(L"\tNumber of children : ") +
                                      CValue(xobj.GetChildren().GetCount()).GetAsText() );
                  }

                  if ( ref.IsA( siParameterID ) )
                  {
                      Parameter param(ref);
                      app.LogMessage( CString(L"\tParameter's value : ") +
                                      param.GetValue().GetAsText() );
                  }
              }

              // Fills an array with CRef objects
              void GetSomeObjects( CRefArray& io_array, const Application& in_app )
              {
                  X3DObject myCube;
                  X3DObject myCone;
                  Material myPhong;

                  Model root = in_app.GetActiveSceneRoot();

                  root.AddGeometry( L"Cube", L"MeshSurface", L"", myCube );
                  root.AddGeometry( L"Cone", L"MeshSurface", L"", myCone );
                  myCone.AddMaterial( L"Phong", false, L"", myPhong );

                  // Add CRef items to the input array
                  io_array.Add( myCube.GetActivePrimitive().GetRef() );
                  io_array.Add( myCone.GetActivePrimitive().GetRef() );
                  io_array.Add( myPhong.GetRef() );
              }

## Constructor & Destructor Documentation

CRef | ( |  | ) |

Default constructor.

CRef | ( | const CRef & | in_xsiRef | ) |

Construct a CRef object from another CRef object.

Parameters:

  | in_xsiRef | constant reference object.

~CRef | ( |  | ) |

Destructor.

## Member Function Documentation

siClassID GetClassID | ( |  | ) | const

Returns the type of the object being referenced.

Returns:
  The class type.

bool IsA | ( | siClassID | in_classID | ) | const

Returns true if a given class type is compatible with the underlying reference object.

Parameters:

  | in_classID | Class type (the siClassID enum).

Returns:
  true if the class is compatible, false otherwise.

CString GetClassIDName | ( |  | ) | const

Returns the type of the referenced object in text format.

Returns:
  The text string.

bool IsValid | ( |  | ) | const

Returns true if the referenced object is valid or false otherwise.

Returns:
  true if valid, false otherwise.

operator bool | ( |  | ) | const

Bool converter operator that returns true if the object is valid or false otherwise.

Returns:
  true if object is valid; false if not valid.

Since:
  4.0

bool operator== | ( | const CRef & | in_ref | ) | const

Equality operator

Parameters:

  | in_ref | Reference object to compare.

Returns:
  true if both CRef objects are identical, false otherwise.

bool operator!= | ( | const CRef & | in_ref | ) | const

Inequality operator

Parameters:

  | in_ref | Reference object to compare.

Returns:
  true if objects are not identical, false otherwise.

CRef& operator= | ( | const CRef & | in_ref | ) |

Assigns a CRef object to this one.

Parameters:

  | in_ref | A source Reference object

Returns:
  A new reference object.

CStatus Set | ( | const CString & | in_str | ) |

Sets CRef from an object's string path. Returns CStatus::Fail if the object's path is invalid.

Tip:
  This is the C++ API equivalent of Dictionary::GetObject

Parameters:

  | in_str | String path to object for example, "Model.null.kine.local.posx"

Returns:
  CStatus::OK success

  CStatus::InvalidArgument string is empty or contains invalid object path.

  CStatus::Fail failure

CString GetAsText | ( |  | ) | const

Returns the object's path as a string.

Returns:
  The object's path.

bool operator< | ( | const CRef & | in_ref | ) | const

Less-than operator. Performs a case-sensitive comparison with a specified CRef object to determine if this CRef is lexicographically less than the specified CRef. The comparison is done with CRef::GetAsText. This is useful for sorting operations with `stl` maps.

Parameters:

  | in_ref | CRef we want to test.

Returns:
  true if this CRef is less than the specified CRef, false otherwise.

Since:
  7.5

bool operator> | ( | const CRef & | in_ref | ) | const

Greater-than operator. Performs a case-sensitive comparison with a specified CRef object to determine if this CRef is lexicographically greater than the specified CRef. The comparison is done with CRef::GetAsText.

Parameters:

  | in_ref | CRef we want to test.

Returns:
  true if this CRef is greater than the specified CRef, false otherwise.

Since:
  7.5

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

- xsi_ref.h