#include <opennurbs_userdata.h>

Inheritance diagram for ON_UserData:

Public Member Functions
	ON_UserData ()

	ON_UserData (const ON_UserData &)

	~ON_UserData ()

virtual bool	Archive () const
	If Archive() returns true, m_application_uuid is not nil, and the virtual Read() and Write() are functions are overridden, then this user data will be written to and read from 3dm archives. More...

virtual bool	DeleteAfterRead (const class ON_BinaryArchive &archive, class ON_Object *parent_object) const
	DeleteAfterRead() is used when opennurbs is reading earlier versions of 3dm archives that used some type of user data that has since become obsolete. More...

virtual bool	DeleteAfterWrite (const class ON_BinaryArchive &archive, const class ON_Object *parent_object) const
	DeleteAfterWrite() is used when opennurbs is writing earlier versions of 3dm archives that used some type of user data that has since become obsolete. More...

void	Dump (ON_TextLog &text_log) const override
	Overrides virtual ON_Object::Dump(). Prints class name, description, and uuid. More...

virtual bool	GetDescription (ON_wString &description)

bool	IsUnknownUserData () const

bool	IsValid (class ON_TextLog *text_log=nullptr) const override
	Tests an object to see if its data members are correctly initialized. More...

ON_UserData *	Next () const

ON_UserData &	operator= (const ON_UserData &)

ON_Object *	Owner () const
	Returns object that owns the user data. More...

unsigned int	SizeOf () const override
	Overrides virtual ON_Object::SizeOf(). More...

virtual bool	Transform (const ON_Xform &)
	If Transform() return false, then the userdata is destroyed when its parent object is transformed. The default Transform() updates m_userdata_xform and returns true. Carefully read the comments above m_userdata_xform More...

ON_UUID	UserDataClassUuid () const

virtual bool	WriteToArchive (const class ON_BinaryArchive &archive, const class ON_Object *parent_object) const
	If WriteToArchive() returns true, m_application_uuid is not nil, and the virtual Read() and Write() are functions are overridden, then this user data will be written to and read from the identified archive. More...

Public Member Functions inherited from ON_Object
	ON_Object () ON_NOEXCEPT

	ON_Object (const ON_Object &)

virtual	~ON_Object ()

virtual ON_AggregateComponentStatus	AggregateComponentStatus () const
	Call whenever a component status setting is modifed by directly changing it on a component in a way that will result in any saved information about the parent object's aggretate component status becoming invalid. More...

bool	AttachUserData (class ON_UserData *pUserData)
	Attach user data to an object. More...

unsigned int	ClearAllComponentStates () const
	Set all active level component states to ON_ComponentStatus::NoneSet. More...

virtual unsigned int	ClearComponentStates (ON_ComponentStatus states_to_clear) const
	Clear the specified states on every component. More...

virtual unsigned int	ClearComponentStates (ON_COMPONENT_INDEX component_index, ON_ComponentStatus states_to_clear) const
	Clear states on an individual component. More...

unsigned int	CopyUserData (const ON_Object &source_object, ON_UUID source_userdata_item_id, ON_Object::UserDataConflictResolution userdata_conflict_resolution)
	Expert user tool that copies user data items with positive values of ON_UserData.m_userdata_copycount from source_object to "this. More...

void	CopyUserData (const ON_Object &source_object)
	Calls CopyUserData(source_object,ON_Object::UserDataConflictResolution::source_object). More...

virtual ON__UINT32	DataCRC (ON__UINT32 current_remainder) const
	Returns a CRC calculated from the information that defines the object. This CRC can be used as a quick way to see if two objects are not identical. More...

virtual bool	DeleteComponents (const ON_COMPONENT_INDEX *ci_list, size_t ci_count)
	Delete the portions of the object identified in ci_list[]. More...

virtual void	DestroyRuntimeCache (bool bDelete=true)
	Expert user function. If you are using openNURBS in its default configuration to read and write 3dm archives, you never need to call this function. Many objects employ lazy creation of (runtime) caches that save information to help speed geometric calculations. This function will destroy all runtime information. More...

bool	DetachUserData (class ON_UserData *pUserData)
	Remove user data from an object. More...

void	EmergencyDestroy ()
	Sets m_user_data_list = 0. More...

class ON_UserData *	FirstUserData () const
	User data is stored as a linked list of ON_UserData classes. FirstUserData gets the first item in the linked list. This is the most recent item attached using AttachUserData(). Remark: To iterate through all the user data on an object, call FirstUserData() and then use ON_UserData::Next() to traverse the list. More...

