SoVRMLAnchor(3)

📦 version 3.1.3, in fedora 43, fedora 44

💖 SoVRMLAnchor 💖

okay bestie, sit down, hydrate, because we're doing SoVRMLAnchor(3) and she's a big one. this is the manual page for the class that links you to other URL resources — like, the VRML node that's basically a hyperlink but make it 3D ✨

heads up: this page is long so it's split into parts, and you're reading part 1. don't go anywhere, there's more coming 🫶

✨ NAME ✨

SoVRMLAnchor — the class that's used for linking to other URL resources. that's it, that's the vibe. she's a link. a whole node whose entire personality is "click me and go somewhere else" 💅

🌸 SYNOPSIS 🌸

#include <Inventor/VRMLnodes/SoVRMLAnchor.h>

Inherits SoVRMLParent. so she's got ancestors, she's got lineage, she's got main character energy handed down through generations of classes 👑

🎀 Public Member Functions 🎀

the stuff just for her:

  • virtual SoType getTypeId (void) const — hands you her type ID, like a little name tag but for the type system.
  • SoVRMLAnchor (void) — the constructor, aka her birth. hi bestie 👋
  • virtual void handleEvent (SoHandleEventAction *action) — this is the one that actually does the linking thing when events come her way.

🦋 Public Member Functions inherited from SoVRMLParent 🦋

she didn't build this, she inherited it, and honestly? iconic:

  • virtual SbBool affectsState (void) const
  • virtual void addChild (SoNode *child)
  • virtual void insertChild (SoNode *child, int idx)
  • virtual SoNode * getChild (int idx) const
  • virtual int findChild (const SoNode *child) const
  • virtual int getNumChildren (void) const
  • virtual void removeChild (int idx)
  • virtual void removeChild (SoNode *child)
  • virtual void removeAllChildren (void)
  • virtual void replaceChild (int idx, SoNode *child)
  • virtual void replaceChild (SoNode *old, SoNode *child)
  • virtual SoChildList * getChildren (void) const
  • virtual void doAction (SoAction *action)
  • virtual void search (SoSearchAction *action)
  • virtual void write (SoWriteAction *action)
  • virtual void getPrimitiveCount (SoGetPrimitiveCountAction *action)

🌈 Public Member Functions inherited from SoGroup 🌈

  • SoGroup (void)
  • SoGroup (int nchildren)
  • virtual void GLRender (SoGLRenderAction *action)
  • virtual void callback (SoCallbackAction *action)
  • virtual void getBoundingBox (SoGetBoundingBoxAction *action)
  • virtual void getMatrix (SoGetMatrixAction *action)
  • virtual void pick (SoPickAction *action)
  • virtual void audioRender (SoAudioRenderAction *action)

⭐ Public Member Functions inherited from SoNode ⭐

  • void setOverride (const SbBool state)
  • SbBool isOverride (void) const
  • void setNodeType (const NodeType type)
  • NodeType getNodeType (void) const
  • virtual SoNode * copy (SbBool copyconnections=FALSE) const
  • virtual void GLRenderBelowPath (SoGLRenderAction *action)
  • virtual void GLRenderInPath (SoGLRenderAction *action)
  • virtual void GLRenderOffPath (SoGLRenderAction *action)
  • virtual void rayPick (SoRayPickAction *action)
  • virtual void grabEventsSetup (void)
  • virtual void grabEventsCleanup (void)
  • virtual void startNotify (void)
  • uint32_t getNodeId (void) const
  • virtual void writeInstance (SoOutput *out)
  • virtual SoNode * addToCopyDict (void) const
  • virtual SoFieldContainer * copyThroughConnection (void) const

💜 Public Member Functions inherited from SoFieldContainer 💜

  • void setToDefaults (void)
  • SbBool hasDefaultValues (void) const
  • SbBool fieldsAreEqual (const SoFieldContainer *container) const
  • void copyFieldValues (const SoFieldContainer *container, SbBool copyconnections=FALSE)
  • SbBool set (const char *const fielddata)
  • void get (SbString &fielddata)
  • virtual int getFields (SoFieldList &l) const
  • virtual int getAllFields (SoFieldList &l) const
  • virtual SoField * getField (const SbName &name) const
  • virtual SoField * getEventIn (const SbName &name) const
  • virtual SoField * getEventOut (const SbName &name) const
  • SbBool getFieldName (const SoField *const field, SbName &name) const
  • SbBool enableNotify (const SbBool flag)
  • SbBool isNotifyEnabled (void) const
  • SbBool set (const char *fielddata, SoInput *input)
  • void get (SbString &fielddata, SoOutput *out)
  • virtual SbBool validateNewFieldValue (SoField *field, void *newval)
  • virtual void addWriteReference (SoOutput *out, SbBool isfromfield=FALSE)
  • SbBool getIsBuiltIn (void) const
  • virtual void getFieldsMemorySize (size_t &managed, size_t &unmanaged) const
  • void setUserData (void *userdata) const
  • void * getUserData (void) const

