SODRAGPOINTDRAGGER(3iv)

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

💅 SoDragPointDragger — the manual, but make it make sense (part 1 of 2)

okay bestie, so we're in SoDragPointDragger(3IV) territory. This is an Inventor toolkit situation and it is so much less scary than the manpage makes it look. Sit down, grab a strawberry thing, let's go. 🍓

✨ NAME ✨

SoDragPointDragger — an object you can translate in 3D by dragging with the mouse. that's it. that's the whole vibe. you grab it, you move it, it moves in all three dimensions. iconic behavior honestly. 🫶

🌸 INHERITS FROM 🌸

the family tree goes like this, oldest ancestor first:

SoBase > SoFieldContainer > SoNode > SoBaseKit > SoInteractionKit > SoDragger > SoDragPointDragger

so it's a whole lineage. it inherited the good genes. 👑

⭐ SYNOPSIS ⭐

first, the include, exact as always:

#include <Inventor/draggers/SoDragPointDragger.h>

🎀 Fields from class SoDragPointDragger

  • SoSFVec3f translation — the one field this class brings to the party

🎀 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 SoDragPointDragger

  • SoDragPointDragger()
  • void setJumpLimit(float limit)
  • float getJumpLimit() const
  • void showNextDraggerSet()
  • 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. SoDragPointDragger is a compound dragger, and what it does is translate in all three dimensions when you drag it with the mouse. all three. not two. three. she's flexible like that. 💅

Here's the tea on how she's built: she's made up of six smaller draggers, and she only ever shows two at a time. Each pair is one plane dragger plus one line dragger. The line dragger sits perpendicular to the plane, so together that plane/line duo lets you move through all of 3-space. teamwork makes the dream work fr fr. 🦋

DragPoint has three of these pairs total, oriented along the x, y, and z axes of its local space. Wanna cycle through the three pairs? Hit the <Control> key with the cursor hovering over the dragger. and no, you do not need to press the mouse button. just vibes and a keyboard. ✨

The line draggers are SoTranslate1Draggers and the plane draggers are SoTranslate2Draggers. Which means you can hold <Shift> to constrain a plane dragger's motion along one of the two axes inside that plane — exactly like the SoTranslate2Draggers man page describes. iykyk. 😌

Now, the extra-fancy part. DragPoint adds extra feedback parts so you actually have a clue where you are in three-space instead of just guessing like a fool. There are three feedback planes and three feedback axes; each one corresponds to one of the plane or line draggers, but it spans a much greater distance.

  • When you drag along a line, that line's bigger feedback axis shows up, and it stays anchored in space while the dragger slides along it. This helps you feel the dragger's motion relative to the rest of the scene.
  • When you drag within a plane, the bigger — but transparent — feedback plane acts like a ground plane for you to move on top of.
  • Where the dragger sits inside that plane is pinpointed by two intersecting axes that always cross below the cursor and stretch out to the edges of the plane.
  • When you move dragPoint to the edge of the feedback plane (or line), the feedback jumps to a new location in that direction, so the dragger never leaves the feedback behind. she never abandons her feedback. loyal. 🫶

The primary directions of motion come from the dragger's local space. Transforms earlier in the scene will affect the dragger, its children, and the orientation of its directions of motion. keep that in mind bestie, it matters.

This node has a translation field which always reflects its position in local space. Set the field and the dragger moves to that point. You can also connect fields of other nodes or engines from this one, so they follow the dragger's motion around like little ducklings. 🐣

Now, even though the child draggers each have their own resources defining default part geometries, the dragPoint dragger overrides these with a whole new set of resources. She also defines resources for the feedback parts she adds. All of that is detailed in the Dragger Resources section of the online reference page for this class. And you can change the parts in any instance of this dragger using setPart().

Wanna make your program use different default resources for the parts? The move is:

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

boom. custom defaults. you're welcome. 🎀

🌈 FIELDS 🌈

  • SoSFVec3f translation — Position of the dragger. that's her location. that's where she's at, literally and figuratively. 📍

👑 METHODS 👑

  • SoDragPointDragger() — Constructor. the birth of an icon. ✨
  • void setJumpLimit(float limit)
  • float getJumpLimit() const

