SoLocateHighlight(3IV)

NAME
     SoLocateHighlight (SoLocHigh) - special separator that performs locate
     highlighting

INHERITS FROM
     SoBase > SoFieldContainer > SoNode > SoGroup > SoSeparator >
     SoLocateHighlight

SYNOPSIS
     #include <Inventor_c/nodes/SoLocateHighlight.h>

     typedef SoLocateHighlight  SoLocHigh

     enum SoLocateHighlightModes {
          SO_LOC_AUTO         highlight when mouse is over (default)
          SO_LOC_ON           always highlight
          SO_LOC_OFF          never highlight
     }

     enum SoLocateHighlightStyles {
          SO_LOC_EMISSIVE          changes emissive color only (default)
          SO_LOC_EMISSIVE_DIFFUSE  changes emissive and diffuse colors
     }

          Fields from class SoLocateHighlight:

     SoSFColor           color
     SoSFEnum            style
     SoSFEnum            mode

          Fields from class SoSeparator:

     SoSFEnum            renderCaching
     SoSFEnum            boundingBoxCaching
     SoSFEnum            renderCulling
     SoSFEnum            pickCulling

          Functions from class SoLocateHighlight:

     SoLocateHighlight *  SoLocHighCreate()
     SoType               SoLocHighGetClassTypeId()

          Functions from class SoSeparator:

     void                SoLocHighSetNumRenderCaches(int howMany)
     int                 SoLocHighGetNumRenderCaches()

          Functions from class SoGroup:

     void                SoLocHighAddChild(SoLocHigh *this, SoNode *child)
     void                SoLocHighInsertChild(SoLocHigh *this, SoNode *child,
                              int newChildIndex)
     SoNode *            SoLocHighGetChild(const SoLocHigh *this, int index)
     int                 SoLocHighFindChild(const SoLocHigh *this, const
                              SoNode *child)
     int                 SoLocHighGetNumChildren(const SoLocHigh *this)
     void                SoLocHighRemoveChild(SoLocHigh *this, int index)
     void                SoLocHighRemoveChildNode(SoLocHigh *this, SoNode
                              *child)
     void                SoLocHighRemoveAllChildren(SoLocHigh *this)
     void                SoLocHighReplaceChild(SoLocHigh *this, int index,
                              SoNode *newChild)
     void                SoLocHighReplaceChildNode(SoLocHigh *this, SoNode
                              *oldChild, SoNode *newChild)

          Functions from class SoNode:

     void                SoLocHighSetOverride(SoLocHigh *this, SbBool state)
     SbBool              SoLocHighIsOverride(const SoLocHigh *this)
     SoNode *            SoLocHighCopy(const SoLocHigh *this, SbBool
                              copyConnections = FALSE)
     SbBool              SoLocHighAffectsState(const SoLocHigh *this)
     SoNode *            SoLocHighGetByName(const char *name)
     int                 SoLocHighGetByNameList(const char *name, SoNodeList
                              *list)

          Functions from class SoFieldContainer:

     void                SoLocHighSetToDflts(SoLocHigh *this)
     SbBool              SoLocHighHasDfltVals(const SoLocHigh *this)
     SbBool              SoLocHighFldsAreEq(const SoLocHigh *this, const
                              SoFieldContainer *fc)
     void                SoLocHighCopyFieldVals(SoLocHigh *this, const
                              SoFieldContainer *fc, SbBool copyConnections =
                              FALSE)
     SbBool              SoLocHighSet(SoLocHigh *this, const char
                              *fieldDataString)
     void                SoLocHighGet(SoLocHigh *this, SbString
                              *fieldDataString)
     int                 SoLocHighGetFields(const SoLocHigh *this, SoFieldList
                              *resultList)
     SoField *           SoLocHighGetField(const SoLocHigh *this, const char
                              *fieldName)
     SbBool              SoLocHighGetFieldName(const SoLocHigh *this, const
                              SoField *field, SbName *fieldName)
     SbBool              SoLocHighIsNotifyEnabled(const SoLocHigh *this)
     SbBool              SoLocHighEnableNotify(SoLocHigh *this, SbBool flag)

          Functions from class SoBase:

     void                SoLocHighRef(SoLocHigh *this)
     void                SoLocHighUnref(const SoLocHigh *this)
     void                SoLocHighUnrefNoDelete(const SoLocHigh *this)

     void                SoLocHighTouch(SoLocHigh *this)
     SoType              SoLocHighGetTypeId(const SoLocHigh *this)
     SbBool              SoLocHighIsOfType(const SoLocHigh *this, SoType type)
     void                SoLocHighSetName(SoLocHigh *this, const char *name)
     SbName              SoLocHighGetName(const SoLocHigh *this)


DESCRIPTION
     This is a subclass of SoSeparator that redraws itself in a different
     color when the cursor is over the contents of the separator.

     The redraw happens for that separator only and not the entire window
     (redraw along the handle event pick path) and in the front buffer, to
     efficiently track the mouse motion. The highlighted redraw overrides the
     emissive and/or diffuse color of the subgraph based on the field values
     in this node.

     NOTE: when using SoLightModel::BASE_COLOR (to turn lighting off) only the
     diffuse color will be used to render objects, so EMISSIVE_DIFFUSE must be
     used for this node to have any effect.

FIELDS
     SoSFColor           color
          highlighting color - default [.3, .3, .3]

     SoSFEnum            style
          highlighting draw style - default EMISSIVE

     SoSFEnum            mode
          Whether to highlight or not - default AUTO


FUNCTIONS
     SoLocateHighlight *  SoLocHighCreate()
          Creates a LocateHighlight node with default settings.

     SoType               SoLocHighGetClassTypeId()
          Returns type identifier for this class.


ACTION BEHAVIOR
     SoHandleEventAction
          Checks to see if the cursor moves onto or off of the contents of the
          separator, and redraws appropriately (if mode is AUTO), otherwise
          traverses as a normal separator.

     SoGLRenderAction
          Redraws either highlighted (if cursor is over the contents of the
          separator when mode == AUTO or always if mode == ON), otherwise
          traverses as a normal separator.

FILE FORMAT/DEFAULTS
     LocateHighlight {
          renderCaching       AUTO
          boundingBoxCaching  AUTO
          renderCulling       AUTO
          pickCulling         AUTO
          mode                AUTO
          style               EMISSIVE
          color               0.3 0.3 0.3
     }

SEE ALSO
     SoSeparator, SoSelection, SoMaterial