Jamoma API  0.6.0.a19
TTObject.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup foundationLibrary
4  *
5  * @brief Create Jamoma object instances.
6  *
7  * @author Timothy Place
8  *
9  * @copyright Copyright © 2012, Timothy Place @n
10  * This code is licensed under the terms of the "New BSD License" @n
11  * http://creativecommons.org/licenses/BSD/
12  */
13 
14 #ifndef __TT_OBJECT_H__
15 #define __TT_OBJECT_H__
16 
17 #include "TTSymbol.h"
18 
19 class TTObjectBase;
20 class TTValue;
21 
22 /****************************************************************************************************/
23 // Class Specifications
24 
25 /**
26  Create and use Jamoma object instances.
27  @see #TTObjectTest
28 */
29 class TTFOUNDATION_EXPORT TTObject {
30 protected:
31  friend class TTEnvironment;
32 
33  TTObjectBase* mObjectInstance;
34 
35 public:
36 
37  /** Constructor.
38  @param aClassName The symbolic name of the class to create/wrap.
39  @param arguments Arguments to the constructor.
40  */
41  // NOTE: arguments *must* be copied -- otherwise a reference to kTTValNONE may overwrite its value and corrupt memory
42  TTObject(const TTSymbol aClassName, const TTValue arguments);
43 
44 
45  /** Constructor to create an empyt container which will be assigned/copied-to at a later point */
46  TTObject(const TTSymbol aClassName);
47 
48 
49  /** Constructor to create an empyt container which will be assigned/copied-to at a later point */
50  TTObject();
51 
52 
53  /** Special constructor to create new object that wraps an existing TTObjectBase pointer.
54  Use of the constructor is generally discouraged as is using TTObjectBase pointers in general.
55  */
56  TTObject(TTObjectBase* anObjectBase);
57 
58 
59  /** Copy constructor */
60  TTObject(const TTObject& anObjectToCopy);
61 
62 
63  /** Destructor.
64  */
65  virtual ~TTObject();
66 
67 
68  /** Query #TTEnvironment for names of all registered #TTObjectBase classes
69 
70  @param[out] classNames #TTValue whose content will be set to an array of #TTSymbol names for available classes
71  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
72  */
73  static TTErr GetRegisteredClassNames(TTValue& classNames);
74 
75  /** Query #TTEnvironment for names of all registered #TTObjectBase classes that share specific tags
76 
77  @param[out] classNames #TTValue whose content will be set to an array of #TTSymbol names for available classes
78  @param[in] searchTags #TTValue array containing the tags used to limit search
79  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
80  */
81  static TTErr GetRegisteredClassNamesForTags(TTValue& classNames, const TTValue& searchTags);
82 
83  /** Query #TTEnvironment for all registered tags used by #TTObjectBase classes
84 
85  @param[out] tags #TTValue whose content will be set to an array of #TTSymbol names for available tags
86  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
87  */
88  static TTErr GetRegisteredTags(TTValue& tags);
89 
90 
91  /** Assign a TTObject instance to another TTObject
92  */
93  TTObject& operator = (TTObject object);
94 
95 
96  /** Return a direct pointer to the internal instance.
97  Not recommended in most cases. */
98  TTObjectBase* instance() const;
99 
100 
101  /** Set an attribute value for an object
102  @param name The name of the attribute to set.
103  @param value The value to use for setting the attribute.
104  This value can be changed(!), for example if the value is out of range for the attribute.
105  Hence, it is not declared const.
106  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
107  */
108  template <class T>
109  TTErr set(const TTSymbol aName, T aValue);
110 
111 
112  /** Get an attribute value for an object
113  @param name The name of the attribute to get.
114  @param value The returned value of the attribute.
115  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
116  */
117  template <class T>
118  TTErr get(const TTSymbol aName, T& aReturnedValue) const;
119 
120 
121  /** Return a list of names of the available attributes.
122  @param attributeNameList Pointer to a list of all attributes registered with this TTObjectBase.
123  */
124  void attributes(TTValue& returnedAttributeNames) const;
125 
126 
127  /** Return the type of an attribute as a symbol.
128  @param aName The name of the attribute we want the type.
129  @return #TTSymbol : kTTSym__none, kTTSym_uint8, kTTSym_int8, kTTSym_uint16, kTTSym_int16, kTTSym_uint32, kTTSym_int32, kTTSym_uint64, kTTSym_int64, kTTSym_float32, kTTSym_float64, kTTSym__boolean, kTTSym_symbol, kTTSym_string, kTTSym_pointer, kTTSym_object, kTTSym_value. Returns kTTSymEmpty if the attribute doesn't exist.
130  */
131  TTSymbol attributeType(const TTSymbol aName);
132 
133 
134  /** Return a list of names of the available messages.
135  @param messageNameList Pointer to a list of all messages registered with this TTObjectBase.
136  */
137  void messages(TTValue& returnedMessageNames) const;
138 
139 
140  /** Return the name of this class.
141  @return The name of this object.
142  */
143  TTSymbol name() const;
144 
145 
146  /** Send a message to this object with no arguments.
147  @param aName The name of the message to send.
148  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
149  */
150  TTErr send(const TTSymbol aName);
151 
152 
153  /** Send a message to this object with arguments.
154  All arguments for input must be packed into a #TTValue container.
155  Any return values from the message will be packed into a second #TTValue container, which you must provide.
156  @param aName The name of the message to send.
157  @param anInputValue Any additional arguments to the message.
158  @param anOutputValue Will be filled-in with data upon return if the message returns data.
159  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
160  */
161  TTValue send(const TTSymbol aName, const TTValue& anInputValue);
162 #define SUPPORT_OLD_SEND_SYNTAX
163 #ifdef SUPPORT_OLD_SEND_SYNTAX
164  TT_DEPRECATED ( TTErr send(const TTSymbol aName, const TTValue& anInputValue, TTValue& anOutputValue) );
165 #endif
166 
167  /** Register an observer.
168  The observer will be monitoring this object.
169 
170  @param anObservingObject Reference to the observing object.
171  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
172  */
173  TTErr registerObserverForNotifications(const TTObject& anObservingObject);
174 
175 
176  /** Unregister an observer for notifications.
177  The observer wiln no longer be monitoring.
178 
179  @param anObservingObject Reference to the observing object.
180  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
181  */
182  TTErr unregisterObserverForNotifications(const TTObject& anObservingObject);
183 
184 
185  /** Determine if the object contained by this TTObject is truly ready for use.
186  @return If ready returns #YES otherwise #NO.
187  */
188  TTBoolean valid() const;
189 
190  /** Enable/Disable reference count tracking of the instance
191  @param newTrackingValue #YES to enable the tracking, #NO to disable it
192  */
193  void track(TTBoolean newTrackingValue);
194 };
195 
196 
197 /** Compare two objects for equality. */
198 bool TTFOUNDATION_EXPORT operator == (const TTObject& anObject, const TTObject& anotherObject);
199 
200 /** Compare two objects for inequality. */
201 bool TTFOUNDATION_EXPORT operator != (const TTObject& anObject, const TTObject& anotherObject);
202 
203 
204 /** Macro to access the actual C++ class that is contained inside of the #TTObject as a pointer.
205  @details In general we want to avoid using casting to access C++ class member directly rather than through their dynamic interface, but there might be some exceptions. E.g., this macro is used in the DSP #TTFilterLib where we have a number of complex filters that are constructed of smaller building-block filters (examples are #TTHalfband3, #TTHalfband5, #TTHalfband9, #TTHilbert9, #TTHilbert33, #TTMirror5 and #TTMirrorBandpass10). The smaller building block filters are full citizen objects, but to call them through the usual calculate methods for each and every sample is incredibly inefficient when compared to using C++ calls that the compiler can inline.
206  @ingroup macros
207  @param instance_ The #TTObject to peek inside.
208  @param class_ The C++ class name represented by the #TTObject.
209  @return Pointer to the C++ class contained inside of the #TTObject.
210  */
211 #define TTBASE( instance_ , class_ ) ((class_*)instance_.instance())
212 
213 
214 #endif // __TT_OBJECT_H__
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
TTErr registerObserverForNotifications(const TTObject &observingObject)
Register an observer.
TTErr unregisterObserverForNotifications(const TTObject &observingObject)
Unregister an observer for notifications.
bool TTFOUNDATION_EXPORT operator!=(const TTObject &anObject, const TTObject &anotherObject)
Compare two objects for inequality.
Definition: TTObject.cpp:173
Create and use Jamoma object instances.
Definition: TTObject.h:29
TTErr set(const TTSymbol aName, T aValue)
Set an attribute value for an object This is the same as calling setAttributeValue().
Definition: TTObjectBase.h:251
Base class for all first-class Jamoma objects.
Definition: TTObjectBase.h:109
TTBoolean valid
If the object isn't completely built, or is in the process of freeing, this will be false...
Definition: TTObjectBase.h:124
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTBoolean track
enable the print of a log message to ease the track of reference counting mechanism on an instance ...
Definition: TTObjectBase.h:125
bool TTFOUNDATION_EXPORT operator==(const TTObject &anObject, const TTObject &anotherObject)
Compare two objects for equality.
Definition: TTObject.cpp:167
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34
The global object maintains all global attributes/settings for the Jamoma environment.
Definition: TTEnvironment.h:47