Jamoma API  0.6.0.a19
TTData.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup modularLibrary
4  *
5  * @brief A Data Object
6  *
7  * @details Establishes a control point, which is to say a TTNode that is dramaticly expanded, for a model to get/set its state.
8  *
9  * @authors Théo de la Hogue
10  *
11  * @copyright © 2010, Théo de la Hogue @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 // TODO: ramp should only be enabled (for real) for mType = "integer", "decimal" and "array"
18 // TODO: dataspace should only be enabled (for real) for mType = "integer", "decimal" and "array"
19 
20 #ifndef __TT_DATA_H__
21 #define __TT_DATA_H__
22 
23 #include "TTModularIncludes.h"
24 
25 /** TTData establishes a control point, which is to say a TTNode that is dramaticly expanded, for a model to get/set its state.
26  @details In Max the externals j.parameter, j.message and j.return externals are based on #TTData
27  */
28 class TTMODULAR_EXPORT TTData : public TTCallback
29 {
31 
32 private:
33 
34  TTValue mValue; ///< ATTRIBUTE: data's value
35  TTValue mValueDefault; ///< ATTRIBUTE: data's default value
36  TTValue mValueStepsize; ///< ATTRIBUTE: amount to increment or decrement by
37 
38  TTSymbol mType; ///< ATTRIBUTE: type of this data's value
39  TTValue mTags; ///< ATTRIBUTE: tag list for this data
40  TTInt32 mPriority; ///< ATTRIBUTE: does this data have a priority over other datas ?
41  TTSymbol mDescription; ///< ATTRIBUTE: text to describe the role of this data
42  TTBoolean mRepetitionsFilter; ///< ATTRIBUTE: is repetitions are filtered out ?
43  TTBoolean mActive; ///< ATTRIBUTE: this used by return only to stop sending values
44  TTBoolean mInitialized; ///< ATTRIBUTE: is the Value attribute has been initialized ?
45 
46  TTValue mRangeBounds; ///< ATTRIBUTE: the range bounds for this data's value
47  TTSymbol mRangeClipmode; ///< ATTRIBUTE: what clip mode to apply if proposed value is outside the range set by #mRangeBounds. Implemented options are none, both, low or high.
48 
49  TTBoolean mDynamicInstances; ///< ATTRIBUTE: is the data can be dynamically instanciated
50  TTValue mInstanceBounds; ///< ATTRIBUTE: two TTValues for a range of dynamic instances (-1 = infini)
51 
52 
53  TTSymbol mRampDrive; ///< ATTRIBUTE: ramp mode // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
54  TTSymbol mRampDriveDefault; ///< ATTRIBUTE: default ramp mode to set when the type change
55 #ifndef TT_NO_DSP
56  TTSymbol mRampFunction; ///< ATTRIBUTE: for setting the function used by the ramping // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
57 #endif
58  TTValue mRampFunctionParameters; ///< ATTRIBUTE: names of parameter's function // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
59  TTBoolean mRampStatus; ///< ATTRIBUTE: is the ramp running ? // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
60 
61  TTSymbol mDataspace; ///< ATTRIBUTE: The dataspace that this data uses (default is 'none') // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
62  TTSymbol mDataspaceUnit; ///< ATTRIBUTE: The unit within the dataspace // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
63  TTBoolean mIsOverridingDataspaceUnit; ///< FLag indicating that this object is currently ramping to a new value using a dataspace unit that temporarily overrides #mDataspaceUnit
64  TTObject mDataspaceConverter; ///< Performs conversions from input unit to the data unit
65  TTObject mDataspaceInverseConverter; ///< Used to convert current #mValue from default #mDataspaceUnit to temporary dataspace unit when setting up a ramp that will temporarily override the default unit.
66 
67  TTSymbol mService; ///< how the data flows into our environnement :
68  ///< as parameter : the data is in full access mode
69  ///< as message : the data don't notify observers it's changing but the value is still returned to his owner
70  ///< as return : the value is not returned to his owner anymore but the data notify observers it's changing
71  ///< Notice that in each case the value can be queried using a getAttributeValue method.
72 
73  TTBoolean mIsSending; ///< Flag to tell us if we are currently sending out our Value attribute
74 
75  TTObject mRamper; ///< Ramp object to ramp value
76 
77  TTMethodValue commandMethod; ///< a specific method depending on mType.
78  ///< we need to wrap the call on specific command methods because a command can be parsed locally (so it have to be deleted after to not create memory leaks)
79 
80  TTAttributePtr valueAttribute; ///< cache value attribute for observer notification
81  TTAttributePtr initializedAttribute; ///< cache value message for observer notification
82 
83  TTFloat64 externalRampTime; ///< only usefull for external ramp drive
84 
85 
86  /** Prepares a command to update the value of TTValue.
87  @param[in] inputValue A command to update the value of #TTData. The command might set value, specify a unit for it, and also request that the change happens as a ramp. If this is a single #TTDictionary, it is passed directly on to the appropriate command for the #TTData type (decimal, integer, etc..), else it is first converted to a #TTDictionary before being passed on.
88  @param[out] outputValue This is not being used.
89  @return #TTErrorNone if the method executes successfully, else an error code.
90  @see #TTDataParseCommand
91  */
92  TTErr Command(const TTValue& inputValue, TTValue& outputValue);
93 
94 
95  /** Prepares a command to update the value of TTValue, optimised for Data of #mType #kTTSym_none.
96  @param[in] inputValue A command to update the value of #TTData. The command might set value, specify a unit for it, and also request that the change happens as a ramp. If this is a single #TTDictionary, it is passed directly on to the appropriate command for the #TTData type (decimal, integer, etc..), else it is first converted to a #TTDictionary before being passed on.
97  @param[out] outputValue This is not being used.
98  @return #TTErrorNone if the method executes successfully, else an error code.
99  @see #TTDataParseCommand
100  */
101  TTErr NoneCommand(const TTValue& inputValue, TTValue& outputValue);
102 
103 
104  /** Prepares a command to update the value of TTValue, optimised for Data of #mType #kTTSym_generic.
105  @param[in] inputValue A command to update the value of #TTData. The command might set value, specify a unit for it, and also request that the change happens as a ramp. If this is a single #TTDictionary, it is passed directly on to the appropriate command for the #TTData type (decimal, integer, etc..), else it is first converted to a #TTDictionary before being passed on.
106  @param[out] outputValue This is not being used.
107  @return #TTErrorNone if the method executes successfully, else an error code.
108  @see #TTDataParseCommand
109  */
110  TTErr GenericCommand(const TTValue& inputValue, TTValue& outputValue);
111 
112 
113  /** Prepares a command to update the value of TTValue, optimised for Data of #mType #kTTSym_boolean.
114  @param[in] inputValue A command to update the value of #TTData. The command might set value, specify a unit for it, and also request that the change happens as a ramp. If this is a single #TTDictionary, it is passed directly on to the appropriate command for the #TTData type (decimal, integer, etc..), else it is first converted to a #TTDictionary before being passed on.
115  @param[out] outputValue This is not being used.
116  @return #TTErrorNone if the method executes successfully, else an error code.
117  @see #TTDataParseCommand
118  */
119  TTErr BooleanCommand(const TTValue& inputValue, TTValue& outputValue);
120 
121 
122  /** Prepares a command to update the value of TTValue, optimised for Data of #mType #kTTSym_decimal, #kTTSym_integer and #kTTSym_array.
123  There are the types whre dataspace and ramping can be used at the same time.
124  @param[in] inputValue A command to update the value of #TTData. The command might set value, specify a unit for it, and also request that the change happens as a ramp. If this is a single #TTDictionary, it is passed directly on to the appropriate command for the #TTData type (decimal, integer, etc..), else it is first converted to a #TTDictionary before being passed on.
125  @param[out] outputValue This is not being used.
126  @return #TTErrorNone if the method executes successfully, else an error code.
127  @see #TTDataParseCommand
128  */
129  TTErr IntegerDecimalArrayCommand(const TTValue& inputValue, TTValue& outputValue);
130 
131 
132  /** Prepares a command to update the value of TTValue, optimised for Data of #mType #kTTSym_string.
133  @param[in] inputValue A command to update the value of #TTData. The command might set value, specify a unit for it, and also request that the change happens as a ramp. If this is a single #TTDictionary, it is passed directly on to the appropriate command for the #TTData type (decimal, integer, etc..), else it is first converted to a #TTDictionary before being passed on.
134  @param[out] outputValue This is not being used.
135  @return #TTErrorNone if the method executes successfully, else an error code.
136  @see #TTDataParseCommand
137  */
138  TTErr StringCommand(const TTValue& inputValue, TTValue& outputValue);
139 
140 
141  /** Setter for #mValue attribute, performs typechecking and calls the appropriate optimised setter method.
142  @param value The new value that the attribute is to be set to.
143  @return #TTErrorNone if the method executes successfully, else an error code.
144  */
145  TTErr getValue(TTValue& value);
146 
147 
148  /** Setter for #mValue attribute, optimised for #mType #kTTSym_none.
149  @param value The new value that the attribute is to be set to.
150  @return #TTErrorNone if the method executes successfully, else an error code.
151  */
152  TTErr setNoneValue(const TTValue& value);
153 
154 
155  /** Setter for #mValue attribute, optimised for #mType #kTTSym_boolean.
156  @param value The new value that the attribute is to be set to.
157  @return #TTErrorNone if the method executes successfully, else an error code.
158  */
159  TTErr setBooleanValue(const TTValue& value);
160 
161 
162  /** Setter for #mValue attribute, optimised for #mType #kTTSym_generic.
163  @param value The new value that the attribute is to be set to.
164  @return #TTErrorNone if the method executes successfully, else an error code.
165  */
166  TTErr setGenericValue(const TTValue& value);
167 
168 
169  /** Setter for #mValue attribute, optimised for #mType #kTTSym_integer, #kTTSym_decimal and #kTTSym_array.
170  These are the types whre dataspace and ramping can be used at the same time.
171  @param[in] The new value that the attribute is to be set to.
172  @return #TTErrorNone if the method executed successfully, elseway an error code.
173  */
174  TTErr setIntegerDecimalArrayValue(const TTValue& value);
175 
176 
177  /** Setter for #mValue attribute, optimised for #mType #kTTSym_string.
178  @param value The new value that the attribute is to be set to.
179  @return #TTErrorNone if the method executes successfully, else an error code.
180  */
181  TTErr setStringValue(const TTValue& value);
182 
183  /** */
184  TTBoolean checkBooleanType(const TTValue& value);
185  TTBoolean checkIntegerType(const TTValue& value);
186  TTBoolean checkIntegerDecimalArrayType(const TTValue& value);
187  TTBoolean checkArrayType(const TTValue& value);
188  TTBoolean checkStringType(const TTValue& value);
189 
190 
191  /* Clips the value according to the values of the #mRangeBounds and #mRangeClipmode attributes.
192  @return boolean value, depending on the result. This is currently not being used.
193  */
194  TTBoolean clipValue();
195 
196 
197  /* Return current #mValue to all observers.
198  @return #TTErrorNone if the method executes successfully, else an error code.
199  */
200  TTErr returnValue();
201 
202 
203  /** Initialize the value with default value */
204  TTErr NoneInit();
205  TTErr GenericInit();
206  TTErr BooleanInit();
207  TTErr IntegerInit();
208  TTErr DecimalInit();
209  TTErr ArrayInit();
210  TTErr StringInit();
211 
212 
213  /** Ramper messages */
214  // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
215  TTErr RampSet(const TTValue& inputValue, TTValue& outputValue);
216 
217 
218  // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
219  TTErr RampTarget(const TTValue& inputValue, TTValue& outputValue);
220 
221 
222  // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
223  TTErr RampGo(const TTValue& inputValue, TTValue& outputValue);
224 
225 
226  // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
227  TTErr RampSlide(const TTValue& inputValue, TTValue& outputValue);
228 
229  /** Increment mValue attribute (and ramp this incrementation)
230  It depends on the command size :
231  1 : 1 incrementation step
232  3 : 1 incrementation step + ramp ramptime
233  default : no value or wrong value
234  */
235  TTErr Inc(const TTValue& inputValue, TTValue& outputValue);
236 
237 
238  /** Decrement mValue attribute (and ramp this decrementation)
239  It depends on the command size :
240  1 : 1 decrementation step
241  3 : 1 decrementation step + ramp ramptime
242  default : no value or wrong value
243  */
244  TTErr Dec(const TTValue& inputValue, TTValue& outputValue);
245 
246  /** Getter and Setter for mValueDefault attribute. */
247  TTErr getValueDefault(TTValue& value);
248  TTErr setValueDefault(const TTValue& value);
249 
250  /** Getter for mValueStepsize attribute.
251  */
252  TTErr getValueStepsize(TTValue& value);
253 
254 
255  /** Setter for mValueStepsize attribute.
256  */
257  TTErr setValueStepsize(const TTValue& value);
258 
259 
260  /** Setter for #mType attribute.
261  @details This methods also sets what type-optimised methods to use to initiate #TTData and for commands. Commands are used to update mValue instantly or by ramping to a new target value over time, and might also specify new (target) value using various dataspace units.
262  @param value The desired value for #mType.
263  @return #TTErrorNone if the method executes successfully, else an error code.
264  */
265  TTErr setType(const TTValue& value);
266 
267 
268  /** Setter for mTags attribute.
269  */
270  TTErr setTags(const TTValue& value);
271 
272 
273  /** Setter for mRepetitionsFilter attribute.
274  */
275  TTErr setRepetitionsFilter(const TTValue& value);
276 
277 
278  /** Setter for mActive attribute.
279  */
280  TTErr setActive(const TTValue& value);
281 
282 
283  /** Setter for mRangeBounds attribute.
284  */
285  TTErr setRangeBounds(const TTValue& value);
286 
287 
288  /** Setter for mRangeClipmode attribute.
289  */
290  TTErr setRangeClipmode(const TTValue& value);
291 
292 
293  /** Setter for mInstanceBounds attribute.
294  */
295  TTErr setInstanceBounds(const TTValue& value);
296 
297 
298  /** Setter for mRampDrive attribute.
299  */
300  // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
301  TTErr setRampDrive(const TTValue& value);
302 
303 
304 #ifndef TT_NO_DSP
305  /** Setter for mRampFunction attribute.
306  */
307  // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
308  TTErr setRampFunction(const TTValue& value);
309 #endif
310 
311 
312  /** Setter for mDataspace attribute.
313  */
314  // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
315  TTErr setDataspace(const TTValue& value);
316 
317 
318  /** Setter for mDataspaceUnit attribute.
319  */
320  // TODO: Jamomacore #294 : Ease the access of the object of a kTypeObject attribute of a TTObject
321  TTErr setDataspaceUnit(const TTValue& value);
322 
323 
324  /** Setter for mDescription attribute.
325  */
326  TTErr setDescription(const TTValue& value);
327 
328 
329  /** Setter for mPriority attribute.
330  */
331  TTErr setPriority(const TTValue& value);
332 
333 
334  /** needed to be handled by a TTTextHandler
335  */
336  TTErr WriteAsText(const TTValue& inputValue, TTValue& outputValue);
337 
338 
339  /** Convert value from temporary dataspace unit to the unit specified by #mDataspaceUnit
340  */
341  TTErr convertUnit(const TTValue& inputValue, TTValue& outputValue);
342 
343 
344  /** Convert value from the dataspace unit specified by #mDataspaceUnit to the temporary unit
345  */
346  TTErr inverseConvertUnit(const TTValue& inputValue, TTValue& outputValue);
347 
348 
349  /**
350  */
351  TTErr notifyObservers(TTSymbol attrName, const TTValue& value);
352 
353 
354  /**
355  */
356  TTErr rampSetup();
357 
358 
359  /**
360  */
361  friend void TTMODULAR_EXPORT TTDataRampCallback(void *o, TTUInt32 n, TTFloat64 *v);
362 };
363 typedef TTData* TTDataPtr;
364 
365 
366 /** Format the command to update the value of #TTData as a #TTDictionary. When updating the value we can make use of the #TTDapaspaceLib to provide new value with various measurement units, and we can set it to ramp (ease) to the new value over time making use of #TTDataRamp.
367  @param[in] commandValue A #TTValue containing one or more elements, taking the form of @n
368  < value (unit:optional) (ramp ramptime : optional) >
369  @n
370  Interprtation of the command depends on the command size : @n
371  @n
372  @n When parsing, we check how many elements we have, and interprete as follows:
373  - 1 element: A new value @n
374  - 2 elements: An array of 2 values OR
375  one value and a unit @n
376  - 3 elements: An array of 3 values OR
377  a array of 2 values and a unit OR
378  a single value, the "ramp" symbol and a ramp time @n
379  - X elements: An array of X values OR
380  an array of X-1 values and a unit OR
381  an array of X-2 values, the "ramp" symbol and a ramp time OR
382  X-3 values, a unit, the "ramp" string and a ramp time.
383  @param[in] parseUnitAndRamp to just store the commandValue into a dictionary whithout processing any parsing
384  @return A dictionary with one or more keys: It always has a value. If it is ramping, it also has a ramp key, and if it has a unit, it also has a unit key.
385  */
386 TTDictionaryBasePtr TTMODULAR_EXPORT TTDataParseCommand(const TTValue& commandValue, TTBoolean parseUnitAndRamp = YES);
387 
388 
389 /**
390  @param baton ..
391  @param data ..
392  @return an error code */
393 void TTMODULAR_EXPORT TTDataRampCallback(void *o, TTUInt32 n, TTFloat64 *v);
394 
395 
396 #endif // __TT_DATA_H__
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
TTModular Library.
This class is used to be sensitive to any TTObject notifications and report them using a function wit...
Definition: TTCallback.h:28
A type that contains a key and a value.
void TTMODULAR_EXPORT TTDataRampCallback(void *o, TTUInt32 n, TTFloat64 *v)
Definition: TTData.cpp:844
Create and use Jamoma object instances.
Definition: TTObject.h:29
TTErr(TTObjectBase::* TTMethodValue)(const TTValue &anInputValue, TTValue &anOutputValue)
A type that can be used to call a message for an object that does not declare the name argument...
Definition: TTObjectBase.h:52
This class represents a single attribute, as used by the TTObjectBase class.
Definition: TTAttribute.h:79
double TTFloat64
64 bit floating point number
Definition: TTBase.h:188
#define TTCLASS_SETUP(className)
TODO Doxygen: need more comments here.
Definition: TTFoundation.h:54
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTDictionaryBasePtr TTMODULAR_EXPORT TTDataParseCommand(const TTValue &commandValue, TTBoolean parseUnitAndRamp=YES)
Format the command to update the value of TTData as a TTDictionary.
Definition: TTData.cpp:703
std::int32_t TTInt32
32 bit signed integer
Definition: TTBase.h:177
TTData establishes a control point, which is to say a TTNode that is dramaticly expanded, for a model to get/set its state.
Definition: TTData.h:28
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
std::uint32_t TTUInt32
32 bit unsigned integer
Definition: TTBase.h:178
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34