Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SoBaseKit(3IV)()					      SoBaseKit(3IV)()

NAME
       SoBaseKit -- base class for all node kits

INHERITS FROM
       SoBase >	SoFieldContainer > SoNode > SoBaseKit

SYNOPSIS
       #include	<Inventor/nodekits/SoBaseKit.h>

	  Parts	from class SoBaseKit:

     (SoNodeKitListPart)  callbackList

	  Methods from class SoBaseKit:

			      SoBaseKit()
     static const SoNodekitCatalog *
			      getClassNodekitCatalog() const
     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)
     static SoType	      getClassTypeId()

	  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
       This is the base	class from which all nodekit nodes are derived.	Nodek-
       its  provide  a convenient mechanism for	creating groups	of scene graph
       nodes with some larger meaning. When you	create a shape node such as an
       indexed	face set, for example, you almost always precede it with a co-
       ordinate	node. You may also want	to add a  transform  node  or  specify
       properties with material, drawing style,	material binding, etc. Instead
       of creating each	of these nodes individually and	 then  arranging  them
       into a subgraph,	you can	use a nodekit of the appropriate type (in this
       case, SoShapeKit).

       Each class of nodekit has a nodekit catalog (SoNodekitCatalog) that de-
       scribes	the  nodes  in the subgraph, referred to as parts. The catalog
       has an entry for	each part, with	 information  such  as	the  partName,
       partType,  and nullByDefault (if	FALSE the constructor creates it). The
       catalog also describes the arrangement of parts in the subgraph.	(Other
       information  is	described below; a complete description	is in the SoN-
       odekitCatalog reference page.)

       If we regard the	scene graph arrangement	as a branching tree, then  the
       top  node  (root)  of the arrangement is	always the nodekit itself. The
       leaf nodes are those at	the  bottom  (containing  no  children).  Some
       leaves of the tree are defined in the catalog to	be public parts, while
       other leaves are	private. All non-leaf parts are	considered internal to
       the nodekit structure and are marked private. Public parts are accessi-
       ble; they may be	requested, changed, or set by the programmer with mem-
       ber  functions  such as getPart(). Private parts	are not	accessible, so
       methods such as getPart() will have no effect on	them. For example,  if
       you  call  getPart()  to	retrieve a private part, NULL will be returned
       even when the part exists.

       Every nodekit reference page has	a Parts	section	describing  the	 func-
       tion  of	 each  public  part it adds to those inherited from its	parent
       class. Also, a Catalog Parts section has	tables of often-needed	infor-
       mation  from  the  catalog  (part type, etc.). These tables include all
       public parts, both new and  inherited.  Only  the  public  parts	 of  a
       nodekit are described in	the reference pages. Nodekits take care	of the
       rest for	you; they automatically	arrange	 the  subgraph,	 creating  and
       deleting	the private parts when necessary. (The SoNodekitCatalog	refer-
       ence page has methods for finding out the part names and	arrangement of
       all parts, both public and private.)

       The  nodekit  catalog is	a template shared by all instances of a	class.
       They use	the shared catalog as a	guide when creating parts (i.e.,  con-
       structing  actual  nodes), but each instance stores its own parts sepa-
       rately. Moreover, nodekits are not SoGroup nodes, and parts  are	 added
       as  hidden  children;  you  can	only  access parts with	the methods of
       SoBaseKit and its derived classes.

       Any public part may be retrieved	with getPart(),	 installed  with  set-
       Part(),	or  removed by giving a	NULL argument to setPart(). Paths from
       the nodekit down	to a part can be created by createPathToPart().

       By default, parts are not created until the user	requests or sets them.
       This  keeps the subgraph	uncluttered and	efficient for traversal. Addi-
       tionally, removing a part (setting it to	NULL) has the extra effect  of
       removing	any internal parts that	are no longer needed.

       Since nodekits hide their children, any SoPath containing nodekits will
       end at the topmost nodekit.  However,  since  nodekits  may  be	nested
       within other nodekits, you may wish to cast an (SoPath *) into an (SoN-
       odeKitPath *). The methods of  SoNodeKitPath  allow  you	 to  view  all
       nodekits	 that  lie  on the path	(see the reference page	for SoNodeKit-
       Path).

       Public parts in the nodekit catalog fall	into three categories:

       [1] regular nodes

       [2] nodekits, or	nested nodekits	(which may nest	recursively). Any node
       which  is  public in a nested nodekit is	accessible to the higher level
       nodekit(s) that contains	it. The	description of getPart()  below	 shows
       how  to	refer  to  nested parts	by name	(e.g., "appearance.material").
       This works for any nodekit method that takes a part name	for  an	 argu-
       ment.

       [3] lists, or list parts. These parts group together children (list el-
       ements) of a particular type or types. As with nested nodekits, you can
       refer  to  individual  elements	using  notation	described in getPart()
       (e.g., "childList[0]", or if the	list elements are  in  turn  nodekits,
       "childList[2].transform").

       When  the catalog denotes that a	part is	a list,	the part itself	is al-
       ways a node of type SoNodeKitListPart. The catalog specifies a  set  of
       permissible  listItemTypes  and	a  listContainerType for that part. It
       gives this information to the SoNodeKitListPart	when  it  creates  it.
       From  then on, the list part will enforce type checking.	So even	if you
       retrieve	the SoNodeKitListPart with getPart(), you will not be able  to
       add  illegal  children.	(See  the SoNodeKitListPart reference page for
       more information). As an	example, the callbackList  part	 of  SoBaseKit
       has  an	SoSeparator  container and allows only SoCallback and SoEvent-
       Callback	nodes in the list. Children may	be added, retrieved,  and  re-
       moved  from an SoNodeKitListPart	node using methods that	parallel those
       of SoGroup. However, type-checking is strictly enforced.

       Note that, although all public parts are	leaves in the nodekit catalog,
       you  are	 free  to add children to them (assuming that they are groups,
       nodekits, or list parts). A part's status as a leaf in the catalog just
       means  that  the	nodekit	will not manage	the part's children. For exam-
       ple, SoWrapperKit has a part called contents with a part	type of	SoSep-
       arator. You can put whatever you	want underneath	the separator, as long
       as contents itself is an	SoSeparator.

       Thus, a nodekit only controls a section of the scene graph.  Above  and
       below that section, anything goes.

       However,	 when  nodekits	 are  nested, they effectively create a	larger
       `known' section of the scene graph. For example,	the appearance part of
       the  SoSeparatorKit  is	a leaf node in the SoSeparatorKit catalog. But
       appearance is in	turn an	SoAppearanceKit, containing parts such as  ma-
       terial  and  drawStyle. The two nodekits	combine	to make	an even	larger
       template, which the SoSeparatorKit can examine by looking at the	 cata-
       logs  for  both classes.	So an SoSeparatorKit can successfully return a
       part named "material"; first it finds (or creates) the appearance part,
       then it gets the	material by calling getPart() on the appearance.

       When  the catalog defines the listItemTypes of a	list part to be	nodek-
       its, the	name-able space	expands	further. For  example,	SoSeparatorKit
       has  a  part childList which permits only SoSeparatorKits, so each list
       element	  can	 be    further	  searched.	Hence	  the	  name
       "childList[0].childList[1].childList[2].material" is perfectly legal.

PARTS
     (SoNodeKitListPart)  callbackList
	  This is the only part	that the base class SoBaseKit creates. It is a
	  public part that is inherited	by all nodekits. It provides  an  easy
	  way  to  add	callbacks for a	nodekit	to use during action traversal
	  (e.g.	SoHandleEventAction). It is a list part	and may	contain	numer-
	  ous SoCallback and/or	SoEventCallback	nodes.

METHODS
			      SoBaseKit()
	  Constructor.

     static const SoNodekitCatalog *
			      getClassNodekitCatalog() const
	  Returns the SoNodekitCatalog for the class SoBaseKit.

     virtual const SoNodekitCatalog *
			      getNodekitCatalog() const
	  Returns  the	SoNodekitCatalog for this instance of SoBaseKit. While
	  each instance	of a given class creates its own distinct set of parts
	  (which  are  actual  nodes),	all  instances	share the same catalog
	  (which describes the parts but contains no actual node pointers).

     virtual   SoNode	*	  getPart(const	  SbName   &partName,	SbBool
				   makeIfNeeded)
	  Searches  the	nodekit	catalog	(and those of all nested nodekits) for
	  the part named partName. Returns a pointer to	the part if a match is
	  found,  the  part is public, and the part has	already	been built. If
	  no match is found, or	if the part is private,	NULL is	 returned.  If
	  partName  is	in  the	 catalog (or that of one of its	nested nodekit
	  parts),  but	the  part  has	not  been  built  yet,	the   argument
	  makeIfNeeded	determines  the	course of action. When makeIfNeeded is
	  FALSE, NULL is returned; when	makeIfNeeded is	TRUE,  getPart()  will
	  create  the  part (as	well as	any necessary intermediary parts), put
	  it in	the correct place, and return a	pointer	to the	newly  created
	  part.

	  Elements  of	list parts and parts within nested nodekits can	all be
	  retrieved with getPart() The full syntax for	legal  partName	 argu-
	  ments	is given below.

	  Part name BNF	notation:

	  partName = singleName	| compoundName

	  compoundName = singleName | compoundName.singleName

	  singleName = singlePartName |	singleListElementName

	  singlePartName = the name of any single part in the catalog (includ-
	  ing those that are lists or nodekits), or in the recursively	nested
	  catalogs of any of its parts.

	  singleListElementName	= singleListName[index]

	  singleListName  = the	name of	any single list-type part in the cata-
	  log, or in the recursively nested catalogs of	any of its parts.

	  index	= integer

	  Examples of valid part names are:

	  "transform",	  "appearance.material",     "childList[2].drawStyle",
	  "foot", "bird.leftLeg.foot", "octopus.leg[4].suctionCup[2].material"

     SbString		      getPartString(const SoBase *part)
	  Given	 a  node or a path to a	node, checks if	the part exists	in the
	  nodekit, in a	nested nodekit,	or an element of a list	part.  If  so,
	  returns  a  string  describing  the part name; otherwise, returns an
	  empty	string ("").

     virtual SoNodeKitPath *  createPathToPart(const SbName &partName,	SbBool
				   makeIfNeeded,  const	SoPath *pathToExtend =
				   NULL)
	  Returns a path that begins at	this nodekit  and  ends	 at  partName.
	  Searching for	the part is the	same as	in getPart(). NULL is returned
	  if partName cannot be	found, or if makeIfNeeded  is  FALSE  and  the
	  part is not yet built. If the	the part is retrieved and the argument
	  pathToExtend is NULL,	the path returned begins at this and  ends  at
	  partName. If pathToExtend is not NULL, the path created is a copy of
	  pathToExtend with entries appended all the way down to partName.  It
	  is  okay for pathToExtend to go beyond the nodekit; extra nodes will
	  be popped off	the tail before	continuing from	this down to partName.

     virtual SbBool	      setPart(const SbName &partName, SoNode *newPart)
	  Inserts the given node (not a	copy) as the  new  part	 specified  by
	  partName. See	getPart() for the syntax of partName. This method adds
	  any extra nodes needed to fit	the part into the  nodekit's  catalog.
	  For example, if you call:
	       mySepKit->setPart("childList[0]", myNewChild);
	  the  kit may need to create the part childList before	it can install
	  myNewChild. Run-time type checking verifies that the	node  type  of
	  newPart  matches  the	 type  called for by partName. For example, if
	  partName was a material for an SoSeparatorKit, but  newPart  was  an
	  SoTransform  node,  then  the	node would not be installed, and FALSE
	  would	be returned.

	  If newPart is	NULL, then the node specified by partName is  removed.
	  If this renders any private parts useless (as	occurs when you	remove
	  the last child of an SoGroup node), they will	also be	removed. Hence
	  nodekits do not retain unnecessary nodes.

	  TRUE is returned on success, and FALSE upon error.

     SbBool		      set(char *partName, char *parameters)
     SbBool		      set(char *nameValuePairs)
	  These	 functions  allow  field values	of parts (nodes) to be set. If
	  partName and parameters are used, then a single part is specified by
	  partName;  the  field	values are specified in	parameters. The	format
	  of paramaters	is the Inventor	File Format syntax.  For example,
	       mySepKit->set("material", "diffuseColor 1 0 0 shininess 0.6");
	  sets the part	material to the	values "diffuseColor 1 0  0  shininess
	  0.6".	 The  values  used in parameters must of course	be appropriate
	  for the node-type to which  partName	belongs.  In  this  case,  the
	  nodekit  SoSeparatorKit  has	a part named material which is of type
	  SoMaterial.

	  The nameValuePairs syntax can	be used	to set	the  field  values  in
	  several  different  parts simultaneously. In this case, the argument
	  string, nameValuePairs contains name-value pairs: "partName1	{  pa-
	  rameters1 } ... partNameN { parametersN }".

	  For example,
	       mySepKit->set("material { diffuseColor 1	1 1 }
			   transform { translation 4 3 .6 }");
	       mySepKit->set("childList[0].material { ambientColor .5 .5 .5 }");

     static SbBool	      isSearchingChildren()
     static void	      setSearchingChildren(SbBool newVal)
	  Sets and queries if nodekit children are searched during SoSearchAc-
	  tion traversal. By default, they are not.

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

MACROS
       SO_GET_PART(kit,	partName, partClass)
	  Calls	getPart() with makeIfNeeded set	to TRUE, then casts the	result
	  to  the  type	 partClass. Note that in the debug library, this macro
	  checks to see	if the part is of type partClass,  while  the  regular
	  library does no type checking.

     SO_CHECK_PART(kit,	partName, partClass)
	  Calls	 getPart(), but	with makeIfNeeded set to FALSE,	then casts the
	  result to the	type partClass.	Note that in the debug	library,  this
	  macro	checks to see if the part is of	type partClass,	while the reg-
	  ular library does no type checking.

ACTION BEHAVIOR
       SoGLRenderAction,  SoCallbackAction,   SoGetBoundingBoxAction,	SoHan-
       dleEventAction
	  Behaves like an SoGroup. Traverses each child	in order.

     SoRayPickAction
	  Traverses each child in order. Then, for any pick containing the kit
	  on its path, makes an	SoNodeKitDetail	as follows: Sets the "detailN-
	  odeKit"  (retrievable	 with  SoNodeKitDetail::getNodeKit())  to be a
	  pointer to itself. Sets the "detailPart" (retrievable	with  SoNodeK-
	  itDetail::getPart())	to  be	a  pointer to the kit's	leaf-most part
	  that lies on the pickPath. Sets  the	"detailPartName"  (retrievable
	  with	SoNodeKitDetail::getPartName())	 to  be	 the  partName of that
	  part,	as found in the	catalog.

	  Does not descend into	nested nodekits. Each nodekit along  the  path
	  is  the  "detailPart"	 in  its parent's detail. However, if the pick
	  path goes through a list part, a pointer to the child	 is  used  for
	  the "detailPart", and	"detailPartName" is of the form	"listName[i]".

     SoGetMatrixAction
	  Behaves  like	an SoGroup. Does nothing unless	the kit	is in the mid-
	  dle of the path chain	the action is being applied  to.  If  so,  the
	  children  up	to  and	 including the next node in the	chain are tra-
	  versed.

     SoSearchAction
	  First, searches itself like an SoNode. Then, checks the value	of is-
	  SearchingChildren().	If  TRUE,  traverses the children in order. If
	  FALSE, returns.

     SoWriteAction
	  Begins by writing out	regular	fields,	then writes out	the  parts.  A
	  nodekit  does	 not write out its parts the way an SoGroup writes out
	  its children.	Instead, it writes each	part  as  an  SoSFNode	field.
	  First	 the  partName	is  written, then the node being used for that
	  part.

	  To keep the files terse, nodekits write out as few parts  as	possi-
	  ble.	However, nodekits always write a part if another instance or a
	  path is writing it. If this is not the case, parts are left out  ac-
	  cording to the following rules:

	  [1]  NULL parts only write if	the catalog states they	are created by
	  default.

	  [2] Empty SoGroup and	SoSeparator nodes do not write.

	  [3] Non-leaf parts only write	if they	have non-default field values.

	  [4] List parts only write if they have children or if	the  container
	  node has non-default field values.

	  [5]  Nested  nodekit	parts  only write if they need to write	one or
	  more parts, or if they have non-default field	values.

CATALOG	PARTS
       +--------------------------------------------------------+
       |		       All parts			|
       |						NULL by	|
       |Part Name      Part Type	 Default Type	Default	|
       |							|
       |callbackList   NodeKitListPart	 --		  yes	|
       |							|
       +--------------------------------------------------------+
       +---------------------------------------------------------------+
       |      Extra information	for list parts from above table	       |
       |							       |
       |Part Name      Container Type	Permissible Types	       |
       |							       |
       |callbackList   Separator	Callback, EventCallback	       |
       |							       |
       +---------------------------------------------------------------+
FILE FORMAT/DEFAULTS
       BaseKit {
	  callbackList	NULL
     }

SEE ALSO
       SoAppearanceKit,	SoCameraKit, SoLightKit,  SoNodeKit,  SoNodeKitDetail,
       SoNodeKitListPart, SoNodeKitPath, SoNodekitCatalog, SoSceneKit, SoSepa-
       ratorKit, SoShapeKit, SoWrapperKit

							      SoBaseKit(3IV)()

NAME | INHERITS FROM | SYNOPSIS | DESCRIPTION | PARTS | METHODS | MACROS | ACTION BEHAVIOR | CATALOG PARTS | FILE FORMAT/DEFAULTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=SoBaseKit&sektion=3iv&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help