NAME SoDirectionalLightManip SoDirLtManip "" { directional light node with 3D interface for editing direction }

INCLUDE manips/SoDirectionalLightManip.h

DESC { 
\cSoDirectionalLightManip\. 
is the base class for all \cSoDirectionalLight\. nodes that have a built-in 
3D user interface (this is the only such class provided with the 
Inventor toolkit).
Since it is derived from \cSoDirectionalLight\., any changes to its
fields result in a change of lighting for nodes that
follow it in the scene graph.
In this case, the interface edits the \vdirection\. field.
Also, the color of the manipulator's geometry will reflect the color of the
light (but you cannot edit the color using this manipulator).
\p
Typically, you will want to replace a regular \cSoDirectionalLight\. with an
\cSoDirectionalLightManip\. (as when the user selects a light to be edited),
or vice versa (as when the user is done moving the light and the interface
should go away).
Use the
\+\mreplaceNode()\. method\.
\-\mSoDirLtManipReplaceNode()\. function\.
to insert a manipulator into a scene graph, and the
\+\mreplaceManip()\. method\.
\-\mSoDirLtManipReplaceManip()\. function\.
to remove it when done.
\p
The \cSoDirectionalLightManip\. 
utilizes an \cSoDirectionalLightDragger\. to provide a 3D interface. 
However, the manipulator differs from the dragger; it lights other objects
in the scene because, as an \cSoDirectionalLight\.,
it alters the state. 
The field values and movement of the dragger, on the other hand, affect only 
the dragger itself.
To find out more about how the interface works and what each part will do,
see the reference page for \cSoDirectionalLightDragger\..  The interfaces of the
dragger and the manipulator are identical.
\p
The \cSoDirectionalLightManip\. utilizes its dragger by adding it
as a hidden child.  When an action is applied to the manipulator,
such as rendering or handling events, the manipulator first traverses the
dragger, and then the manipulator adds its lighting parameters to the state.
When you click-drag-release over the manipulator, it passes these events down
to the dragger, which moves as a result ("I can't \ehelp\. it, I'm a dragger!").
\p
The manipulator maintains consistency between the fields
of the dragger and its own fields. Let's say you use the mouse to rotate
the \edragger\.. Callbacks ensure that the 
\vdirection\. field of the \emanipulator\. will change by the same 
amount, thus changing the lighting of nodes which follow 
in the scene graph.
Similarly, if you set the \vdirection\. field of the 
\cSoDirectionalLightManip\., the manipulator will
orient the dragger accordingly. 
\p 
Because the dragger is a \ehidden\. child, you can see the dragger on screen
and interact with it, but the dragger 
does not show up when you write the manipulator to file. Also, any \cSoPath\.
will end at the manipulator. (See the Actions section of this reference page for
a complete description of when the dragger is traversed).
\p
If you want to get a pointer to the dragger
you can get it from the manipulator using the 
\m\+getDragger()\.\-SoDirLtManipGetDragger()\.\. method.  You will need to 
do this if you want to change the geometry of a manipulator, since the
geometry actually belongs to the dragger.
}

METHOD "" SoDirectionalLightManip() {
Constructor.
}

METHOD getDrag SoDragger *getDragger() {
Returns a pointer to the dragger being used by this manipulator.
Given this pointer, you can customize the dragger just like you would
any other dragger.  You can change geometry using 
the \m\+setPart()\.\-SoDragSetPart()\.\. method, or add callbacks using 
the methods found in the \cSoDragger\. reference page.
}

METHOD "" SbBool replaceNode( SoPath *p ) {
Replaces the tail of the path with this manipulator.
The tail of the path must be an \cSoDirectionalLight\. 
node (or subclass thereof).
If the path has a nodekit, this will try to use
\m\+setPart()\.\-SoBaseKitSetPart()\.\. to insert the manipulator.
Otherwise, the manipulator requires that the
next to last node in the path chain be a group.
\p
The field values from the directional light node will be copied to
this manipulator, and the light node will be replaced.
\p
The manipulator will not call
\m\+ref()\.\-SoDirLtRef()\.\.  on the node it is replacing.
The old node will disappear if
it has no references other than from the input path \ap\. and its parent,
since this manipulator will be replacing it in both of those places.
Nor will the manipulator make any
changes to field connections of the old node.  
The calling process is thus responsible for keeping
track of its own nodes and field connections.
}

METHOD "" SbBool replaceManip(SoPath *p, SoDirectionalLight *newOne ) const {
Replaces the tail of the path, which must be this manipulator,
with the given \cSoDirectionalLight\. node.
If the path has a nodekit, this will try to use
\m\+setPart()\.\-SoBaseKitSetPart()\.\. to insert the new node.
Otherwise, the manipulator requires that the
next to last node in the path chain be a group.
\p
The field values from the manipulator will be copied
to the directional light node, and the manipulator will be replaced.
\p
The manipulator will not call
\+\mref()\. or \munref()\.\.
\-\mSoDirLtRef()\. or \mSoDirLtUnref()\.\.
on the node which is replacing it, nor will it make any
changes to field connections.
The calling process is thus responsible for keeping
track of its own nodes and field connections.
}

METHOD "" static SoType getClassTypeId() {
Returns type identifier for this class.
}

ACTION SoGLRenderAction, SoCallbackAction,
       SoGetBoundingBoxAction, SoGetMatrixAction,
       SoHandleEventAction, SoRayPickAction {
First, traverses the dragger the way an \cSoGroup\. would. All draggers
place themselves in space, but leave the current transformation unchanged
when finished. 
Then the \cSoDirectionalLightManip\. adds a 
directional light to the state 
just like its base class, \cSoDirectionalLight\..
}

ACTION SoSearchAction {
Searches just like an \cSoDirectionalLight\..  Does not search the dragger,
which is a hidden child.
}

ACTION SoWriteAction {
Writes out just like an \cSoDirectionalLight\.. Does not write the dragger,
which is a hidden child.   If you really need to write valuable information 
about the dragger, such as customized geometry, you 
can retrieve the dragger with the 
\m\+getDragger()\.\-SoDirLtManipGetDragger()\.\. method and then write 
it out separately.
}

ALSO {
SoDragger,
SoDirectionalLight,
SoDirectionalLightDragger,
SoPointLightManip,
SoSpotLightManip
}

