XRefObject : Node

An XRefObject value represents an XRef object in 3ds Max. An XRefObject value is returned when the xrefs.addNewXRefObject() function is called. There are two objects associated with an XRef object in 3ds Max - the non-proxy object and the proxy object. The proxy object is typically a lower resolution object that is used as a standin for the non-proxy object in the viewports.

Constructor:

xrefs.addNewXRefObject <filename> {<objectname> | <objectname_array>} [#proxy] \
 modifiers:{#xref | #merge | #drop}	manipulators: {		#xref | #merge }		\
dupMtlNameAction: {#prompt |	#useXRefed |	#useScene |	#autoRename}

Loads the specified node object from the specified scene file as an XRef object. The case of objectname_string must match the object's name in the scene file.

If an array of object names is specified, the return value will be an array of the XRef'ed objects. Note that if a manipulator's name is specified in the array, and manipulator: #merge is specified, the merged manipulator is not included in the result array since it isn't an XRef Object.

If #proxy is specified, the node object is loaded as the proxy object, otherwise it is loaded as the non-proxy object.

The XRefObject is always loaded at world center.

References between XRef objects brought in as a single operation are maintained, so that if you have a object parameter controlled by a manipulator, and you XRef in both the object and the manipulator, the manipulator will still control the object's parameter.

Modifiers:

#xref - XRef Object contains any modifiers on object (default)

#merge - XRef Object contains base object, any modifiers on object are

applied to the XRef Object

#drop - XRef Object contains base object, any modifiers on object are dropped

Manipulators:

#xref - bring manipulator in as an xref

#merge - bring in manipulator as a manipulator

dupMtlNameAction:(available in 3ds Max 2010 and higher)

#prompt- Prompts the user to define the duplicated material names action (default)

#useXRefed- Uses the material from the XRef.

#useScene- Uses the scene material.

#autoRename- Rename the material to avoid dupilication.

In 3ds Max 6 and higher, xrefs.addNewXRefObject returns undefined when the argument is a file with DRF extension.

Properties

<XRefObject>.proxyFileName String default: varies   

The file name of the proxy object.

<XRefObject>.fileName String default: varies 

The file name of the non-proxy object.

<XRefObject>.currentFileName String default: varies 

The file name of the non-proxy object if the useProxy property is false , the file name of the proxy object if the useProxy property is true .

<XRefObject>.objectName String default: varies 

The name of the non-proxy object.

<XRefObject>.proxyObjectName String default: varies 

The name of the proxy object.

<XRefObject>.currentObjectName String default: varies 

The name of the non-proxy object if the useProxy property is false , the name of the proxy object if the useProxy property is true .

<XRefObject>.useProxy Boolean default: varies 

If true , the proxy object will be displayed in the viewports, otherwise the non-proxy object will be displayed.

If the XRef object is added to the scene using the xrefs.addNewXRefObject() method, this parameters default value will be true if #proxy is specified, false otherwise.

<XRefObject>.renderProxy Boolean default: false 

If true , the proxy object will be rendered, otherwise the non-proxy object will be rendered.

<XRefObject>.updateMaterial Boolean default: false 

If true , sets the Update Material option on.

<XRefObject>.ignoreAnimation Boolean default: false 

If true , sets the Ignore Animation option on.

<XRefObject>.actualBaseObject -- read-only 

Returns the actual base object of the referenced object as opposed to the base object of the XRefObject.

If 'Use Proxy' is turned on for the XRefObject, the proxy base object is returned if a proxy object is defined, otherwise a value of 'undefined' is returned.

Available in 3ds Max 8 and higher.

Methods

updateXRef <XRefObject> 

Reloads the XRef object.

The following XRefObject interfaces are available in 3ds Max 8 and higher:

XRefObject interfaces:

Interface:IXRefItem 

Properties:

.srcFileName : filename : Read 

Contains the source file name.

Read-only.

.srcItemName : string : Read 

Contains the name of the source item.

Read-only.

.xrefRecord : Interface : Read 

Contains the XRef record Interface.

Read-only.

.unresolved : bool : Read 

Contains true if the XRef is unresolved, false otherwise.

Read-only.

.nested : bool : Read 

Contains true if the XRef is nested, false otherwise.

Read-only.

Methods:

<maxObject>GetSrcItem resolveNested:<bool> 

resolveNested default value: false 

Returns the source item object of the XRef Object.

If the object is being referenced from nested files (in other words, the object is referenced from a Max file containing an XRef of the object from another file instead of the actual object) and resolveNested is set to true, nested XRef files will be resolved.

<DWORD>GetParentItems <&maxObject array>parentItems 

parentItems is Out parameter 

Returns an array of parent items in the by-reference Out parameter.

<DWORD>GetRootItems <&maxObject array>rootItems 

rootItems is Out parameter 

Returns an array of root items in the by-reference Out parameter.

<DWORD>GetChildItems <&maxObject array>childItems 

childItems is Out parameter 

Returns an array of child items in the by-reference Out parameter.

<void>GetNodes <&node array>xrefNodes 

xrefNodes is Out parameter 

Returns an array of XRef nodes in the by-reference Out parameter.

Interface:IXRefProxy 

Properties:

.proxyFileName : filename : Read 

Contains the proxy file name.Read-only.

.proxyItemName : string : Read 

Contains the proxy item name.Read-only.

.proxyRecord : Interface : Read 

Contains the proxy record Interface.Read-only.

.displayProxy : bool : Read|Write 

When set to True, the proxy will be used in the viewport.

.renderProxy : bool : Read|Write 

When set to True, the proxy will be used by the production renderer.

.useLocal : bool : Read|Write

Get/set the state of the "Enable/Use Local" property in the "Proxy Object" rollout.

When set to False (default), the Proxy Object will not be used and the XRef content will be loaded instead.

When set to True, the local Proxy Object will be loaded.

Available in 3ds Max 2016 and higher.

Interface:IXRefObject 

Properties:

.activeFileName : filename : Read 

Contains the active file name.Read-only.

.activeObjName : string : Read 

Contains the active object name.Read-only.

.activeRecord : Interface : Read 

Contains the active record Interface.Read-only.

Methods:

<maxObject>GetSourceObject <bool>resolveNestedXRef modifiers:<&maxObject array> 

modifiers default value: #() 
modifiers is Out parameter 

Returns the source object. The optional modifiers: by-reference parameter will return the array of modifiers applied to the source object.