Element.h

/***********************************************************************
    filename:   CEGUI/Element.h
    created:    18/8/2011
    author:     Martin Preisler

    purpose:    Defines a class representing an item in a graph
                (deals with relative positions, relative dimensions, ...)
*************************************************************************/
/***************************************************************************
 *   Copyright (C) 2004 - 2011 Paul D Turner & The CEGUI Development Team
 *
 *   Permission is hereby granted, free of charge, to any person obtaining
 *   a copy of this software and associated documentation files (the
 *   "Software"), to deal in the Software without restriction, including
 *   without limitation the rights to use, copy, modify, merge, publish,
 *   distribute, sublicense, and/or sell copies of the Software, and to
 *   permit persons to whom the Software is furnished to do so, subject to
 *   the following conditions:
 *
 *   The above copyright notice and this permission notice shall be
 *   included in all copies or substantial portions of the Software.
 *
 *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 *   OTHER DEALINGS IN THE SOFTWARE.
 ***************************************************************************/

#ifndef _CEGUIElement_h_
#define _CEGUIElement_h_

#include "CEGUI/Base.h"
#include "CEGUI/PropertySet.h"
#include "CEGUI/EventSet.h"
#include "CEGUI/EventArgs.h"

#if defined(_MSC_VER)
#   pragma warning(push)
#   pragma warning(disable : 4251)
#endif

namespace CEGUI
{

enum HorizontalAlignment
{
    HA_LEFT,
    HA_CENTRE,
    HA_RIGHT
};

template<>
class PropertyHelper<HorizontalAlignment>
{
public:
    typedef HorizontalAlignment return_type;
    typedef return_type safe_method_return_type;
    typedef HorizontalAlignment pass_type;
    typedef String string_return_type;

    static const String& getDataTypeName()
    {
        static String type("HorizontalAlignment");

        return type;
    }

    static return_type fromString(const String& str)
    {
        if (str == "Centre")
        {
            return HA_CENTRE;
        }
        else if (str == "Right")
        {
            return HA_RIGHT;
        }
        else
        {
            return HA_LEFT;
        }
    }

    static string_return_type toString(pass_type val)
    {
        if (val == HA_CENTRE)
        {
            return "Centre";
        }
        else if (val == HA_RIGHT)
        {
            return "Right";
        }
        else if (val == HA_LEFT)
        {
            return "Left";
        }
        else
        {
            assert(false && "Invalid horizontal alignment");
            return "Centre";
        }
    }
};

enum VerticalAlignment
{
    VA_TOP,
    VA_CENTRE,
    VA_BOTTOM
};

template<>
class PropertyHelper<CEGUI::VerticalAlignment>
{
public:
    typedef VerticalAlignment return_type;
    typedef return_type safe_method_return_type;
    typedef VerticalAlignment pass_type;
    typedef String string_return_type;

    static const String& getDataTypeName()
    {
        static String type("VerticalAlignment");

        return type;
    }

    static return_type fromString(const String& str)
    {
      if (str == "Centre")
      {
          return VA_CENTRE;
      }
      else if (str == "Bottom")
      {
          return VA_BOTTOM;
      }
      else
      {
          return VA_TOP;
      }
    }

    static string_return_type toString(pass_type val)
    {
        if (val == VA_CENTRE)
        {
            return "Centre";
        }
        else if (val == VA_BOTTOM)
        {
            return "Bottom";
        }
        else if (val == VA_TOP)
        {
            return "Top";
        }
        else
        {
            assert(false && "Invalid vertical alignment");
            return "Centre";
        }
    }
};

class CEGUIEXPORT ElementEventArgs : public EventArgs
{
public:
    ElementEventArgs(Element* element):
        element(element)
    {}

