Interface: objXRefMgr

The objXRefMgr Core Interface provides access to the XRef Manager, and is the preferred way for working with XRefs in MAXScript. Scripts should not use both the methods in this interface and those exposed by XRefObject. The objXrefMgr coordinates all object xref additions and changes in a scene.

Available in 3ds Max 8 and higher.

You may find the following concepts useful when working with XRefs in MAXScript:

• Xrefs are organized by the file they come from, which is represented by an IXRefRecord object. For example, the objXRefMgr.AddXrefItemsFromFile() method returns this object. See the IXrefRecordMixinInterface for methods available from this interface.
• Individual Xrefs in an XrefRecord are held in IXrefItem objects. See IXRefItem MixinInterface for methods exposed by that interface.

Interface: objXRefMgr

Properties:

objXRefMgr.includeAll : bool : Read|Write

Get/set the state of the "Include All" checkbox.

Default is True.

Available in 3ds Max 2016 and higher.

objXRefMgr.enableUseLocalProxySettings : bool : Read|Write

When set to True, local proxy settings will be used.

Default is False.

Available in 3ds Max 2016 and higher.

objXRefMgr.recordCount: DWORD : Read

Returns the number of Object XRef records.

objXRefMgr.dupObjNameAction : enum : Read|Write

dupObjNameAction enums: {#prompt|#xref|#skip|#deleteOld|#autoRename}

Get/set the action to perform when duplicate names have been detected.

objXRefMgr.dupMtlNameAction : enum : Read|Write

dupMtlNameAction enums: {#prompt|#useXRefed|#useScene|#autoRename}

Get/set the action to perform when duplicate material names have been detected.

objXRefMgr.mergeTransforms : bool : Read|Write

Get/set whether to merge the transformation controllers of the Object XRefs. When set to true, the transform controllers will be merged into the main scene and will lose the live connection to the referenced file. Default is false.

objXRefMgr.mergeMaterials : bool : Read|Write

Get/set whether to merge the materials of the Object XRefs. When set to true, the materials of the referenced objects will be merged into the main scene and will lose the live connection to the referenced file. This option must be set before creating the Object XRef. Default is false.

objXRefMgr.mergeManipulators : bool : Read|Write

Get/set whether to merge the manipulators of the Object XRefs. When set to true, the manipulators of the referenced objects will be merged into the main scene and will lose the live connection to the referenced file. This option must be set before creating the Object XRef. Default is false.

objXRefMgr.mergeModifiers : enum : Read|Write

mergeModifiers enums: {#xrefModifiers|#ignoreModifiers|#mergeModifiers}

Get/set the handling of the modifiers of the Object XRef.

When the #xrefModifiers option is specified, the modifiers will be applied to the XRef Object before it is merged into the main scene and cannot be changed.

When the #ignoreModifiers option is specified, the modifiers from the referenced file will not be applied to the XRef Object.

When the #mergeModifiers option is specified, the modifiers from the referenced file will be merged into the main scene and can be manipulated, but will lose their live connection to the referenced file.

This option must be set before creating the Object XRef.

objXRefMgr.getAutoUpdate : bool : Read|Write

Get/set whether to update the Object XRefs automatically when the referenced source file has been saved.

Methods:

<Interface>objXRefMgr.GetRecord <index>index

Returns the indexed record, where index is between 1 and the .recordCount

<Interface>objXRefMgr.FindRecord <DWORD>handle

Returns the record by handle.

See IXrefRecordMixinInterface for details on the return value.

<bool>objXRefMgr.RemoveRecordFromScene <Interface>record

record Validated by Validator function

Removes the specified record from the scene.

Returns true on success, false on failure.

See IXrefRecord MixinInterface for details on the record argument.

<bool>objXRefMgr.MergeRecordIntoScene <Interface>record

record Validated by Validator function

Merges the specified record into the scene.

Returns true on success, false on failure.

See IXrefRecord MixinInterface for details on the record argument.

<bool>objXRefMgr.SetRecordSrcFile <Interface>xrefRecord <filename>fileName

Sets the source file of the specified record to the given file name.

Returns true on success, false on failure.

See IXrefRecord MixinInterface for details on the record argument.

<bool>objXRefMgr.UpdateAllRecords()

Updates all records in the scene. Returns true on success, false on failure.

<boolean>objXRefMgr.SetXRefItemSrcName <maxObject>xrefItem <string>itemName

Sets the source item name of the object passed by-reference to the given string.

Returns true on success, false on failure.

<boolean>objXRefMgr.SetProxyItemSrcName <maxObject>proxyItem <string>itemName

Sets name of the proxy of the object passed by-reference to the given string.

Returns true on success, false on failure.

Example

Illustrate the use of SetProxyItemSrcName, SetProxyItemSrcFile, and AddXrefItemsFromFile:

sphereFile = @"mySphereScene.max"
teapotFile = @"myTeapotScene.max"

-- Create a scene file containing a sphere, this will be the proxy object
resetMaxFile #noPrompt
s = sphere name:"mySphere"
saveMaxFile sphereFile useNewFile:false

-- create a scene file containing a teapot, this will be the xref object
resetMaxFile #noPrompt
-- add a teapot, we'll use the sphere as a proxy
t = teapot name:"myTeapot"
saveMaxFile teapotFile useNewFile:false

-- create our xref and our proxy
resetMaxFile #noPrompt
xrefRecord = objXrefMgr.AddXrefItemsFromFile teapotFile promptObjNames:false \
xrefOptions:#(#mergeModifiers, #mergeControllers, #mergeManipulators, #mergeMaterials)

xrefItem = xrefRecord.getItem 1 #XrefObjectType
objXrefMgr.SetProxyItemSrcFile xrefItem @"mySphereScene.max"
objXrefMgr.SetProxyItemSrcName xrefItem "mySphere"

<boolean>objXRefMgr.SetXRefItemSrcFile <maxObject>xrefItem <filename>fileName

Sets the source item file name of the object passed by-reference to the given filename string.

Returns true on success, false on failure.

<boolean>objXRefMgr.SetProxyItemSrcFile <maxObject>proxyItem <filename>fileName

Sets the proxy item file name of the object passed by-reference to the given filename string.

Returns true on success, false on failure.

<bool>objXRefMgr.AddXRefItemsToRecord <Interface>record promptObjNames:<bool>objNames:<string array>

record Validated by Validator function
promptObjNames default value: false
objNames default value: #()

Adds XRefs for the array of object names in the scene to the given record.

See IXrefRecord MixinInterface for details on the record argument.

<Interface>objXRefMgr.AddXRefItemsFromFile <filename>fileName promptObjNames:<boolean> objNames:<string array> objHandles:<int64 array> xrefOptions:<enum array>
       promptObjNames default value: false
       objNames default value: #()
       xrefOptions enums: {#asProxy|#xrefModifiers|#dropModifiers|#mergeModifiers|#mergeManipulators|#selectNodes|#mergeControllers|#mergeMaterials|#xrefControllers|#localControllers|#mergeChildren}
       xrefOptions default value: #()

Returns an XRef record object (IXRefRecord) that contains the XRefs (as IXRefItem objects) added to the scene from the specified file, of the specified objects.

You can specify objects by node handle with the objectHandles parameter. Node handles are guaranteed to be unique in a scene. You can obtain a list of node handles in a scene with the getMaxFileObjects() function, or by looking at the .handle property of nodes.

See IXrefRecord MixinInterface for details on the record argument.

<bool>objXRefMgr.CanCombineRecords <Interface>firstRecord <Interface>secondRecord

firstRecord Validated by Validator function
secondRecord Validated by Validator function

Returns true if the two records can be combined, false otherwise.

See IXrefRecord MixinInterface for details on the record arguments.

<Interface>objXRefMgr.CombineRecords <Interface array>records
       records Validated by Validator function

Combines the records given as by-reference array of interfaces to a single interface.

See IXrefRecord MixinInterface for details on the record argument and return value.

<boolean>objXRefMgr.RemoveXRefItemsFromScene <maxObject array>xrefItems

Removes the given XRef Items from the scene.

Returns true on success, false on failure.

<boolean>objXRefMgr.MergeXRefItemsIntoScene <maxObject array>xrefItems

Merges the XRef Items specified as an array into the scene.

Returns true on success, false on failure.

<void>objXRefMgr.ApplyXRefMaterialsToXRefObjects <maxObject array>objectXRefItems

Applies XRef Materials to the specified XRef objects.

<Interface>objXRefMgr.IsNodeXRefed <node>node

If the node is XRef-ed, returns an IXRefItem MixinInterface.

<void>objXRefMgr.ApplyXRefControllersToXRefObjects <maxObject array>objectXRefItems

Applies XRef controllers to the Object XRef items specified by the by-reference array argument.

<boolean>objXRefMgr.ResetXRefControllersPRSOffset <maxObject array>xrefItems

Applies Position/Rotation/Scale offset to the XRef controllers of the Object XRef items specified by the by-reference array argument.

<boolean>objXRefMgr.CanResetXRefControllersPRSOffset <maxObject>xrefItem

Returns true if Position/Rotation/Scale offset can be applied to the XRef controllers of the Object XRef item specified by the by-reference argument.

The following MixinInterface represents an Object XRef Record:

Interface: IXRefRecord

Properties:

<IXRefRecord MixinInterface>.includeAll : bool : Read|Write

Get/Set the state of the Include All checkbox. When set to true, all objects in the record will be included.

<IXRefRecord MixinInterface>.autoUpdate : bool : Read|Write

Get/Set the state of the Auto Update checkbox. When set to true, changes to the XRef source will be automatically updated in the scene.

<IXRefRecord MixinInterface>.enabled : bool : Read|Write

Get/Set the state of the Enable checkbox.

<IXRefRecord MixinInterface>.uptodate : bool : Read|Write

Get/Set the whether the record is up to date or outdated.

<IXRefRecord MixinInterface>.empty : bool : Read

Contains true if the record is empty, false otherwise.

<IXRefRecord MixinInterface>.nested : bool : Read

Contains true if the record is nested, false otherwise.

<IXRefRecord MixinInterface>.unresolved : bool : Read

Contains true if the record is unresolved, false otherwise.

<IXRefRecord MixinInterface>.srcFileName : filename : Read|Write

Contains the file name of the source file. This property can be set in 3ds Max 9 and higher, prior to 3ds Max 9 it was read-only.

<IXRefRecord MixinInterface>.recordID : DWORD : Read

Contains the record's ID.

<IXRefRecord MixinInterface>.handle : DWORD : Read

Contains the record's Handle.

<IXRefRecord MixinInterface>.xrefOptions : enum by value array : Read

xrefOptions enums: {#asProxy|#xrefModifiers|#dropModifiers|#mergeModifiers|#mergeManipulators|#selectNodes|#mergeMaterials|#mergeChildren}

Contains an array of the XRef Options.

Methods:

<DWORD><IXRefRecord MixinInterface>.ItemCount <enum array>types

types enums: {#XRefObjectType|#XRefMaterialType|#XRefAtmospheric Type|#XRefAllType}

Returns the number of items in the record that correspond to the types passed by the by-reference array argument.

<maxObject><IXRefRecord MixinInterface>.GetItem <index>index <enum>type

type enums: {#XRefObjectType|#XRefMaterialType|#XRefAtmosphericType}

Returns the indexed item of the specified XRef type.

<DWORD><IXRefRecord MixinInterface>.GetItems <&enum array>types <&maxObject array>xrefItems

types enums: {#XRefObjectType|#XRefMaterialType|#XRefAtmosphericType|#XRefAllType}
types is In and Out parameter
xrefItems is In and Out parameter

Returns all items of the types specified by the by-reference array of the first argument into the by-reference array of the second argument.

<DWORD><IXRefRecord MixinInterface>.GetChildRecords <&Interface array>children

children is Out parameter

Returns the child records into the by-reference array. See IXrefRecord MixinInterface for details on the array's values type.

<DWORD><IXRefRecord MixinInterface>.GetParentRecords <&Interface array>parents

parents is Out parameter

Returns the parent records into the by-reference array. See IXrefRecord MixinInterface for details on the array's values type.

<DWORD><IXRefRecord MixinInterface>.GetRootRecords <&Interface array>roots

roots is Out parameter

Returns the root records into the by-reference array. See IXrefRecord MixinInterface for details on the array's values type.

<bool><IXRefRecord MixinInterface>.CheckSrcFileChanged()

Returns true if the source file has changed, false if it has not.

<bool><IXRefRecord MixinInterface>.Update()

Forces an update of the XRef Record and returns true on success, false on failure.

The following MixinInterface represents an Object XRef Item:

Interface: IXRefItem

Properties:

<IXRefItem MixinInterface>.srcFileName : filename : Read|Write

Contains the file name of the source file.

This property was read-only in versions prior to 3ds Max 9.

<IXRefItem MixinInterface>.srcItemName : string : Read|Write

Contains the name of the source item.

This property was read-only in versions prior to 3ds Max 9.

<IXRefItem MixinInterface>.xrefRecord : Interface : Read

Contains the Xref Record's IXRefRecord MixinInterface.

<IXRefItem MixinInterface>.unresolved : bool : Read

Contains true if the XRef is unresolved, false otherwise.

<IXRefItem MixinInterface>.nested : bool : Read

Contains true if the XRef is nested, false otherwise.

<IXRefItem MixinInterface>.retargetable : bool : Read

Contains true if the XRef can be retargeted, false otherwise.

Methods:

<maxObject><IXRefItem MixinInterface>.GetSrcItemresolveNested:<bool>

resolveNested default value: false

Returns the source item. If the resolveNested optional keyword is specified and is true, nested XRefs will be resolved to get the source item. If not specified or false, nested XRefs will not be resolved.

<DWORD><IXRefItem MixinInterface>.GetParentItems <&maxObject array>parentItems

parentItems is Out parameter

Returns the parent items into the by-reference array argument.

<DWORD><IXRefItem MixinInterface>.GetRootItems <&maxObject array>rootItems

rootItems is Out parameter

Returns the root items into the by-reference array argument.

<DWORD><IXRefItem MixinInterface>.GetChildItems <&maxObject array>childItems

childItems is Out parameter

Returns the child items into the by-reference array argument.

<void><IXRefItem MixinInterface>.GetNodes<&node array>xrefNodes

xrefNodes is Out parameter

Returns the XRef nodes into the by-reference array argument.

The following MixinInterface represents an Object XRef Proxy:

Interface: IXRefProxy

Properties:

<IXRefProxy MixinInterface>.proxyFileName : filename : Read|Write

Contains the proxy filename.

This property was read-only in versions prior to 3ds Max 9.

<IXRefProxy MixinInterface>.proxyItemName : string : Read|Write

Contains the proxy item name.

This property was read-only in versions prior to 3ds Max 9.

<IXRefProxy MixinInterface>.proxyRecord : Interface : Read

Contains the IXRefRecord Interface of the Proxy.

<IXRefProxy MixinInterface>.displayProxy: bool : Read|Write

Get/set whether to display the proxy in the viewports or not.

<IXRefProxy MixinInterface>.renderProxy : bool : Read|Write

Get/set whether to render the proxy or not.

The following MixinInterface represents an Object XRef Proxy:

Interface: IXRefObject

Properties:

<IXRefObject MixinInterface>.activeFileName : filename : Read

Contains the active filename.

<IXRefObject MixinInterface>.activeObjName: string : Read

Contains the active object name.

<IXRefObjectMixinInterface>.activeRecord : Interface : Read

Contains the IXRefRecord Interface of the Xref Object.

Methods:

<maxObject><IXRefObject MixinInterface>.GetSourceObject <bool>resolveNestedXRef modifiers:<&maxObject array>

modifiers default value: #()
modifiers is Out parameter

Returns the Source Object. When the first argument is set to true, nested XRefs will be resolved. The optional modifiers: array parameter will be populated with the modifiers of the object.