🍓 Public Member Functions inherited from SoBase 🍓

  • void ref (void) const
  • void unref (void) const
  • void unrefNoDelete (void) const
  • int32_t getRefCount (void) const
  • void touch (void)
  • SbBool isOfType (SoType type) const
  • virtual SbName getName (void) const
  • virtual void setName (const SbName &newname)
  • void addAuditor (void *const auditor, const SoNotRec::Type type)
  • void removeAuditor (void *const auditor, const SoNotRec::Type type)
  • const SoAuditorList & getAuditors (void) const
  • SbBool shouldWrite (void)
  • void assertAlive (void) const

🧚 Static Public Member Functions 🧚

the ones you can call without even making an instance. no object, no problem:

  • static SoType getClassTypeId (void)
  • static void initClass (void)
  • static void setFetchURLCallBack (SoVRMLAnchorCB *, void *closure) — sets the callback that handles fetching URLs. yes, this is the spicy one for links 🔥

🌸 Static Public Member Functions inherited from SoVRMLParent 🌸

  • static SoType getClassTypeId (void)
  • static void initClass (void)
  • static void updateChildList (const SoNode *const *nodes, const int numnodes, SoChildList &cl)
  • static void updateChildList (SoNode *nodewithsfnode, SoChildList &cl)

🎀 Static Public Member Functions inherited from SoGroup 🎀

  • static SoType getClassTypeId (void)
  • static void initClass (void)

✨ Static Public Member Functions inherited from SoNode ✨

  • static uint32_t getCompatibilityTypes (const SoType &nodetype)
  • static SoType getClassTypeId (void)
  • static SoNode * getByName (const SbName &name)
  • static int getByName (const SbName &name, SoNodeList &l)
  • static void initClass (void)
  • static void initClasses (void)
  • static uint32_t getNextNodeId (void)
  • static int getActionMethodIndex (const SoType type)
  • static void getBoundingBoxS (SoAction *action, SoNode *node)
  • static void GLRenderS (SoAction *action, SoNode *node)
  • static void callbackS (SoAction *action, SoNode *node)
  • static void getMatrixS (SoAction *action, SoNode *node)
  • static void handleEventS (SoAction *action, SoNode *node)
  • static void pickS (SoAction *action, SoNode *node)
  • static void rayPickS (SoAction *action, SoNode *node)
  • static void searchS (SoAction *action, SoNode *node)
  • static void writeS (SoAction *action, SoNode *node)
  • static void audioRenderS (SoAction *action, SoNode *node)
  • static void getPrimitiveCountS (SoAction *action, SoNode *node)

🦋 Static Public Member Functions inherited from SoFieldContainer 🦋

  • static void initClass (void)
  • static SoType getClassTypeId (void)
  • static void cleanupClass (void)
  • static void initCopyDict (void)
  • static void addCopy (const SoFieldContainer *orig, const SoFieldContainer *copy)
  • static SoFieldContainer * checkCopy (const SoFieldContainer *orig)
  • static SoFieldContainer * findCopy (const SoFieldContainer *orig, const SbBool copyconnections)
  • static void copyDone (void)

💫 Static Public Member Functions inherited from SoBase 💫

  • static void initClass (void)
  • static SoType getClassTypeId (void)
  • static void addName (SoBase *const base, const char *const name)
  • static void removeName (SoBase *const base, const char *const name)
  • static void incrementCurrentWriteCounter (void)
  • static void decrementCurrentWriteCounter (void)
  • static SoBase * getNamedBase (const SbName &name, SoType type)
  • static int getNamedBases (const SbName &name, SoBaseList &baselist, SoType type)
  • static SbBool read (SoInput *input, SoBase *&base, SoType expectedtype)
  • static void setInstancePrefix (const SbString &c)
  • static void setTraceRefs (SbBool trace)
  • static SbBool getTraceRefs (void)
  • static SbBool connectRoute (SoInput *input, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname)
  • static SbBool readRoute (SoInput *input)

