Rhino C++ API  8.5
Public Member Functions | Public Attributes | Friends | List of all members
ON_UserData Class Reference

#include <opennurbs_userdata.h>

Inheritance diagram for ON_UserData:
ON_Object CRhinoPolylineOnMeshUserData CUD_source_index ON_ObsoleteUserData ON_UnknownUserData ON_UserStringList ON_XMLUserData ON_RdkMaterialInstanceIdObsoleteUserData ON_CurvePipingUserData ON_DisplacementUserData ON_EdgeSofteningUserData ON_RdkUserData ON_ShutLiningUserData ON_ThickeningUserData

Public Member Functions

 ON_UserData ()
 
 ON_UserData (const ON_UserData &)
 
 ~ON_UserData ()
 
virtual bool Archive () const
 
virtual bool DeleteAfterRead (const class ON_BinaryArchive &archive, class ON_Object *parent_object) const
 
virtual bool DeleteAfterWrite (const class ON_BinaryArchive &archive, const class ON_Object *parent_object) const
 
void Dump (ON_TextLog &text_log) const override
 
virtual bool GetDescription (ON_wString &description)
 
bool IsUnknownUserData () const
 
bool IsValid (class ON_TextLog *text_log=nullptr) const override
 
ON_UserDataNext () const
 
ON_UserDataoperator= (const ON_UserData &)
 
ON_ObjectOwner () const
 Returns object that owns the user data. More...
 
unsigned int SizeOf () const override
 
virtual bool Transform (const ON_Xform &)
 
ON_UUID UserDataClassUuid () const
 
virtual bool WriteToArchive (const class ON_BinaryArchive &archive, const class ON_Object *parent_object) const
 
- Public Member Functions inherited from ON_Object
 ON_Object () ON_NOEXCEPT
 
 ON_Object (const ON_Object &)
 
virtual ~ON_Object ()
 
virtual ON_AggregateComponentStatus AggregateComponentStatus () const
 
bool AttachUserData (class ON_UserData *pUserData)
 
unsigned int ClearAllComponentStates () const
 
virtual unsigned int ClearComponentStates (ON_COMPONENT_INDEX component_index, ON_ComponentStatus states_to_clear) const
 
virtual unsigned int ClearComponentStates (ON_ComponentStatus states_to_clear) const
 
void CopyUserData (const ON_Object &source_object)
 
unsigned int CopyUserData (const ON_Object &source_object, ON_UUID source_userdata_item_id, ON_Object::UserDataConflictResolution userdata_conflict_resolution)
 
virtual ON__UINT32 DataCRC (ON__UINT32 current_remainder) const
 
virtual bool DeleteComponents (const ON_COMPONENT_INDEX *ci_list, size_t ci_count)
 
virtual void DestroyRuntimeCache (bool bDelete=true)
 
bool DetachUserData (class ON_UserData *pUserData)
 
void EmergencyDestroy ()
 
class ON_UserDataFirstUserData () const
 
virtual unsigned int GetComponentsWithSetStates (ON_ComponentStatus states_filter, bool bAllEqualStates, ON_SimpleArray< ON_COMPONENT_INDEX > &components) const
 
class ON_UserDataGetUserData (const ON_UUID &userdata_uuid) const
 
bool GetUserString (const wchar_t *key, ON_wString &string_value) const
 
int GetUserStringKeys (ON_ClassArray< ON_wString > &user_string_keys) const
 
int GetUserStrings (ON_ClassArray< ON_UserString > &user_strings) const
 
bool IsCorrupt (bool bRepair, bool bSilentError, class ON_TextLog *text_log) const
 
bool IsKindOf (const ON_ClassId *pClassId) const
 
virtual void MarkAggregateComponentStatusAsNotCurrent () const
 
virtual void MemoryRelocate ()
 
virtual ON_UUID ModelObjectId () const
 
void MoveUserData (ON_Object &source_object)
 
unsigned int MoveUserData (ON_Object &source_object, ON_UUID source_userdata_item_id, ON_Object::UserDataConflictResolution userdata_conflict_resolution, bool bDeleteAllSourceItems)
 
virtual ON::object_type ObjectType () const
 
ON_Objectoperator= (const ON_Object &)
 
void PurgeUserData ()
 
virtual bool Read (ON_BinaryArchive &binary_archive)
 
virtual unsigned int SetComponentStates (ON_COMPONENT_INDEX component_index, ON_ComponentStatus states_to_set) const
 
virtual unsigned int SetComponentStatus (ON_COMPONENT_INDEX component_index, ON_ComponentStatus status_to_copy) const
 
