XRefScene Values

An XRefScene value represents an XRef Scene object in 3ds Max. An XRefScene value is returned when the xrefs.addNewXRefFile() and xrefs.getXRefFile() functions are called.

XRef Scene objects can be nested. For example, scene file A can contain an XRef Scene object specifying XRef file B, and XRef file B can contain an XRef Scene object specifying XRef file C (eg: A xrefs B, and B xrefs C). To provide access to the nested XRef scene objects, the applicable XRefScene methods provide an optional root keyword parameter. If this argument is provided then these methods act on the root node of the specified XRefScene value, otherwise they act on root node of the current scene. To get to C from A, you load A and do something like:

EXAMPLE

bXref = xrefs.getXRefFile 1-- taken from root node of current scene
cXref = xrefs.getXRefFile 1 root:bXref-- taken from root of bXref
cRoot = cXref.tree -- to get root of C

NOTE:

Scenes with a script controller whose script has explicit references ($sphere01, etc.) to objects in an incoming xref scene have a problem where the objects in the xref scene are invisible to MAXScript, and so the script will fail. This is actually a general problem with xrefs, you cannot have scripts of any kind in the xref scene (scripts controllers, param wires, callback scripts, etc.) that depend on explicit scene object references.

This problem has been solved in 3ds Max 8 and higher where scripted controllers store references using parameter blocks and can resolve them within nested xrefs.

Constructor