👑 Public Attributes 👑

her actual data, the fields, the whole point:

  • SoMFString url — the URLs she links to. multi-value, so she can have options.
  • SoSFString description — a lil description, for when you need words.
  • SoMFString parameter — parameters, plural, as many as you like.
  • SoSFVec3f bboxCenter — center of the bounding box.
  • SoSFVec3f bboxSize — size of the bounding box.

💜 Public Attributes inherited from SoVRMLParent 💜

  • SoMFNode children

🎀 Protected Member Functions 🎀

for her and her subclasses only, mind your business 🙈

  • virtual const SoFieldData * getFieldData (void) const
  • virtual ~SoVRMLAnchor ()

🌸 Protected Member Functions inherited from SoVRMLParent 🌸

  • SoVRMLParent (void)
  • SoVRMLParent (int approxchildren)
  • virtual ~SoVRMLParent ()
  • virtual void notify (SoNotList *list)
  • virtual SbBool readInstance (SoInput *in, unsigned short flags)
  • virtual void copyContents (const SoFieldContainer *from, SbBool copyConn)

⭐ Protected Member Functions inherited from SoGroup ⭐

  • virtual ~SoGroup ()
  • virtual SbBool readChildren (SoInput *in)

🦋 Protected Member Functions inherited from SoNode 🦋

  • SoNode (void)
  • virtual ~SoNode ()

🍓 Protected Member Functions inherited from SoFieldContainer 🍓

  • SoFieldContainer (void)
  • virtual ~SoFieldContainer ()

💜 Protected Member Functions inherited from SoBase 💜

  • SoBase (void)
  • virtual ~SoBase ()
  • virtual void destroy (void)
  • SbBool hasMultipleWriteRefs (void) const
  • SbBool writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine) const
  • void writeFooter (SoOutput *out) const
  • virtual const char * getFileFormatName (void) const

✨ Static Protected Member Functions ✨

  • static const SoFieldData ** getFieldDataPtr (void)

🌈 Static Protected Member Functions inherited from SoVRMLParent 🌈

  • static const SoFieldData ** getFieldDataPtr (void)

🎀 Static Protected Member Functions inherited from SoGroup 🎀

  • static const SoFieldData ** getFieldDataPtr (void)

⭐ Static Protected Member Functions inherited from SoNode ⭐

  • static const SoFieldData ** getFieldDataPtr (void)
  • static void setNextActionMethodIndex (int index)
  • static int getNextActionMethodIndex (void)
  • static void incNextActionMethodIndex (void)
  • static void setCompatibilityTypes (const SoType &nodetype, const uint32_t bitmask)

💫 Static Protected Member Functions inherited from SoBase 💫

  • static uint32_t getCurrentWriteCounter (void)
  • static void staticDataLock (void)
  • static void staticDataUnlock (void)

🫶 Additional Inherited Members 🫶

the deep lore. the family tree. the stuff that got passed down and you gotta know about:

🦋 Public Types inherited from SoNode 🦋

  • enum NodeType { INVENTOR = 0x0000, VRML1 = 0x0001, VRML2 = 0x0002, INVENTOR_1 = 0x0004, INVENTOR_2_0 = 0x0008, INVENTOR_2_1 = 0x0010, INVENTOR_2_5 = 0x0020, INVENTOR_2_6 = 0x0040, COIN_1_0 = 0x0080, COIN_2_0 = 0x0100, EXTENSION = 0x0200, COIN_2_2 = 0x0400, COIN_2_3 = 0x0800, COIN_2_4 = 0x1000, INVENTOR_5_0 = 0x2000, COIN_2_5 = 0x4000, COIN_3_0 = 0x8000, INVENTOR_6_0 = 0x10000 }

🍓 Protected Types inherited from SoBase 🍓

  • enum BaseFlags { IS_ENGINE = 0x01, IS_GROUP = 0x02 }

🌸 Protected Attributes inherited from SoVRMLParent 🌸

  • SoMFNode addChildren
  • SoMFNode removeChildren

