Jamoma API  0.6.0.a19
TTNode.h
Go to the documentation of this file.
1 /** @file
2  * @ingroup foundationLibrary
3  *
4  * @brief References an object using a name, an instance and any contextual environnement information
5  *
6  * @details some details about the class.
7 
8  * other details. @n@n
9 
10  * another details. @n@n
11  *
12  * @see TTApplicationManager, Protocol, TTMirror
13  *
14  * @copyright Copyright © 2008, Théo de la Hogue & Tim Place @n
15  * This code is licensed under the terms of the "New BSD License" @n
16  * http://creativecommons.org/licenses/BSD/
17  */
18 
19 #if !defined( __TT_NODE_H__ ) && !defined ( DISABLE_NODELIB )
20 #define __TT_NODE_H__
21 
22 #ifdef WIN_VERSION
23  #pragma warning(disable:4083) //warning C4083: expected 'newline'; found identifier 's'
24 #endif // WIN_VERSION
25 
26 #include "TTFoundationAPI.h"
27 #include "TTCallback.h"
28 #include "TTAddress.h"
29 #include "TTAddressTable.h"
30 #include "TTNodeDirectory.h"
31 
32 class TTNode;
33 typedef TTNode* TTNodePtr;
34 
35 class TTNodeDirectory;
37 
38 class TTCallback;
39 typedef TTCallback* TTCallbackPtr;
40 
41 /****************************************************************************************************/
42 // Class Specifications
43 
44 /**
45  We build a directory of TTNodes, and you can request a pointer for any TTNode, or add an observer to any TTNode, etc.
46 
47  Every time we create a TTNode (or a string passed to something somewhere?) then this gets added to the directory.
48  If a TTNode is specified, such as /degrade~/audio/mute,
49  and we assume degrade~ has been added to the directory but 'audio' hasn't, then 'audio' is added followed by adding 'mute',
50  so that the directory is properly completed.
51 
52  When a TTNode is requested, the directory is traversed to find the pointer for the TTNode.
53  After the traversal (assuming no wildcards) the pointer is returned and also stored
54  in a hash table so that future requests for that TTNode are faster.
55 
56  The case of wildcards is handled, because a request is cached (keyed on the request),
57  and the value is a linked list of all of the matches.
58  */
59 class TTFOUNDATION_EXPORT TTNode {
60 
61 private:
62 
63  TTSymbol name; ///< the name of the node
64  TTSymbol instance; ///< an instance symbol (default to "")
65 
66  TTNodePtr parent; ///< pointer to the parent node in the directory
67  TTHashPtr children; ///< a hashtab of hashtabs:
68  ///< hashed on children names which containing hashtabs hashed on instances
69 
70  TTObject object; ///< an object referenced by the node
71  TTPtr context; ///< any pointer to precise the object place in its environnement (e.g. The owning t_object* in Max)
72 
73  TTNodeDirectoryPtr directory; ///< pointer to a node directory
74 
75 public:
76 
77  /** Constructor
78  @param aName the name of the node
79  @param anInstance an instance symbol
80  @param anObject an object referenced by the node
81  @param aContext any pointer to precise the object place in its environnement
82  @param aDirectory a pointer to a node directory */
83  TTNode (TTSymbol& aName, TTSymbol& anInstance, TTObject& anObject, TTPtr aContext, TTNodeDirectoryPtr aDirectory);
84 
85  /** Destructor */
86  virtual ~TTNode ();
87 
88  /** Set the name and the instance of the node
89  @details It maintains the directory and the directory
90  @param aNameInstance #TTAddress name.instance to set
91  @param newInstance the returned #TTSymbol instance if a new have been created
92  @param newInstanceCreated true if a new instance have been created
93  @return #TTErr an error code */
94  TTErr setNameInstance(TTAddress& aNameInstance, TTSymbol& newInstance, TTBoolean *newInstanceCreated);
95 
96  /** Set the parent of the node
97  @details This method ensure that the path to the node exist
98  @param parentAddress The address to check
99  @param newParentCreated This parameter will be set to true upon return if a new TTNode was created, or false if one was not created -
100  e.g. because a TTNode already existed with this address and instance name.
101  @return #TTErr an error code */
102  TTErr setParent(TTAddress parentAddress, TTBoolean *newParentCreated);
103 
104  /** Add a node as a child of the node
105  @param child a TTNodePtr to add as children of the TTNode.
106  @return #TTErr a kTTErrGeneric if the instance of the given child already exist. */
107  TTErr setChild(TTNodePtr child);
108 
109  /** Set the object of the node
110  @param anObject the object to reference
111  @return #TTErr always returns #kTTErrNone */
112  TTErr setObject(TTObject anObject = TTObject());
113 
114  /** Set the context of the node
115  @param aContext any pointer usefull to precise a context
116  @return #TTErr always returns #kTTErrNone */
117  TTErr setContext(TTPtr aContext);
118 
119  /** Get the name of the node
120  @return #TTSymbol the name of the node */
121  TTSymbol& getName();
122 
123  /** Get the instance of the node
124  @return #TTSymbol the instance of the node */
125  TTSymbol& getInstance();
126 
127  /** Get a pointer to the parent node of the node
128  @return #TTNodePtr the parent node */
129  TTNodePtr getParent();
130 
131  /** Get a linklist of children of the node : select them by name and instance (use wilcards to select them all)
132  @return #TTErr an error code */
133  TTErr getChildren(TTSymbol& name, TTSymbol& instance, TTList& returnedChildren);
134 
135  /** Get a linklist of children name
136  @return #TTErr an error code */
137  TTErr getChildrenName(TTList& returnedChildrenName);
138 
139  /** Get a linklist of children instance for a given name
140  @return #TTErr an error code */
141  TTErr getChildrenInstance(TTSymbol& aName, TTList& returnedChildrenInstance);
142 
143  /** Get the object binded by this node. It return also NULL when the object is not valid
144  @return #TTObject the referenced object */
145  TTObject& getObject();
146 
147  /** Get a pointer to the context of this node
148  @return #TTPtr the context pointer */
149  TTPtr getContext();
150 
151  /** Get the address of the node
152  @details It is computed dynamicaly by asking to all the ancestor of the node
153  @param returnedAddress a #TTAddress with the address is returned in this parameter.
154  @param from an address from where to start the returned address in order to have a relative address
155  @return #TTErr an error code*/
156  TTErr getAddress(TTAddress& returnedAddress, TTAddress from = kTTAdrsEmpty);
157 
158  /** Generate a new instance of a given child
159  @param childName the name of a child.
160  @param newInstance a new instance created (or "" if not) .
161  @return #TTErr a kTTErrGeneric if the child doesn't exist. */
162  TTErr generateInstance(TTSymbol& childName, TTSymbol& newInstance);
163 };
164 
165 
166 #endif // __TT_NODE_H__
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
This class is used to be sensitive to any TTObject notifications and report them using a function wit...
Definition: TTCallback.h:28
We build a directory of TTNodes, and you can request a pointer for any TTNode, or add an observer to ...
Definition: TTNode.h:59
The TTAddress class is used to represent a string and efficiently pass and compare that string...
Definition: TTAddress.h:29
Create and use Jamoma object instances.
Definition: TTObject.h:29
Maintain a collection of TTValue objects indexed by TTSymbol pointers.
Definition: TTHash.h:36
void * TTPtr
A generic pointer.
Definition: TTBase.h:248
This class is used to create a backward communication channel to notify a client that something chang...
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTCallback * TTCallbackPtr
Pointer to a TTCallback object.
Definition: TTCallback.h:75
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
We build a tree of TTNodes, and you can request a pointer for any TTNode, or add an observer to any T...