Point Cloud Library (PCL)  1.9.1-dev
opennurbs_object.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 ////////////////////////////////////////////////////////////////
18 //
19 // virtual base class for all openNURBS objects
20 //
21 ////////////////////////////////////////////////////////////////
22 
23 #if !defined(OPENNURBS_OBJECT_INC_)
24 #define OPENNURBS_OBJECT_INC_
25 
26 
27 class ON_ClassId; // used for runtime class identification
28 
29 ////////////////////////////////////////////////////////////////
30 //
31 // Runtime class id
32 //
33 
34 // Description:
35 // Every class derived from ON_Object has a class id that records
36 // its class name, baseclass name, and class uuid. The
37 // ON_OBJECT_DECLARE and ON_OBJECT_IMPLEMENT macros generate
38 // the code that creates and initializes class ids.
39 //
40 // The ON_Object::IsKindOf() and ON_Object::Cast() functions
41 // use these class ids.
42 class ON_CLASS ON_ClassId
43 {
44 public:
45 
46  // Description:
47  // This constructor is called to initialize each class id.
48  // The call is generated by the ON_OBJECT_IMPLEMENT macro.
49  //
50  // Parameters:
51  // sClassName - [in] name of the class (like ON_Geometry)
52  // sBaseClassName - [in] name of baseclass (like ON_Object)
53  // create - [in] function to create a new object(like CreateNewON_Geometry())
54  // copy - [in] function to copy
55  // sUUID - [in] UUID in registry format from Windows guidgen.exe
56  ON_ClassId(
57  const char* sClassName,
58  const char* sBaseClassName,
59  ON_Object* (*create)(),
60  const char* sUUID
61  );
62 
63  ON_ClassId(
64  const char* sClassName,
65  const char* sBaseClassName,
66  ON_Object* (*create)(),
67  bool (*copy)(const ON_Object*,ON_Object* ),
68  const char* sUUID
69  );
70 
71  ~ON_ClassId();
72 
73  // Description:
74  // Gets a class's ON_ClassId from the class's name.
75  // Parameters:
76  // sClassName - [in] name of class
77  // Returns:
78  // Pointer to the class's ON_ClassId.
79  // Example:
80  // const ON_ClassId* brep_id = ON_CLassId::ClassId("ON_Brep");
81  static const ON_ClassId* ClassId(
82  const char* sClassName
83  );
84 
85  // Description:
86  // Gets a class's ON_ClassId from the class's uuid.
87  // Parameters:
88  // class_uuid - [in] uuid for the class
89  // Returns:
90  // Pointer to the class's ON_ClassId.
91  // Example:
92  // ON_UUID brep_uuid = ON_UuidFromString("60B5DBC5-E660-11d3-BFE4-0010830122F0");
93  // const ON_ClassId* brep_id = ON_CLassId::ClassId(brep_uuid);
94  static const ON_ClassId* ClassId(
95  ON_UUID class_uuid
96  );
97 
98  // Description:
99  // Each class derived from ON_Object has a corresponding ON_ClassId
100  // stored in a linked list and the class is marked with an integer
101  // value. ON_ClassId::IncrementMark() increments the value used to
102  // mark new classes and returns the new marking value.
103  // Returns:
104  // Value that will be used to mark all future ON_ClassIds.
105  static int IncrementMark();
106  static int CurrentMark();
107  static const ON_ClassId* LastClassId();
108 
109  // Description:
110  // Each class derived from ON_Object has a corresponding
111  // ON_ClassId stored in a linked list. If a class definition
112  // is going to disappear (which happens when the derived object
113  // definition is in a DLL that uses openNURBS as a DLL and the
114  // DLL containing the derived object's definition is unloaded),
115  // then the class's ON_ClassId needs to be removed from the class
116  // list. ON_ClassId::Purge( mark ) removes all ON_ClassIds with a
117  // a prescribed mark and returns the number of classes that
118  // were purged.
119  // Parameters:
120  // mark - [in] All ON_ClassIds with this mark will be purged.
121  // Returns:
122  // Number of classes that were purged.
123  // Example:
124  // // Call ON_ClassId::IncrementMark() BEFORE loading MY.DLL.
125  // int my_dll_classid_mark = ON_ClassId::IncrementMark();
126  // load MY.DLL with classes derived from ON_Object
127  // ...
128  // // Call ON_ClassId::Purge() BEFORE unloading MY.DLL.
129  // ON_ClassId::Purge( my_dll_classid_mark );
130  // unload MY.DLL
131  static int Purge(int mark);
132  static bool PurgeAfter(const ON_ClassId* pClassId);
133 
134  // Description:
135  // Dumps the ON_ClassId list
136  // Parameters:
137  // dump - [in] destination for the text dump.
138  static void Dump(
139  ON_TextLog& dump
140  );
141 
142  // Returns:
143  // class name
144  const char* ClassName() const;
145 
146  // Returns:
147  // base class name
148  const char* BaseClassName() const;
149 
150  // Returns:
151  // base class id
152  const ON_ClassId* BaseClass() const;
153 
154  // Description:
155  // Determine if the class associated with this ON_ClassId
156  // is derived from another class.
157  // Parameters:
158  // potential_parent - [in] Class to test as parent.
159  // Returns:
160  // true if this is derived from potential_parent.
161  ON_BOOL32 IsDerivedFrom(
162  const ON_ClassId* potential_parent
163  ) const;
164 
165  // Descrption:
166  // Create an instance of the class associated with
167  // class id.
168  // Returns:
169  // Instance of the class id's class.
170  ON_Object* Create() const;
171 
172  // Returns:
173  // class uuid
174  ON_UUID Uuid() const;
175 
176  /*
177  Description:
178  Opennurbs classes have a mark value of 0. Core Rhino
179  classes have a mark value of 1. Rhino plug-in classes
180  have a mark value of > 1.
181  Returns:
182  Class mark value
183  */
184  int Mark() const;
185 
186  unsigned int ClassIdVersion() const;
187 
188 private:
189  static ON_ClassId* m_p0; // first id in the linked list of class ids
190  static ON_ClassId* m_p1; // last id in the linked list of class ids
191  static int m_mark0; // current mark value
192  ON_ClassId* m_pNext; // next in the linked list of class ids
193  const ON_ClassId* m_pBaseClassId; // base class id
194  char m_sClassName[80];
195  char m_sBaseClassName[80];
196  ON_Object* (*m_create)();
197  ON_UUID m_uuid;
198  int m_mark; // bit 0x80000000 is used to indicate new extensions
199 
200 private:
201  // no implementaion to prohibit use
202  ON_ClassId();
203  ON_ClassId( const ON_ClassId&);
204  ON_ClassId& operator=( const ON_ClassId&);
205 
206  void ConstructorHelper(
207  const char* sClassName,
208  const char* sBaseClassName,
209  const char* sUUID
210  );
211 
212  // This is a temporary way to add simple virtual functions
213  // to ON_Object without breaking the SDK. At V6 these will
214  // be redone to be ordinary virtual functions.
215  friend class ON_Object;
216  unsigned int m_class_id_version;
217  bool (*m_copy)(const ON_Object*,ON_Object*); // on version 1 class ids
218  void* m_f2;
219  void* m_f3;
220  void* m_f4;
221  void* m_f5;
222  void* m_f6;
223  void* m_f7;
224  void* m_f8;
225 };
226 
227 // Description:
228 // Macro to easily get a pointer to the ON_ClassId for a
229 // given class;
230 //
231 // Example:
232 //
233 // const ON_ClassId* brep_class_id = ON_CLASS_ID("ON_Brep");
234 //
235 #define ON_CLASS_ID( cls ) ON_ClassId::ClassId( #cls )
236 
237 /*
238 Description:
239  Expert user function to get the value of ON_ClassId::m_uuid
240  of the last instance of ON_ClassId to call ON_ClassId::Create().
241  This function was created to support Rhino's .NET SDK.
242  This function returns the value of a static id in
243  opennurbs_object.cpp and is NOT thread safe.
244 Returns:
245  Value of ON_ClassId::m_uuid of the instance of ON_ClassId that
246  most recently called ON_ClassId::Create().
247 */
248 ON_DECL
249 ON_UUID ON_GetMostRecentClassIdCreateUuid();
250 
251 /*
252 All classes derived from ON_Object must have
253 
254  ON_OBJECT_DECLARE( <classname> );
255 
256 as the first line in their class definition an a corresponding
257 
258  ON_VIRTUAL_OBJECT_IMPLEMENT( <classname>, <basclassname>, <classuuid> );
259 
260 or
261 
262  ON_OBJECT_IMPLEMENT( <classname>, <basclassname>, <classuuid> );
263 
264 in a .CPP file.
265 */
266 #define ON_OBJECT_DECLARE( cls ) \
267  protected: \
268  static void* m_s_##cls##_ptr; \
269  public: \
270  static const ON_ClassId m_##cls##_class_id; \
271  /*record used for ON_Object runtime type information*/ \
272  \
273  static cls * Cast( ON_Object* ); \
274  /*Description: Similar to C++ dynamic_cast*/ \
275  /*Returns: object on success. NULL on failure*/ \
276  \
277  static const cls * Cast( const ON_Object* ); \
278  /*Description: Similar to C++ dynamic_cast*/ \
279  /*Returns: object on success. NULL on failure*/ \
280  \
281  virtual const ON_ClassId* ClassId() const; \
282  /*Description:*/ \
283  \
284  private: \
285  virtual ON_Object* DuplicateObject() const; \
286  /*used by Duplicate to create copy of an object.*/ \
287  \
288  static bool Copy##cls( const ON_Object*, ON_Object* ); \
289  /* used by ON_Object::CopyFrom copy object into this. */ \
290  /* In V6 Copy##cls will vanish and be replaced with */ \
291  /* virtual bool CopyFrom( const ON_Object* src ) */ \
292  \
293  public: \
294  cls * Duplicate() const; \
295  /*Description: Expert level tool - no support available.*/ \
296  /*If this class is derived from CRhinoObject, use CRhinoObject::DuplicateRhinoObject instead*/
297 
298 // Objects derived from ON_Object that do not have a valid new, operator=,
299 // or copy constructor must use ON_VIRTUAL_OBJECT_IMPLEMENT instead of
300 // ON_OBJECT_IMPLEMENT. Objects defined with ON_VIRTUAL_OBJECT_IMPLEMENT
301 // cannot be serialized using ON_BinaryArchive::ReadObject()/WriteObject()
302 // or duplicated using ON_Object::Duplicate().
303 //
304 // The Cast() and ClassId() members work on objects defined with either
305 // ON_VIRTUAL_OBJECT_IMPLEMENT or ON_OBJECT_IMPLEMENT.
306 #define ON_VIRTUAL_OBJECT_IMPLEMENT( cls, basecls, uuid ) \
307  void* cls::m_s_##cls##_ptr = 0;\
308  const ON_ClassId cls::m_##cls##_class_id(#cls,#basecls,0,0,uuid);\
309  cls * cls::Cast( ON_Object* p) {return(cls *)Cast((const ON_Object*)p);} \
310  const cls * cls::Cast( const ON_Object* p) {return(p&&p->IsKindOf(&cls::m_##cls##_class_id))?(const cls *)p:0;} \
311  const ON_ClassId* cls::ClassId() const {return &cls::m_##cls##_class_id;} \
312  ON_Object* cls::DuplicateObject() const {return 0;} \
313  bool cls::Copy##cls( const ON_Object*, ON_Object* ) {return false;} \
314  cls * cls::Duplicate() const {return static_cast<cls *>(DuplicateObject());}
315 
316 // Objects derived from ON_Object that use ON_OBJECT_IMPLEMENT must
317 // have a valid operator= and copy constructor. Objects defined with
318 // ON_OBJECT_IMPLEMENT may be serialized using
319 // ON_BinaryArchive::ReadObject()/WriteObject()
320 // and duplicated by calling ON_Object::Duplicate().
321 #define ON_OBJECT_IMPLEMENT( cls, basecls, uuid ) \
322  void* cls::m_s_##cls##_ptr = 0;\
323  static ON_Object* CreateNew##cls() {return new cls();} \
324  const ON_ClassId cls::m_##cls##_class_id(#cls,#basecls,CreateNew##cls,cls::Copy##cls,uuid);\
325  cls * cls::Cast( ON_Object* p) {return(cls *)Cast((const ON_Object*)p);} \
326  const cls * cls::Cast( const ON_Object* p) {return(p&&p->IsKindOf(&cls::m_##cls##_class_id))?(const cls *)p:0;} \
327  const ON_ClassId* cls::ClassId() const {return &cls::m_##cls##_class_id;} \
328  ON_Object* cls::DuplicateObject() const {cls* p = new cls(); if (p) *p=*this; return p;} \
329  bool cls::Copy##cls( const ON_Object* src, ON_Object* dst ){cls* d;const cls* s;if (0!=(s=cls::Cast(src))&&0!=(d=cls::Cast(dst))) {d->cls::operator=(*s);return true;}return false;} \
330  cls * cls::Duplicate() const {return static_cast<cls *>(DuplicateObject());}
331 
332 #define ON__SET__THIS__PTR(ptr) if (ptr) *((void**)this) = ptr
333 
334 class ON_UserData;
335 
336 class ON_CLASS ON_UserString
337 {
338 public:
339  ON_UserString();
340  ~ON_UserString();
343 
344  void Dump(ON_TextLog& text_log) const;
345  bool Write(ON_BinaryArchive&) const;
346  bool Read(ON_BinaryArchive&);
347 };
348 
349 #if defined(ON_DLL_TEMPLATE)
350 // This stuff is here because of a limitation in the way Microsoft
351 // handles templates and DLLs. See Microsoft's knowledge base
352 // article ID Q168958 for details.
353 #pragma warning( push )
354 #pragma warning( disable : 4231 )
355 ON_DLL_TEMPLATE template class ON_CLASS ON_ClassArray<ON_UserString>;
356 #pragma warning( pop )
357 #endif
358 
359 /*
360 Description:
361  When ON_Object::IsValid() fails and returns false, ON_IsNotValid()
362  is called. This way, a developer can put a breakpoint in
363  ON_IsNotValid() and stop execution at the exact place IsValid()
364  fails.
365 Returns:
366  false;
367 */
368 ON_DECL
369 bool ON_IsNotValid();
370 
371 ////////////////////////////////////////////////////////////////
372 
373 // Description:
374 // Pure virtual base class for all classes that must provide
375 // runtime class id or support object level 3DM serialization
376 class ON_CLASS ON_Object
377 {
378  /////////////////////////////////////////////////////////////////
379  //
380  // Any object derived from ON_Object should have a
381  // ON_OBJECT_DECLARE(ON_...);
382  // as the last line of its class definition and a
383  // ON_OBJECT_IMPLEMENT( ON_..., ON_baseclass );
384  // in a .cpp file.
385  //
386  // These macros declare and implement public members
387  //
388  // static ON_ClassId m_ON_Object;
389  // static cls * Cast( ON_Object* );
390  // static const cls * Cast( const ON_Object* );
391  // virtual const ON_ClassId* ClassId() const;
392  ON_OBJECT_DECLARE(ON_Object);
393 public:
394 
395  /*
396  Description:
397  Copies src into this, if possible.
398  Parameters:
399  src - [in]
400  Returns:
401  True if this->operator= could be called to copy src.
402  Remarks:
403  This should be virtual function declared in the
404  ON_OBJECT_DECLARE macro along the lines of DuplicateObject()
405  but is was added after the SDK was frozen (adding virtual
406  functions breaks the SDK). In V6, the function will work
407  the same but be implemented like DuplicateObject();
408  */
409  bool CopyFrom( const ON_Object* src );
410 
411 public:
412 
413  ON_Object();
414  ON_Object( const ON_Object& );
415  ON_Object& operator=( const ON_Object& );
416  virtual ~ON_Object();
417 
418  /*
419  Description:
420  Sets m_user_data_list = 0.
421  */
422  void EmergencyDestroy();
423 
424  /*
425  Description:
426  The MemoryRelocate() function is called when an
427  object's location in memory is changed. For
428  example, if an object resides in a chunk of
429  memory that is grown by calling a realloc
430  that has to allocate a new chunk and
431  copy the contents of the old chunk to the
432  new chunk, then the location of the object's
433  memory changes. In practice this happens when
434  classes derived from ON_Object are stored
435  in dynamic arrays, like the default implementation
436  of ON_ObjectArray<>'s that use realloc to grow
437  the dynamic array.
438  */
439  virtual
440  void MemoryRelocate();
441 
442  /*
443  Description:
444  Low level tool to test if an object is derived
445  from a specified class.
446  Parameters:
447  pClassId - [in] use classname::ClassId()
448  Returns:
449  true if the instantiated object is derived from the
450  class whose id is passed as the argument.
451  Example:
452 
453  ON_Object* p = ....;
454  if ( p->IsKindOf( ON_NurbsCurve::ClassId() ) )
455  {
456  it's a NURBS curve
457  }
458 
459  Remarks:
460  The primary reason for IsKindOf() is to support the
461  static Cast() members declared in the ON_OBJECT_DECLARE
462  macro. If we determine that dynamic_cast is properly
463  supported and implemented by all supported compilers,
464  then IsKindOf() may dissappear. If an application needs
465  to determine if a pointer points to a class derived from
466  ON_SomeClassName, then call
467  ON_SomeClassName::Cast(mystery pointer) and check for
468  a non-null return.
469  */
470  ON_BOOL32 IsKindOf(
471  const ON_ClassId* pClassId
472  ) const;
473 
474  /*
475  Description:
476  Tests an object to see if its data members are correctly
477  initialized.
478  Parameters:
479  text_log - [in] if the object is not valid and text_log
480  is not NULL, then a brief englis description of the
481  reason the object is not valid is appened to the log.
482  The information appended to text_log is suitable for
483  low-level debugging purposes by programmers and is
484  not intended to be useful as a high level user
485  interface tool.
486  Returns:
487  @untitled table
488  true object is valid
489  false object is invalid, uninitialized, etc.
490  */
491  virtual
492  ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const = 0;
493 
494  /*
495  Description:
496  Creates a text dump of the object.
497  Remarks:
498  Dump() is intended for debugging and is not suitable
499  for creating high quality text descriptions of an
500  object.
501 
502  The default implementations of this virtual function
503  prints the class's name.
504  */
505  virtual
506  void Dump( ON_TextLog& ) const;
507 
508  /*
509  Returns:
510  An estimate of the amount of memory the class uses in bytes.
511  */
512  virtual
513  unsigned int SizeOf() const;
514 
515  /*
516  Description:
517  Returns a CRC calculated from the information that defines
518  the object. This CRC can be used as a quick way to see
519  if two objects are not identical.
520  Parameters:
521  current_remainder - [in];
522  Returns:
523  CRC of the information the defines the object.
524  */
525  virtual
526  ON__UINT32 DataCRC(ON__UINT32 current_remainder) const;
527 
528  /*
529  Description:
530  Low level archive writing tool used by ON_BinaryArchive::WriteObject().
531  Parameters:
532  binary_archive - archive to write to
533  Returns:
534  Returns true if the write is successful.
535  Remarks:
536  Use ON_BinaryArchive::WriteObject() to write objects.
537  This Write() function should just write the specific definition of
538  this object. It should not write and any chunk typecode or length
539  information.
540 
541  The default implementation of this virtual function returns
542  false and does nothing.
543  */
544  virtual
545  ON_BOOL32 Write(
546  ON_BinaryArchive& binary_archive
547  ) const;
548 
549  /*
550  Description:
551  Low level archive writing tool used by ON_BinaryArchive::ReadObject().
552  Parameters:
553  binary_archive - archive to read from
554  Returns:
555  Returns true if the read is successful.
556  Remarks:
557  Use ON_BinaryArchive::ReadObject() to read objects.
558  This Read() function should read the objects definition back into
559  its data members.
560 
561  The default implementation of this virtual function returns
562  false and does nothing.
563  */
564  virtual
565  ON_BOOL32 Read(
566  ON_BinaryArchive& binary_archive
567  );
568 
569  /*
570  Description:
571  Useful for switch statements that need to differentiate
572  between basic object types like points, curves, surfaces,
573  and so on.
574 
575  Returns:
576  ON::object_type enum value.
577 
578  @untitled table
579  ON::unknown_object_type unknown object
580  ON::point_object derived from ON_Point
581  ON::pointset_object some type of ON_PointCloud, ON_PointGrid, ...
582  ON::curve_object derived from ON_Curve
583  ON::surface_object derived from ON_Surface
584  ON::brep_object derived from ON_Brep
585  ON::extrusion_object derived from ON_Extrusion
586  ON::mesh_object derived from ON_Mesh
587  ON::layer_object derived from ON_Layer
588  ON::material_object derived from ON_Material
589  ON::light_object derived from ON_Light
590  ON::annotation_object derived from ON_Annotation,
591  ON::userdata_object derived from ON_UserData
592  ON::text_dot derived from ON_TextDot
593 
594  Remarks:
595  The default implementation of this virtual function returns
596  ON::unknown_object_type
597  */
598  virtual
599  ON::object_type ObjectType() const;
600 
601 
602 
603  /*
604  Description:
605  All objects in an opennurbs model have an id
606  ( ON_Layer.m_layer_id, ON_Font.m_font_id,
607  ON_Material.m_material_id, ON_3dmObjectAttributes.m_uuid
608  ).
609  Returns:
610  The id used to identify the object in the openurbs model.
611  */
612  virtual
613  ON_UUID ModelObjectId() const;
614 
615  //////////////////////////////////////////////////////////////////
616  //
617  // BEGIN: User string support
618  //
619 
620  /*
621  Description:
622  Attach a user string to the object. This information will
623  perisist through copy construction, operator=, and file IO.
624  Parameters:
625  key - [in] id used to retrieve this string.
626  string_value - [in]
627  If NULL, the string with this id will be removed.
628  Returns:
629  True if successful.
630  */
631  bool SetUserString(
632  const wchar_t* key,
633  const wchar_t* string_value
634  );
635 
636  /*
637  Description:
638  Append entries to the user string list
639  Parameters:
640  count - [in]
641  number of element in us[] array
642  user_strings - [in]
643  entries to append.
644  bReplace - [in]
645  If bReplace is true, then existing entries with the same key are
646  updated with the new entry's value. If bReplace is false, then
647  existing entries are not updated.
648  Returns:
649  Number of entries added, deleted, or modified.
650  */
651  int SetUserStrings( int count, const ON_UserString* user_strings, bool bReplace );
652 
653  /*
654  Description:
655  Get user string from the object.
656  Parameters:
657  key - [in] id used to retrieve the string.
658  string_value - [out]
659  Returns:
660  True if a string with id was found.
661  */
662  bool GetUserString(
663  const wchar_t* key,
664  ON_wString& string_value
665  ) const;
666 
667  /*
668  Description:
669  Get a list of all user strings on the object.
670  Parameters:
671  user_strings - [out]
672  user strings are appended to this list.
673  Returns:
674  Number of elements appended to the user_strings list.
675  */
676  int GetUserStrings(
677  ON_ClassArray<ON_UserString>& user_strings
678  ) const;
679 
680  /*
681  Description:
682  Get a list of all user string keys on the object.
683  Parameters:
684  user_string_keys - [out]
685  user string keys are appended to this list.
686  Returns:
687  Number of elements appended to the user_strings list.
688  */
689  int GetUserStringKeys(
690  ON_ClassArray<ON_wString>& user_string_keys
691  ) const;
692 
693  /*
694  Returns:
695  Number of user strings on the object.
696  */
697  int UserStringCount() const;
698 
699  //
700  // END: User string support
701  //
702  //////////////////////////////////////////////////////////////////
703 
704  /////////////////////////////////////////////////////////////////
705  //
706  // User data provides a standard way for extra information to
707  // be attached to any class derived from ON_Object. The attached
708  // information can persist and be transformed. If you use user
709  // data, please carefully read all the comments from here to the
710  // end of the file.
711  //
712 
713  /*
714  Description:
715  Attach user data to an object.
716  Parameters:
717  pUserData - [in] user data to attach to object.
718  The ON_UserData pointer passed to AttachUserData()
719  must be created with new.
720  Returns:
721  If true is returned, then ON_Object will delete the user
722  data when appropriate. If false is returned, then data
723  could not be attached and caller must delete.
724  Remarks:
725  AttachUserData() will fail if the user data's m_userdata_uuid
726  field is nil or not unique.
727  */
728  ON_BOOL32 AttachUserData(
729  ON_UserData* pUserData
730  );
731 
732  /*
733  Description:
734  Remove user data from an object.
735  Parameters:
736  pUserData - [in] user data to attach to object.
737  The ON_UserData pointer passed to DetachUserData()
738  must have been previously attached using
739  AttachUserData().
740  Returns:
741  If true is returned, then the user data was
742  attached to this object and it was detached. If false
743  is returned, then the user data was not attached to this
744  object to begin with. In all cases, you can be assured
745  that the user data is no longer attached to "this".
746  Remarks:
747  Call delete pUserData if you want to destroy the user data.
748  */
749  ON_BOOL32 DetachUserData(
750  ON_UserData* pUserData
751  );
752 
753 
754  /*
755  Description:
756  Get a pointer to user data.
757  Parameters:
758  userdata_uuid - [in] value of the user data's
759  m_userdata_uuid field.
760  Remarks:
761  The returned user data is still attached to the object.
762  Deleting the returned user data will automatically remove
763  the user data from the object.
764  */
765  ON_UserData* GetUserData(
766  const ON_UUID& userdata_uuid
767  ) const;
768 
769  /*
770  Description:
771  PurgeUserData() removes all user data from object.
772  Remarks:
773  Use delete GetUserData(...) to destroy a single piece
774  of user data.
775  */
776  void PurgeUserData();
777 
778  /*
779  Description:
780  User data is stored as a linked list of ON_UserData
781  classes. FirstUserData gets the first item in the
782  linked list. This is the most recent item attached
783  using AttachUserData().
784  Remark:
785  To iterate through all the user data on an object,
786  call FirstUserData() and then use ON_UserData::Next()
787  to traverse the list.
788  */
789  ON_UserData* FirstUserData() const;
790 
791  /*
792  Description:
793  Objects derived from ON_Geometry must call
794  TransformUserData() in their Transform() member function.
795  Parameters:
796  xform - [in] transformation to apply to user data
797  */
798  void TransformUserData(
799  const ON_Xform& xform
800  );
801 
802  /*
803  Description:
804  Expert user tool that copies user data that has a positive
805  m_userdata_copycount from the source_object to this.
806  Parameters:
807  source_object - [in] source of user data to copy
808  Remarks:
809  Generally speaking you don't need to use CopyUserData().
810  Simply rely on ON_Object::operator=() or the copy constructor
811  to do the right thing.
812  */
813  void CopyUserData(
814  const ON_Object& source_object
815  );
816 
817  /*
818  Description:
819  Expert user tool Moves user data from source_object
820  to this, including user data with a nil m_userdata_copycount.
821  Deletes any source user data with a duplicate m_userdata_uuid
822  on this.
823  */
824  void MoveUserData(
825  ON_Object& source_object
826  );
827 
828 
829  /////////////////////////////////////////////////////////////////
830  //
831  // Expert interface
832  //
833 
834  /*
835  Description:
836  Expert user function. If you are using openNURBS in its
837  default configuration to read and write 3dm archives,
838  you never need to call this function.
839  Many objects employ lazy creation of (runtime) caches
840  that save information to help speed geometric calculations.
841  This function will destroy all runtime information.
842  Parameters:
843  bDelete - [in] if true, any cached information is properly
844  deleted. If false, any cached information
845  is simply discarded. This is useful when
846  the cached information may be in alternate
847  memory pools that are managed in nonstandard
848  ways.
849  */
850  virtual
851  void DestroyRuntimeCache( bool bDelete = true );
852 
853 private:
854  friend int ON_BinaryArchive::ReadObject( ON_Object** );
855  friend bool ON_BinaryArchive::WriteObject( const ON_Object& );
857  friend bool ON_BinaryArchive::WriteObjectUserData( const ON_Object& );
858  friend class ON_UserData;
859  ON_UserData* m_userdata_list;
860 };
861 
862 #endif
863 
friend class ON_UserData
ON_wString m_string_value
int ReadObject(ON_Object **ppObject)
bool WriteObject(const ON_Object *)
bool WriteObjectUserData(const ON_Object &object)
bool ReadObjectUserData(ON_Object &object)
ON_wString m_key