    Element* element;
};

class CEGUIEXPORT Element :
    public PropertySet,
    public EventSet,
    public AllocatedObject<Element>
{
public:
    static const String EventNamespace;

    static const String EventSized;
    static const String EventParentSized;
    static const String EventMoved;
    static const String EventHorizontalAlignmentChanged;
    static const String EventVerticalAlignmentChanged;
    static const String EventRotated;
    static const String EventChildAdded;
    static const String EventChildRemoved;
    static const String EventZOrderChanged;
    static const String EventNonClientChanged;

    class CachedRectf
    {
    public:
        typedef Rectf (Element::*DataGenerator)(bool) const;

        CachedRectf(Element const* element, DataGenerator generator):
            d_element(element),
            d_generator(generator),
            // we don't have to initialise d_cachedData here, it will get
            // regenerated and reset anyways
            d_cacheValid(false)
        {}

        inline const Rectf& get() const
        {
            if (!d_cacheValid)
            {
                regenerateCache();
            }

            return d_cachedData;
        }

        inline Rectf getFresh(bool skipAllPixelAlignment = false) const
        {
            // if the cache is not valid we will use this chance to regenerate it
            // of course this is only applicable if we are allowed to use pixel alignment where applicable
            if (!d_cacheValid && !skipAllPixelAlignment)
            {
                return get();
            }

            return CEGUI_CALL_MEMBER_FN(*d_element, d_generator)(skipAllPixelAlignment);
        }

        inline void invalidateCache() const
        {
            d_cacheValid = false;
        }

        inline bool isCacheValid() const
        {
            return d_cacheValid;
        }

        inline void regenerateCache() const
        {
            // false, since when we are caching we don't want to skip anything, we want everything to act
            // exactly as it was setup
            d_cachedData = CEGUI_CALL_MEMBER_FN(*d_element, d_generator)(false);

            d_cacheValid = true;
        }

    private:
        Element const* d_element;
        const DataGenerator d_generator;

        mutable Rectf d_cachedData;
        mutable bool  d_cacheValid;
    };

    Element();

    virtual ~Element();

    inline Element* getParentElement() const
    {
        return d_parent;
    }

    virtual void setArea(const UVector2& pos, const USize& size);

    inline void setArea(const UDim& xpos, const UDim& ypos,
                        const UDim& width, const UDim& height)
    {
        setArea(UVector2(xpos, ypos), USize(width, height));
    }

    inline void setArea(const URect& area)
    {
        setArea(area.d_min, area.getSize());
    }

    inline const URect& getArea() const
    {
        return d_area;
    }

    inline void setPosition(const UVector2& pos)
    {
        setArea_impl(pos, d_area.getSize());
    }

    inline void setXPosition(const UDim& pos)
    {
        setPosition(UVector2(pos, getYPosition()));
    }

    inline void setYPosition(const UDim& pos)
    {
        setPosition(UVector2(getXPosition(), pos));
    }

    inline const UVector2& getPosition() const
    {
        return d_area.getPosition();
    }

    inline const UDim& getXPosition() const
    {
        return getPosition().d_x;
    }

    inline const UDim& getYPosition() const
    {
        return getPosition().d_y;
    }

    virtual void setHorizontalAlignment(const HorizontalAlignment alignment);

    inline HorizontalAlignment getHorizontalAlignment() const
    {
        return d_horizontalAlignment;
    }

    virtual void setVerticalAlignment(const VerticalAlignment alignment);

    inline VerticalAlignment getVerticalAlignment() const
    {
        return d_verticalAlignment;
    }

    inline void setSize(const USize& size)
    {
        setArea(d_area.getPosition(), size);
    }

    inline void setWidth(const UDim& width)
    {
        setSize(USize(width, getSize().d_height));
    }

    inline void setHeight(const UDim& height)
    {
        setSize(USize(getSize().d_width, height));
    }

    inline USize getSize() const
    {
        return d_area.getSize();
    }

    inline UDim getWidth() const
    {
        return getSize().d_width;
    }

    inline UDim getHeight() const
    {
        return getSize().d_height;
    }

    void setMinSize(const USize& size);

    inline const USize& getMinSize() const
    {
        return d_minSize;
    }

    void setMaxSize(const USize& size);

    inline const USize& getMaxSize() const
    {
        return d_maxSize;
    }

    void setAspectMode(const AspectMode mode);

    inline AspectMode getAspectMode() const
    {
        return d_aspectMode;
    }

    void setAspectRatio(const float ratio);

    inline float getAspectRatio() const
    {
        return d_aspectRatio;
    }

    void setPixelAligned(const bool setting);

    inline bool isPixelAligned() const
    {
        return d_pixelAligned;
    }

    inline const Vector2f& getPixelPosition() const
    {
        return getUnclippedOuterRect().get().d_min;
    }

    inline const Sizef& getPixelSize() const
    {
        return d_pixelSize;
    }

    Sizef calculatePixelSize(bool skipAllPixelAlignment = false) const;

    Sizef getParentPixelSize(bool skipAllPixelAlignment = false) const;

    void setRotation(const Quaternion& rotation);

    inline const Quaternion& getRotation() const
    {
        return d_rotation;
    }

    void addChild(Element* element);

    void removeChild(Element* element);

    inline Element* getChildElementAtIdx(size_t idx) const
    {
        return d_children[idx];
    }

    inline size_t getChildCount() const
    {
        return d_children.size();
    }

    bool isChild(const Element* element) const;

    bool isAncestor(const Element* element) const;

    void setNonClient(const bool setting);

    inline bool isNonClient() const
    {
        return d_nonClient;
    }

    inline const CachedRectf& getUnclippedOuterRect() const
    {
        return d_unclippedOuterRect;
    }

    inline const CachedRectf& getUnclippedInnerRect() const
    {
        return d_unclippedInnerRect;
    }

    inline const CachedRectf& getUnclippedRect(const bool inner) const
    {
        return inner ? getUnclippedInnerRect() : getUnclippedOuterRect();
    }

    virtual const CachedRectf& getClientChildContentArea() const;

    virtual const CachedRectf& getNonClientChildContentArea() const;

    inline const CachedRectf& getChildContentArea(const bool non_client = false) const
    {
        return non_client ? getNonClientChildContentArea() : getClientChildContentArea();
    }

    virtual void notifyScreenAreaChanged(bool recursive = true);

    virtual const Sizef& getRootContainerSize() const;

protected:
    void addElementProperties();

    virtual void setArea_impl(const UVector2& pos, const USize& size,
                              bool topLeftSizing = false, bool fireEvents = true);

    inline bool isInnerRectSizeChanged() const
    {
        const Sizef old_sz(d_unclippedInnerRect.get().getSize());
        d_unclippedInnerRect.invalidateCache();
        return old_sz != d_unclippedInnerRect.get().getSize();
    }

    virtual void setParent(Element* parent);

    virtual void addChild_impl(Element* element);

    virtual void removeChild_impl(Element* element);

    virtual Rectf getUnclippedOuterRect_impl(bool skipAllPixelAlignment) const;
    virtual Rectf getUnclippedInnerRect_impl(bool skipAllPixelAlignment) const;

    void fireAreaChangeEvents(const bool moved, const bool sized);
    void notifyChildrenOfSizeChange(const bool non_client,
                                    const bool client);

    /*************************************************************************
        Event trigger methods
    *************************************************************************/
    virtual void onSized(ElementEventArgs& e);

    virtual void onParentSized(ElementEventArgs& e);

    virtual void onMoved(ElementEventArgs& e);

    virtual void onHorizontalAlignmentChanged(ElementEventArgs& e);

    virtual void onVerticalAlignmentChanged(ElementEventArgs& e);

    virtual void onRotated(ElementEventArgs& e);

    virtual void onChildAdded(ElementEventArgs& e);

    virtual void onChildRemoved(ElementEventArgs& e);

    virtual void onNonClientChanged(ElementEventArgs& e);

    /*************************************************************************
        Implementation Data
    *************************************************************************/
    typedef std::vector<Element*
        CEGUI_VECTOR_ALLOC(Element*)> ChildList;

    ChildList d_children;
    Element* d_parent;

    bool d_nonClient;

    URect d_area;
    HorizontalAlignment d_horizontalAlignment;
    VerticalAlignment d_verticalAlignment;
    USize d_minSize;
    USize d_maxSize;
    AspectMode d_aspectMode;
    float d_aspectRatio;
    bool d_pixelAligned;
    Sizef d_pixelSize;
    Quaternion d_rotation;

    CachedRectf d_unclippedOuterRect;
    CachedRectf d_unclippedInnerRect;

private:
    /*************************************************************************
        May not copy or assign Element objects
    *************************************************************************/
    Element(const Element&);

    Element& operator=(const Element&) {return *this;}
};

} // End of  CEGUI namespace section


#if defined(_MSC_VER)
#   pragma warning(pop)
#endif

#endif  // end of guard _CEGUIElement_h_