NodeData Class Reference

#include <c4d_nodedata.h>

Inheritance diagram for NodeData:

Detailed Description

A data class for creating node plugins.

Note

See the derived classes for creating standard node plugins, like objects, tags and materials.

Use RegisterNodePlugin() to register a node plugin.

Public Member Functions
	NodeData ()
GeListNode *	Get ()
const GeListNode *	Get () const
virtual Bool	Message (GeListNode *node, Int32 type, void *data)
virtual void	GetBubbleHelp (GeListNode *node, maxon::String &str)
virtual const BaseDocument *	GetDocument (const GeListNode *node) const
virtual maxon::Result< Bool >	GetBranchInfo (const GeListNode *node, const maxon::ValueReceiver< const BranchInfo & > &info, GETBRANCHINFO flags) const
virtual Bool	IsInstanceOf (const GeListNode *node, Int32 type) const
virtual Bool	IsDocumentRelated (const GeListNode *node, Bool &docrelated) const
virtual maxon::Result< Bool >	GetAccessedObjects (const BaseList2D *node, METHOD_ID method, AccessedObjectsCallback &access) const
virtual maxon::Result< maxon::GenericData >	GroupChanges (BaseList2D *node)
Public Member Functions inherited from BaseData
virtual	~BaseData ()
void	Destructor ()

Protected Attributes
GeListNode *	private_link

Init/Free
virtual Bool	Init (GeListNode *node, Bool isCloneInit)
virtual void	Free (GeListNode *node)

Read/Write/Copy
virtual Bool	Read (GeListNode *node, HyperFile *hf, Int32 level)
virtual Bool	Write (const GeListNode *node, HyperFile *hf) const
virtual Bool	CopyTo (NodeData *dest, const GeListNode *snode, GeListNode *dnode, COPYFLAGS flags, AliasTrans *trn) const

Description
virtual Bool	GetDDescription (const GeListNode *node, Description *description, DESCFLAGS_DESC &flags) const
virtual Bool	GetDParameter (const GeListNode *node, const DescID &id, GeData &t_data, DESCFLAGS_GET &flags) const
virtual Bool	SetDParameter (GeListNode *node, const DescID &id, const GeData &t_data, DESCFLAGS_SET &flags)
virtual Bool	GetDEnabling (const GeListNode *node, const DescID &id, const GeData &t_data, DESCFLAGS_ENABLE flags, const BaseContainer *itemdesc) const
virtual Bool	TranslateDescID (GeListNode *node, const DescID &id, DescID &res_id, C4DAtom *&res_at)

Constructor & Destructor Documentation

NodeData()

NodeData

(

)

Default constructor.

Since

R17.032

Member Function Documentation

Get() [1/2]

GeListNode* Get

(

)

Gets the GeListNode connected with the NodeData instance.

Returns

The list node connected with this instance. Cinema 4D owns the pointed node.

Get() [2/2]

const GeListNode* Get

(

)

const

Init()

virtual Bool Init ( GeListNode *  node, Bool  isCloneInit  )

virtual

Called when a new instance of the node type is being allocated.

The parameters of a node must be initialized in this method. NodeData::Init is being called frequently due to nodes being reallocated in the background by Cinema 4D. One should therefore be careful with carrying out computationally complex tasks in this function.

Bool BlinkerKey::Init(GeListNode* node, Bool isCloneInit)
{
  BaseKey* op = (BaseKey*) node;
  BaseContainer& data = op->GetDataInstanceRef();
 
  data.SetFloat(BLINKERKEY_NUMBER, 1.0);
  data.SetFloat(BLINKERKEY_STRENGTH, 1.0);
  data.SetBool(BLINKERKEY_SOFT, false);
 
  return true;
}

Note

If the node data class has a constructor it is called as usual before, but at that time there is no GeListNode link established.

Parameters

[in]

node

The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.

Returns

true if the node was initialized, otherwise false.

Reimplemented in GvOperatorData, and EffectorData.

Free()

virtual void Free ( GeListNode *  node )

virtual

Called when a node data instance is deallocated.
Deallocate member variables of the node data class here.