virtual unsigned int	GetComponentsWithSetStates (ON_ComponentStatus states_filter, bool bAllEqualStates, ON_SimpleArray< ON_COMPONENT_INDEX > &components) const

class ON_UserData *	GetUserData (const ON_UUID &userdata_uuid) const
	Get a pointer to user data. More...

bool	GetUserString (const wchar_t *key, ON_wString &string_value) const
	Get user string from the object. More...

int	GetUserStringKeys (ON_ClassArray< ON_wString > &user_string_keys) const
	Get a list of all user string keys on the object. More...

int	GetUserStrings (ON_ClassArray< ON_UserString > &user_strings) const
	Get a list of all user strings on the object. More...

bool	IsKindOf (const ON_ClassId *pClassId) const
	Low level tool to test if an object is derived from a specified class. More...

virtual void	MarkAggregateComponentStatusAsNotCurrent () const
	Call whenever a component status setting is modifed by directly changing it on a component in a way that will result in any saved information about the parent object's aggretate component status becoming invalid. More...

virtual void	MemoryRelocate ()
	The MemoryRelocate() function is called when an object's location in memory is changed. For example, if an object resides in a chunk of memory that is grown by calling a realloc that has to allocate a new chunk and copy the contents of the old chunk to the new chunk, then the location of the object's memory changes. In practice this happens when classes derived from ON_Object are stored in dynamic arrays, like the default implementation of ON_ObjectArray<>'s that use realloc to grow the dynamic array. More...

virtual ON_UUID	ModelObjectId () const
	All objects in an opennurbs model have an id ( ON_Layer.m_layer_id, ON_Font.m_font_id, ON_Material.m_material_id, ON_3dmObjectAttributes.m_uuid ). More...

unsigned int	MoveUserData (ON_Object &source_object, ON_UUID source_userdata_item_id, ON_Object::UserDataConflictResolution userdata_conflict_resolution, bool bDeleteAllSourceItems)
	Expert user tool that moves user data items from source_object to "this. More...

void	MoveUserData (ON_Object &source_object)
	Calls MoveUserData(source_object,ON_Object::UserDataConflictResolution::source_object,true). More...

virtual ON::object_type	ObjectType () const
	Useful for switch statements that need to differentiate between basic object types like points, curves, surfaces, and so on. More...

ON_Object &	operator= (const ON_Object &)

void	PurgeUserData ()
	PurgeUserData() removes all user data from object. More...

virtual bool	Read (ON_BinaryArchive &binary_archive)
	Low level archive writing tool used by ON_BinaryArchive::ReadObject(). More...

virtual unsigned int	SetComponentStates (ON_COMPONENT_INDEX component_index, ON_ComponentStatus states_to_set) const
	Set states on an individual component. More...

virtual unsigned int	SetComponentStatus (ON_COMPONENT_INDEX component_index, ON_ComponentStatus status_to_copy) const
	Copy status settings to an individual component. More...

bool	SetUserString (const wchar_t key, const wchar_t string_value)
	Attach a user string to the object. This information will perisist through copy construction, operator=, and file IO. More...

int	SetUserStrings (int count, const ON_UserString *user_strings, bool bReplace)
	Append entries to the user string list More...

void	TransformUserData (const class ON_Xform &xform)
	Objects derived from ON_Geometry must call TransformUserData() in their Transform() member function. More...

virtual bool	UpdateReferencedComponents (const class ON_ComponentManifest &source_manifest, const class ON_ComponentManifest &destination_manifest, const class ON_ManifestMap &manifest_map)
	Uses the destination_manifest to update references to other components. This is typically done when a component's references came from a "source" context and are being updated to the "destination" context. For example, inserting one model into another when index, id, and name conflicts need to be resolved at the time of insertion. More...

int	UserStringCount () const

virtual bool	Write (ON_BinaryArchive &binary_archive) const
	Low level archive writing tool used by ON_BinaryArchive::WriteObject(). More...

Public Attributes
ON_UUID	m_application_uuid
	This uuid is used to identify the application that created this piece of user data. In the case of Rhino, this is the id of the plug-in that created the user data. User data with a nil application id will not be saved in 3dm archives. More...

unsigned int	m_userdata_copycount

ON_UUID	m_userdata_uuid
	This uuid is the value that must be passed to ON_Object::GetUserData() to retrieve this piece of user data. More...

ON_Xform	m_userdata_xform

Friends
int	ON_BinaryArchive::ReadObject (ON_Object **)

bool	ON_BinaryArchive::ReadObjectUserData (ON_Object &)

bool	ON_BinaryArchive::WriteObject (const ON_Object &)

bool	ON_BinaryArchive::WriteObjectUserData (const ON_Object &)

class	ON_Object

