====== Object references ======

Object references enable to load an object from a file, and store it in a resource directory. Such objects can then be used from the xl code as either: 
  - An instance of that object: i.e. a node with the 3d geometry of the object.
  - A resolved graph: i.e. the loaded graph from the object.

=====  =====

A single object reference can be used several times in the graph. Both as instances and as sub-graph. The reference object is ''Reference("xx")''. The name of the reference (i.e. "xx") should be given as the complete name of the reference object (as seen in the Object explorer):

{{:01_user_documentation:05_object:03_modeling:03_references:object_ref_rgg.png?800|}}

By default when a file is added to the [[:01_user_documentation:03_interacting_with_groimp:02_panels:02_explorers:07_objects|object explorer]], the complete name of the file is used as name. When using the it, both Reference object with or without the file extension, will resolve to the same object. But using the complete name prevent any potential conflict with other references with the same name and different file extension.
Another solution to prevent conflicts would be to rename references. The name does not have to follow the file name.

To access a Reference in rgg you can either create a Node from the Reference (in XL blocks) or create a new object (in java block). E.g.
<code java>
[ Axiom ==> Reference("nrgg"); ]
{ Reference r = new Reference("nrgg");}
</code>

==== Instance ====

When added in the graph, the object ''Reference'' is turned into an ''instance'' by default. E.g. the previous code produce: 

{{:01_user_documentation:05_object:03_modeling:03_references:object_ref_instance.png?200|}}

The Reference is actually turned into a graph Node whose instantiation rule is the sub-graph produced by the object.

==== Resolved graph ====

It is also possible to resolve the reference and access the sub-graph directly with the ''Reference'' method ''resolveNode()''. 

<code java>
{ Node rootRef = Reference("nrgg").resolveNode(); }
</code>

The resolved graph can be inserted in the graph with: 
<code java>
protected void init ()
[
{Node r = new Reference("nrgg.x3d") .resolveNode(); }
	Axiom ==>  [r ] ;
]
</code>

which produce:

{{:01_user_documentation:05_object:03_modeling:03_references:object_ref_resolved.png?600|}}


**Note:** if you modify the graph given by the resolveNode() method, it modify the object behind the Reference. Thus, all new Reference to that object will have the modifications.