Note

If the node data class has a destructor it is called as usual after.

Parameters

[in]

node

The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.

Reimplemented in EffectorData.

Read()

virtual Bool Read ( GeListNode *  node, HyperFile *  hf, Int32  level  )

virtual

Called when a node is loaded from a file.

Warning

If at least one of Read(), Write() and CopyTo() is implemented, it is recommended to implement all three, otherwise data might be lost.

Read any member variable for the node data class. Example:

hf->ReadLong(&offset);
hf->ReadBool(&object_access);

For future extensions of the node data check the level and only read the appropriate values:

if (level >= 0)
{
  hf->ReadLong(&offset);
  hf->ReadBool(&object_access);
}
if (level >= 1)
{
  hf->ReadReal(&new_feature);
}

Note

Init() is called before Read().

Warning

It is recommended to store as much as possible in the node's container as Cinema 4D handles the reading of those values automatically. Only use member variables when necessary.

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in]	hf	The hyper file to read from. Cinema 4D owns the pointed hyper file.
[in]	level	The plugin level is similar to a version number. The default level is 0. Increase this for new revisions of a plugin to allow for forward and backward compatibility. As an example you may have updated a plugin. If you now need to write additional information for new member variables or changed types for old members increase the level. During loading either a 0 is passed (if the file was written by the old plugin) or 1 (if the file was written by the new plugin). This allows to easily write/read new values. For forward and backward compatibility to work any existing read order from a given level must not be changed. Cinema 4D skips any new settings automatically if they have not been read. level is only useful if variables are written/read in NodeData::Write/ NodeData::Read. If all values are stored in the node's container, you do not have to deal with the level.

Returns

true if the node was read, otherwise false.

Write()

virtual Bool Write ( const GeListNode *  node, HyperFile *  hf  ) const

virtual

Called when a node is saved to a file.

Warning

If at least one of Read(), Write() and CopyTo() is implemented, it is recommended to implement all three, otherwise data might be lost.

Write any member variable for the node data class.
Example:

hf->WriteLong(offset);
hf->WriteBool(object_access);

For future extensions of the node data make sure to introduce a new level when writing new values:

// Level 0
hf->WriteLong(offset);
hf->WriteBool(object_access);
 
// Level 1
hf->WriteReal(new_feature);

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in]	hf	The hyper file to write to. Cinema 4D owns the pointed hyper file.

Returns

true if the node was written, otherwise false.

CopyTo()

virtual Bool CopyTo ( NodeData *  dest, const GeListNode *  snode, GeListNode *  dnode, COPYFLAGS  flags, AliasTrans *  trn  ) const

virtual

Called when a node is duplicated.

Warning

If at least one of Read(), Write() and CopyTo() is implemented, it is recommended to implement all three, otherwise data might be lost.

Copy any member variable for the node plugin. Simply transfer from this to dest and/or snode to dnode:

MyNodeDataImplementation* destImpl = static_cast<MyNodeDataImplementation*>(dest);
destImpl->offset = offset;
destImpl->object_access = object_access;

Note

Init() is called for the destination node before.

Warning

It is recommended to store as much as possible in the node's container as Cinema 4D handles the copying of those values automatically. Only use member variables when necessary.

Parameters

[out]	dest	The destination node data. Cinema 4D owns the pointed node.
[in]	snode	The source node. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[out]	dnode	The destination node. Cinema 4D owns the pointed node.
[in]	flags	The copy flags: COPYFLAGS
[in]	trn	An alias translator for the operation. Can be nullptr. The sender owns the pointed alias translator.

Returns

true if the node was copied, otherwise false.

Reimplemented in EffectorData.

Message()

virtual Bool Message ( GeListNode *  node, Int32  type, void *  data  )

virtual

Called when a node receives messages.

See also

C4DAtom::Message

Note

Some notification messages are automatically passed along to branches: MSG_POINTS_CHANGED, MSG_POLYGONS_CHANGED and MSG_SEGMENTS_CHANGED. This is for convenience and historical reasons.

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in]	type	The message type: MSG
[in,out]	data	The message data. The sender owns the pointed data.

