Provided by: inventor-doc_2.1.5-10+dfsg-2_all bug

NAME

       SoCenterballDragger — striped ball you rotate and re-center by dragging with the mouse

INHERITS FROM

       SoBase  >  SoFieldContainer  >  SoNode  >  SoBaseKit  >  SoInteractionKit  >  SoDragger  >
       SoCenterballDragger

SYNOPSIS

       #include <Inventor/draggers/SoCenterballDragger.h>

          Fields from class SoCenterballDragger:

     SoSFRotation        rotation
     SoSFVec3f           center

          Fields from class SoDragger:

     SoSFBool            isActive

          Fields from class SoInteractionKit:

     SoSFEnum            renderCaching
     SoSFEnum            boundingBoxCaching
     SoSFEnum            renderCulling
     SoSFEnum            pickCulling

          Parts from class SoBaseKit:

     (SoNodeKitListPart)  callbackList

          Methods from class SoCenterballDragger:

                         SoCenterballDragger()
     static const SoNodekitCatalog *
                         getClassNodekitCatalog() const
     static SoType       getClassTypeId()

          Methods from class SoDragger:

     void                addStartCallback(SoDraggerCB *f, void *userData = NULL)
     void                removeStartCallback(SoDraggerCB *f, void *userData = NULL)
     void                addMotionCallback(SoDraggerCB *f, void *userData = NULL)
     void                removeMotionCallback(SoDraggerCB *f, void *userData = NULL)
     void                addFinishCallback(SoDraggerCB *f, void *userData = NULL)
     void                removeFinishCallback(SoDraggerCB *f, void *userData = NULL)
     void                addValueChangedCallback(SoDraggerCB *f, void *userData = NULL)
     void                removeValueChangedCallback(SoDraggerCB *f, void *userData = NULL)
     SbBool              enableValueChangedCallbacks()
     void                setMinGesture(int pixels)
     int                 getMinGesture() const
     static void         setMinScale(float newMinScale)
     static float        getMinScale()

          Methods from class SoInteractionKit:

     virtual SbBool      setPartAsPath(const SbName &partName, SoPath *surrogatePath )

          Methods from class SoBaseKit:

     virtual const SoNodekitCatalog *
                              getNodekitCatalog() const
     virtual SoNode *         getPart(const SbName &partName, SbBool makeIfNeeded)
     SbString                 getPartString(const SoBase *part)
     virtual SoNodeKitPath *  createPathToPart(const SbName &partName, SbBool makeIfNeeded, const
                                   SoPath *pathToExtend = NULL)
     virtual SbBool           setPart(const SbName &partName, SoNode *newPart)
     SbBool                   set(char *partName, char *parameters)
     SbBool                   set(char *nameValuePairs)
     static SbBool            isSearchingChildren()
     static void              setSearchingChildren(SbBool newVal)

          Methods from class SoNode:

     void                setOverride(SbBool state)
     SbBool              isOverride() const
     SoNode *            copy(SbBool copyConnections = FALSE) const
     virtual SbBool      affectsState() const
     static SoNode *     getByName(const SbName &name)
     static int          getByName(const SbName &name, SoNodeList &list)

          Methods from class SoFieldContainer:

     void                setToDefaults()
     SbBool              hasDefaultValues() const
     SbBool              fieldsAreEqual(const SoFieldContainer *fc) const
     void                copyFieldValues(const  SoFieldContainer  *fc,  SbBool  copyConnections =
                              FALSE)
     void                get(SbString &fieldDataString)
     virtual int         getFields(SoFieldList &resultList) const
     virtual SoField *   getField(const SbName &fieldName) const
     SbBool              getFieldName(const SoField *field, SbName &fieldName) const
     SbBool              isNotifyEnabled() const
     SbBool              enableNotify(SbBool flag)

          Methods from class SoBase:

     void                ref()
     void                unref() const
     void                unrefNoDelete() const
     void                touch()
     virtual SoType      getTypeId() const
     SbBool              isOfType(SoType type) const
     virtual void        setName(const SbName &name)
     virtual SbName      getName() const

          Macros from class SoBaseKit:

     SO_GET_PART(kit, partName, partClass)
     SO_CHECK_PART(kit, partName, partClass)