Set and get the point at which the feedback axes will jump to a new position. For example, if set to .1 — which is the default, btw — the feedback axes will jump when the dragger gets within 10% of the end of the axis. so she bails a little early. respectfully. 💀

  • void showNextDraggerSet()

The dragPoint dragger contains three pairs of draggers, each one holding a plane dragger and a line dragger (peep the Description above for the full lore). The dragger starts with the (y-line/xz-plane) pair displayed. Call this method and it cycles next through the (z-line/xy-plane), then the (x-line/yz-plane). round and round she goes. 🔄

  • static const SoNodekitCatalog *getClassNodekitCatalog() const — Returns an SoNodekitCatalog for this class.
  • static SoType getClassTypeId() — Returns type identifier for this class.

and that's where part 1 wraps up bestie — part 2 is right behind it, don't go anywhere. 🌸

🎀 CATALOG PARTS 🎀

okay bestie, here's the whole cast list of parts this dragger brings to the function 💖 Every single one of them is NULL by default, so nothing's set up until you set it up, iykyk.

All parts — Part Name, Part Type, Default Type, and whether it's NULL by default:

  • callbackList — Part Type: NodeKitListPart; Default Type: --; NULL by default: yes
  • xTranslator — Part Type: Translate1Dragger; Default Type: --; NULL by default: yes
  • xyTranslator — Part Type: Translate2Dragger; Default Type: --; NULL by default: yes
  • xzTranslator — Part Type: Translate2Dragger; Default Type: --; NULL by default: yes
  • zTranslator — Part Type: Translate1Dragger; Default Type: --; NULL by default: yes
  • yzTranslator — Part Type: Translate2Dragger; Default Type: --; NULL by default: yes
  • yTranslator — Part Type: Translate1Dragger; Default Type: --; NULL by default: yes
  • xFeedback — Part Type: Separator; Default Type: --; NULL by default: yes
  • yFeedback — Part Type: Separator; Default Type: --; NULL by default: yes
  • zFeedback — Part Type: Separator; Default Type: --; NULL by default: yes
  • yzFeedback — Part Type: Separator; Default Type: --; NULL by default: yes
  • xzFeedback — Part Type: Separator; Default Type: --; NULL by default: yes
  • xyFeedback — Part Type: Separator; Default Type: --; NULL by default: yes

🌸 Extra information for list parts from above table 🌸

these ones are special, they're list parts so they get extra deets 🦋

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

💅 DRAGGER RESOURCES 💅

this is the good part, the resource glow-up section ✨ For each one you get its Resource name, the Part it lives on, its Appearance, and what it does. Slay.

  • dragPointXTranslatorTranslator
    • Part: xTranslator.translator
    • Appearance: white cylinder with axis aligned in X direction
    • Description: picking this initiates linear motion in X direction
  • dragPointXTranslatorTranslatorActive
    • Part: xTranslator.translatorActive
    • Appearance: yellow cylinder with axis aligned in X direction
    • Description: shown when moving in X direction
  • dragPointYTranslatorTranslator
    • Part: yTranslator.translator
    • Appearance: white cylinder with axis aligned in Y direction
    • Description: picking this initiates linear motion in Y direction
  • dragPointYTranslatorTranslatorActive
    • Part: yTranslator.translatorActive
    • Appearance: yellow cylinder with axis aligned in Y direction
    • Description: shown when moving in Y direction
  • dragPointZTranslatorTranslator
    • Part: zTranslator.translator
    • Appearance: white cylinder with axis aligned in Z direction
    • Description: picking this initiates linear motion in Z direction
  • dragPointZTranslatorTranslatorActive
    • Part: zTranslator.translatorActive
    • Appearance: yellow cylinder with axis aligned in Z direction
    • Description: shown when moving in Z direction
  • dragPointYZTranslatorTranslator
    • Part: yzTranslator.translator
    • Appearance: white flattened cube within the yz plane of motion
    • Description: picking this initiates planar motion in yz plane
  • dragPointYZTranslatorTranslatorActive
    • Part: yzTranslator.translatorActive
    • Appearance: yellow flattened cube within the yz plane of motion
    • Description: shown when moving in yz plane
  • dragPointXZTranslatorTranslator
    • Part: xzTranslator.translator
    • Appearance: white flattened cube within the xz plane of motion
    • Description: picking this initiates planar motion in xz plane
  • dragPointXZTranslatorTranslatorActive
    • Part: xzTranslator.translatorActive
    • Appearance: yellow flattened cube within the xz plane of motion
    • Description: shown when moving in xz plane
  • dragPointXYTranslatorTranslator
    • Part: xyTranslator.translator
    • Appearance: white flattened cube within the xy plane of motion
    • Description: picking this initiates planar motion in xy plane
  • dragPointXYTranslatorTranslatorActive
    • Part: xyTranslator.translatorActive
    • Appearance: yellow flattened cube within the xy plane of motion
    • Description: shown when moving in xy plane
  • dragPointXFeedback
    • Part: xFeedback
    • Appearance: douple-headed purple arrow
    • Description: feedback for motion in x direction
  • dragPointYFeedback
    • Part: yFeedback
    • Appearance: douple-headed purple arrow
    • Description: feedback for motion in y direction
  • dragPointZFeedback
    • Part: zFeedback
    • Appearance: douple-headed purple arrow
    • Description: feedback for motion in z direction
  • dragPointYZFeedback
    • Part: yzFeedback
    • Appearance: semi-transparent green square in yz plane
    • Description: feedback for motion in yz plane
  • dragPointXZFeedback
    • Part: xzFeedback
    • Appearance: semi-transparent green square in yz plane
    • Description: feedback for motion in xz plane
  • dragPointXYFeedback
    • Part: xyFeedback
    • Appearance: semi-transparent green square in yz plane
    • Description: feedback for motion in xy plane
