gls_resources.h

Go to the documentation of this file.

/*! \file
  \brief  disti::GlsResourceFilter classes and methods.

  \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 _GLS_RESOURCES_H
#define _GLS_RESOURCES_H

#include "display_frame.h"

namespace disti
{
/** Used for specifiying a filter for accessing resources 
  */
class GlsResourceFilter
{
public:
    int                             _levelsUp;
    int                             _groupLevelsDown;
    DynamicArray<char*, true>       _excludeList;
    DynamicArray<char*, true>       _includeList;
    bool                            _namesOnly;
    DynamicArray<const char*, true> _parentNameStack;

public:
    GLS_EXPORT GlsResourceFilter();
    /// Copy constructor
    GLS_EXPORT GlsResourceFilter( GlsResourceFilter* source );
    GLS_EXPORT GlsResourceFilter( GlsResourceFilter& source );

    virtual GLS_EXPORT ~GlsResourceFilter();

    /** How many levels of qualification above the starting point to show in the attribute names.
      * This is based on the component heirarchy, not the draw hierarchy.
      * For example if you call Altimeter->GetResources() with:
      *  LevelsUp = 0, expect:
      *    Altitude: 1000
      *  LevelsUp = 1, expect:
      *    Altimeter.Altitude:
      *  LevelsUp = 2, expect:
      *    Cockpit.Altimeter.Altitude:
      * -1 means full qualification.
      */
    inline int  LevelsUp() { return _levelsUp; }
    inline void LevelsUp( int value ) { _levelsUp = value; }

    /** How many levels of children to show.
      * This is different from LevelsUp because this is based on the draw
      * heirarchy (Groups rather than components).
      * For example with:
      *  GroupLevelsDown = 0, only the specified object's resources will be shown.
      *  GroupLevelsDown = 1, only the immeadiate children of the object's resources will be shown.
      *  GroupLevelsDown = -1, means all children will be shown.
      * Note that the name stays fully qualified for the children.  For example:
      * if GroupLevelsDown == 1 the results would include:
      *    Altimeter.Visible: 1
      *    Altimeter.Group1.Visible: 1
      * but NOT:
      *    Altimeter.Group1.Poly.Visible: 1
      */
    inline int  GroupLevelsDown() { return _groupLevelsDown; }
    inline void GroupLevelsDown( int value ) { _groupLevelsDown = value; }

    /** If true, only a list of names will be returned.
      * Values will not be returned.
      * The format changes to not include the ":".
      */
    inline bool NamesOnly() { return _namesOnly; }
    inline void NamesOnly( bool value ) { _namesOnly = value; }

    /** Add a resource name to the exclude filter
      * Resources on the exclude list will not pass the filter.
      * Excludes take precedence over includes
      */
    void GLS_EXPORT AddExclude( const char* name );

    /// Returns the number of exclude entries in the filter
    GLS_EXPORT unsigned int ExcludeCount() const;

    /** Returns the resource name for the given exclude list entry
      * \param index < ExcludeCount()
      */
    GLS_EXPORT const char* GetExclude( unsigned int index ) const;

    /** Removes a entry from the exclude list
      * This will reduce the ExcludeCount()
      * \param index < ExcludeCount()
      */
    GLS_EXPORT void RemoveExclude( unsigned int index );

    /// Removes all entries from the exclude list
    GLS_EXPORT void ClearExcludes();

    /** Add a resource name to the include filter
      * If there are no includes specified, all resources
      * will pass the filter by default.
      * If IncludeCount() > 0, then only resources that
      * are included will pass the filter.
      */
    void GLS_EXPORT AddInclude( const char* name );

    /// Returns the number of includes in the filter
    GLS_EXPORT unsigned int IncludeCount() const;

    /** Returns the resource name for the given include list entry
      * \param index < IncludeCount()
      */
    GLS_EXPORT const char* GetInclude( unsigned int index ) const;

    /** Removes a entry from the include list
      * This will reduce the IncludeCount()
      * \param index < IncludeCount()
      */
    GLS_EXPORT void RemoveInclude( unsigned int index );

    /// Removes all entries from the include list
    GLS_EXPORT void ClearIncludes();

    /// \returns the qualified name for a DisplayFrame.
    static GLS_EXPORT std::string BuildHierarchyName( DisplayFrame* frame, GlsResourceFilter* filter );
    /// \returns the qualified name for a DisplayObject.
    static GLS_EXPORT std::string BuildHierarchyName( DisplayObject* obj, GlsResourceFilter* filter );

    /// Test a resource name against the filter
    virtual GLS_EXPORT bool PassFilter( const char* name );

    /** Pushes a parent name onto the filter's parent stack. This is a list of names of objects
      * that represents the hierarchy above this object; this should be used by the
      * BuildHierarchyName to prepend the parent names when in the editor, as we don't have the
      * ComponentBase's Parent frame pointers available.
      */
    GLS_EXPORT void PushParentName( const char* parent );

    /** Returns the size of the parent name stack */
    GLS_EXPORT unsigned int ParentNameCount() const;

    /** Returns the parent name for the given position on the stack */
    GLS_EXPORT const char* GetParentName( unsigned int index ) const;

    /** Removes the top entry on the parent name stack */
    GLS_EXPORT void PopParentName();

    /** Removes all entries on the parent name stack */
    GLS_EXPORT void ClearParentNames();

    /// assignment operator
    GLS_EXPORT GlsResourceFilter& operator=( const GlsResourceFilter& rhs );
};

} // namespace disti

#endif