DESCRIPTION

       SoCenterballDragger is a composite dragger.  Its  shape  is  a  sphere  defined  by  three
       intersecting  circles.  Where  the  circles intersect (at the ends of the x, y and z axes)
       there are sets of small green crosshairs. Dragging a pair  of  crosshairs  translates  the
       entire  centerball  within  the  plane  of the crosshairs. The interface of the sphere and
       circles is just like SoTrackballDragger. Dragging a circle  rotates  about  a  constrained
       axis  and  dragging  the areas between them rotates the sphere freely about the center. An
       invisible but pickable sphere initiates the free-rotation dragging.

       When you drag the crosshairs, the center field is updated; there is no translation  field.
       Dragging  other  parts of the centerball updates the rotation field. As with all draggers,
       if you change the fields the dragger moves in response.

       The draggers used for the  crosshair  parts  are  SoTranslate2Draggers,  so  pressing  the
       <Shift>  key  allows  you  to constrain motion to slide along either the local x axis or y
       axis of that crosshair.. The direction is determined by your initial mouse  gesture  after
       pressing the key. Releasing the key removes the constraint.

       Remember: This is not an SoTransform! If you want to move other objects with this dragger,
       you can either:

       [a] Use an SoCenterballManip,  which  is  subclassed  from  SoTransform.  The  manipulator
       creates  one  of  these  draggers  and  uses it as the interface to edit the manipulator's
       fields. (See the SoCenterballManip man page.)

       [b] Use field-to-field connections to connect the fields of this dragger to those  of  any
       SoTransformation node.

       You can change the parts in any instance of this dragger using setPart(). The default part
       geometries are defined as resources for this SoCenterballDragger class. They are  detailed
       in the Dragger Resources section of the online reference page for this class. You can make
       your  program  use  different  default  resources  for  the  parts  by  copying  the  file
       /usr/share/data/draggerDefaults/centerballDragger.iv  into your own directory, editing the
       file, and then setting the environment variable  SO_DRAGGER_DIR  to  be  a  path  to  that
       directory.

FIELDS

     SoSFRotation        rotation
          Orientation of the centerball dragger.

     SoSFVec3f           center
          Center of rotation and scale of the centerball dragger.

METHODS

                         SoCenterballDragger()
          Constructor.

     static const SoNodekitCatalog *
                         getClassNodekitCatalog() const
          Returns an SoNodekitCatalog for this class.

     static SoType       getClassTypeId()
          Returns type identifier for this class.

CATALOG PARTS

       ┌──────────────────────────────────────────────────────────────────────┐
       │                              All parts                               │
       │                                                              NULL by │
       │Part Name           Part Type                  Default Type   Default │
       │                                                                      │
       │callbackList        NodeKitListPart            --               yes   │
       │translateToCenter   MatrixTransform            --               yes   │
       │surroundScale       SurroundScale              --               yes   │
       │antiSquish          AntiSquish                 --               no    │
       │lightModel          LightModel                 --               yes   │
       │XAxis               Separator                  --               yes   │
       │YAxis               Separator                  --               yes   │
       │ZAxis               Separator                  --               yes   │
       │rotator             RotateSphericalDragger     --               yes   │
       │YRotator            RotateCylindricalDragger   --               yes   │
       │ZCenterChanger      Translate2Dragger          --               yes   │
       │ZRotator            RotateCylindricalDragger   --               yes   │
       │YCenterChanger      Translate2Dragger          --               yes   │
       │XCenterChanger      Translate2Dragger          --               yes   │
       │XRotator            RotateCylindricalDragger   --               yes   │
       │                                                                      │
       └──────────────────────────────────────────────────────────────────────┘
       ┌───────────────────────────────────────────────────────────────┐
       │      Extra information for list parts from above table        │
       │                                                               │
       │Part Name      Container Type   Permissible Types              │
       │                                                               │
       │callbackList   Separator        Callback, EventCallback        │
       │                                                               │
       └───────────────────────────────────────────────────────────────┘