Returns

true or false depending on the message type.

Reimplemented in EffectorData.

GetBubbleHelp()

virtual void GetBubbleHelp ( GeListNode *  node, maxon::String &  str  )

virtual

Called to create a contextual bubble help and status bar information for the node.

Note

When dealing with strings it is advised to use the string resources files and the GeLoadString function.
This keeps the plugin easy to localize for any language to support and makes full use of the language features of Cinema 4D.

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in]	str	The bubble help string.

GetDocument()

virtual const BaseDocument* GetDocument ( const GeListNode *  node ) const

virtual

Called to tell Cinema 4D how to retrieve the document for the node.
Any call to GeListNode::GetDocument() ends up here.

Note

Useful if new BaseList elements are defined.

Parameters

[in]

node

The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.

Returns

The document for the node.

GetBranchInfo()

virtual maxon::Result<Bool> GetBranchInfo ( const GeListNode *  node, const maxon::ValueReceiver< const BranchInfo & > &  info, GETBRANCHINFO  flags  ) const

virtual

Called to specify that the node acts as a container of other nodes.
This is for instance used by the animator module to make sure that the nodes are animated. Simply fill in the passed array:

info[0].head = myHead;
info[0].name ="MyName";
...
info[1].head = myOtherHead;
...
return 2; // 2 elements filled

Note

For the standard node types, for example objects, it is not needed to override GetBranchInfo. Cinema 4D already knows that objects contain tags.

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[out]	info	An array of max BranchInfo structures to fill in. Cinema 4D owns the pointed array.
[in]	flags	The get branch info flags: GETBRANCHINFO

Returns

The number of BranchInfo elements filled in the info array.

IsInstanceOf()

virtual Bool IsInstanceOf ( const GeListNode *  node, Int32  type  ) const

virtual

Called to check if the node is an instance of a base type.

See also

C4DAtom::IsInstanceOf.

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in]	type	The type to check.

Returns

true if the node is an instance of the given type, otherwise false.

Reimplemented in EffectorData.

GetDDescription()

virtual Bool GetDDescription ( const GeListNode *  node, Description *  description, DESCFLAGS_DESC &  flags  ) const

virtual

Called to add parameters to the description for the node.
Modify the passed description as needed, set the appropriate flags. Make sure to include a call to the parent at the end.

Note

{The SUPER syntax is only available when the INSTANCEOF macro has been invoked for the NodeData which contains the NodeData::GetDDescription implementation.}

return SUPER::GetDDescription(data, description, flags, parentdescription);

If only a description resource is used it is not needed to overload GetDDescription.

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in,out]	description	The node's description to add the parameters to. Cinema 4D owns the pointed description.
[in,out]	flags	The flags for the description operation: DESCFLAGS_DESC

Returns

true if successful, otherwise false. It is recommended to include a call to the parent function as last return.

Reimplemented in GvOperatorData, and EffectorData.

GetDParameter()

virtual Bool GetDParameter ( const GeListNode *  node, const DescID &  id, GeData &  t_data, DESCFLAGS_GET &  flags  ) const

virtual

Called to override the reading of description parameters.
Necessary for parameters that are not simply stored in the node's container, e.g. the global position of an object.
Modify the passed t_data if the right id is provided, and set the appropriate flags. Make sure to include a call to the parent at the end.

Note

{The SUPER syntax is only available when the INSTANCEOF macro has been invoked for the NodeData which contains the NodeData::GetDParameter implementation.}

return SUPER::GetDParameter(data, id, t_data, flags);

If only a description resource is used it is not needed to overload GetDParameter.

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in]	id	The ID of the parameter.
[out]	t_data	The parameter data to return. Cinema 4D owns the pointed data.
[in,out]	flags	The flags for the description operation: DESCFLAGS_GET

Returns

true if successful, otherwise false. It is recommended to include a call to the parent function as last return.

Reimplemented in GvOperatorData.

SetDParameter()

virtual Bool SetDParameter ( GeListNode *  node, const DescID &  id, const GeData &  t_data, DESCFLAGS_SET &  flags  )