Additional Inherited Members
Public Types inherited from ON_Object
enum	UserDataConflictResolution : unsigned char { UserDataConflictResolution::destination_object = 0, UserDataConflictResolution::source_object = 1, UserDataConflictResolution::source_copycount_gt = 2, UserDataConflictResolution::source_copycount_ge = 3, UserDataConflictResolution::destination_copycount_gt = 4, UserDataConflictResolution::destination_copycount_ge = 5, UserDataConflictResolution::delete_item = 6 }
	When a userdata item is copied or moved from a source object to a destination object, the ON_Object::UserDataConflictResolution enum values specify how conficts are resolved. Remark: A userdata item "conflict" occurs when both the destination and source object have a user data item with the same value of ON_UserData::m_userdata_uuid. More...

Constructor & Destructor Documentation

◆ ON_UserData() [1/2]

ON_UserData::ON_UserData ( )

◆ ON_UserData() [2/2]

ON_UserData::ON_UserData ( const ON_UserData & )

◆ ~ON_UserData()

ON_UserData::~ON_UserData ( )

Member Function Documentation

◆ Archive()

virtual bool ON_UserData::Archive ( ) const

virtual

If Archive() returns true, m_application_uuid is not nil, and the virtual Read() and Write() are functions are overridden, then this user data will be written to and read from 3dm archives.

Returns

true if user data should be saved in binary archives. false if the user data should not be saved in binary archives.

The default implementation returns false. If you override ON_UserData::Archive so that it returns true, then your constructor must set m_application_uuid, you must override the virtual ON_Object::Read and ON_Object::Write functions and you must CAREFULLY TEST your code.

ON_UserData requires expert programming and testing skills.

If you need to know more details about the archive or parent object to determine if the userdata should be saved, then override WriteToArchive().

YOU SHOULD READ AND UNDERSTAND EVERY COMMENT IN THIS HEADER FILE IN BEFORE ATTEMPTING TO USE ON_UserData.

Reimplemented in ON_UserStringList, and ON_UnknownUserData.

◆ DeleteAfterRead()

virtual bool ON_UserData::DeleteAfterRead	(	const class ON_BinaryArchive &	archive,
		class ON_Object *	parent_object
	)		const

virtual

DeleteAfterRead() is used when opennurbs is reading earlier versions of 3dm archives that used some type of user data that has since become obsolete.

Parameters

archive	[in] archive that was read from. If needed, you can inspect the version of 3dm archive this is being saved and other information that you may need to determine the approprite return value.
parent_object	[in] If needed, you can inspect the parent object to determine the approprite return value.

Returns: True if the user data should be deleted because the information it contains has been added to the parent object using the methods that are current.

◆ DeleteAfterWrite()

virtual bool ON_UserData::DeleteAfterWrite	(	const class ON_BinaryArchive &	archive,
		const class ON_Object *	parent_object
	)		const

virtual

DeleteAfterWrite() is used when opennurbs is writing earlier versions of 3dm archives that used some type of user data that has since become obsolete.

Parameters

archive	[in] archive that will be written to. If needed, you can inspect the version of 3dm archive this is being saved and other information that you may need to determine the approprite return value.
parent_object	[in] If needed, you can inspect the parent object to determine the approprite return value.

Returns

True if the user data should be written the next time the parent object is saved to a 3dm archive and then deleted.

Typically, DeleteAfterWrite() is used in the situation where 1) User data was used to add information to an opennurbs class whose data fields could not be modified because the SDK was fixed at the time. 2) Once the class data fields could be modified, the new data fields were added to the class and the user data from step 1 became obsolete. 3) The class's Write function is called and the value of ON_BinaryArchive::Archive3dmVersion() corresponds to the version of the 3dm archive that was being saved in step 1. The write function fills in and attaches the obsolete user data to the class. When ON_BinaryArchive::WriteObject() writes the obsolete user data to the earlier version file, it then deletes it.

◆ Dump()

void ON_UserData::Dump ( ON_TextLog & text_log ) const

overridevirtual

Overrides virtual ON_Object::Dump(). Prints class name, description, and uuid.

Parameters

text_log [in] Information is sent to this text log.

Reimplemented from ON_Object.

Reimplemented in ON_UserStringList, and ON_UnknownUserData.

◆ GetDescription()

virtual bool ON_UserData::GetDescription ( ON_wString & description )

virtual

Parameters

description [out] description of user data shown in object properties dump.

Returns: True if user data class is ready.

Reimplemented in ON_UserStringList, ON_RdkMaterialInstanceIdObsoleteUserData, and ON_UnknownUserData.

◆ IsUnknownUserData()