⭐ Protected Attributes inherited from SoGroup ⭐

  • SoChildList * children

🦋 Protected Attributes inherited from SoNode 🦋

  • uint32_t uniqueId

💜 Protected Attributes inherited from SoFieldContainer 💜

  • SbBool isBuiltIn

💫 Static Protected Attributes inherited from SoNode 💫

  • static uint32_t nextUniqueId = 1
  • static int nextActionMethodIndex = 0

and that's the whole SYNOPSIS section, bestie!! every last inherited member, no crumbs left behind 💅

part 2 is coming, so don't close the tab — we've still got the DESCRIPTION, the real talk about what she actually does, and the rest of the lore. stay tuned 🎀

💖 DETAILED DESCRIPTION 💖

okay so bestie, the SoVRMLAnchor class is literally the thing that links you to other URL resources. it's giving hyperlink but make it 1997 VRML ✨

the full class documentation here is taken verbatim from the VRML97 standard (ISO/IEC 14772-1:1997). it is copyright The Web3D Consortium, and used by permission of the Consortium:

Anchor {
  eventIn      MFNode   addChildren
  eventIn      MFNode   removeChildren
  exposedField MFNode   children        []
  exposedField SFString description     ""
  exposedField MFString parameter       []
  exposedField MFString url             []
  field        SFVec3f  bboxCenter      0 0 0     # (-inf, inf)
  field        SFVec3f  bboxSize        -1 -1 -1  # (0, inf) or -1,-1,-1
}

so the Anchor grouping node pulls the content of a URL when the user activates (like, clicks 👆) some geometry that lives inside the Anchor node's children. if the URL points to a valid VRML file, that world replaces the world the Anchor node is part of — except when the parameter field (more on that below) changes up this behaviour. if it's non-VRML data being retrieved, the browser gets to decide how to handle it; typically it gets passed off to an appropriate non-VRML browser. 🫶

