Jamoma API  0.6.0.a19
TTMirror.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup modularLibrary
4  *
5  * @brief A Mirror Object
6  *
7  * @details
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 #ifndef __TT_MIRROR_H__
18 #define __TT_MIRROR_H__
19 
20 #include "TTModularIncludes.h"
21 
22 /** TTMirror ... TODO : an explanation
23 
24 
25  */
26 
27 
28 /** A convenience macro to be used for registering mirror attribute.
29  Note that we don't lower the attribute name because we use the name of an existing attribute.
30  @param name The TTSymbol name of the attribute.
31  @param type The type of the value.
32  */
33 #define addMirrorAttribute(name, type) TTObjectBase::registerAttribute(name, type, NULL, (TTGetterMethod)& TTMirror::getMirrorAttribute, (TTSetterMethod)& TTMirror::setMirrorAttribute )
34 
35 /** A convenience macro to be used for registering mirror cached attribute.
36  Note that we don't lower the attribute name because we use the name of an existing attribute.
37  @param name The TTSymbol name of the attribute.
38  @param type The type of the value.
39  */
40 #define addMirrorCachedAttribute(name, type) TTObjectBase::registerAttribute(name, type, NULL, (TTGetterMethod)& TTMirror::getMirrorCachedAttribute, (TTSetterMethod)& TTMirror::setMirrorCachedAttribute )
41 
42 /** TODO : how to have TTGetterMethod and TTSetterMethod for Mirror attribute Property ?
43 
44  A convenience macro to be used for registering properties of mirror attributes.
45  Note that we don't lower the attribute name because we use the name of an existing attribute.
46  @param name The TTSymbol name of the attribute.
47  @param propertyName The name of the property.
48  @param initialValue The value of the property.
49  */
50 //#define addMirrorAttributeProperty(name, propertyName, initialValue) registerAttributeProperty(name, TTSymbol(#propertyName), initialValue, (TTGetterMethod)& TTAttribute::get##propertyName , (TTSetterMethod)& TTAttribute::set##propertyName )
51 
52 
53 /** A convenience macro to be used for registering mirror message.
54  @param name The name of the message.
55  @param flag The flag of the message.
56  */
57 #define addMirrorMessage(name, flag) TTObjectBase::registerMessage(name, (TTMethod)& TTMirror::sendMirrorMessage , flag)
58 
59 /** TODO : how to have TTGetterMethod and TTSetterMethod for Mirror message Property ?
60 
61  A convenience macro to be used for registering properties of messages.
62  Note that we don't lower the message name because we use the name of an existing attribute.
63  @param name The TTSymbol name of the attribute.
64  @param propertyName The name of the property.
65  @param initialValue The value of the property.
66  */
67 //#define addMessageProperty(name, propertyName, initialValue) registerMessageProperty(name, TTSymbol(#propertyName), initialValue, (TTGetterMethod)& TTMessage::get##propertyName , (TTSetterMethod)& TTMessage::set##propertyName )
68 
69 
70 class TTMODULAR_EXPORT TTMirror : public TTObjectBase
71 {
73 
74 private:
75 
76  TTSymbol mType; ///< the type of the object binded by the mirror
77  TTBoolean mIsListening; ///< to not forget to disable listening when the Mirror will be destroyed
78 
79  TTObject mGetAttributeCallback; ///< a way to get the attribute value
80  TTObject mSetAttributeCallback; ///< a way to set the attribute value
81  TTObject mSendMessageCallback; ///< a way to send a message
82  TTObject mListenAttributeCallback; ///< a way to listen the attribute value
83 
84  TTHash mAttributeValueCache; ///< a hash table to cache attribute value (if no mGetAttributeCallback)
85 
86  TTErr getMirrorAttribute(TTAttribute& anAttribute, TTValue& value);
87  TTErr setMirrorAttribute(TTAttribute& anAttribute, const TTValue& value);
88 
89  TTErr getMirrorCachedAttribute(TTAttribute& anAttribute, TTValue& value);
90  TTErr setMirrorCachedAttribute(TTAttribute& anAttribute, const TTValue& value);
91 
92  TTErr sendMirrorMessage(const TTSymbol* messageName, const TTValue& inputValue, TTValue& outputValue);
93 
94  /** When the type doesn't refer to a known class, use this method to instantiate the attributes to mirror
95  @param inputValue all attribute names to mirror
96  @param outputValue nothing
97  @return #TTErr error code */
98  TTErr AttributesInstantiate(const TTValue& inputValue, TTValue& outputValue);
99 
100  /** When the type doesn't refer to a known class, use this method to instantiate the messages to mirror
101  @param inputValue all message names to mirror
102  @param outputValue nothing
103  @return #TTErr error code */
104  TTErr MessagesInstantiate(const TTValue& inputValue, TTValue& outputValue);
105 
106  /** Add an attribute to cache its value and avoid the use of mGetAttributeCallback
107  @param inputValue the name of an attribute to add to the cache, a pointer to a value to cache
108  @param outputValue nothing
109  @return #TTErr error code */
110  TTErr AttributeCache(const TTValue& inputValue, TTValue& outputValue);
111 
112  /** Remove an attribute to don't cache its and prefer to use mGetAttributeCallback if exist
113  @param inputValue the name of an attribute
114  @param outputValue nothing
115  @return #TTErr error code */
116  TTErr AttributeUncache(const TTValue& inputValue, TTValue& outputValue);
117 
118 public:
119  TTErr updateAttributeValue(const TTSymbol attributeName, TTValue& value);
120 
121  /** Enable the listening of an attribute value using protocol solution if exist.
122  @details you have to unregister all observers for notification on the attribute before to disable the listening
123  @param inputValue a TTAttribute object, a TTBoolean value to enable/disable
124  @param outputValue nothing
125  @return #TTErr error code */
126  TTErr enableListening(const TTAttribute& anAttribute, TTBoolean enable);
127 
128  // over writting of the TTObjectBase::getName() method
129  TTSymbol getName();
130 
131 };
132 
133 typedef TTMirror* TTMirrorPtr;
134 
135 #endif // __TT_MIRROR_H__
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
TTModular Library.
TTSymbol getName() const
Return the name of this class.
Create and use Jamoma object instances.
Definition: TTObject.h:29
This class represents a single attribute, as used by the TTObjectBase class.
Definition: TTAttribute.h:79
Base class for all first-class Jamoma objects.
Definition: TTObjectBase.h:109
Maintain a collection of TTValue objects indexed by TTSymbol pointers.
Definition: TTHash.h:36
#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
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
TODO : how to have TTGetterMethod and TTSetterMethod for Mirror message Property ?
Definition: TTMirror.h:70
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34