bool ON_UserData::IsUnknownUserData ( ) const

◆ IsValid()

bool ON_UserData::IsValid ( class ON_TextLog * text_log = nullptr ) const

overridevirtual

Tests an object to see if its data members are correctly initialized.

Parameters

text_log	[in] if the object is not valid and text_log is not nullptr, then a brief englis description of the reason the object is not valid is appened to the log. The information appended to text_log is suitable for
low	level debugging purposes by programmers and is not intended to be useful as a high level user interface tool.

Returns: table true object is valid false object is invalid, uninitialized, etc.

Reimplemented from ON_Object.

Reimplemented in ON_UnknownUserData.

◆ Next()

ON_UserData* ON_UserData::Next ( ) const

◆ operator=()

ON_UserData& ON_UserData::operator= ( const ON_UserData & )

◆ Owner()

ON_Object* ON_UserData::Owner ( ) const

Returns object that owns the user data.

◆ SizeOf()

unsigned int ON_UserData::SizeOf ( ) const

overridevirtual

Overrides virtual ON_Object::SizeOf().

Returns: Approximate number of bytes this class uses.

Reimplemented from ON_Object.

Reimplemented in ON_UserStringList, and ON_UnknownUserData.

◆ Transform()

virtual bool ON_UserData::Transform ( const ON_Xform & )

virtual

If Transform() return false, then the userdata is destroyed when its parent object is transformed. The default Transform() updates m_userdata_xform and returns true. Carefully read the comments above m_userdata_xform

◆ UserDataClassUuid()

ON_UUID ON_UserData::UserDataClassUuid ( ) const

◆ WriteToArchive()

virtual bool ON_UserData::WriteToArchive	(	const class ON_BinaryArchive &	archive,
		const class ON_Object *	parent_object
	)		const

virtual

If WriteToArchive() returns true, m_application_uuid is not nil, and the virtual Read() and Write() are functions are overridden, then this user data will be written to and read from the identified archive.

Parameters

archive	[in] The archive being written to. Typically, you will test archive.Archive3dmVersion() to deterime if your userdata should be saved.
parent_object	[in] The object managing this userdata.

Returns

true if user data should be saved in the binary archives. false if the user data should not be saved in binary archives.

The default implementation calls the legacy Archive() function.

Reimplemented in ON_RdkMaterialInstanceIdObsoleteUserData.

Friends And Related Function Documentation

◆ ON_BinaryArchive::ReadObject

int ON_BinaryArchive::ReadObject ( ON_Object ** )

friend

◆ ON_BinaryArchive::ReadObjectUserData

bool ON_BinaryArchive::ReadObjectUserData ( ON_Object & )

friend

◆ ON_BinaryArchive::WriteObject

bool ON_BinaryArchive::WriteObject ( const ON_Object & )

friend

◆ ON_BinaryArchive::WriteObjectUserData

bool ON_BinaryArchive::WriteObjectUserData ( const ON_Object & )

friend

◆ ON_Object

friend class ON_Object

friend

Member Data Documentation

◆ m_application_uuid

ON_UUID ON_UserData::m_application_uuid

This uuid is used to identify the application that created this piece of user data. In the case of Rhino, this is the id of the plug-in that created the user data. User data with a nil application id will not be saved in 3dm archives.

◆ m_userdata_copycount

unsigned int ON_UserData::m_userdata_copycount

◆ m_userdata_uuid

ON_UUID ON_UserData::m_userdata_uuid

This uuid is the value that must be passed to ON_Object::GetUserData() to retrieve this piece of user data.

◆ m_userdata_xform

ON_Xform ON_UserData::m_userdata_xform

Public Member Functions

Public Attributes

Friends

Additional Inherited Members

Constructor & Destructor Documentation

◆ ON_UserData() [1/2]

◆ ON_UserData() [2/2]

◆ ~ON_UserData()

Member Function Documentation

◆ Archive()

◆ DeleteAfterRead()

◆ DeleteAfterWrite()

◆ Dump()

◆ GetDescription()

◆ IsUnknownUserData()

◆ IsValid()

◆ Next()

◆ operator=()

◆ Owner()

◆ SizeOf()

◆ Transform()

◆ UserDataClassUuid()

◆ WriteToArchive()

Friends And Related Function Documentation

◆ ON_BinaryArchive::ReadObject

◆ ON_BinaryArchive::ReadObjectUserData

◆ ON_BinaryArchive::WriteObject

◆ ON_BinaryArchive::WriteObjectUserData

◆ ON_Object

Member Data Documentation

◆ m_application_uuid

◆ m_userdata_copycount

◆ m_userdata_uuid

◆ m_userdata_xform