virtual

Called to override the writing of parameters.

Read the passed t_data if the right id was provided, store the data, and set the appropriate flags. Make sure to include a call to the parent at the end.

Note

{The SUPER syntax is only available when the INSTANCEOF macro has been invoked for the NodeData which contains the NodeData::SetDParameter implementation.}

class MyObjectData : public ObjectData
{
  INSTANCEOF(MyObjectData, ObjectData)
  // ...
}
 
Bool MyObjectData::SetDParameter(GeListNode* node, const DescID& id, const GeData& t_data, DESCFLAGS_SET& flags)
{
  // ...
  return SUPER::SetDParameter(node, id, t_data, flags);
}

If only a description resource is used it is not needed to overload SetDParameter.

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in]	id	The ID of the parameter.
[in]	t_data	The parameter data to set. Cinema 4D owns the pointed data.
[in,out]	flags	The flags for the description operation: DESCFLAGS_SET

Returns

true if successful, otherwise false. It is recommended to include a call to the parent function as last return.

Reimplemented in GvOperatorData.

GetDEnabling()

virtual Bool GetDEnabling ( const GeListNode *  node, const DescID &  id, const GeData &  t_data, DESCFLAGS_ENABLE  flags, const BaseContainer *  itemdesc  ) const

virtual

Called to decide which description parameters should be enabled or disabled.
Can be used both for parameters that are stored in the node's description and for dynamic parameters.
Read the passed t_data if the right id was provided, and return true to enable the parameter or false to disable it. Make sure to include a call to the parent at the end.

Note

{The SUPER syntax is only available when the INSTANCEOF macro has been invoked for the NodeData which contains the NodeData::GetDEnabling implementation.}

return SUPER::GetDEnabling(data, id, t_data, flags, itemdesc);

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in]	id	The ID of the parameter.
[in]	t_data	The parameter data. Cinema 4D owns the pointed data.
[in]	flags	Not used.
[in]	itemdesc	The parameter's description, encoded to a container as described in Description.

Returns

true if the parameter should be enabled, otherwise false. It is recommended to include a call to the parent function as last return.

Reimplemented in GvOperatorData, and EffectorData.

TranslateDescID()

virtual Bool TranslateDescID ( GeListNode *  node, const DescID &  id, DescID &  res_id, C4DAtom *&  res_at  )

virtual

Called by the Attribute Manager for every object and every description ID.
Gives a node data the opportunity to route a description ID in the description of a GeListNode to another one.
For example used for tags that are embedded in an object description so that the keyframer for a tag property creates the track on the tag and not on the object.

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in]	id	The source description ID.
[out]	res_id	Assign the target description ID.
[out]	res_at	Assign the target object.

Returns

true if successful, otherwise false.

IsDocumentRelated()

virtual Bool IsDocumentRelated ( const GeListNode *  node, Bool &  docrelated  ) const

virtual

Called by the Attribute Manager for correct undo handling.

Warning

Should not be overridden by regular plugins and should be used with extra care. If false is returned no undo is possible.

Parameters

[in]	node	The GeListNode connected with the NodeData instance. Equal to Get(). Provided for speed and convenience. Cinema 4D owns the pointed node.
[in]	docrelated	Assign true if the node is part of the document, otherwise false.

Returns

true if successful, otherwise false.

Reimplemented in SculptBrushModifierData.

GetAccessedObjects()

virtual maxon::Result<Bool> GetAccessedObjects ( const BaseList2D *  node, METHOD_ID  method, AccessedObjectsCallback &  access  ) const

virtual

Reimplemented in EffectorData.

GroupChanges()

virtual maxon::Result<maxon::GenericData> GroupChanges ( BaseList2D *  node )

virtual

Called to group subsequent changes (e.g., calls to SetParameter). The grouping ends when the lifetime of the returned GenericData ends. You can override this function if your code has to do some costly update and you want to prevent this for intermediate changes.

Returns

An object to control the lifetime of the grouping.

Member Data Documentation

private_link

GeListNode* private_link

protected