GL Studio C++ Runtime API
traverser.h
Go to the documentation of this file.
1/// \file traverser.h
2/// \brief The disti::TraverseGroup class and corresponding Traverse namespace.
3///
4/// \par Copyright Information
5///
6/// Copyright (c) 2017 by The DiSTI Corporation.<br>
7/// 12249 Science Drive; Suite 300<br>
8/// Orlando, Florida 32826<br>
9/// USA<br>
10/// <br>
11/// All rights reserved.<br>
12///
13/// This Software contains proprietary trade secrets of DiSTI and may not be
14/// reproduced, in whole or part, in any form, or by any means of electronic,
15/// mechanical, or otherwise, without the written permission of DiSTI. Said
16/// permission may be derived through the purchase of applicable DiSTI product
17/// licenses which detail the distribution rights of this content and any
18/// Derivative Works based on this or other copyrighted DiSTI Software.
19///
20/// NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21/// AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22/// PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23/// AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24/// IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25/// PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26///
27/// LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28/// IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29/// INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30/// DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31/// INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32/// INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33/// OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34/// EXCEED FIVE DOLLARS (US$5.00).
35///
36/// The aforementioned terms and restrictions are governed by the laws of the
37/// State of Florida and the United States of America.
38
39#ifndef INCLUDED_DISTI_TRAVERSER_H
40#define INCLUDED_DISTI_TRAVERSER_H
41
42#include "display.h"
43#include "disti_metadata.h"
44#include "gls_color.h"
45#include "group.h"
46
47namespace disti
48{
49namespace Traverse
50{
51 /// \details The ResultEnum enumeration. Describes the state of a located object.
52 /// </summary>
53 typedef enum
54 {
55 NOT_FOUND = 0,
56 FOUND_EQUAL = 1,
57 FOUND_NOT_EQUAL = 2
58 } ResultEnum;
59} // namespace Traverse
60
61/** The TraverseGroup class
62 */
63template<class T, class argType = int, class arg2Type = int>
65{
66public:
67 /// Just to see if the object contains one of T.
68 /// \param obj The object to check within.
69 /// \param findThis An optional specific object to check for.
70 /// \return If findThis is NULL, will return true if any one is found.
71 /// If findThis has a value, will return true only if findThis is found.
72 static bool Contained( DisplayObject* obj, DisplayObject* findThis = nullptr )
73 {
74 if( dynamic_cast<T*>( obj ) )
75 {
76 if( findThis == nullptr )
77 return true;
78 else if( findThis == obj )
79 return true;
80 }
81
82 if( dynamic_cast<Group*>( obj ) )
83 {
84 // Call for groups children
85 auto* grp = dynamic_cast<Group*>( obj );
86 for( unsigned int i = 0; i < grp->Count(); ++i )
87 {
88 if( Contained( ( *grp )[ i ], findThis ) )
89 return true;
90 }
91 }
92 return false;
93 }
94
95 /// Like Contained(), but looks only one level deep.
96 /// \param grp The object to check within.
97 /// \param findThis An optional specific object to check for.
98 /// \return If findThis is NULL, will return true if any one is found.
99 /// If findThis has a value, will return true only if findThis is found.
100 static bool ContainedNoChildren( Group* grp, DisplayObject* findThis = nullptr )
101 {
102 if( grp )
103 {
104 // Call for groups children
105 for( unsigned int i = 0; i < grp->Count(); ++i )
106 {
107 T* specific = dynamic_cast<T*>( ( *grp )[ i ] );
108 if( specific )
109 {
110 if( findThis == nullptr )
111 return true;
112 else if( findThis == specific )
113 return true;
114 }
115 }
116 }
117 return false;
118 }
119
120 /// \return A group containing all of the matching children that are of the specified class.
121 /// \note Does not traverse sub groups.
122 /// \param grp The object to check within.
124 {
125 Group* newGrp = nullptr;
126 if( grp )
127 {
128 for( unsigned int i = 0; i < grp->Count(); ++i )
129 {
130 T* specific = dynamic_cast<T*>( ( *grp )[ i ] );
131 if( specific )
132 {
133 if( !newGrp )
134 newGrp = new Group();
135
136 newGrp->InsertObject( specific, false, false, -1 );
137 }
138 }
139 }
140 return newGrp;
141 }
142
143 /// \returns The nth object (1 is the first) of the template type in the specified selections.
144 /// The value of n will be decremented to zero if found.
145 /// return Value will be NULL if not found.
146 /// \param obj The object to check within.
147 /// \param n The index to retrieve.
148 static T* GetNth( DisplayObject* obj, const int n )
149 {
150 int temp = n;
151 return GetNthRecurse( obj, temp );
152 }
153
154 /// Helper function for use with GetNth().
155 /// \param obj The object to check within.
156 /// \param n The index to retrieve.
157 /// \return The pointer to the object found, or NULL.
158 static T* GetNthRecurse( DisplayObject* obj, int& n )
159 {
160 if( dynamic_cast<T*>( obj ) && n > 0 )
161 {
162 T* specific = dynamic_cast<T*>( obj );
163 --n;
164 return specific;
165 }
166 else if( dynamic_cast<Group*>( obj ) )
167 {
168 // Call for groups children
169 auto* grp = dynamic_cast<Group*>( obj );
170 for( unsigned int i = 0; i < grp->Count(); ++i )
171 {
172 T* specific = GetNthRecurse( ( *grp )[ i ], n );
173 if( n == 0 )
174 return specific;
175 }
176 }
177 return NULL;
178 }
179
180 /// T::variable
181 /// \param obj The object to locate, or group to search through.
182 /// \param variablePtr The returned underlying storage of argType.
183 /// \param foundValue The returned value of the underlying storage of argType.
184 /// \return The ResultEnum found state for the object.
185 static Traverse::ResultEnum GetValue( DisplayObject* obj, argType T::*variablePtr, argType& foundValue )
186 {
187 Traverse::ResultEnum foundOne = Traverse::NOT_FOUND;
188
189 if( dynamic_cast<T*>( obj ) )
190 {
191 T* specific = dynamic_cast<T*>( obj );
192 foundValue = specific->*variablePtr;
193 foundOne = Traverse::FOUND_EQUAL;
194 }
195
196 if( dynamic_cast<Group*>( obj ) )
197 {
198 // Call for groups children
199 auto* grp = dynamic_cast<Group*>( obj );
200 argType tempVal;
201 for( unsigned int i = 0; i < grp->Count(); ++i )
202 {
203 Traverse::ResultEnum result = GetValue( ( *grp )[ i ], variablePtr, tempVal );
204 if( result != Traverse::NOT_FOUND )
205 {
206 if( result == Traverse::FOUND_EQUAL )
207 {
208 if( tempVal == foundValue )
209 {
210 foundOne = Traverse::FOUND_EQUAL;
211 }
212 else
213 {
214 foundOne = Traverse::FOUND_NOT_EQUAL;
215 }
216 }
217 else
218 foundOne = Traverse::FOUND_NOT_EQUAL;
219
220 // Save the value either way.
221 foundValue = tempVal;
222 }
223 }
224 }
225 return foundOne;
226 }
227
228 typedef void ( T::*void_CallMethod_void )(); ///< Typedef for a function pointer with no arguments or return value.
229
230 /// void Method()
231 /// \param obj The object to locate, or group to search through.
232 /// \param method The function pointer to call on said object.
233 /// \return True if one is found.
234 static bool Call( DisplayObject* obj, void_CallMethod_void method )
235 {
236 bool foundOne = false;
237
238 if( dynamic_cast<T*>( obj ) )
239 {
240 T* specific = dynamic_cast<T*>( obj );
241 ( specific->*method )();
242 foundOne = true;
243 }
244
245 if( dynamic_cast<Group*>( obj ) )
246 {
247 // Call for groups children
248 auto* grp = dynamic_cast<Group*>( obj );
249 for( unsigned int i = 0; i < grp->Count(); ++i )
250 {
251 if( Call( ( *grp )[ i ], method ) )
252 foundOne = true;
253 }
254 }
255 return foundOne;
256 }
257
258 typedef void ( T::*void_CallMethod_argType )( argType ); ///< Typedef for a function pointer taking one argument and no return value.
259
260 /// void Method(int)
261 /// \param obj The object to locate, or group to search through.
262 /// \param method The function pointer to call on said object.
263 /// \param arg1 The argument to pass through the function pointer.
264 /// \returns true If one is found.
265 static bool Call( DisplayObject* obj, void_CallMethod_argType method, const argType arg1 )
266 {
267 bool foundOne = false;
268
269 if( dynamic_cast<T*>( obj ) )
270 {
271 T* specific = dynamic_cast<T*>( obj );
272 ( specific->*method )( arg1 );
273 foundOne = true;
274 }
275
276 if( dynamic_cast<Group*>( obj ) )
277 {
278 // Call for groups children
279 auto* grp = dynamic_cast<Group*>( obj );
280 for( unsigned int i = 0; i < grp->Count(); ++i )
281 {
282 if( Call( ( *grp )[ i ], method, arg1 ) )
283 foundOne = true;
284 }
285 }
286 return foundOne;
287 }
288
289 typedef void ( T::*void_CallMethod_argType_arg2Type )( argType, arg2Type ); ///< Typedef for a function pointer taking two arguments and no return value.
290
291 /// void Method(type,type)
292 /// \param obj The object to locate, or group to search through.
293 /// \param method The function pointer to call on said object.
294 /// \param arg1 The first argument to pass through the function pointer.
295 /// \param arg2 The second argument to pass through the function pointer.
296 /// \return True if one is found.
297 static bool Call( DisplayObject* obj, void_CallMethod_argType_arg2Type method, argType arg1, arg2Type arg2 )
298 {
299 bool foundOne = false;
300
301 if( dynamic_cast<T*>( obj ) )
302 {
303 T* specific = dynamic_cast<T*>( obj );
304 ( specific->*method )( arg1, arg2 );
305 foundOne = true;
306 }
307
308 if( dynamic_cast<Group*>( obj ) )
309 {
310 // Call for groups children
311 auto* grp = dynamic_cast<Group*>( obj );
312 for( unsigned int i = 0; i < grp->Count(); ++i )
313 {
314 if( Call( ( *grp )[ i ], method, arg1, arg2 ) )
315 foundOne = true;
316 }
317 }
318 return foundOne;
319 }
320
321 typedef void ( T::*void_CallMethod_argTypeRef )( argType& ); ///< Typedef for a function pointer taking one argument as a reference, no return value.
322
323 /// void Method(int&)
324 /// \param obj The object to locate, or group to search through.
325 /// \param method The function pointer to call on said object.
326 /// \param arg1 The argument to pass through the function pointer.
327 /// \return True if one is found.
328 static bool Call( DisplayObject* obj, void_CallMethod_argTypeRef method, argType& arg1 )
329 {
330 bool foundOne = false;
331
332 if( dynamic_cast<T*>( obj ) )
333 {
334 T* specific = dynamic_cast<T*>( obj );
335 ( specific->*method )( arg1 );
336 foundOne = true;
337 }
338
339 if( dynamic_cast<Group*>( obj ) )
340 {
341 // Call for groups children
342 auto* grp = dynamic_cast<Group*>( obj );
343 for( unsigned int i = 0; i < grp->Count(); ++i )
344 {
345 if( Call( ( *grp )[ i ], method, arg1 ) )
346 foundOne = true;
347 }
348 }
349 return foundOne;
350 }
351
352 typedef argType ( T::*argType_CallMethod_void )(); ///< Typedef for a function pointer with no arguments, and has a return value.
353
354 /// int Method(void)
355 /// \param obj The object to locate, or group to search through.
356 /// \param method The function pointer to call on said object.
357 /// \param notFoundValue The value to set if not found.
358 /// \param multipleValue The value to set if multiple values are found.
359 /// \param rvalFoundOne Used for recursion.
360 /// \note This will not get the values from groups themselves, just their children.
361 /// \return notFoundValue If not found.
362 /// returns multipleValue If multiple values are found.
363 static argType ReturnCall( DisplayObject* obj, argType_CallMethod_void method, const argType notFoundValue = argType( 0 ), const argType multipleValue = argType( -1 ), bool* rvalFoundOne = nullptr )
364 {
365 argType rval = notFoundValue;
366 bool weFoundOne = false;
367
368 // Check this object first
369 if( dynamic_cast<T*>( obj ) )
370 {
371 T* specific = dynamic_cast<T*>( obj );
372
373 rval = ( specific->*method )();
374 weFoundOne = true;
375 }
376
377 if( dynamic_cast<Group*>( obj ) )
378 {
379 // Check each of the children
380 argType temp;
381 auto* grp = dynamic_cast<Group*>( obj );
382 for( unsigned int i = 0; i < grp->Count(); ++i )
383 {
384 bool foundOneThisIndex;
385 temp = ReturnCall( ( *grp )[ i ], method, notFoundValue, multipleValue, &foundOneThisIndex );
386
387 if( foundOneThisIndex )
388 {
389 if( weFoundOne )
390 {
391 // We already found one
392 if( temp != rval )
393 {
394 // Different values: no need to continue
395 rval = multipleValue;
396 break;
397 }
398 }
399 else
400 {
401 // This is the first one
402 weFoundOne = true;
403 rval = temp;
404 }
405 }
406 }
407 }
408
409 if( rvalFoundOne )
410 {
411 *rvalFoundOne = weFoundOne;
412 }
413 return rval;
414 }
415
416 typedef GlsColor ( T::*GlsColor_CallMethod_void )(); ///< Typedef for a function pointer that has no arguments, and returns a GlsColor.
417
418 /// GlsColor Method(void)
419 /// \note This will not get the values from groups themselves, just their children.
420 /// \param obj The object to locate, or group to search through.
421 /// \param method The function pointer to call on said object.
422 /// \param foundColor The returned located color.
423 /// \return 0 if not found.
424 /// Returns -1 if multiple values are found.
425 /// Returns 1 if a single value is found.
426 static int Call( DisplayObject* obj, GlsColor_CallMethod_void method, GlsColor& foundColor )
427 {
428 int rval = 0;
429
430 if( dynamic_cast<Group*>( obj ) )
431 {
432 // Call for group's children
433 GlsColor tempColor;
434 int temp;
435 auto* grp = dynamic_cast<Group*>( obj );
436 for( unsigned int i = 0; i < grp->Count(); ++i )
437 {
438 temp = Call( ( *grp )[ i ], method, tempColor );
439
440 // If found duplicate, were done.
441 if( temp == -1 )
442 return temp;
443
444 // If we haven't found one yet
445 if( rval == 0 )
446 {
447 if( temp == 1 )
448 {
449 foundColor = tempColor;
450 rval = 1;
451 }
452 }
453 else // We need to compare with what we have
454 {
455 if( foundColor != tempColor )
456 {
457 // Colors don't match, so we are finished.
458 return -1;
459 }
460 }
461 }
462 }
463 else if( dynamic_cast<T*>( obj ) )
464 {
465 T* specific = dynamic_cast<T*>( obj );
466 foundColor = ( specific->*method )();
467 rval = 1; // Since we found one
468 }
469
470 return rval;
471 }
472};
473
474} // namespace disti
475
476#endif
Definition: display.h:95
Definition: gls_color.h:53
Definition: group.h:52
unsigned int Count() const
Definition: group.h:170
virtual void InsertObject(DisplayObject *obj, bool reparent=true, bool recalculateBoundingbox=true, int loc=-1)
Definition: traverser.h:65
static T * GetNth(DisplayObject *obj, const int n)
Definition: traverser.h:148
void(T::* void_CallMethod_void)()
Typedef for a function pointer with no arguments or return value.
Definition: traverser.h:228
static bool Call(DisplayObject *obj, void_CallMethod_argType method, const argType arg1)
Definition: traverser.h:265
static Group * AllMatchingNoChildren(Group *grp)
Definition: traverser.h:123
static int Call(DisplayObject *obj, GlsColor_CallMethod_void method, GlsColor &foundColor)
Definition: traverser.h:426
static bool Call(DisplayObject *obj, void_CallMethod_argTypeRef method, argType &arg1)
Definition: traverser.h:328
static T * GetNthRecurse(DisplayObject *obj, int &n)
Definition: traverser.h:158
static bool Call(DisplayObject *obj, void_CallMethod_argType_arg2Type method, argType arg1, arg2Type arg2)
Definition: traverser.h:297
argType(T::* argType_CallMethod_void)()
Typedef for a function pointer with no arguments, and has a return value.
Definition: traverser.h:352
GlsColor(T::* GlsColor_CallMethod_void)()
Typedef for a function pointer that has no arguments, and returns a GlsColor.
Definition: traverser.h:416
static bool Contained(DisplayObject *obj, DisplayObject *findThis=nullptr)
Definition: traverser.h:72
static argType ReturnCall(DisplayObject *obj, argType_CallMethod_void method, const argType notFoundValue=argType(0), const argType multipleValue=argType(-1), bool *rvalFoundOne=nullptr)
Definition: traverser.h:363
void(T::* void_CallMethod_argType)(argType)
Typedef for a function pointer taking one argument and no return value.
Definition: traverser.h:258
static bool Call(DisplayObject *obj, void_CallMethod_void method)
Definition: traverser.h:234
void(T::* void_CallMethod_argType_arg2Type)(argType, arg2Type)
Typedef for a function pointer taking two arguments and no return value.
Definition: traverser.h:289
void(T::* void_CallMethod_argTypeRef)(argType &)
Typedef for a function pointer taking one argument as a reference, no return value.
Definition: traverser.h:321
static bool ContainedNoChildren(Group *grp, DisplayObject *findThis=nullptr)
Definition: traverser.h:100
static Traverse::ResultEnum GetValue(DisplayObject *obj, argType T::*variablePtr, argType &foundValue)
Definition: traverser.h:185
The disti::DisplayObject class and global enumerations.
The disti metadata.
The Color class: Implements a 4 component RGBA color.
The disti::Group class. Implements groups of objects.
Definition: bmpimage.h:46
ResultEnum
Definition: traverser.h:54