exactly how a user activates geometry contained by the Anchor node depends on the pointing device and is determined by the VRML browser. typically, clicking with the pointing device means the new scene replaces the current scene. an Anchor node with an empty url does nothing when its children are chosen — no cap, nothing happens 💀. a description of how multiple Anchors and pointing-device sensors are resolved on activation lives in 4.6.7, Sensor nodes (http://www.web3d.org/x3d/specifications/vrml/ISO-IEC-14772-VRML97/part1/concepts.html#4.6.7).

more deets on the children, addChildren, and removeChildren fields and eventIns can be found in 4.6.5, Grouping and children nodes (http://www.web3d.org/x3d/specifications/vrml/ISO-IEC-14772-VRML97/part1/concepts.html#4.6.5).

the description field in the Anchor node specifies a textual description of the Anchor node. browser-specific user interfaces that wanna present users with more detailed info about the Anchor may use it. the parameter exposed field may be used to supply any additional information to be interpreted by the browser. each string shall consist of "keyword=value" pairs. for example, some browsers allow the specification of a 'target' for a link to display a link in another part of an HTML document. so the parameter field is then:

Anchor {
  parameter [ "target=name_of_frame" ]
  ...
}

an Anchor node may be used to bind the initial Viewpoint node in a world by specifying a URL ending with "#ViewpointName", where "ViewpointName" is the name of a viewpoint defined in the VRML file. for example:

Anchor {
  url "http://www.school.edu/vrml/someScene.wrl#OverView"
  children  Shape { geometry Box {} }
}

this specifies an anchor that loads the VRML file "someScene.wrl" and binds the initial user view to the Viewpoint node named "OverView" when the Anchor node's geometry (Box) is activated. if the named Viewpoint node is not found in the VRML file, the VRML file is loaded using the default Viewpoint node binding stack rules (see VRMLViewpoint). 🌈

if the url field is specified in the form "#ViewpointName" (i.e. no file name), the Viewpoint node with the given name ("ViewpointName") in the Anchor's run-time name scope(s) shall be bound (set_bind TRUE).

🚨 bestie WATCH OUT: the results are undefined if there are multiple Viewpoints with the same name in the Anchor's run-time name scope(s). and also undefined if the Anchor node isn't part of any run-time name scope, or is part of more than one run-time name scope. no vibe check can save you from undefined behaviour 😭

see 4.4.6, Run-time name scope, for a description of run-time name scopes. see VRMLViewpoint, for the Viewpoint transition rules that specify how browsers shall interpret the transition from the old Viewpoint node to the new one. for example:

Anchor {
  url "#Doorway"
  children Shape {
    geometry Sphere {}
  }
}

this binds the viewer to the viewpoint defined by the "Doorway" viewpoint in the current world when the sphere is activated. in this case, if the Viewpoint is not found, no action occurs on activation. more details on the url field are contained in 4.5, VRML and the World Wide Web (http://www.web3d.org/x3d/specifications/vrml/ISO-IEC-14772-VRML97/part1/concepts.html#4.5). 🦋

the bboxCenter and bboxSize fields specify a bounding box that encloses the Anchor's children. this is a hint that may be used for optimization purposes.

⚠️ and yes, another one: the results are undefined if the specified bounding box is smaller than the actual bounding box of the children at any time. ✋

the default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, shall be calculated by the browser. more details on the bboxCenter and bboxSize fields can be found in 4.6.4, Bounding boxes (http://www.web3d.org/x3d/specifications/vrml/ISO-IEC-14772-VRML97/part1/concepts.html#4.6.4).

🎀 CONSTRUCTOR & DESTRUCTOR DOCUMENTATION 🎀

SoVRMLAnchor::SoVRMLAnchor (void )

the default constructor. the classic. the origin story 💅

SoVRMLAnchor::~SoVRMLAnchor () [protected], [virtual]

the destructor. it's the goodbye, but make it clean 🫶

✨ MEMBER FUNCTION DOCUMENTATION ✨

SoType SoVRMLAnchor::getTypeId (void ) const [virtual]

returns the type identification of an object derived from a class inheriting SoBase. this is used for run-time type checking and "downward" casting. very main character of it, honestly 👑

usage example:

void foo(SoNode * node)
{
  if (node->getTypeId() == SoFile::getClassTypeId()) {
    SoFile * filenode = (SoFile *)node;  // safe downward cast, knows the type
  }
}

for application programmers wanting to extend the library with new nodes, engines, nodekits, draggers or others: this method needs to be overridden in all subclasses. this is typically done as part of setting up the full type system for extension classes, which is usually accomplished by using the pre-defined macros available through, for instance, Inventor/nodes/SoSubNode.h (SO_NODE_INIT_CLASS and SO_NODE_CONSTRUCTOR for node classes), Inventor/engines/SoSubEngine.h (for engine classes) and so on. 🧚

for more info on writing Coin extensions, see the class documentation of the toplevel superclasses for the various class groups.

Reimplemented from SoVRMLParent.

const SoFieldData * SoVRMLAnchor::getFieldData (void ) const [protected], [virtual]

returns a pointer to the class-wide field data storage object for this instance. if no fields are present, returns NULL. simple as that, no notes 🌸

Reimplemented from SoVRMLParent.

void SoVRMLAnchor::setFetchURLCallBack (SoVRMLAnchorCB * f, void * closure) [static]

sets the callback that will be called when the node is selected. 📞

void SoVRMLAnchor::handleEvent (SoHandleEventAction * action) [virtual]

action method for SoHandleEventAction.

inspects the event data from action, and processes it if it's something this node should react to. if it's not for you, it's not for you, periodt 💅

nodes influencing relevant state variables for how event handling is done also override this method.

Reimplemented from SoGroup.

💜 MEMBER DATA DOCUMENTATION 💜

SoMFString SoVRMLAnchor::url

the URL string. the whole point, lowkey 🌐

SoSFString SoVRMLAnchor::description

the textual description of the URL.

SoMFString SoVRMLAnchor::parameter

may be used to supply additional information to the browser.

each string should be pairs of keyword = value.

SoSFVec3f SoVRMLAnchor::bboxCenter

children bounding box hint center. default value is (0, 0, 0). 📦

SoSFVec3f SoVRMLAnchor::bboxSize

children bounding box size hint. default value is (-1, -1, -1).

👑 AUTHOR

generated automatically by Doxygen for Coin from the source code. iconic behaviour honestly, letting the robot write your author section ✨

aaaand that's a wrap bestie!! 🎀 this page came from Coin, Version 3.1.3, dated SoVRMLAnchor(3) — go forth and anchor all your URL resources, but please, for the love of everything, don't create multiple Viewpoints with the same name. undefined behaviour is not the vibe. mwah 💖🦋

📦 where this page comes from