Jamoma API  0.6.0.a19
TTAttribute.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup foundationLibrary
4  *
5  * @brief The TTAttribute class represents a single attribute, as used by the TTObjectBase class.
6  *
7  * @details
8  *
9  * @author Timothy Place, Theo de la Hogue, Nils Peters, Trond Lossius
10  *
11  * @copyright Copyright © 2008, Timothy Place @n
12  * This code is licensed under the terms of the "New BSD License" @n
13  * http://creativecommons.org/licenses/BSD/
14  */
15 
16 
17 #ifndef __TT_ATTRIBUTE_H__
18 #define __TT_ATTRIBUTE_H__
19 
20 #include "TTObjectBase.h"
21 
22 // for now, we support the old macros...
23 #define SUPPORT_OLD_ATTRIBUTE_REGISTRATION
24 
25 /** A convenience macro to be used by subclasses for registering attributes with a custom getter.
26  @param name The name of the attribute, which is also the name of the classes' member holding the value, and used for the getter method name.
27  @param type The type of the value.
28 */
29 #define addAttribute(name, type) TTString _attrname_##name(#name); _attrname_##name.at(0)=tolower(_attrname_##name.at(0)); registerAttribute(_attrname_##name, type, &m##name)
30 #ifdef SUPPORT_OLD_ATTRIBUTE_REGISTRATION
31 #define registerAttributeSimple(name, type) registerAttribute(#name, type, &name)
32 #endif
33 
34 /** A convenience macro to be used by subclasses for registering attributes with a custom getter.
35  @param name The name of the attribute, which is also the name of the classes' member holding the value, and used for the getter method name.
36  @param type The type of the value.
37 */
38 #define addAttributeWithGetter(name, type) TTString _attrname_##name(#name); _attrname_##name.at(0)=tolower(_attrname_##name.at(0)); registerAttribute(_attrname_##name, type, &m##name, (TTGetterMethod)& thisTTClass ::get##name )
39 #ifdef SUPPORT_OLD_ATTRIBUTE_REGISTRATION
40 #define registerAttributeWithGetter(name, type) registerAttribute(#name, type, &name, (TTGetterMethod)& thisTTClass ::get##name )
41 #endif
42 
43 /** A convenience macro to be used by subclasses for registering attributes with a custom setter.
44  @param name The name of the attribute, which is also the name of the classes' member holding the value, and used for the setter method name.
45  @param type The type of the value.
46 */
47 #define addAttributeWithSetter(name, type) TTString _attrname_##name(#name); _attrname_##name.at(0)=tolower(_attrname_##name.at(0)); registerAttribute(_attrname_##name, type, &m##name, (TTSetterMethod)& thisTTClass ::set##name )
48 #ifdef SUPPORT_OLD_ATTRIBUTE_REGISTRATION
49 #define registerAttributeWithSetter(name, type) registerAttribute(#name, type, &name, (TTSetterMethod)& thisTTClass ::set##name )
50 #endif
51 
52 /** A convenience macro to be used by subclasses for registering attributes with a custom getter and setter.
53  Note that we don't bother passing the address of the value in this macro, because the default setter/getter is not used to access it.
54  @param name The name of the attribute, which is also the name of the classes' member holding the value, and used for the getter/setter method names.
55  @param type The type of the value.
56 */
57 #define addAttributeWithGetterAndSetter(name, type) TTString _attrname_##name(#name); _attrname_##name.at(0)=tolower(_attrname_##name.at(0)); registerAttribute(_attrname_##name, type, NULL, (TTGetterMethod)& thisTTClass ::get##name, (TTSetterMethod)& thisTTClass ::set##name )
58 #ifdef SUPPORT_OLD_ATTRIBUTE_REGISTRATION
59 #define registerAttributeWithSetterAndGetter(name, type) registerAttribute(#name, type, NULL, (TTGetterMethod)& thisTTClass ::get##name, (TTSetterMethod)& thisTTClass ::set##name )
60 #endif
61 
62 
63 /** A convenience macro to be used for registering properties of attributes.
64  This assumes that the property is one that has been explicitly supported by TTAttribute through the definition of accessor methods.
65  If you are adding a custom property then you must define your own accessor methods and register the property by calling the
66  TTObjectBase::registerAttributeProperty() method directly.
67 */
68 #define addAttributeProperty(attributeName, propertyName, initialValue) registerAttributeProperty(_attrname_##attributeName, #propertyName, initialValue, (TTGetterMethod)& TTAttribute::get##propertyName , (TTSetterMethod)& TTAttribute::set##propertyName )
69 
70 /****************************************************************************************************/
71 // Class Specifications
72 
73 
74 /**
75  This class represents a single attribute, as used by the TTObjectBase class.
76  At the moment we define it in the same file because we are sharing the typedef
77  for TTMethod.
78 */
79 class TTFOUNDATION_EXPORT TTAttribute : public TTObjectBase {
80 private:
81 public:
82  // Should make this group private, but to get things working initially, we're leaving them public...
83  const TTSymbol name; ///< The name of the attribute.
84  TTDataType type; ///< The data type of the attribute value.
85  void* address; ///< Pointer to the memory holding the attribute value.
86  TTGetterMethod getter; ///< Method to fetch the attribute value.
87  TTSetterMethod setter; ///< Method to set the attribute value.
88  const TTObjectBasePtr getterObject; ///< TTObjectBasePtr to fetch the attribute value.
89  const TTObjectBasePtr setterObject; ///< TTObjectBasePtr to set the attribute value.
90  TTAttributeFlags getterFlags; ///< Define the behavior of the attribute getter method.
91  TTAttributeFlags setterFlags; ///< Define the behavior of the attribute setter method.
92  TTValue internalValue; ///< Attributes that maintain their own data use this member to store it.
93  ///< This should typically only be used by attribute properties that are not performance critical.
94  TTBoolean readOnly; ///< The readonly property, if defined, means an attribute cannot be set.
95  TTFloat64 rangeLowBound; ///< If the range property is defined, this is the bottom of a value's range.
96  TTFloat64 rangeHighBound; ///< If the range property is defined, this is the top of a value's range.
97  TTSymbol rangeChecking; ///< If the rangeChecking property is defined, the value should be checked for range and modified accordingly.
98  TTBoolean hidden; ///< Property: this attribute is private/invisible to the outside world
99  TTSymbol description; ///< Property: description of this attribute
100  TTValue mDefaultValue; ///< Property: the default value for this attribute
101 
102  /** Object constructor.
103  */
104  TTAttribute(const TTSymbol newName, TTDataType newType, void* newAddress);
105  TTAttribute(const TTSymbol newName, TTDataType newType, void* newAddress, TTGetterMethod newGetter);
106  TTAttribute(const TTSymbol newName, TTDataType newType, void* newAddress, TTSetterMethod newSetter);
107  TTAttribute(const TTSymbol newName, TTDataType newType, void* newAddress, TTGetterMethod newGetter, TTSetterMethod newSetter);
108  TTAttribute(const TTSymbol newName, const TTObjectBasePtr newGetterObject, const TTObjectBasePtr newSetterObject);
109  TTAttribute(TTAttributePtr extendedAttribute, const TTObjectBasePtr extendedObject);
110 
111  /** Object destructor.
112  */
113  virtual ~TTAttribute();
114 
115  /** Set the getterFlag property of the attribute, defining the behavior of the attribute getter method.
116  @param newFlags The new value for the getterFlag property.
117  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
118  */
119  void setGetterFlags(TTAttributeFlags newFlags);
120 
121  /** Get the current getterFlag property of the attribute, describing the behavior of the attribute getter method.
122  @param currentFlags Pointer to a #TTValue used to return the current value of the getterFlag property.
123  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
124  */
125  void getGetterFlags(TTAttributeFlags& currentFlags);
126 
127  /** Set the setterFlag property of the attribute, defining the behavior of the attribute setter method.
128  @param newFlags The new value for the setterFlag property.
129  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
130  */
131  void setSetterFlags(TTAttributeFlags newFlags);
132 
133  /** Get the current setterFlag property of the attribute, describing the behavior of the attribute setter method.
134  @param currentFlags Pointer to a #TTValue used to return the current value of the setterFlag property.
135  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
136  */
137  void getSetterFlags(TTAttributeFlags& currentFlags);
138 
139  /** The default method for getting the current attribute value.
140  @param TTAttribute The attribute
141  @param TTValue Pointer to a #TTValue used to return the current value of the attribute.
142  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
143  */
144  TTErr defaultGetter(const TTAttribute& attribute, TTValue& value);
145 
146  /** The default method for setting the attribute value.
147  @param TTAttribute The attribute
148  @param TTValue The new value of the attribute.
149  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
150  */
151  TTErr defaultSetter(const TTAttribute& attribute, const TTValue& value);
152 
153  /** TODO: This needs to be documented.
154  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
155  */
156  TTErr callbackGetter(const TTAttribute& attribute, TTValue& value);
157 
158  /** TODO: This needs to be documented.
159  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
160  */
161  TTErr callbackSetter(const TTAttribute& attribute, TTValue& value);
162 
163  /** TODO: This needs to be documented.
164  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
165  */
166  TTErr extendedGetter(const TTAttribute& attribute, TTValue& value);
167 
168  /** TODO: This needs to be documented.
169  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
170  */
171  TTErr extendedSetter(const TTAttribute& attribute, TTValue& value);
172 
173 
174  /** Set the readOnly property of the attribute, controlling if the attribute value can be changed or not.
175  @param newReadOnlyValue The new value for the readOnly property.
176  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
177  */
178  TTErr setreadOnly(const TTValue& newReadOnlyValue);
179 
180 
181  /** Get the readOnly property of the attribute, controlling if the attribute value can be changed or not.
182  @param currentReadOnlyValue Pointer to a #TTValue used to return the current value of the readOnly property.
183  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
184  */
185  TTErr getreadOnly(TTValue& currentReadOnlyValue);
186 
187 
188  /** Set the range of possible values for the attribute.
189  @param newRange The new value for the range property.
190  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
191  */
192  TTErr setrange(const TTValue& newRange);
193 
194 
195  /** Get the range of possible values for the attribute.
196  @param currentRange Pointer to a #TTValue used to return the current value for the range property.
197  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
198  */
199  TTErr getrange(TTValue& currentRange);
200 
201 
202  /** Set the range boundary checking mode property for the attribute.
203  @param newRangeCheckingMode The new range range boundary checking mode property for the attribute.
204  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
205  */
206  TTErr setrangeChecking(const TTValue& newRangeCheckingMode);
207 
208 
209  /** Get the range boundary checking mode property for the attribute.
210  @param currentRangeCheckingMode Pointer to a #TTValue used to return the current value for the range boundary checking mode property.
211  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
212  */
213  TTErr getrangeChecking(TTValue& currentRangeCheckingMode);
214 
215  /** Set the hidden flag for the attribute, determining if this attribute is private/invisible to the outside world.
216  @param newHiddenFlag The new value for the hidden flag.
217  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
218  */
219  TTErr sethidden(const TTValue& newHiddenFlag);
220 
221  /** Get the hidden flag for the attribute, indicating if this attribute is private/invisible to the outside world.
222  @param currentHiddenFlag Pointer to a #TTValue used to return the current value for the hidden flag.
223  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
224  */
225  TTErr gethidden(TTValue& currentHiddenFlag);
226 
227  /** Set the description property of the attribute, used for documentation purposes.
228  @param newDescription The new value for the documentation property.
229  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
230  */
231  TTErr setdescription(const TTValue& newDescription);
232 
233  /** Get the description property of the attribute, used for documentation purposes.
234  @param returnedDescription Pointer to a #TTValue used to return the current value for the documentation property.
235  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
236  */
237  TTErr getdescription(TTValue& returnedDescription);
238 
239  TTErr setdefaultValue(const TTValue& aDefaultValue);
240  TTErr getdefaultValue(TTValue& aReturnedDefaultValue);
241 
242 };
243 
244 
245 #endif // __TT_ATTRIBUTE_H__
246 
const TTObjectBasePtr getterObject
TTObjectBasePtr to fetch the attribute value.
Definition: TTAttribute.h:88
TTErr(TTObjectBase::* TTSetterMethod)(const TTAttribute &attribute, const TTValue &value)
A type that can be used to store a pointer to a message for an object.
Definition: TTObjectBase.h:78
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
The Jamoma Object Base Class.
TTSymbol description
Property: description of this attribute.
Definition: TTAttribute.h:99
TTDataType type
The data type of the attribute value.
Definition: TTAttribute.h:84
void * address
Pointer to the memory holding the attribute value.
Definition: TTAttribute.h:85
TTValue internalValue
Attributes that maintain their own data use this member to store it.
Definition: TTAttribute.h:92
TTDataType
TTBlue Data Types Enumeration of data types used through out TTBlue, including the TTValue class and ...
Definition: TTBase.h:269
This class represents a single attribute, as used by the TTObjectBase class.
Definition: TTAttribute.h:79
TTValue mDefaultValue
Property: the default value for this attribute.
Definition: TTAttribute.h:100
TTSetterMethod setter
Method to set the attribute value.
Definition: TTAttribute.h:87
Base class for all first-class Jamoma objects.
Definition: TTObjectBase.h:109
double TTFloat64
64 bit floating point number
Definition: TTBase.h:188
TTBoolean hidden
Property: this attribute is private/invisible to the outside world.
Definition: TTAttribute.h:98
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
const TTObjectBasePtr setterObject
TTObjectBasePtr to set the attribute value.
Definition: TTAttribute.h:89
TTAttributeFlags setterFlags
Define the behavior of the attribute setter method.
Definition: TTAttribute.h:91
TTFloat64 rangeLowBound
If the range property is defined, this is the bottom of a value's range.
Definition: TTAttribute.h:95
const TTSymbol name
The name of the attribute.
Definition: TTAttribute.h:83
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
TTFloat64 rangeHighBound
If the range property is defined, this is the top of a value's range.
Definition: TTAttribute.h:96
TTAttributeFlags getterFlags
Define the behavior of the attribute getter method.
Definition: TTAttribute.h:90
TTAttributeFlags
Flags that determine the behavior of messages.
Definition: TTObjectBase.h:94
TTGetterMethod getter
Method to fetch the attribute value.
Definition: TTAttribute.h:86
TTSymbol rangeChecking
If the rangeChecking property is defined, the value should be checked for range and modified accordin...
Definition: TTAttribute.h:97
TTErr(TTObjectBase::* TTGetterMethod)(const TTAttribute &attribute, TTValue &value)
A type that can be used to store a pointer to a message for an object.
Definition: TTObjectBase.h:73
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34
TTBoolean readOnly
The readonly property, if defined, means an attribute cannot be set.
Definition: TTAttribute.h:94