traverser.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::TraverseGroup class and corresponding Traverse namespace.

  \par Copyright Information

  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/
#ifndef _TRAVERSER_H
#define _TRAVERSER_H

#include "display.h"
#include "disti_metadata.h"
#include "gls_color.h"
#include "group.h"

namespace disti
{
namespace Traverse
{
    typedef enum
    {
        NOT_FOUND       = 0,
        FOUND_EQUAL     = 1,
        FOUND_NOT_EQUAL = 2
    } ResultEnum;
}

/** The TraverseGroup class
  */
template<class T, class argType = int, class arg2Type = int>
class TraverseGroup
{
public:
    ////////// Just to see if the object contains one of T ///////////
    // If findThis is NULL, will return true if any one is found.
    // If findThis has a value, will return true only if findThis is found.
    static bool Contained( DisplayObject* obj, DisplayObject* findThis = NULL )
    {
        if( dynamic_cast<T*>( obj ) )
        {
            if( findThis == NULL )
                return true;
            else if( findThis == obj )
                return true;
        }

        if( dynamic_cast<Group*>( obj ) )
        {
            // Call for groups children
            Group* grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                if( Contained( ( *grp )[ i ], findThis ) )
                    return true;
            }
        }
        return false;
    }
    // Looks only one level deep.
    static bool ContainedNoChildren( Group* grp, DisplayObject* findThis = NULL )
    {
        if( grp )
        {
            // Call for groups children
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                T* specific = dynamic_cast<T*>( ( *grp )[ i ] );
                if( specific )
                {
                    if( findThis == NULL )
                        return true;
                    else if( findThis == specific )
                        return true;
                }
            }
        }
        return false;
    }

    // Return a group containing all of the matching children that are of the specified class.
    // Do not traverse sub groups.
    static Group* AllMatchingNoChildren( Group* grp )
    {
        Group* newGrp = NULL;
        if( grp )
        {
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                T* specific = dynamic_cast<T*>( ( *grp )[ i ] );
                if( specific )
                {
                    if( !newGrp )
                        newGrp = new Group();

                    newGrp->InsertObject( specific, false, false, -1 );
                }
            }
        }
        return newGrp;
    }

    // Returns the nth object (1 is the first) of the template type
    // in the specified selections
    // The value of n will be decremented to zero if found.
    // return value will be NULL if not found.
    static T* GetNth( DisplayObject* obj, const int n )
    {
        int temp = n;
        return GetNthRecurse( obj, temp );
    }
    static T* GetNthRecurse( DisplayObject* obj, int& n )
    {
        if( dynamic_cast<T*>( obj ) && n > 0 )
        {
            T* specific = dynamic_cast<T*>( obj );
            n--;
            return specific;
        }
        else if( dynamic_cast<Group*>( obj ) )
        {
            // Call for groups children
            Group* grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                T* specific = GetNthRecurse( ( *grp )[ i ], n );
                if( n == 0 )
                    return specific;
            }
        }
        return NULL;
    }
    ////////// T::variable ///////////
    // Returns true if one is found.

    static Traverse::ResultEnum GetValue( DisplayObject* obj, argType T::*variablePtr, argType& foundValue )
    {
        Traverse::ResultEnum foundOne = Traverse::NOT_FOUND;

        if( dynamic_cast<T*>( obj ) )
        {
            T* specific = dynamic_cast<T*>( obj );
            foundValue  = specific->*variablePtr;
            foundOne    = Traverse::FOUND_EQUAL;
        }

        if( dynamic_cast<Group*>( obj ) )
        {
            // Call for groups children
            Group*  grp = dynamic_cast<Group*>( obj );
            argType tempVal;
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                Traverse::ResultEnum result = GetValue( ( *grp )[ i ], variablePtr, tempVal );
                if( result != Traverse::NOT_FOUND )
                {
                    if( result == Traverse::FOUND_EQUAL )
                    {
                        if( tempVal == foundValue )
                        {
                            foundOne = Traverse::FOUND_EQUAL;
                        }
                        else
                        {
                            foundOne = Traverse::FOUND_NOT_EQUAL;
                        }
                    }
                    else
                        foundOne = Traverse::FOUND_NOT_EQUAL;

                    // Save the value either way.
                    foundValue = tempVal;
                }
            }
        }
        return foundOne;
    }

    ////////// void Method() ///////////
    // Returns true if one is found.
    typedef void ( T::*void_CallMethod_void )( void );
    static bool Call( DisplayObject* obj, void_CallMethod_void method )
    {
        bool foundOne = false;

        if( dynamic_cast<T*>( obj ) )
        {
            T* specific = dynamic_cast<T*>( obj );
            ( specific->*method )();
            foundOne = true;
        }

        if( dynamic_cast<Group*>( obj ) )
        {
            // Call for groups children
            Group* grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                if( Call( ( *grp )[ i ], method ) )
                    foundOne = true;
            }
        }
        return foundOne;
    }

    ////////// void Method(int) ///////////
    // Returns true if one is found.
    typedef void ( T::*void_CallMethod_argType )( argType );
    static bool Call( DisplayObject* obj, void_CallMethod_argType method, const argType arg1 )
    {
        bool foundOne = false;

        if( dynamic_cast<T*>( obj ) )
        {
            T* specific = dynamic_cast<T*>( obj );
            ( specific->*method )( arg1 );
            foundOne = true;
        }

        if( dynamic_cast<Group*>( obj ) )
        {
            // Call for groups children
            Group* grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                if( Call( ( *grp )[ i ], method, arg1 ) )
                    foundOne = true;
            }
        }
        return foundOne;
    }

    ////////// void Method(type,type) ///////////
    // Returns true if one is found.
    typedef void ( T::*void_CallMethod_argType_arg2Type )( argType, arg2Type );
    static bool Call( DisplayObject* obj, void_CallMethod_argType_arg2Type method, argType arg1, arg2Type arg2 )
    {
        bool foundOne = false;

        if( dynamic_cast<T*>( obj ) )
        {
            T* specific = dynamic_cast<T*>( obj );
            ( specific->*method )( arg1, arg2 );
            foundOne = true;
        }

        if( dynamic_cast<Group*>( obj ) )
        {
            // Call for groups children
            Group* grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                if( Call( ( *grp )[ i ], method, arg1, arg2 ) )
                    foundOne = true;
            }
        }
        return foundOne;
    }

    ////////// void Method(int&) ///////////
    // Returns true if one is found.
    typedef void ( T::*void_CallMethod_argTypeRef )( argType& );
    static bool Call(
        DisplayObject*             obj,
        void_CallMethod_argTypeRef method,
        argType&                   arg1 )
    {
        bool foundOne = false;

        if( dynamic_cast<T*>( obj ) )
        {
            T* specific = dynamic_cast<T*>( obj );
            ( specific->*method )( arg1 );
            foundOne = true;
        }

        if( dynamic_cast<Group*>( obj ) )
        {
            // Call for groups children
            Group* grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                if( Call( ( *grp )[ i ], method, arg1 ) )
                    foundOne = true;
            }
        }
        return foundOne;
    }

    //////// int Method(void) //////////////
    // returns notFoundValue if not found
    // returns multipleValue if multiple values are found
    // This will not get the values from groups themselves, just their children.
    typedef argType ( T::*argType_CallMethod_void )();
    static argType ReturnCall( DisplayObject* obj, argType_CallMethod_void method, const argType notFoundValue = argType( 0 ), const argType multipleValue = argType( -1 ), /* used for recursion */ bool* rvalFoundOne = NULL )
    {
        argType rval       = notFoundValue;
        bool    weFoundOne = false;

        // Check this object first
        if( dynamic_cast<T*>( obj ) )
        {
            T* specific = dynamic_cast<T*>( obj );

            rval       = ( specific->*method )();
            weFoundOne = true;
        }

        if( dynamic_cast<Group*>( obj ) )
        {
            // Check each of the children
            argType temp;
            Group*  grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                bool foundOneThisIndex;
                temp = ReturnCall( ( *grp )[ i ], method, notFoundValue, multipleValue, &foundOneThisIndex );

                if( foundOneThisIndex )
                {
                    if( weFoundOne )
                    {
                        // We already found one
                        if( temp != rval )
                        {
                            // Different values: no need to continue
                            rval = multipleValue;
                            break;
                        }
                    }
                    else
                    {
                        // This is the first one
                        weFoundOne = true;
                        rval       = temp;
                    }
                }
            }
        }

        if( rvalFoundOne )
        {
            *rvalFoundOne = weFoundOne;
        }
        return rval;
    }

    //////// GlsColor Method(void) //////////////
    // returns 0 if not found
    // returns -1 if multiple values are found
    // returns 1 if a single value is found
    // This will not get the values from groups themselves, just their children.
    typedef GlsColor ( T::*GlsColor_CallMethod_void )();
    static int Call( DisplayObject* obj, GlsColor_CallMethod_void method, GlsColor& foundColor )
    {
        int rval = 0;

        if( dynamic_cast<Group*>( obj ) )
        {
            // Call for group's children
            GlsColor tempColor;
            int      temp;
            Group*   grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                temp = Call( ( *grp )[ i ], method, tempColor );

                // If found duplicate, were done.
                if( temp == -1 )
                    return temp;

                // If we haven't found one yet
                if( rval == 0 )
                {
                    if( temp == 1 )
                    {
                        foundColor = tempColor;
                        rval       = 1;
                    }
                }
                else // We need to compare with what we have
                {
                    if( foundColor != tempColor )
                    {
                        // Colors don't match, so we are finished.
                        return -1;
                    }
                }
            }
        }
        else if( dynamic_cast<T*>( obj ) )
        {
            T* specific = dynamic_cast<T*>( obj );
            foundColor  = ( specific->*method )();
            rval        = 1; // Since we found one
        }

        return rval;
    }
};

} // namespace disti

#endif