xrefs.addNewXRefFile <filename_string> [		#noLoad] [		root: <XRefScene>]

Adds a new XRef Scene object and returns a XRefScene value. If #noLoad is not specified, the XRef Scene file is loaded immediately and the scene updated. If #noLoad is specified, the scene is not updated until the user requests it. Use the updateXRef() method to load the XRef Scene object.

If root:<XRefScene> is specified, the XRef Scene object is treated in the current file during the current session as if it was an XRef Scene object in the file corresponding to the XRefScene value specified. If the specified root XRef Scene object is reloaded, either because the current scene was saved and then reloaded, or because updateXRef() was executed on the root XRef Scene object, the XRef Scene object is deleted from the scene.

xrefs.addNewXRefFile does not return an error when passed a DRF file - it will return a value different from undefined, and the xref-ed DRF file will appear in red, meaning that there is a "problem" with it. This behaviour is the same as if the user would have opened a DRF file in the File Xref Scene | Add dialog after choosing the All Files filter (*.*)

xrefs.getXRefFile <index> [	 root: <XRefScene>]

If root is not specified, returns the XRefScene value corresponding to the indexed XRef Scene object in the XRef Scenes dialog. If the root:<XRefScene> is specified, the XRefScene value corresponding to a nested XRef Scene object within the XRefScene's XRef Scene object is returned. The index is 1-based, and corresponds to the order of the XRef Scene objects listed in the XRef Scenes dialog. You can use the xrefs.getXRefFileCount() method to determine the number of XRef Scene objects in the scene.

xrefs.addNewXRefObject <filename string> <object name> dupMtlNameAction: { #prompt|  #useXRefed|  #useScene|  #autoRename}

Adds a new XRef Scene Object using the given MAX file name and object name and returns the new object if successful or undefined if the filename and/or the object name is not found.

The optional dupMtlNameAction: keyword introduced in 3ds Max 2010 controls the behavior of the method on duplicated material detection. The default behavior when not specified is #prompt .

Note that the method objXRefs.adNewXRefObject() in the objXRefs Interface does not provide this option.

<RootNode> as XRefScene

NEW in 3ds Max 2018 Coerces from MAXRootNode to XRefScene. If the RootNode is the root node of an xref scene, this returns the corresponding XRefScene value. If RootNode is the scene root node, this returns undefined.

Properties

<XRefScene>.filename String default: varies

The file name of the XRef Scene object. If you change this property to a new scene file name, the objects in the specified file are displayed, replacing the objects from the initial scene file.

<XRefScene>.owner RootNode default: varies

NEW in 3ds Max 2018: The "owning" root node for this XRef Scene object. This is a read-only property. If this is a top level XRefScene, this returns the scene root node. Otherwise returns the root node of the "owning" scene xref.

<XRefScene>.root XRefScene default: varies

NEW in 3ds Max 2018: The "owning" XRefScene for this XRef Scene object. This is a read-only property. If this is a top level XRefScene, this returns undefined .

FOR EXAMPLE:

aXref = xrefs.getXRefFile 1 --> XRefScene:"xrefed_teapot.max"
bXref = xrefs.getXRefFile 1 root:aXref --> XRefScene:"teapot.max"
aXref.owner --> $<root>
classof aXref.owner --> MAXRootNode
aXref.root --> undefined
bXref.owner --> $<root>
classof bXref.owner --> MAXRootNode
bXref.root --> XRefScene:"xrefed_teapot.max"
classof bXref.root --> XRefScene

<XRefScene>.tree Node

The root node of the XRef Scene object. This is a read-only property. You can access the children objects in an XRef Scene object using this property.

FOR EXAMPLE:

aXref=xrefs.getXRefFile 1-- returns first XRef Scene object
aXref.tree.children-- objects in the XRef Scene object,
-- for example, may return:
-- #children($Box01, $Box02)
aXref.tree.children[1].width-- returns width value of $Box01

<XRefScene>.parent Node default: undefined

The parent of the XRef Scene object. By default this is undefined but can be set to any node in the scene.

<XRefScene>.autoUpdate Boolean default: false

If true, automatic XRef file updating is on.

<XRefScene>.boxDisp Boolean default: false

If true, all nodes the in the XRef Scene object are displayed in Box display mode.

<XRefScene>.hidden Boolean default: false

If true, the XRef Scene object is hidden.

<XRefScene>.disabled Boolean default: false

If true, the XRef Scene object is disabled.

<XRefScene>.ignoreLights Boolean default: false

If true, the lights in the XRef Scene object will not be displayed.

<XRefScene>.ignoreCameras Boolean default: false

If true, the cameras in the XRef Scene object will not be displayed.

<XRefScene>.ignoreShapes Boolean default: false

If true, the shapes in the XRef Scene object will not be displayed.

<XRefScene>.ignoreHelpers Boolean default: false

If true, the helpers in the XRef Scene object will not be displayed.

<XRefScene>.ignoreAnimation Boolean default: false

If true, any animation in the XRef Scene object will be ignored.

Methods

delete <XRefScene>

Deletes the XRef Scene object.

merge <XRefScene>

Merges the nodes in the XRef Scene object into the scene and deletes the XRef Scene object.

updateXRef <XRefScene>

Tries to reload the XRef Scene object. Returns true if the operation is successful, false otherwise.

flagChanged <XRefScene>

This method indicates that the specified XRef Scene object has been changed and should be updated. Use the xrefs.updateChangedXRefs() method to update the changed XRef Scene objects.

Associated Methods

xrefs.getXRefFileCount [root: <XRefScene>]

If root is not specified, returns the total number of top-level XRef Scene objects in the scene. If the root:<XRefScene> is specified, the total number of XRef Scene objects in the nested XRef file within the XRefScene's XRef file is returned.

xrefs.deleteAllXRefs [root: <XRefScene>]

If root is not specified, deletes all XRef Scene objects. If the root:<XRefScene> is specified, only the specified XRefScene's XRef Scene object, and its nested XRef Scene objects, are deleted.

xrefs.updateChangedXRefs [#noRedraw] [root: <XRefScene>]

If root is not specified, updates all XRef Scene objects flagged as changed. If the root:<XRefScene> is specified, only the specified XRefScene's XRef Scene objects flagged as changed are updated. If #noRedraw is specified, the viewports won't be updated after the XRef Scene objects are loaded. Returns true if the XRef Scene objects were loaded okay, otherwise false .

xrefs.findUnresolvedXRefs [root: <XRefScene>]

If root is not specified, returns an array of file name strings for all the unresolved XRef Scene objects. If the root:<XRefScene> is specified, only the unresolved XRef Scene objects within the specified XRefScene's XRef Scene object are returned.

xrefs.attemptUnresolvedXRefs [root: <XRefScene>]

If root is not specified, tries to load any XRef Scene objects that are currently unresolved. If the root:<XRefScene> is specified, only the unresolved XRef Scene objects within the specified XRefScene's XRef Scene object are loaded.