SOTRACKBALLDRAGGER(3iv)

📦 version 2.1.6.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

SoTrackballDragger — the striped ball that spins 💫

okay bestie, welcome to the SoTrackballDragger(3IV) page, this is part 1 of 2 so buckle up, we're going in 🌸

✨ NAME ✨

SoTrackballDragger — a striped ball that you can rotate or scale uniformly by dragging it with the mouse. it's giving "fidget toy but make it 3D" 💅

🧬 INHERITS FROM 🧬

SoBase > SoFieldContainer > SoNode > SoBaseKit > SoInteractionKit >
SoDragger > SoTrackballDragger

so yeah she's deep in the family tree, generational talent fr fr 👑

📜 SYNOPSIS 📜

first things first, the include:

#include <Inventor/draggers/SoTrackballDragger.h>

🌟 Fields from class SoTrackballDragger

SoSFVec3f           scaleFactor
SoSFRotation        rotation

🌟 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 SoTrackballDragger

                     SoTrackballDragger()
SbBool              isAnimationEnabled()
void                setAnimationEnabled(SbBool newVal)
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 💖

okay so picture this: SoTrackballDragger is literally just a ball wrapped in three circular stripes. the stripes are oriented like wheels that spin around the x, y, and z axes. drag the stripes to rotate the trackball around those axes 🎡

and here's the slay part — you do not have to hit the lines. pick anywhere within the stripe's outline. no pixel-hunting required, we're not doing that today 💅

wanna rotate the trackball freely in 3 dimensions? click the area between the stripes and then drag. an invisible but pickable sphere initiates this dragging — sneaky, iconic, no cap 👻✨

if the mouse is still moving when you release it, the trackball will continue to spin. yes, momentum. she has main character energy and she keeps going.

press the <Control> key to scale the trackball uniformly instead of rotating 🫶

press the <Shift> key and the user axis appears — it's a draggable axis with an extra stripe around it. moving the mouse along the surface of the sphere drags the 'pole' of the axis. release the <Shift> key and the user axis remains (she's not leaving, she lives here now). drag the new stripe for constrained rotation around the user axis 🌈

to make the user axis disappear, press <Shift> and drag the pole to where two of the other stripes intersect. this aligns the user axis with a primary axis, at which point the user axis disappears. poof. gone. periodt 💫

as you drag the trackball, it updates its rotation field, or its scaleFactor field if the <Control> key is down. and as with all draggers, if you change the fields the dragger moves in response. two-way street bestie 🔁

Remember: This is not an SoTransform! 🚨 this is the single most important line on this page. do not come for me saying "why isn't my object moving".

if you want to move other objects with this dragger, you have two options:

[a] use an SoTrackballManip, 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 SoTrackballManip reference 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 SoTrackballDragger class. they are detailed in the Dragger Resources section of the online reference page for this class 📚

wanna make your program use different default resources for the parts? so easy:

copy the file /usr/share/data/draggerDefaults/trackballDragger.iv into your own directory
edit the file
then set the environment variable SO_DRAGGER_DIR to be a path to that directory

boom. customized. ate and left no crumbs 🍓

🎀 FIELDS 🎀

SoSFVec3f scaleFactor — the Scale of the dragger. how big she's feeling today 💅
SoSFRotation rotation — the Orientation of the dragger. which way she's facing. her vibe check, if you will 🦋

🛠️ METHODS 🛠️

SoTrackballDragger() — Constructor. she is born ✨
SbBool isAnimationEnabled()
void setAnimationEnabled(SbBool newVal)

