1/****************************************************************************************
2
3 Copyright (C) 2015 Autodesk, Inc.
4 All rights reserved.
5
6 Use of this software is subject to the terms of the Autodesk license agreement
7 provided at the time of installation or download, or which otherwise accompanies
8 this software in either electronic or hard copy form.
9
10****************************************************************************************/
11
12//! \file fbxpropertyhandle.h
13#ifndef _FBXSDK_CORE_PROPERTY_HANDLE_H_
14#define _FBXSDK_CORE_PROPERTY_HANDLE_H_
15
16#include <fbxsdk/fbxsdk_def.h>
17
18#include <fbxsdk/core/fbxconnectionpoint.h>
19#include <fbxsdk/core/fbxpropertytypes.h>
20#include <fbxsdk/core/fbxpropertydef.h>
21
22#include <fbxsdk/fbxsdk_nsbegin.h>
23
24class FbxPropertyPage;
25class FbxPropertyHandle;
26class FbxConnectionPointFilter;
27
28//! \brief Class to manage property handle.
29class FBXSDK_DLL FbxPropertyHandle
30{
31public:
32 /**
33 * \name Constructor and Destructor
34 */
35 //@{
36 //! Create an instance
37 static FbxPropertyHandle Create();
38
39 /** Create an instance with given instance.
40 * \param pInstanceOf The given instance. */
41 static FbxPropertyHandle Create(const FbxPropertyHandle& pInstanceOf);
42
43 /** Create an instance with given name and type.
44 * \param pName Property name.
45 * \param pType Property type. */
46 static FbxPropertyHandle Create(const char* pName, EFbxType pType=eFbxUndefined);
47
48 /** Create an instance with given name and type info.
49 * \param pName
50 * \param pTypeInfo */
51 static FbxPropertyHandle Create(const char* pName, FbxPropertyHandle pTypeInfo);
52
53 /** If this property is root property, delete the property page, otherwise delete the property.
54 * \return If succeed, return true. */
55 bool Destroy();
56
57 //! Default constructor.
58 FbxPropertyHandle();
59
60 /** Copy constructor.
61 * \param pAddress FbxPropertyHandle copied to this one. */
62 FbxPropertyHandle(const FbxPropertyHandle& pAddress);
63
64 //! Destructor
65 ~FbxPropertyHandle();
66
67 /** Character constructor.
68 * \param pPage
69 * \param pId */
70 FbxPropertyHandle(FbxPropertyPage* pPage, FbxInt pId=FBXSDK_PROPERTY_ID_ROOT);
71 //@}
72
73 /**
74 * \name Assignment and basic info
75 */
76 //@{
77 /** FbxPropertyHandle assignment operator.
78 * \param pHandle FbxPropertyHandle assigned to this one. */
79 FbxPropertyHandle& operator=(const FbxPropertyHandle& pHandle);
80
81 /** Equality operator.
82 * \param pHandle FbxPropertyHandle compared with this one.
83 * \return \c True if equal, \c false otherwise. */
84 bool operator==(const FbxPropertyHandle& pHandle) const;
85
86 /** Inequality operator.
87 * \param pHandle FbxPropertyHandle compared with this one.
88 * \return \c True if unequal, \c false otherwise. */
89 bool operator!=(const FbxPropertyHandle& pHandle) const;
90
91 /** Lesser operator, used to sort property handle in map.
92 * \param pHandle The property handle compared to this property handle.
93 * \return \c true if less, \c false otherwise. */
94 bool operator< (const FbxPropertyHandle& pHandle) const;
95
96 /** Greater operator, used to sort property handle in map.
97 * \param pProperty The property handle compared to this property handle.
98 * \return \c true if greater, \c false otherwise. */
99 bool operator> (const FbxPropertyHandle& pHandle) const;
100
101 /** Compare type info together
102 * \param pHandle FbxPropertyHandle compared with this one.
103 * \return \c True if equal, \c false otherwise. */
104 bool Is(const FbxPropertyHandle& pHandle) const;
105
106 //! Judge validity
107 bool Valid() const;
108
109 //! Get the property name
110 const char* GetName() const;
111
112 //! Get the property label
113 const char* GetLabel() const;
114
115 /** Set a label to the property
116 * \param pLabel The given label string
117 * \return \c true if successful. */
118 bool SetLabel(const char* pLabel);
119
120 //! Get the property type
121 EFbxType GetType() const;
122
123 //! Get the property type info
124 FbxPropertyHandle GetTypeInfo() const;
125
126 //! Get the property attribute state
127 FbxPropertyFlags::EFlags GetFlags() const;
128
129 /** Gets the inheritance type for the given flag.
130 * \param pFlags The flag to query
131 * \param pCheckReferences Decide whether check instance. If it is true, check instance.
132 * \return The inheritance type */
133 FbxPropertyFlags::EInheritType GetFlagsInheritType(FbxPropertyFlags::EFlags pFlags, bool pCheckReferences) const;
134
135 /** According the given parameter Change the attributes of the property.
136 * \param pFlags The given flags used as mask.
137 * \param pValue If pValue is true, set mask with given flags, otherwise unset mask with given flags.
138 * \return If succeed, return true. */
139 bool ModifyFlags(FbxPropertyFlags::EFlags pFlags, bool pValue);
140
141 /**Sets the inheritance type for the given flag
142 * \param pFlags The flag to set
143 * \param pType The inheritance type to set
144 * \return If succeed, return true. */
145 bool SetFlagsInheritType(FbxPropertyFlags::EFlags pFlags, FbxPropertyFlags::EInheritType pType);
146
147 //! Get the property user data.
148 void* GetUserData() const;
149
150 /** Set user data to the property
151 * \param pUserData The given user data
152 * \return If succeed, return true. */
153 bool SetUserData(const void* pUserData);
154
155 //! Get the property user tag
156 int GetUserTag() const;
157
158 /** Set user tag to the property
159 * \param pUserData The given user tag
160 * \return If succeed, return true. */
161 bool SetUserTag(int pUserData);
162 //@}
163
164 /**
165 * \name Enum management
166 */
167 //@{
168 /** Add new value at the end of the enum list in the property.
169 * \param pStringValue The given new value
170 * \return The index of the value. */
171 int AddEnumValue(const char* pStringValue);
172
173 /** Insert new value at the given index of the enum list in property.
174 * \param pIndex The given index
175 * \param pStringValue The given new value */
176 void InsertEnumValue(int pIndex, const char* pStringValue);
177
178 /** Get the enum count of enum list in property
179 * \return The enum count of enum list in property */
180 int GetEnumCount();
181
182 /** Set value at the given index of the enum list in the property.
183 * \param pIndex The given index
184 * \param pStringValue The given new value used to instead the old value. */
185 void SetEnumValue(int pIndex, const char* pStringValue);
186
187 /** Remove the value at the index of the enum list in the property.
188 * \param pIndex The given index */
189 void RemoveEnumValue(int pIndex);
190
191 /** Get the value at the index of enum list in the property.
192 * \param pIndex The given index
193 * \return The value at the given index */
194 char* GetEnumValue(int pIndex);
195 //@}
196
197 /**
198 * \name Child and Struct management
199 */
200 //@{
201 //! Create the map for find property in the property page
202 void BeginCreateOrFindProperty();
203
204 //! Clear the map which created for find property.
205 void EndCreateOrFindProperty();
206
207 /** Judge if the property is the root property.
208 * \return Return true if this property is root property. */
209 inline bool IsRoot() const { return ( mPage && mId == 0 ) ? true : false; }
210
211 /** Judge if the property is the child property of the given parent property.
212 * \param pParent The given parent property handle
213 * \return Return true if this property is child of given property. */
214 bool IsChildOf(const FbxPropertyHandle& pParent) const;
215
216 /** Judge if the property is descendent property of the given property.
217 * \param pParent The given parent property handle
218 * \return Return true if this property is descendant of given property. */
219 bool IsDescendentOf(const FbxPropertyHandle& pParent) const;
220
221 /** Set parent property handle.No matter what enters,the result is always false.
222 * \param pOther
223 * \return False */
224 bool SetParent(const FbxPropertyHandle& pOther );
225
226 /** Add a property to the property page.
227 * \param pName The name of property.
228 * \param pTypeInfo The added property's type info.
229 * \return The handle of the new added property */
230 FbxPropertyHandle Add(const char* pName, const FbxPropertyHandle& pTypeInfo);
231
232 /** Get parent property
233 * \return If the parent property exists, return the property handle,otherwise return -1. */
234 FbxPropertyHandle GetParent() const;
235
236 /** Get child property
237 * \return If the child property is exist, return the property handle,otherwise return -1. */
238 FbxPropertyHandle GetChild() const;
239
240 /** Get sibling property
241 * \return If the sibling property is exist, return the property handle,otherwise return -1. */
242 FbxPropertyHandle GetSibling() const;
243
244 /** Get first descendent property
245 * \return If the descendent property is exist, return the first descendent property handle,otherwise return -1. */
246 FbxPropertyHandle GetFirstDescendent() const;
247
248 /** Get first descendent property which after the given property
249 * \param pHandle The given property handle
250 * \return If the descendent property can be found after the given property,
251 * return the first found property handle,otherwise return -1. */
252 FbxPropertyHandle GetNextDescendent(const FbxPropertyHandle& pHandle) const;
253
254 /** Find the property with given name
255 * \param pName The given property name
256 * \param pCaseSensitive Decide if the given property name is case sensitive
257 * \return Return a property handle which be created with the found property. */
258 FbxPropertyHandle Find(const char* pName, bool pCaseSensitive) const;
259
260 /** Find the property with given name and type info.
261 * \param pName The given property name
262 * \param pTypeInfo The given property type info
263 * \param pCaseSensitive Decide if the given property name is case sensitive
264 * \return Return a property handle which be created with the found property. */
265 FbxPropertyHandle Find(const char* pName, const FbxPropertyHandle& pTypeInfo, bool pCaseSensitive) const;
266
267 /** Separate the given name by children separator string and then find the property.The step is
268 * strip the first part of the name and search, if the property can be found, strip the second part
269 * of the name and continue search, until no property be found,then return the last found property.
270 * \param pName The given property name
271 * \param pChildrenSeparator The given children separator string
272 * \param pCaseSensitive Decide if the given property name is case sensitive
273 * \return Return a property handle which be created with the found property. */
274 FbxPropertyHandle Find(const char* pName, const char* pChildrenSeparator, bool pCaseSensitive) const;
275
276 /** Separate the given name by children separator string and then find the property.The step is
277 * strip the first part of the name and search, if the property can be found, strip the second part
278 * of the name and continue search, until no property be found,then return the last found property.
279 * \param pName The given property name
280 * \param pChildrenSeparator The given children separator string
281 * \param pTypeInfo The given property type info
282 * \param pCaseSensitive Decide if the given property name is case sensitive
283 * \return Return a property handle which be created with the found property. */
284 FbxPropertyHandle Find(const char* pName, const char* pChildrenSeparator, const FbxPropertyHandle& pTypeInfo, bool pCaseSensitive) const;
285 //@}
286
287 /**
288 * \name Connection management
289 */
290 //@{
291 /** Connect source property.
292 * \param pSrc The given source property
293 * \param pType The given property type
294 * \return If connect successfully, return true,otherwise, return false. */
295 bool ConnectSrc(const FbxPropertyHandle& pSrc, const FbxConnection::EType pType=FbxConnection::eDefault);
296
297 /** Get source properties' count.
298 * \param pFilter The filter used to get sub connection point. If it is not zero, return the source count of the sub connection point.
299 * Otherwise, return the src count of this property.
300 * \return The count of source properties */
301 int GetSrcCount(FbxConnectionPointFilter* pFilter=0) const;
302
303 /** Get source property with the given index.
304 * \param pFilter The filter used to get sub connection point. If it is not zero, return the source property of the sub connection point.
305 * Otherwise, return the source property of this property.
306 * \param pIndex The given index
307 * \return The source property handle. */
308 FbxPropertyHandle GetSrc(FbxConnectionPointFilter* pFilter=0, int pIndex=0) const;
309
310 /** Disconnect source property.
311 * \param pSrc The given source property
312 * \return If disconnect successfully, return true, otherwise return false. */
313 bool DisconnectSrc(const FbxPropertyHandle& pSrc);
314
315 /** Judge if it is connected with the given source property.
316 * \param pSrc The given source property
317 * \return If it is connected, return true, otherwise return false. */
318 bool IsConnectedSrc(const FbxPropertyHandle& pSrc);
319
320 /** Connect destination property.
321 * \param pDst The given destination property
322 * \param pType The given property type
323 * \return If connect successfully, return true,otherwise, return false. */
324 bool ConnectDst(const FbxPropertyHandle& pDst, const FbxConnection::EType pType=FbxConnection::eDefault);
325
326 /** Get destination properties' count.
327 * \param pFilter The filter used to get sub connection point.If it is not zero,return the destination count of the sub connection point.
328 * Otherwise, return the destination count of this property.
329 * \return The count of destination properties */
330 int GetDstCount(FbxConnectionPointFilter* pFilter=0) const;
331
332 /** Get destination property with the given index.
333 * \param pFilter The filter used to get sub connection point.If it is not zero,return the destination property of the sub connection point.
334 * Otherwise, return the destination property of this property.
335 * \param pIndex The given index
336 * \return The destination property handle. */
337 FbxPropertyHandle GetDst(FbxConnectionPointFilter* pFilter=0, int pIndex=0) const;
338
339 /** Disconnect destination property.
340 * \param pDst The given destination property
341 * \return If disconnect successfully, return true,otherwise, return false. */
342 bool DisconnectDst(const FbxPropertyHandle& pDst);
343
344 /** Judge if it is connected with the given destination property.
345 * \param pDst The given destination property
346 * \return If it is connected, return true,otherwise, return false. */
347 bool IsConnectedDst(const FbxPropertyHandle& pDst);
348
349 //! Clear connect cache
350 void ClearConnectCache();
351
352 //! Clear all connect without sending any notification (Internal use ONLY)
353 void WipeAllConnections();
354 //@}
355
356 /** \name Limits Functions
357 * Minimum and maximum value limits can be associated with properties, but FBX
358 * will not verify that these limits are respected. FBX however will store and
359 * retrieve limits from files, and will assure that they are persistent in memory
360 * while the property handle object exists.
361 *
362 * Soft minimums and maximums values are specifying a second set of limits that can be
363 * used for UI objects such as sliders. FBX will handle them the same way it does
364 * with the normal limits. */
365 //@{
366 /** Judge if this property has a minimum value.
367 * \return If the minimum value exist, return true,otherwise, return false. */
368 bool HasMin() const;
369
370 /** Get the minimum value and value type of this property.
371 * \param pValue The minimum value of this property.
372 * \param pValueType The value type of this property.
373 * \return If the minimum value exist, return true,otherwise, return false. */
374 bool GetMin(void* pValue, EFbxType pValueType) const;
375
376 /** Set the minimum value and value type for this property.
377 * \param pValue The given minimum value .
378 * \param pValueType The given value type .
379 * \return If it be set successfully, return true,otherwise, return false. */
380 bool SetMin(const void* pValue, EFbxType pValueType);
381
382 /** According the given value and its value type, set the minimum value and value type for this property.
383 * \param pValue The given value .
384 * \return If it be set successfully, return true,otherwise, return false.
385 */
386 template <class T> inline bool SetMin(const T& pValue){ return SetMin(&pValue, FbxTypeOf(pValue)); }
387
388 /** Get the minimum value of this property.
389 * \param pFBX_TYPE Not used in this function. This is a dummy argument for
390 * the correct instantiation of the templated function.
391 * \return The minimum value of this property */
392 template <class T> inline T GetMin(const T* pFBX_TYPE) const { T lValue; GetMin(&lValue, FbxTypeOf(lValue)); return lValue; }
393
394 /** Judge if this property has soft minimum value.
395 * \return If the soft minimum value exist, return true,otherwise, return false. */
396 bool HasSoftMin() const;
397
398 /** Get the soft minimum value and value type of this property.
399 * \param pValue The soft minimum value of this property.
400 * \param pValueType The value type of this property.
401 * \return If the soft minimum value exist, return true,otherwise, return false. */
402 bool GetSoftMin(void* pValue, EFbxType pValueType) const;
403
404 /** Set the soft minimum value and value type for this property.
405 * \param pValue The given soft minimum value .
406 * \param pValueType The given value type .
407 * \return If it be set successfully, return true,otherwise, return false. */
408 bool SetSoftMin(const void* pValue, EFbxType pValueType);
409
410 /** According the given value and its value type, set the soft minimum value and value type for this property.
411 * \param pValue The given value .
412 * \return If it be set successfully, return true,otherwise, return false. */
413 template <class T> inline bool SetSoftMin(const T& pValue){ return SetSoftMin(&pValue, FbxTypeOf(pValue)); }
414
415 /** Get the soft minimum value of this property.
416 * \param pFBX_TYPE Not used in this function. This is a dummy argument for
417 * the correct instantiation of the templated function.
418 * \return The soft minimum value of this property */
419 template <class T> inline T GetSoftMin(const T* pFBX_TYPE) const { T lValue; GetSoftMin(&lValue, FbxTypeOf(lValue)); return lValue; }
420
421 /** Judge if this property has maximum value.
422 * \return If the maximum value exist, return true,otherwise, return false. */
423 bool HasMax() const;
424
425 /** Get the maximum value and value type of this property.
426 * \param pValue The maximum value of this property.
427 * \param pValueType The value type of this property.
428 * \return If the maximum value exist, return true,otherwise, return false. */
429 bool GetMax(void* pValue, EFbxType pValueType) const;
430
431 /** Set the maximum value and value type for this property.
432 * \param pValue The given maximum value .
433 * \param pValueType The given value type .
434 * \return If it be set successfully, return true,otherwise, return false. */
435 bool SetMax(const void* pValue, EFbxType pValueType);
436
437 /** According the given value and its value type, set the maximum value and value type for this property.
438 * \param pValue The given value .
439 * \return If it be set successfully, return true,otherwise, return false. */
440 template <class T> inline bool SetMax(const T& pValue){ return SetMax(&pValue, FbxTypeOf(pValue)); }
441
442 /** Get the maximum value of this property.
443 * \param pFBX_TYPE Not used in this function. This is a dummy argument for
444 * the correct instantiation of the templated function.
445 * \return The maximum value of this property */
446 template <class T> inline T GetMax(const T* pFBX_TYPE) const { T lValue; GetMax(&lValue, FbxTypeOf(lValue)); return lValue; }
447
448 /** Judge if this property has soft maximum value.
449 * \return If the soft maximum value exist, return true,otherwise, return false. */
450 bool HasSoftMax() const;
451
452 /** Get the soft maximum value and value type of this property.
453 * \param pValue The soft maximum value of this property.
454 * \param pValueType The value type of this property.
455 * \return If the soft maximum value exist, return true,otherwise, return false. */
456 bool GetSoftMax(void* pValue, EFbxType pValueType) const;
457
458 /** Set the soft maximum value and value type for this property.
459 * \param pValue The given soft maximum value .
460 * \param pValueType The given value type .
461 * \return If it be set successfully, return true,otherwise, return false. */
462 bool SetSoftMax(const void* pValue, EFbxType pValueType);
463
464 /** According the given value and its value type, set the soft maximum value and value type for this property.
465 * \param pValue The given value .
466 * \return If it be set successfully, return true,otherwise, return false. */
467 template <class T> inline bool SetSoftMax(const T& pValue){ return SetSoftMax(&pValue, FbxTypeOf(pValue)); }
468
469 /** Get the soft maximum value of this property.
470 * \param pFBX_TYPE Not used in this function. This is a dummy argument for
471 * the correct instantiation of the templated function.
472 * \return The soft maximum value of this property */
473 template <class T> inline T GetSoftMax(const T* pFBX_TYPE) const { T lValue; GetSoftMax(&lValue, FbxTypeOf(lValue)); return lValue; }
474 //@}
475
476 /**
477 * \name Value
478 */
479 //@{
480 /** Get value inherit type of this property.
481 * \param pCheckReferences If it is true,check instance of this property page,otherwise,only check this page.
482 * \return The value inherit type of this property */
483 FbxPropertyFlags::EInheritType GetValueInheritType(bool pCheckReferences) const;
484
485 /** Set value inherit type for this property .
486 * \param pType The given value inherit type.
487 * \return If set successfully, return true,otherwise, return false. */
488 bool SetValueInheritType(FbxPropertyFlags::EInheritType pType);
489
490 /** Get default value and value type of this property .
491 * \param pValue The gotten default value of this property.
492 * \param pValueType The gotten default value type of this property.
493 * \return If default value be gotten successfully, return true,otherwise, return false. */
494 bool GetDefaultValue(void* pValue, EFbxType pValueType) const;
495
496 /** Get value and value type of this property .
497 * \param pValue The gotten value of this property.
498 * \param pValueType The gotten value type of this property.
499 * \return If value be gotten successfully, return true,otherwise, return false. */
500 bool Get(void* pValue, EFbxType pValueType) const;
501
502 /** Set property value and value type for this property.
503 * \param pValue The given property value .
504 * \param pValueType The given property value type
505 * \param pCheckValueEquality If it is true, when the given value is equal with
506 * the property value, the property value will not be set.
507 * \return If the property value be set successfully, return true,otherwise, return false. */
508 bool Set(const void* pValue, EFbxType pValueType, bool pCheckValueEquality);
509
510 /** Set property value with the given value .
511 * \param pValue The given value .
512 * \return If set successfully, return true,otherwise, return false. */
513 template <class T> inline bool Set(const T& pValue){ return Set(&pValue, FbxTypeOf(pValue)); }
514
515 /** get property value.
516 * \param pFBX_TYPE Not be used.
517 * \return The gotten property value. */
518 template <class T> inline T Get(const T* pFBX_TYPE) const { T lValue; Get(&lValue, FbxTypeOf(lValue)); return lValue; }
519 //@}
520
521 /**
522 * \name Page settings
523 */
524 //@{
525 /** Set the property page data pointer.
526 * \param pData The given page data pointer. */
527 void SetPageDataPtr(void* pData);
528
529 /** Get property page data pointer.
530 * \return The gotten property page data pointer. */
531 void* GetPageDataPtr() const;
532 //@}
533
534 /**
535 * \name Page Internal Entry Management
536 */
537 //@{
538 /** Push properties to parent instance.
539 * \return If push successful return true,otherwise,return false. */
540 bool PushPropertiesToParentInstance();
541 //@}
542
543 /**
544 * \name Reference Management
545 */
546 //@{
547 /** Judge if this property page is a instance of other page.
548 * \return If this property page is a instance of other page, return true,otherwise,return false. */
549 bool IsAReferenceTo(void) const;
550
551 /** Get the property page which this property page make reference to
552 * \return The property page which this property page make reference to */
553 void* GetReferenceTo(void) const;
554
555 /** Judge if this property page is referenced by other pages.
556 * \return If this property page is referenced by other pages, return true,otherwise,return false. */
557 bool IsReferencedBy(void) const;
558
559 /** Get the count of property pages which make reference to this property page.
560 * \return The count of property pages which make reference to this property page. */
561 int GetReferencedByCount(void) const;
562
563 /** According the given index,get the property page which make reference to this property page.
564 * \param pIndex The given index
565 * \return The pointer to the property page which reference to this property page and be found by index. */
566 void* GetReferencedBy(int pIndex) const;
567 //@}
568
569private:
570 FbxPropertyPage* mPage;
571 FbxInt mId;
572};
573
574#include <fbxsdk/fbxsdk_nsend.h>
575
576#endif /* _FBXSDK_CORE_PROPERTY_HANDLE_H_ */
577