DRAGGER RESOURCES

       .in 0n+.5i
     Resource:         centerballRotator
       .in 0n+.5i
     Part:             rotator.rotator
     Appearance:       Invisible but pickable sphere
     Description:      When  picked,  initiates  free  rotation  about the center point. Slightly
                         smaller radius than the stripes, so you must pick between the stripes to
                         use it.

                         .in 0n+.5i
     Resource:         centerballRotatorActive
                         .in 0n+.5i
     Part:             rotator.rotatorActive
     Appearance:       Invisible sphere
     Description:      Displayed during unconstrained 3D rotation instead of centerballRotator.

                         .in 0n+.5i
     Resource:         centerballStripe
                         .in 0n+.5i
     Parts:            XRotator.rotator
                                           YRotator.rotator
                                           ZRotator.rotator
     Appearance:       White circle aligned with rotation axis.
     Description:      When  picked, initiates constrained rotation. Each rotator rotates locally
                         about its Y axis. The centerball contains private transform  parts  that
                         orient the draggers along three different axes.

                         .in 0n+.5i
     Resource:         centerballStripeActive
                         .in 0n+.5i
     Parts:            XRotator.rotatorActive
                                           YRotator.rotatorActive
                                           ZRotator.rotatorActive
     Appearance:       White circle aligned with the rotation axis.
     Description:      Displayed  during  constrained  rotation  instead of the rotator part. The
                         centerball orients the draggers along three different axes.

                         .in 0n+.5i
     Resource:         centerballCenterChanger
                         .in 0n+.5i
     Parts:            XCenterChanger.translator
                                           YCenterChanger.translator
                                           ZCenterChanger.translator
     Appearance:       Two sets of small green crosshairs, one located at  each  intersection  of
     axis and ball.
     Description:      When  picked,  initiates  2D  translation of ball through space. Edits the
                         center field,  which  becomes  center  for  subsequent  rotations.  Each
                         translator  works  locally  in  its  X-Y  plane. The centerball contains
                         private transform parts that place the draggers  along  three  different
                         axes.

                         .in 0n+.5i
     Resource:         centerballCenterChangerActive
                         .in 0n+.5i
     Parts:            XCenterChanger.translatorActive
                                           YCenterChanger.translatorActive
                                           ZCenterChanger.translatorActive
     Appearance:       Yellow version of centerballCenterChanger.
     Description:      Displayed  during  2D  translation instead of regular translator part. The
                         centerball places the draggers along three different axes.

                         .in 0n+.5i
     Resource:         centerballCenterXAxisFeedback
                         .in 0n+.5i
     Parts:            XCenterChanger.xAxisFeedback
                                           YCenterChanger.xAxisFeedback
                                           ZCenterChanger.xAxisFeedback
     Appearance:       Double-headed purple arrows, one located at each intersection of axis  and
     ball. Located atop X axis of crosshair.
     Description:      Only  shown  if dragger is moving and the axis is a permitted direction of
                         motion. When pressing  <shift>,  motion  is  constrained,  and  this  is
                         displayed  only if the primary motion is in the X direction of the child
                         dragger's local space. The centerball places the  draggers  along  three
                         different  axes;  so  not  all  of these parts aligns with the X axis in
                         centerball space.

                         .in 0n+.5i
     Resource:         centerballCenterYAxisFeedback
                         .in 0n+.5i
     Parts:            XCenterChanger.yAxisFeedback
                                           YCenterChanger.yAxisFeedback
                                           ZCenterChanger.yAxisFeedback
     Appearance:       Double-headed purple arrows, one located at each intersection of axis  and
     ball. Located atop Y axis of crosshair.
     Description:      Only  shown  if dragger is moving and the axis is a permitted direction of
                         motion. When pressing  <shift>,  motion  is  constrained,  and  this  is
                         displayed  only if the primary motion is in the Y direction of the child
                         dragger's local space. The centerball places the  draggers  along  three
                         different  axes;  so  not  all  of these parts aligns with the Y axis in
                         centerball space.

                         .in 0n+.5i
     Resource:         centerballXAxis
                         .in 0n+.5i
     Part:             XAxis
     Appearance:       Thin yellow line connecting left and right crosshairs.
     Description:      Feedback  shown  alone  during  rotation  about  X  axis;  displayed  with
                         centerballYAxis and centerballZAxis while center is dragged.

                         .in 0n+.5i
     Resource:         centerballYAxis
                         .in 0n+.5i
     Part:             YAxis
     Appearance:       Thin yellow line connecting lower and upper crosshairs.
     Description:      Feedback  shown  alone  during  rotation  about  Y  axis;  displayed  with
                         centerballXAxis and centerballZAxis while center is dragged.

                         .in 0n+.5i
     Resource:         centerballZAxis
                         .in 0n+.5i
     Part:             ZAxis
     Appearance:       Thin yellow line connecting near and far crosshairs.
     Description:      Feedback  shown  alone  during  rotation  about  Z  axis;  displayed  with
                         centerballXAxis and centerballYAxis while center is dragged.