if the mouse is moving while you release it, the trackball will continue to spin afterwards. these two methods will query and set whether this feature is turned on or off. by default, the animation feature is turned on 🔥 (yes, the spin-forever thing is default behaviour, you're welcome)

static const SoNodekitCatalog * getClassNodekitCatalog() const — Returns an SoNodekitCatalog for this class 🗂️
static SoType getClassTypeId() — Returns type identifier for this class 🏷️

📦 CATALOG PARTS 📦

All parts

here's the full roster of parts, with their type, default type, and whether they're NULL by default 👑

callbackList — Part Type: NodeKitListPart — Default Type: -- — NULL by Default: yes
surroundScale — Part Type: SurroundScale — Default Type: -- — NULL by Default: yes
antiSquish — Part Type: AntiSquish — Default Type: -- — NULL by Default: no
rotator — Part Type: Separator — Default Type: -- — NULL by Default: yes
rotatorActive — Part Type: Separator — Default Type: -- — NULL by Default: yes
XRotator — Part Type: Separator — Default Type: -- — NULL by Default: yes
XRotatorActive — Part Type: Separator — Default Type: -- — NULL by Default: yes
YRotator — Part Type: Separator — Default Type: -- — NULL by Default: yes
YRotatorActive — Part Type: Separator — Default Type: -- — NULL by Default: yes
ZRotator — Part Type: Separator — Default Type: -- — NULL by Default: yes
ZRotatorActive — Part Type: Separator — Default Type: -- — NULL by Default: yes
userAxis — Part Type: Separator — Default Type: -- — NULL by Default: yes
userAxisActive — Part Type: Separator — Default Type: -- — NULL by Default: yes
userRotator — Part Type: Separator — Default Type: -- — NULL by Default: yes
userRotatorActive — Part Type: Separator — Default Type: -- — NULL by Default: yes

Extra information for list parts from above table

callbackList — Container Type: Separator — Permissible Types: Callback, EventCallback

okay bestie that's part 1, and there is more coming — don't go anywhere 🌸

✨ DRAGGER RESOURCES ✨

okay bestie, this is the part where we meet every single resource this dragger has 💖 each one is a little part with its own vibe, so let's go one by one, no skipping, we're doing all of them 🫶

🌸 Resource: `trackballRotator`

Part: rotator
Appearance: Invisible but pickable sphere
Description: Initiates unconstrained 3D rotation. Slightly smaller radius than the stripes, so you must pick between the stripes to use it.

🌸 Resource: `trackballRotatorActive`

Part: rotatorActive
Appearance: Invisible sphere
Description: Displayed during unconstrained 3D rotation.

🌸 Resource: `trackballXRotator`

Part: XRotator
Appearance: White outline of a stripe aligned with the X axis.
Description: Pick this to initiate constrained rotation about the X axis.

🌸 Resource: `trackballXRotatorActive`

Part: XRotatorActive
Appearance: Yellow version of the regular XRotator
Description: Displayed during constrained rotation about the X axis.

🌸 Resource: `trackballYRotator`

Part: YRotator
Appearance: White outline of a stripe aligned with the Y axis.
Description: Pick this to initiate constrained rotation about the Y axis.

🌸 Resource: `trackballYRotatorActive`

Part: YRotatorActive
Appearance: Yellow version of the regular YRotator
Description: Displayed during constrained rotation about the Y axis.

🌸 Resource: `trackballZRotator`

Part: ZRotator
Appearance: White outline of a stripe aligned with the Z axis.
Description: Pick this to initiate constrained rotation about the Z axis.

🌸 Resource: `trackballZRotatorActive`

Part: ZRotatorActive
Appearance: Yellow version of the regular ZRotator
Description: Displayed during constrained rotation about the Z axis.

🌸 Resource: `trackballUserAxis`

Part: userAxis
Appearance: Thin purple line
Description: Displays the user axis. Dragging the userRotator rotates about this line.

🌸 Resource: `trackballUserAxisActive`

Part: userAxisActive
Appearance: Thin purple line
Description: Displays the user axis. Dragging the userRotator rotates about this line.

🌸 Resource: `trackballUserRotator`

Part: userRotator
Appearance: Transparent green stripe circling the user axis.
Description: Pick to initiate constrained rotation about the user axis.

🌸 Resource: `trackballUserRotatorActive`

Part: userRotatorActive
Appearance: Brighter green version of the regular userRotator
Description: Displayed during constrained rotation about the user axis.

💾 FILE FORMAT/DEFAULTS 💾

like, here's literally the whole default setup, copy-paste energy, do not touch a single character bestie 😭

TrackballDragger {
   renderCaching       AUTO
   boundingBoxCaching  AUTO
   renderCulling       AUTO
   pickCulling         AUTO
   isActive            FALSE
   rotation            0 0 1  0
   scaleFactor         1 1 1
   callbackList        NULL
   surroundScale       NULL
   antiSquish          AntiSquish {
       sizing LONGEST_DIAGONAL }

   rotator             <trackballRotator resource>
   rotatorActive       <trackballRotatorActive resource>
   XRotator            <trackballXRotator resource>
   XRotatorActive      <trackballXRotatorActive resource>
   YRotator            <trackballYRotator resource>
   YRotatorActive      <trackballYRotatorActive resource>
   ZRotator            <trackballZRotator resource>
   ZRotatorActive      <trackballZRotatorActive resource>
   userAxis            <trackballUserAxis resource>
   userAxisActive      <trackballUserAxisActive resource>
   userRotator         <trackballUserRotator resource>
   userRotatorActive   <trackballUserRotatorActive resource>
}

🫢 NOTE 🫢

okay so this is lowkey tea ☕ — unlike most multi-function draggers, SoTrackballDragger is not a compound dragger made up of other draggers that perform its smaller tasks. And it's not because it was inappropriate, nope — it's because the trackball was written before implementation of the methods that take care of synchronizing multiple child draggers 🙈

The younger SoCenterballDragger is similar in form to the trackball, but the centerball is a compound dragger. periodt. 💅

👀 SEE ALSO 👀

go read these next, bestie, they're all family:

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

and that's a wrap on SoTrackballDragger, the 3IV girlies' finest 💖 no date on this one so I can't tell you when it was written, but the source and version you're holding is SoTrackballDragger(3IV)() — slay, bye bestie, go rotate something 🦋✨

📦 where this page comes from

debian bookworm: inventor-doc 2.1.5-10+dfsg-2 · LGPL-2.0-or-later
debian trixie: inventor-doc 2.1.6+ds-2 · LGPL-2.0-or-later
ubuntu jammy: inventor-doc 2.1.5-10-24
ubuntu noble: inventor-doc 2.1.5-10+dfsg-2.1build2 · LGPL-2.0-or-later
ubuntu questing: inventor-doc 2.1.6+ds-2
ubuntu resolute: inventor-doc 2.1.6.1+ds-1 · LGPL-2.0-or-later
ubuntu stonking: inventor-doc 2.1.6.1+ds-1 · LGPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms