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;        ///< Levels of qualification to show in names, -1 is fully qualified.
    int                       _groupLevelsDown; ///< How many levels to recurse through groups, -1 is fully recursive.
    DynamicArray<char*>       _excludeList;     ///< List of names to exclude from the filter, takes precedence over includes.
    DynamicArray<char*>       _includeList;     ///< List of names to include, if empty all names are acceptable.
    bool                      _namesOnly;       ///< If true, will return names only, and not names and values.
    DynamicArray<const char*> _parentNameStack; ///< List of parent names, used to append to the name during traversal.
 
public:
    GLS_EXPORT GlsResourceFilter();
 
    /// Copy constructor
    /// \param source The object to copy from.
    GLS_EXPORT GlsResourceFilter( GlsResourceFilter* source );
 
    /// Copy constructor
    /// \param source The object to copy from.
    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.
    /// \param value The new qualification level value to set.
    inline void LevelsUp( int value ) { _levelsUp = value; }
 
    /// \return Te number of levels of qualification.
    inline int LevelsUp() { return _levelsUp; }
 
    /// 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
    /// \param value The new group traversal level to set.
    inline void GroupLevelsDown( int value ) { _groupLevelsDown = value; }
 
    /// \return The number of group levels to traverse.
    inline int GroupLevelsDown() { return _groupLevelsDown; }
 
    /// If true, only a list of names will be returned.
    /// Values will not be returned.
    /// The format changes to not include the ":".
    /// \param value The new names only flag to set.
    inline void NamesOnly( bool value ) { _namesOnly = value; }
 
    /// \return Whether names only, or names and values will be returned.
    inline bool NamesOnly() { return _namesOnly; }
 
    /// Add a resource name to the exclude filter
    /// Resources on the exclude list will not pass the filter.
    /// Excludes take precedence over includes.
    /// \param name The new name to add to the exclude list.
    void GLS_EXPORT AddExclude( const char* name );
 
    /// \return The number of exclude entries in the filter.
    GLS_EXPORT unsigned int ExcludeCount() const;
 
    /// \return 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.
    /// \param name The new name to add to the include list.
    void GLS_EXPORT AddInclude( const char* name );
 
    /// \return The number of includes in the filter.
    GLS_EXPORT unsigned int IncludeCount() const;
 
    /// \return 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();
 
    /// \return The qualified name for a DisplayFrame.
    /// \param frame The object to build the name for.
    /// \param filter The filter currently in use (as this is a static function).
    static GLS_EXPORT std::string BuildHierarchyName( DisplayFrame* frame, GlsResourceFilter* filter );
 
    /// \return The qualified name for a DisplayObject.
    /// \param obj The object to build the name for.
    /// \param filter The filter currently in use (as this is a static function).
    static GLS_EXPORT std::string BuildHierarchyName( DisplayObject* obj, GlsResourceFilter* filter );
 
    /// Test a resource name against the filter.
    /// \param name The name to test against the filter.
    /// \return True if the name passes.
    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.
    /// \param parent The new parent name to push onto the stack.
    GLS_EXPORT void PushParentName( const char* parent );
 
    /// \return The size of the parent name stack.
    GLS_EXPORT unsigned int ParentNameCount() const;
 
    /// \return The parent name for the given position on the stack.
    /// \param index The index of the parent name to return.
    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
    /// \param rhs The object to copy from.
    /// \return The resulting object (this).
    GLS_EXPORT GlsResourceFilter& operator=( const GlsResourceFilter& rhs );
};
 
} // namespace disti
 
#endif