bool SetUserString (const wchar_t *key, const wchar_t *string_value)
 
int SetUserStrings (int count, const ON_UserString *user_strings, bool bReplace)
 
bool ThisIsNullptr (bool bSilentError) const
 
void TransformUserData (const class ON_Xform &xform)
 
virtual bool UpdateReferencedComponents (const class ON_ComponentManifest &source_manifest, const class ON_ComponentManifest &destination_manifest, const class ON_ManifestMap &manifest_map)
 
int UserStringCount () const
 
virtual bool Write (ON_BinaryArchive &binary_archive) const
 

Public Attributes

ON_UUID m_application_uuid
 
unsigned int m_userdata_copycount
 
ON_UUID m_userdata_uuid
 
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
 < don't look and don't touch - these may change More...
 

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
}
 

Detailed Description

Copyright (c) 1993-2022 Robert McNeel & Associates. All rights reserved. OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert McNeel & Associates.

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF MERCHANTABILITY ARE HEREBY DISCLAIMED.

For complete openNURBS copyright information see http://www.opennurbs.org.

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 ( )

The destructor automatically removes the user data from ON_Object::m_userdata_list.

Member Function Documentation

◆ Archive()

virtual bool ON_UserData::Archive ( ) const
virtual

Description: 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.

Remarks: 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_XMLUserData, ON_UserStringList, ON_UnknownUserData, and CRhinoPolylineOnMeshUserData.

◆ DeleteAfterRead()

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

Description: 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 appropriate return value. parent_object - [in] If needed, you can inspect the parent object to determine the appropriate 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

Description: 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 appropriate return value. parent_object - [in] If needed, you can inspect the parent object to determine the appropriate 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.

Remarks: 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

Description: Overrides virtual ON_Object::Dump(). Prints class name, description, and uuid. Parameters: text_log - [in] Information is sent to this text log. Remarks:

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_RdkUserData, ON_ShutLiningUserData, ON_CurvePipingUserData, ON_ThickeningUserData, ON_EdgeSofteningUserData, ON_DisplacementUserData, ON_UserStringList, ON_RdkMaterialInstanceIdObsoleteUserData, ON_UnknownUserData, and CRhinoPolylineOnMeshUserData.

◆ IsUnknownUserData()

bool ON_UserData::IsUnknownUserData ( ) const

Returns true if the user data is anonymous. This happens when the user data class is not defined at the time the user data is read from an archive. For example, if a class derived from ON_UserData is defined in application A but is not defined in application B, then the class can be defined when an archive is written by A but not exist when an archive is read by B. In this case, the user data is not lost, it is just read as ON_UnknownUserData by application B. If application B saves the parent object in an archive, the unknown user data is resaved in a form that can be read by application A.

◆ IsValid()

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

Description: 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: @untitled 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

Used for traversing list of user data attached to an object.

◆ 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

Description: 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

Description: 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

Reimplemented in ON_RdkUserData, ON_ShutLiningUserData, ON_CurvePipingUserData, ON_ThickeningUserData, and ON_DisplacementUserData.

◆ UserDataClassUuid()

ON_UUID ON_UserData::UserDataClassUuid ( ) const

Returns the class id which is not necessarily the same as m_userdata_uuid.

◆ WriteToArchive()

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

Description: 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.

Remarks: The default implementation calls the legacy Archive() function.

Reimplemented in ON_RdkMaterialInstanceIdObsoleteUserData.

Friends And Related Function Documentation

◆ ON_BinaryArchive::ReadObject

◆ ON_BinaryArchive::ReadObjectUserData

◆ ON_BinaryArchive::WriteObject

bool ON_BinaryArchive::WriteObject ( const ON_Object )
friend

◆ ON_BinaryArchive::WriteObjectUserData

◆ ON_Object

friend class ON_Object
friend

< don't look and don't touch - these may change

Member Data Documentation

◆ m_application_uuid

ON_UUID ON_UserData::m_application_uuid

Description: 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

If m_userdata_copycount is 0, user data is not copied when object is copied. If > 0, user data is copied and m_copycount is incremented when parent object is copied. The user data's operator=() is used to copy.
The default ON_UserData::ON_UserData() constructor sets m_userdata_copycount to zero.

◆ m_userdata_uuid

ON_UUID ON_UserData::m_userdata_uuid

Description: 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

Updated if user data is attached to a piece of geometry that is transformed and the virtual ON_UserData::Transform() is not overridden. If you override ON_UserData::Transform() and want m_userdata_xform to be updated, then call the ON_UserData::Transform() in your override. The default constructor sets m_userdata_xform to the identity.