FILE FORMAT/DEFAULTS

       CenterballDragger {
          renderCaching                    AUTO
          boundingBoxCaching               AUTO
          renderCulling                    AUTO
          pickCulling                      AUTO
          isActive                         FALSE
          rotation                         0 0 1  0
          center                           0 0 0
          callbackList                     NULL
          translateToCenter                MatrixTransform {
              matrix 1 0 0 0
                                               0 1 0 0
                                               0 0 1 0
                                               0 0 0 1 }

          surroundScale                    NULL
          antiSquish                       AntiSquish {
              sizing LONGEST_DIAGONAL }

          lightModel                       LightModel {
              model PHONG }

          XAxis                            <centerballXAxis resource>
          YAxis                            <centerballYAxis resource>
          ZAxis                            <centerballZAxis resource>
          rotator                          RotateSphericalDragger {
          }

          YRotator                         RotateCylindricalDragger {
          }

          ZCenterChanger                   Translate2Dragger {
          }

          ZRotator                         RotateCylindricalDragger {
          }

          YCenterChanger                   Translate2Dragger {
          }

          XCenterChanger                   Translate2Dragger {
          }

          XRotator                         RotateCylindricalDragger {
          }

          rotator.rotator                  <centerballRotator resource>
          rotator.rotatorActive            <centerballRotatorActive resource>
          XRotator.rotator                 <centerballStripe resource>
          YRotator.rotator                 <centerballStripe resource>
          ZRotator.rotator                 <centerballStripe resource>
          XRotator.rotatorActive           <centerballStripeActive resource>
          YRotator.rotatorActive           <centerballStripeActive resource>
          ZRotator.rotatorActive           <centerballStripeActive resource>
          XCenterChanger.translator        <centerballCenterChanger resource>
          YCenterChanger.translator        <centerballCenterChanger resource>
          ZCenterChanger.translator        <centerballCenterChanger resource>
          XCenterChanger.translatorActive  <centerballCenterChangerActive resource>
          YCenterChanger.translatorActive  <centerballCenterChangerActive resource>
          ZCenterChanger.translatorActive  <centerballCenterChangerActive resource>
          XCenterChanger.xAxisFeedback     <centerballCenterXAxisFeedback resource>
          YCenterChanger.xAxisFeedback     <centerballCenterXAxisFeedback resource>
          ZCenterChanger.xAxisFeedback     <centerballCenterXAxisFeedback resource>
          XCenterChanger.yAxisFeedback     <centerballCenterYAxisFeedback resource>
          YCenterChanger.yAxisFeedback     <centerballCenterYAxisFeedback resource>
          ZCenterChanger.yAxisFeedback     <centerballCenterYAxisFeedback resource>
     }

SEE ALSO

       SoInteractionKit,      SoDragger,      SoDirectionalLightDragger,      SoDragPointDragger,
       SoHandleBoxDragger,   SoJackDragger,   SoPointLightDragger,    SoRotateCylindricalDragger,
       SoRotateDiscDragger,     SoRotateSphericalDragger,    SoScale1Dragger,    SoScale2Dragger,
       SoScale2UniformDragger,   SoScaleUniformDragger,   SoSpotLightDragger,    SoTabBoxDragger,
       SoTabPlaneDragger,    SoTrackballDragger,    SoTransformBoxDragger,   SoTranslate1Dragger,
       SoTranslate2Dragger

                                                                       SoCenterballDragger(3IV)()