💀 not me pointing out that yes, the feedback appearances are literally spelled douple-headed and yes, the XZ and XY feedback entries really do say yz plane — that's what the page says bestie, I just work here 🙈

🌈 FILE FORMAT/DEFAULTS 🌈

here's the whole default tree, verbatim, no edits, periodt 👑

DragPointDragger {
   renderCaching                  AUTO
   boundingBoxCaching             AUTO
   renderCulling                  AUTO
   pickCulling                    AUTO
   isActive                       FALSE
   translation                    0 0 0
   callbackList                   NULL
   xTranslator                    Translate1Dragger {
   }

   xyTranslator                   Translate2Dragger {
   }

   xzTranslator                   Translate2Dragger {
   }

   zTranslator                    Translate1Dragger {
   }

   yzTranslator                   Translate2Dragger {
   }

   yTranslator                    Translate1Dragger {
   }

   xFeedback                      <dragPointXFeedback resource>
   yFeedback                      <dragPointYFeedback resource>
   zFeedback                      <dragPointZFeedback resource>
   yzFeedback                     <dragPointYZFeedback resource>
   xzFeedback                     <dragPointXZFeedback resource>
   xyFeedback                     <dragPointXYFeedback resource>
   xTranslator.translator         <dragPointXTranslatorTranslator resource>
   xTranslator.translatorActive   <dragPointXTranslatorTranslatorActive resource>
   yTranslator.translator         <dragPointYTranslatorTranslator resource>
   yTranslator.translatorActive   <dragPointYTranslatorTranslatorActive resource>
   zTranslator.translator         <dragPointZTranslatorTranslator resource>
   zTranslator.translatorActive   <dragPointZTranslatorTranslatorActive resource>
   yzTranslator.translator        <dragPointYZTranslatorTranslator resource>
   yzTranslator.translatorActive  <dragPointYZTranslatorTranslatorActive resource>
   xzTranslator.translator        <dragPointXZTranslatorTranslator resource>
   xzTranslator.translatorActive  <dragPointXZTranslatorTranslatorActive resource>
   xyTranslator.translator        <dragPointXYTranslatorTranslator resource>
   xyTranslator.translatorActive  <dragPointXYTranslatorTranslatorActive resource>
}

🫶 SEE ALSO 🫶

the friend group, the whole squad, go say hi to all of them 💖

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

and that's a wrap on SoDragPointDragger(3IV), bestie 🎀 the footer of this page is literally just SoDragPointDragger(3IV)() — that's your source/version tag and the date slot, and yeah the date part is sitting there empty, which is honestly such a mood 😭✨ go drag some points, you're the main character, periodt 💅🦋

📦 where this page comes from