Point Cloud Library (PCL)  1.9.1-dev
opennurbs_userdata.h
1 /* $NoKeywords: $ */
2 /*
3 //
4 // Copyright (c) 1993-2012 Robert McNeel & Associates. All rights reserved.
5 // OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert
6 // McNeel & Associates.
7 //
8 // THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
9 // ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF
10 // MERCHANTABILITY ARE HEREBY DISCLAIMED.
11 //
12 // For complete openNURBS copyright information see <http://www.opennurbs.org>.
13 //
14 ////////////////////////////////////////////////////////////////
15 */
16 
17 #if !defined(OPENNURBS_USERDATA_INC_)
18 #define OPENNURBS_USERDATA_INC_
19 
20 class ON_CLASS ON_UserData : public ON_Object
21 {
22  ON_OBJECT_DECLARE(ON_UserData);
23 public:
24  ON_UserData();
25  ON_UserData(const ON_UserData&);
27 
28  //////////
29  // The destructor automatically removes the user data
30  // from ON_Object::m_userdata_list.
31  ~ON_UserData();
32 
33  /*
34  Description:
35  Tests an object to see if its data members are correctly
36  initialized.
37  Parameters:
38  text_log - [in] if the object is not valid and text_log
39  is not NULL, then a brief englis description of the
40  reason the object is not valid is appened to the log.
41  The information appended to text_log is suitable for
42  low-level debugging purposes by programmers and is
43  not intended to be useful as a high level user
44  interface tool.
45  Returns:
46  @untitled table
47  true object is valid
48  false object is invalid, uninitialized, etc.
49  Remarks:
50  Overrides virtual ON_Object::IsValid
51  */
52  ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
53 
54  /*
55  Description:
56  Overrides virtual ON_Object::Dump().
57  Prints class name, description, and uuid.
58  Parameters:
59  text_log - [in] Information is sent to this text log.
60  Remarks:
61  */
62  void Dump( ON_TextLog& text_log ) const;
63 
64  /*
65  Description:
66  Overrides virtual ON_Object::SizeOf().
67  Returns:
68  Approximate number of bytes this class uses.
69  */
70  unsigned int SizeOf() const;
71 
72  ////////
73  // Returns object that owns the user data
74  ON_Object* Owner() const;
75 
76  ////////
77  // Used for traversing list of user data attached
78  // to an object.
79  ON_UserData* Next() const;
80 
81  ////////
82  // Returns the class id which is not necessarily the
83  // same as m_userdata_uuid.
84  ON_UUID UserDataClassUuid() const;
85 
86  //////////
87  // Returns true if the user data is anonymous. This happens
88  // when the user data class is not defined at the time the
89  // user data is read from an archive. For example, if a class
90  // derived from ON_UserData is defined in application A
91  // but is not defined in application B, then the class can be
92  // defined when an archive is written by A but not exist when
93  // an archive is read by B. In this case, the
94  // user data is not lost, it is just read as ON_UnknownUserData
95  // by application B. If application B saves the parent
96  // object in an archive, the unknown user data is resaved in
97  // a form that can be read by application A.
98  ON_BOOL32 IsUnknownUserData() const;
99 
100  /*
101  Parameters:
102  description - [out] description of user data shown in
103  object properties dump.
104  Returns:
105  True if user data class is ready.
106  */
107  virtual
108  ON_BOOL32 GetDescription( ON_wString& description );
109 
110  /*
111  Description:
112  User will persist in binary archives if Archive() returns
113  true, m_application_uuid is not nil, and the virtual Read()
114  and Write() are functions are overridden.
115 
116  Returns:
117  true if user data should persist in binary archives.
118  false if the user data should not be save in binary archives.
119 
120  Remarks:
121  The default implementation returns false. If you override
122  ON_UserData::Archive so that it returns true, then your
123  constructor must set m_application_uuid, you must override
124  the virtual ON_Object::Read and ON_Object::Write functions and
125  you must CAREFULLY TEST your code.
126 
127  ON_UserData requires expert programming and testing skills.
128 
129  YOU SHOULD READ AND UNDERSTAND EVERY COMMENT IN THIS
130  HEADER FILE IN BEFORE ATTEMPTING TO USE ON_UserData.
131  */
132  virtual
133  ON_BOOL32 Archive() const;
134 
135  /*
136  Description:
137  If Transform() return false, then the userdata is destroyed when
138  its parent object is transformed. The default Transform()
139  updates m_userdata_xform and returns true.
140  Carefully read the comments above m_userdata_xform
141  */
142  virtual
143  ON_BOOL32 Transform( const ON_Xform& );
144 
145  /*
146  Description:
147  This uuid is the value that must be passed to
148  ON_Object::GetUserData() to retrieve
149  this piece of user data.
150  */
152 
153  /*
154  Description:
155  This uuid is used to identify the application that
156  created this piece of user data. In the case of
157  Rhino, this is the id of the plug-in that created
158  the user data. User data with a nil application id
159  will not be saved in 3dm archives.
160  */
162 
163  ////////
164  // If m_userdata_copycount is 0, user data is not copied when
165  // object is copied. If > 0, user data is copied and m_copycount
166  // is incremented when parent object is copied. The user data's
167  // operator=() is used to copy.
168  // The default ON_UserData::ON_UserData() constructor sets
169  // m_userdata_copycount to zero.
170  unsigned int m_userdata_copycount;
171 
172  ////////
173  // Updated if user data is attached to a piece of geometry that is
174  // transformed and the virtual ON_UserData::Transform() is not
175  // overridden. If you override ON_UserData::Transform() and want
176  // m_userdata_xform to be updated, then call the
177  // ON_UserData::Transform() in your override.
178  // The default constructor sets m_userdata_xform to the identity.
180 
181 private: // don't look and don't touch - these may change
182  friend int ON_BinaryArchive::ReadObject( ON_Object** );
183  friend bool ON_BinaryArchive::WriteObject( const ON_Object& );
185  friend bool ON_BinaryArchive::WriteObjectUserData( const ON_Object& );
186  friend class ON_Object;
187  ON_Object* m_userdata_owner;
188  ON_UserData* m_userdata_next;
189 };
190 
191 class ON_CLASS ON_UnknownUserData : public ON_UserData
192 {
193  ON_OBJECT_DECLARE(ON_UnknownUserData);
194  // used to hold user data will application class is not loaded
195  // at time data is read
196 public:
201 
202  // ON_Object overrides
203 
204  /*
205  Description:
206  Tests an object to see if its data members are correctly
207  initialized.
208  Parameters:
209  text_log - [in] if the object is not valid and text_log
210  is not NULL, then a brief englis description of the
211  reason the object is not valid is appened to the log.
212  The information appended to text_log is suitable for
213  low-level debugging purposes by programmers and is
214  not intended to be useful as a high level user
215  interface tool.
216  Returns:
217  @untitled table
218  true object is valid
219  false object is invalid, uninitialized, etc.
220  Remarks:
221  Overrides virtual ON_Object::IsValid
222  */
223  ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
224 
225  void Dump( ON_TextLog& ) const;
226  ON_BOOL32 Write( ON_BinaryArchive& ) const;
227  ON_BOOL32 Read( ON_BinaryArchive& );
228 
229  unsigned int SizeOf() const; // return amount of memory used by user data
230  ON_BOOL32 GetDescription( ON_wString& ); // description of user data
231  ON_BOOL32 Archive() const;
232 
233  // Convert unknown user data to actual user data. Useful if
234  // definition of actual user data is dynamically linked after
235  // archive containing user data is read.
236  ON_UserData* Convert() const;
237 
238  /*
239  Description:
240  This is the uuid of the missing class. This uuid
241  is the 3rd parameter to the ON_OBJECT_IMPLEMENT()
242  macro of the missing class.
243  */
246  void* m_buffer;
247 
248  // These version numbers are set when unknown user data is read
249  // from a file record the version of the 3dm archive and the
250  // version of opennurbs that were used when the plug-in wrote
251  // the user data.
252  // This information was added in to V5 opennurbs 200910190.
253  // For files written with earlier versions of opennurbs, these
254  // values are set from the archive containing the user data.
255  // The purpose of this version information is to have it accompany
256  // unknown user data so that if is is eventually read by the plug-in
257  // an ON_BinaryArchive with correct version information can be
258  // passed to the plug-in's reading code. In archives, these values
259  // are stored in the TCODE_USER_TABLE_RECORD_HEADER chunk.
260  int m_3dm_version; // 3dm archive version (0,1,2,3,4,5,50,...)
261  int m_3dm_opennurbs_version; // 0 or YYYYMMDDN
262 };
263 
264 class ON_CLASS ON_UserStringList : public ON_UserData
265 {
266  ON_OBJECT_DECLARE(ON_UserStringList);
267 public:
268 
271 
272  // override virtual ON_Object::Dump function
273  void Dump( ON_TextLog& text_log ) const;
274 
275  // override virtual ON_Object::SizeOf function
276  unsigned int SizeOf() const;
277 
278  // override virtual ON_Object::DataCRC function
279  ON__UINT32 DataCRC(ON__UINT32 current_remainder) const;
280 
281  // override virtual ON_Object::Write function
282  ON_BOOL32 Write(ON_BinaryArchive& binary_archive) const;
283 
284  // override virtual ON_Object::Read function
285  ON_BOOL32 Read(ON_BinaryArchive& binary_archive);
286 
287  // override virtual ON_UserData::GetDescription function
288  ON_BOOL32 GetDescription( ON_wString& description );
289 
290  // override virtual ON_UserData::Archive function
291  ON_BOOL32 Archive() const;
292 
293  /*
294  Description:
295  Add, replace or remove a user string.
296  Parameters:
297  key - [in]
298  must be a non-empty string. If an entry with the same key
299  (case insensitive compares are used) exists, the existing
300  entry is updated.
301  string_value - [in]
302  If string_value is empty and an entry with a matching key
303  exists, the entry is deleted.
304  Returns:
305  True if the key is valid.
306  */
307  bool SetUserString( const wchar_t* key, const wchar_t* string_value );
308 
309  bool GetUserString( const wchar_t* key, ON_wString& string_value ) const;
310 
311  /*
312  Description:
313  Append entries to the user string list
314  Parameters:
315  count - [in]
316  number of element in us[] array
317  us - [in]
318  entries to append.
319  bReplace - [in]
320  If bReplace is true, then existing entries with the same key are
321  updated with the new entry's value. If bReplace is false, then
322  existing entries are not updated.
323  Returns:
324  Number of entries added, deleted, or modified.
325  */
326  int SetUserStrings( int count, const ON_UserString* us, bool bReplace );
327 
329 };
330 
331 class ON_CLASS ON_UserDataHolder : public ON_Object
332 {
333 public:
334  /*
335  Description:
336  Transfers the user data from source_object to "this".
337  When MoveUserDataFrom() returns source_object will not
338  have any user data. If "this" had user data when
339  MoveUserDataFrom() was called, then that user data is
340  destroyed.
341  Parameters:
342  source_object - [in] The "const" is a lie. It is
343  there because, in practice the source object is frequently
344  const and const_cast ends up being excessively used.
345  Returns:
346  True if source_object had user data that was transfered
347  to "this". False if source_object had no user data.
348  In any case, any user data that was on the input "this"
349  is destroyed.
350  */
351  bool MoveUserDataFrom( const ON_Object& source_object );
352 
353  /*
354  Description:
355  Transfers the user data on "this" to source_object.
356  When MoveUserDataTo() returns "this" will not have any
357  user data.
358  Parameters:
359  source_object - [in] The "const" is a lie. It is
360  there because, in practice the source object is generally
361  const and const_cast ends up being constantly used.
362  bAppend - [in] if true, existing user data on source_object
363  is left unchanged. If false, existing user data on source_object
364  is destroyed, even when there is no user data on "this".
365  Returns:
366  True if "this" had user data that was transfered to source_object.
367  In any case, any user data that was on the input "this"
368  is destroyed.
369  */
370  bool MoveUserDataTo( const ON_Object& source_object, bool bAppend );
371 
372  ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
373 };
374 
375 /*
376 Description:
377  An ON_DocumentUserStringList object is saved in the list of user
378  tables. The Rhino SetDocumentText and GetDocumentText
379  commands use the ON_Object SetUserString, GetUserString,
380  GetUserStrings, GetUserStringKeys functions on an
381  ON_DocumentUserStringList class to manage the tag-value pairs of
382  strings.
383 */
384 class ON_CLASS ON_DocumentUserStringList : public ON_Object
385 {
386  ON_OBJECT_DECLARE(ON_DocumentUserStringList);
387 public:
390 
391  ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
392  void Dump( ON_TextLog& ) const;
393  ON__UINT32 DataCRC(ON__UINT32 current_remainder) const;
394  ON_BOOL32 Write(ON_BinaryArchive& binary_archive) const;
395  ON_BOOL32 Read(ON_BinaryArchive& binary_archive);
396 
397  // Use the
398  // ON_Object::SetUserString()
399  // ON_Object::GetUserString()
400  // ON_Object::GetUserStrings()
401  // ON_Object::GetUserStringKeys()
402  // ON_Object::UserStringCount()
403  // functions to access and modify user string information.
404 };
405 
406 #endif
virtual ON_BOOL32 IsValid(ON_TextLog *text_log=NULL) const =0
ON_Xform m_userdata_xform
bool GetUserString(const wchar_t *key, ON_wString &string_value) const
virtual ON_BOOL32 GetDescription(ON_wString &description)
void Dump(ON_TextLog &text_log) const
unsigned int m_userdata_copycount
friend class ON_UserData
ON_UUID m_userdata_uuid
virtual ON_BOOL32 Write(ON_BinaryArchive &binary_archive) const
bool SetUserString(const wchar_t *key, const wchar_t *string_value)
ON_ClassArray< ON_UserString > m_e
int ReadObject(ON_Object **ppObject)
bool WriteObject(const ON_Object *)
bool WriteObjectUserData(const ON_Object &object)
virtual ON_BOOL32 Read(ON_BinaryArchive &binary_archive)
virtual unsigned int SizeOf() const
unsigned int SizeOf() const
virtual void Dump(ON_TextLog &) const
ON_Object & operator=(const ON_Object &)
ON_UserData & operator=(const ON_UserData &)
virtual ON_BOOL32 Archive() const
bool ReadObjectUserData(ON_Object &object)
ON_UUID m_application_uuid
ON_BOOL32 IsValid(ON_TextLog *text_log=NULL) const
virtual ON__UINT32 DataCRC(ON__UINT32 current_remainder) const
int SetUserStrings(int count, const ON_UserString *user_strings, bool bReplace)