Page MenuHome
Differential D6807 Diff 21591 extern/opennurbs/opennurbs_userdata.h

Changeset View

Standalone View

View Options

extern/opennurbs/opennurbs_userdata.h

  • This file was added.
/* $NoKeywords: $ */
/*
//
// Copyright (c) 1993-2012 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>.
//
////////////////////////////////////////////////////////////////
*/
#if !defined(OPENNURBS_USERDATA_INC_)
#define OPENNURBS_USERDATA_INC_
class ON_CLASS ON_UserData : public ON_Object
{
ON_OBJECT_DECLARE(ON_UserData);
public:
ON_UserData();
ON_UserData(const ON_UserData&);
ON_UserData& operator=(const ON_UserData&);
//////////
// The destructor automatically removes the user data
// from ON_Object::m_userdata_list.
~ON_UserData();
/*
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 NULL, 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.
Remarks:
Overrides virtual ON_Object::IsValid
*/
ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
/*
Description:
Overrides virtual ON_Object::Dump().
Prints class name, description, and uuid.
Parameters:
text_log - [in] Information is sent to this text log.
Remarks:
*/
void Dump( ON_TextLog& text_log ) const;
/*
Description:
Overrides virtual ON_Object::SizeOf().
Returns:
Approximate number of bytes this class uses.
*/
unsigned int SizeOf() const;
////////
// Returns object that owns the user data
ON_Object* Owner() const;
////////
// Used for traversing list of user data attached
// to an object.
ON_UserData* Next() const;
////////
// Returns the class id which is not necessarily the
// same as m_userdata_uuid.
ON_UUID UserDataClassUuid() 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.
ON_BOOL32 IsUnknownUserData() const;
/*
Parameters:
description - [out] description of user data shown in
object properties dump.
Returns:
True if user data class is ready.
*/
virtual
ON_BOOL32 GetDescription( ON_wString& description );
/*
Description:
User will persist in binary archives if Archive() returns
true, m_application_uuid is not nil, and the virtual Read()
and Write() are functions are overridden.
Returns:
true if user data should persist in binary archives.
false if the user data should not be save 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.
YOU SHOULD READ AND UNDERSTAND EVERY COMMENT IN THIS
HEADER FILE IN BEFORE ATTEMPTING TO USE ON_UserData.
*/
virtual
ON_BOOL32 Archive() const;
/*
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
*/
virtual
ON_BOOL32 Transform( const ON_Xform& );
/*
Description:
This uuid is the value that must be passed to
ON_Object::GetUserData() to retrieve
this piece of user data.
*/
ON_UUID m_userdata_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.
*/
ON_UUID m_application_uuid;
////////
// 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.
unsigned int m_userdata_copycount;
////////
// 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.
ON_Xform m_userdata_xform;
private: // don't look and don't touch - these may change
friend int ON_BinaryArchive::ReadObject( ON_Object** );
friend bool ON_BinaryArchive::WriteObject( const ON_Object& );
friend bool ON_BinaryArchive::ReadObjectUserData( ON_Object& );
friend bool ON_BinaryArchive::WriteObjectUserData( const ON_Object& );
friend class ON_Object;
ON_Object* m_userdata_owner;
ON_UserData* m_userdata_next;
};
class ON_CLASS ON_UnknownUserData : public ON_UserData
{
ON_OBJECT_DECLARE(ON_UnknownUserData);
// used to hold user data will application class is not loaded
// at time data is read
public:
ON_UnknownUserData();
ON_UnknownUserData(const ON_UnknownUserData&);
~ON_UnknownUserData();
ON_UnknownUserData& operator=(const ON_UnknownUserData&);
// ON_Object overrides
/*
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 NULL, 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.
Remarks:
Overrides virtual ON_Object::IsValid
*/
ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
void Dump( ON_TextLog& ) const;
ON_BOOL32 Write( ON_BinaryArchive& ) const;
ON_BOOL32 Read( ON_BinaryArchive& );
unsigned int SizeOf() const; // return amount of memory used by user data
ON_BOOL32 GetDescription( ON_wString& ); // description of user data
ON_BOOL32 Archive() const;
// Convert unknown user data to actual user data. Useful if
// definition of actual user data is dynamically linked after
// archive containing user data is read.
ON_UserData* Convert() const;
/*
Description:
This is the uuid of the missing class. This uuid
is the 3rd parameter to the ON_OBJECT_IMPLEMENT()
macro of the missing class.
*/
ON_UUID m_unknownclass_uuid;
int m_sizeof_buffer;
void* m_buffer;
// These version numbers are set when unknown user data is read
// from a file record the version of the 3dm archive and the
// version of opennurbs that were used when the plug-in wrote
// the user data.
// This information was added in to V5 opennurbs 200910190.
// For files written with earlier versions of opennurbs, these
// values are set from the archive containing the user data.
// The purpose of this version information is to have it accompany
// unknown user data so that if is is eventually read by the plug-in
// an ON_BinaryArchive with correct version information can be
// passed to the plug-in's reading code. In archives, these values
// are stored in the TCODE_USER_TABLE_RECORD_HEADER chunk.
int m_3dm_version; // 3dm archive version (0,1,2,3,4,5,50,...)
int m_3dm_opennurbs_version; // 0 or YYYYMMDDN
};
class ON_CLASS ON_UserStringList : public ON_UserData
{
ON_OBJECT_DECLARE(ON_UserStringList);
public:
ON_UserStringList();
~ON_UserStringList();
// override virtual ON_Object::Dump function
void Dump( ON_TextLog& text_log ) const;
// override virtual ON_Object::SizeOf function
unsigned int SizeOf() const;
// override virtual ON_Object::DataCRC function
ON__UINT32 DataCRC(ON__UINT32 current_remainder) const;
// override virtual ON_Object::Write function
ON_BOOL32 Write(ON_BinaryArchive& binary_archive) const;
// override virtual ON_Object::Read function
ON_BOOL32 Read(ON_BinaryArchive& binary_archive);
// override virtual ON_UserData::GetDescription function
ON_BOOL32 GetDescription( ON_wString& description );
// override virtual ON_UserData::Archive function
ON_BOOL32 Archive() const;
/*
Description:
Add, replace or remove a user string.
Parameters:
key - [in]
must be a non-empty string. If an entry with the same key
(case insensitive compares are used) exists, the existing
entry is updated.
string_value - [in]
If string_value is empty and an entry with a matching key
exists, the entry is deleted.
Returns:
True if the key is valid.
*/
bool SetUserString( const wchar_t* key, const wchar_t* string_value );
bool GetUserString( const wchar_t* key, ON_wString& string_value ) const;
/*
Description:
Append entries to the user string list
Parameters:
count - [in]
number of element in us[] array
us - [in]
entries to append.
bReplace - [in]
If bReplace is true, then existing entries with the same key are
updated with the new entry's value. If bReplace is false, then
existing entries are not updated.
Returns:
Number of entries added, deleted, or modified.
*/
int SetUserStrings( int count, const ON_UserString* us, bool bReplace );
ON_ClassArray<ON_UserString> m_e;
};
class ON_CLASS ON_UserDataHolder : public ON_Object
{
public:
/*
Description:
Transfers the user data from source_object to "this".
When MoveUserDataFrom() returns source_object will not
have any user data. If "this" had user data when
MoveUserDataFrom() was called, then that user data is
destroyed.
Parameters:
source_object - [in] The "const" is a lie. It is
there because, in practice the source object is frequently
const and const_cast ends up being excessively used.
Returns:
True if source_object had user data that was transfered
to "this". False if source_object had no user data.
In any case, any user data that was on the input "this"
is destroyed.
*/
bool MoveUserDataFrom( const ON_Object& source_object );
/*
Description:
Transfers the user data on "this" to source_object.
When MoveUserDataTo() returns "this" will not have any
user data.
Parameters:
source_object - [in] The "const" is a lie. It is
there because, in practice the source object is generally
const and const_cast ends up being constantly used.
bAppend - [in] if true, existing user data on source_object
is left unchanged. If false, existing user data on source_object
is destroyed, even when there is no user data on "this".
Returns:
True if "this" had user data that was transfered to source_object.
In any case, any user data that was on the input "this"
is destroyed.
*/
bool MoveUserDataTo( const ON_Object& source_object, bool bAppend );
ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
};
/*
Description:
An ON_DocumentUserStringList object is saved in the list of user
tables. The Rhino SetDocumentText and GetDocumentText
commands use the ON_Object SetUserString, GetUserString,
GetUserStrings, GetUserStringKeys functions on an
ON_DocumentUserStringList class to manage the tag-value pairs of
strings.
*/
class ON_CLASS ON_DocumentUserStringList : public ON_Object
{
ON_OBJECT_DECLARE(ON_DocumentUserStringList);
public:
ON_DocumentUserStringList();
~ON_DocumentUserStringList();
ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
void Dump( ON_TextLog& ) const;
ON__UINT32 DataCRC(ON__UINT32 current_remainder) const;
ON_BOOL32 Write(ON_BinaryArchive& binary_archive) const;
ON_BOOL32 Read(ON_BinaryArchive& binary_archive);
// Use the
// ON_Object::SetUserString()
// ON_Object::GetUserString()
// ON_Object::GetUserStrings()
// ON_Object::GetUserStringKeys()
// ON_Object::UserStringCount()
// functions to access and modify user string information.
};
#endif