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
{
    /// \details The ResultEnum enumeration. Describes the state of a located object.
    /// </summary>
    typedef enum
    {
        NOT_FOUND       = 0,
        FOUND_EQUAL     = 1,
        FOUND_NOT_EQUAL = 2
    } ResultEnum;
} // namespace Traverse
 
/** 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.
    /// \param obj The object to check within.
    /// \param findThis An optional specific object to check for.
    /// \return 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 = nullptr )
    {
        if( dynamic_cast<T*>( obj ) )
        {
            if( findThis == nullptr )
                return true;
            else if( findThis == obj )
                return true;
        }
 
        if( dynamic_cast<Group*>( obj ) )
        {
            // Call for groups children
            auto* grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                if( Contained( ( *grp )[ i ], findThis ) )
                    return true;
            }
        }
        return false;
    }
 
    /// Like Contained(), but looks only one level deep.
    /// \param grp The object to check within.
    /// \param findThis An optional specific object to check for.
    /// \return 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 ContainedNoChildren( Group* grp, DisplayObject* findThis = nullptr )
    {
        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 == nullptr )
                        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.
    /// \note Does not traverse sub groups.
    /// \param grp The object to check within.
    static Group* AllMatchingNoChildren( Group* grp )
    {
        Group* newGrp = nullptr;
        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.
    /// \param obj The object to check within.
    /// \param n The index to retrieve.
    static T* GetNth( DisplayObject* obj, const int n )
    {
        int temp = n;
        return GetNthRecurse( obj, temp );
    }
 
    /// Helper function for use with GetNth().
    /// \param obj The object to check within.
    /// \param n The index to retrieve.
    /// \return The pointer to the object found, or NULL.
    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
            auto* 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
    /// \param obj The object to locate, or group to search through.
    /// \param variablePtr The returned underlying storage of argType.
    /// \param foundValue The returned value of the underlying storage of argType.
    /// \return The ResultEnum found state for the object.
    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
            auto*   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;
    }
 
    typedef void ( T::*void_CallMethod_void )(); ///< Typedef for a function pointer with no arguments or return value.
 
    /// void Method()
    /// \param obj The object to locate, or group to search through.
    /// \param method The function pointer to call on said object.
    /// \return True if one is found.
    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
            auto* grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                if( Call( ( *grp )[ i ], method ) )
                    foundOne = true;
            }
        }
        return foundOne;
    }
 
    typedef void ( T::*void_CallMethod_argType )( argType ); ///< Typedef for a function pointer taking one argument and no return value.
 
    /// void Method(int)
    /// \param obj The object to locate, or group to search through.
    /// \param method The function pointer to call on said object.
    /// \param arg1 The argument to pass through the function pointer.
    /// \returns true If one is found.
    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
            auto* grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                if( Call( ( *grp )[ i ], method, arg1 ) )
                    foundOne = true;
            }
        }
        return foundOne;
    }
 
    typedef void ( T::*void_CallMethod_argType_arg2Type )( argType, arg2Type ); ///< Typedef for a function pointer taking two arguments and no return value.
 
    /// void Method(type,type)
    /// \param obj The object to locate, or group to search through.
    /// \param method The function pointer to call on said object.
    /// \param arg1 The first argument to pass through the function pointer.
    /// \param arg2 The second argument to pass through the function pointer.
    /// \return True if one is found.
    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
            auto* 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;
    }
 
    typedef void ( T::*void_CallMethod_argTypeRef )( argType& ); ///< Typedef for a function pointer taking one argument as a reference, no return value.
 
    /// void Method(int&)
    /// \param obj The object to locate, or group to search through.
    /// \param method The function pointer to call on said object.
    /// \param arg1 The argument to pass through the function pointer.
    /// \return True if one is found.
    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
            auto* grp = dynamic_cast<Group*>( obj );
            for( unsigned int i = 0; i < grp->Count(); i++ )
            {
                if( Call( ( *grp )[ i ], method, arg1 ) )
                    foundOne = true;
            }
        }
        return foundOne;
    }
 
    typedef argType ( T::*argType_CallMethod_void )(); ///< Typedef for a function pointer with no arguments, and has a return value.
 
    /// int Method(void)
    /// \param obj The object to locate, or group to search through.
    /// \param method The function pointer to call on said object.
    /// \param notFoundValue The value to set if not found.
    /// \param multipleValue The value to set if multiple values are found.
    /// \param rvalFoundOne Used for recursion.
    /// \note This will not get the values from groups themselves, just their children.
    /// \return notFoundValue If not found.
    /// returns multipleValue If multiple values are found.
    static argType ReturnCall( DisplayObject* obj, argType_CallMethod_void method, const argType notFoundValue = argType( 0 ), const argType multipleValue = argType( -1 ), bool* rvalFoundOne = nullptr )
    {
        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;
            auto*   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;
    }
 
    typedef GlsColor ( T::*GlsColor_CallMethod_void )(); ///< Typedef for a function pointer that has no arguments, and returns a GlsColor.
 
    /// GlsColor Method(void)
    /// \note This will not get the values from groups themselves, just their children.
    /// \param obj The object to locate, or group to search through.
    /// \param method The function pointer to call on said object.
    /// \param foundColor The returned located color.
    /// \return 0 if not found.
    /// Returns -1 if multiple values are found.
    /// Returns 1 if a single value is found.
    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;
            auto*    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