libogre-1.9-dev 1.9.0+dfsg1-4 / usr / include / OGRE / Overlay / OgreOverlayElement.h

/*
-----------------------------------------------------------------------------
This source file is part of OGRE
(Object-oriented Graphics Rendering Engine)
For the latest info, see http://www.ogre3d.org/

Copyright (c) 2000-2013 Torus Knot Software Ltd

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 OR COPYRIGHT HOLDERS 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 __OverlayElement_H__
#define __OverlayElement_H__

#include "OgreOverlayPrerequisites.h"
#include "OgreString.h"
#include "OgreRenderable.h"
#include "OgreUTFString.h"
#include "OgreStringInterface.h"
#include "OgreOverlayElementCommands.h"

#include "OgreColourValue.h"

namespace Ogre {
	/** \addtogroup Core
	*  @{
	*/
	/** \addtogroup Overlays
	*  @{
	*/

#if OGRE_UNICODE_SUPPORT
	typedef UTFString DisplayString;
#	define OGRE_DEREF_DISPLAYSTRING_ITERATOR(it) it.getCharacter()
#else
	typedef String DisplayString;
#	define OGRE_DEREF_DISPLAYSTRING_ITERATOR(it) *it
#endif
    /** Enum describing how the position / size of an element is to be recorded. 
    */
    enum GuiMetricsMode
    {
        /// 'left', 'top', 'height' and 'width' are parametrics from 0.0 to 1.0
        GMM_RELATIVE,
        /// Positions & sizes are in absolute pixels
        GMM_PIXELS,
        /// Positions & sizes are in virtual pixels
        GMM_RELATIVE_ASPECT_ADJUSTED
    };

    /** Enum describing where '0' is in relation to the parent in the horizontal dimension.
    @remarks Affects how 'left' is interpreted.
    */
    enum GuiHorizontalAlignment
    {
        GHA_LEFT,
        GHA_CENTER,
        GHA_RIGHT
    };
    /** Enum describing where '0' is in relation to the parent in the vertical dimension.
    @remarks Affects how 'top' is interpreted.
    */
    enum GuiVerticalAlignment
    {
        GVA_TOP,
        GVA_CENTER,
        GVA_BOTTOM
    };

    /** Abstract definition of a 2D element to be displayed in an Overlay.
    @remarks
    This class abstracts all the details of a 2D element which will appear in
    an overlay. In fact, not all OverlayElement instances can be directly added to an
    Overlay, only those which are OverlayContainer instances (a subclass of this class).
    OverlayContainer objects can contain any OverlayElement however. This is just to 
    enforce some level of grouping on widgets.
    @par
    OverlayElements should be managed using OverlayManager. This class is responsible for
    instantiating / deleting elements, and also for accepting new types of element
    from plugins etc.
    @par
    Note that positions / dimensions of 2D screen elements are expressed as parametric
    values (0.0 - 1.0) because this makes them resolution-independent. However, most
    screen resolutions have an aspect ratio of 1.3333:1 (width : height) so note that
    in physical pixels 0.5 is wider than it is tall, so a 0.5x0.5 panel will not be
    square on the screen (but it will take up exactly half the screen in both dimensions).
    @par
    Because this class is designed to be extensible, it subclasses from StringInterface
    so its parameters can be set in a generic way.
    */
    class _OgreOverlayExport OverlayElement : public StringInterface, public Renderable, public OverlayAlloc
    {
    public:

    protected:
        // Command object for setting / getting parameters
        static OverlayElementCommands::CmdLeft msLeftCmd;
        static OverlayElementCommands::CmdTop msTopCmd;
        static OverlayElementCommands::CmdWidth msWidthCmd;
        static OverlayElementCommands::CmdHeight msHeightCmd;
        static OverlayElementCommands::CmdMaterial msMaterialCmd;
        static OverlayElementCommands::CmdCaption msCaptionCmd;
        static OverlayElementCommands::CmdMetricsMode msMetricsModeCmd;
        static OverlayElementCommands::CmdHorizontalAlign msHorizontalAlignCmd;
        static OverlayElementCommands::CmdVerticalAlign msVerticalAlignCmd;
        static OverlayElementCommands::CmdVisible msVisibleCmd;


        String mName;
        bool mVisible;
        bool mCloneable;
        Real mLeft;
        Real mTop;
        Real mWidth;
        Real mHeight;
        String mMaterialName;
        MaterialPtr mMaterial;
        DisplayString mCaption;
        ColourValue mColour;
        RealRect mClippingRegion;

        GuiMetricsMode mMetricsMode;
        GuiHorizontalAlignment mHorzAlign;
        GuiVerticalAlignment mVertAlign;

        // metric-mode positions, used in GMM_PIXELS & GMM_RELATIVE_ASPECT_ADJUSTED mode.
        Real mPixelTop;
        Real mPixelLeft;
        Real mPixelWidth;
        Real mPixelHeight;
        Real mPixelScaleX;
        Real mPixelScaleY;

        /// Parent pointer
        OverlayContainer* mParent;
        /// Overlay attached to
        Overlay* mOverlay;

        // Derived positions from parent
        Real mDerivedLeft;
        Real mDerivedTop;
        bool mDerivedOutOfDate;

        /// Flag indicating if the vertex positions need recalculating
        bool mGeomPositionsOutOfDate;
		/// Flag indicating if the vertex uvs need recalculating
		bool mGeomUVsOutOfDate;

        /** Zorder for when sending to render queue.
            Derived from parent */
        ushort mZOrder;

        /// World transforms
        Matrix4 mXForm;

        /// Is element enabled?
        bool mEnabled;

		/// Is element initialised?
		bool mInitialised;

        /// Used to see if this element is created from a Template
        OverlayElement* mSourceTemplate ;

        /** Internal method which is triggered when the positions of the element get updated,
        meaning the element should be rebuilding it's mesh positions. Abstract since
        subclasses must implement this.
        */
        virtual void updatePositionGeometry(void) = 0;
		/** Internal method which is triggered when the UVs of the element get updated,
		meaning the element should be rebuilding it's mesh UVs. Abstract since
		subclasses must implement this.
		*/
		virtual void updateTextureGeometry(void) = 0;

        /** Internal method for setting up the basic parameter definitions for a subclass. 
        @remarks
        Because StringInterface holds a dictionary of parameters per class, subclasses need to
        call this to ask the base class to add it's parameters to their dictionary as well.
        Can't do this in the constructor because that runs in a non-virtual context.
        @par
        The subclass must have called it's own createParamDictionary before calling this method.
        */
        virtual void addBaseParameters(void);

    public:
        /// Constructor: do not call direct, use OverlayManager::createElement
        OverlayElement(const String& name);
        virtual ~OverlayElement();

        /** Initialise gui element */
        virtual void initialise(void) = 0;

        /** Gets the name of this overlay. */
        const String& getName(void) const;


        /** Shows this element if it was hidden. */
        virtual void show(void);

        /** Hides this element if it was visible. */
        virtual void hide(void);

        /** Returns whether or not the element is visible. */
        bool isVisible(void) const;

        bool isEnabled() const;
        virtual void setEnabled(bool b);


        /** Sets the dimensions of this element in relation to the screen (1.0 = screen width/height). */
        void setDimensions(Real width, Real height);

        /** Sets the position of the top-left corner of the element, relative to the screen size
        (1.0 = screen width / height) */
        void setPosition(Real left, Real top);

        /** Sets the width of this element in relation to the screen (where 1.0 = screen width) */
        void setWidth(Real width);
        /** Gets the width of this element in relation to the screen (where 1.0 = screen width) */
        Real getWidth(void) const;

        /** Sets the height of this element in relation to the screen (where 1.0 = screen height) */
        void setHeight(Real height);
        /** Gets the height of this element in relation to the screen (where 1.0 = screen height) */
        Real getHeight(void) const;

        /** Sets the left of this element in relation to the screen (where 0 = far left, 1.0 = far right) */
        void setLeft(Real left);
        /** Gets the left of this element in relation to the screen (where 0 = far left, 1.0 = far right)  */
        Real getLeft(void) const;

        /** Sets the top of this element in relation to the screen (where 0 = top, 1.0 = bottom) */
        void setTop(Real Top);
        /** Gets the top of this element in relation to the screen (where 0 = top, 1.0 = bottom)  */
        Real getTop(void) const;

        /** Gets the left of this element in relation to the screen (where 0 = far left, 1.0 = far right)  */
        Real _getLeft(void) const { return mLeft; }
        /** Gets the top of this element in relation to the screen (where 0 = far left, 1.0 = far right)  */
        Real _getTop(void) const { return mTop; }
        /** Gets the width of this element in relation to the screen (where 1.0 = screen width)  */
        Real _getWidth(void) const { return mWidth; }
        /** Gets the height of this element in relation to the screen (where 1.0 = screen height)  */
        Real _getHeight(void) const { return mHeight; }
        /** Sets the left of this element in relation to the screen (where 1.0 = screen width) */
        void _setLeft(Real left);
        /** Sets the top of this element in relation to the screen (where 1.0 = screen width) */
        void _setTop(Real top);
        /** Sets the width of this element in relation to the screen (where 1.0 = screen width) */
        void _setWidth(Real width);
        /** Sets the height of this element in relation to the screen (where 1.0 = screen width) */
        void _setHeight(Real height);
        /** Sets the left and top of this element in relation to the screen (where 1.0 = screen width) */
        void _setPosition(Real left, Real top);
        /** Sets the width and height of this element in relation to the screen (where 1.0 = screen width) */
        void _setDimensions(Real width, Real height);

        /** Gets the name of the material this element uses. */
        virtual const String& getMaterialName(void) const;

        /** Sets the name of the material this element will use. 
        @remarks
        Different elements will use different materials. One constant about them
        all though is that a Material used for a OverlayElement must have it's depth
        checking set to 'off', which means it always gets rendered on top. OGRE
        will set this flag for you if necessary. What it does mean though is that 
        you should not use the same Material for rendering OverlayElements as standard 
        scene objects. It's fine to use the same textures, just not the same
        Material.
        */
        virtual void setMaterialName(const String& matName);


        // --- Renderable Overrides ---
        /** See Renderable */
        const MaterialPtr& getMaterial(void) const;

        // NB getRenderOperation not implemented, still abstract here

        /** See Renderable */
        void getWorldTransforms(Matrix4* xform) const;

        /** Tell the object to recalculate */
        virtual void _positionsOutOfDate(void);

        /** Internal method to update the element based on transforms applied. */
        virtual void _update(void);

        /** Updates this elements transform based on it's parent. */
        virtual void _updateFromParent(void);

        /** Internal method for notifying the GUI element of it's parent and ultimate overlay. */
        virtual void _notifyParent(OverlayContainer* parent, Overlay* overlay);

        /** Gets the 'left' position as derived from own left and that of parents. */
        virtual Real _getDerivedLeft(void);

        /** Gets the 'top' position as derived from own left and that of parents. */
        virtual Real _getDerivedTop(void);

		/** Gets the 'width' as derived from own width and metrics mode. */
		virtual Real _getRelativeWidth(void);
		/** Gets the 'height' as derived from own height and metrics mode. */
		virtual Real _getRelativeHeight(void);


        /** Gets the clipping region of the element */
        virtual void _getClippingRegion(RealRect &clippingRegion);

        /** Internal method to notify the element when Z-order of parent overlay
        has changed.
        @remarks
        Overlays have explicit Z-orders. OverlayElements do not, they inherit the 
        Z-order of the overlay, and the Z-order is incremented for every container
        nested within this to ensure that containers are displayed behind contained
        items. This method is used internally to notify the element of a change in
        final Z-order which is used to render the element.
		@return Return the next Z-ordering number available. For single elements, this
		is simply 'newZOrder + 1', except for containers. They increment it once for each
		child (or even more if those children are also containers with their own elements).
        */
        virtual ushort _notifyZOrder(ushort newZOrder);

        /** Internal method to notify the element when it's world transform
         of parent overlay has changed.
        */
        virtual void _notifyWorldTransforms(const Matrix4& xform);

        /** Internal method to notify the element when the viewport
         of parent overlay has changed.
        */
        virtual void _notifyViewport();

        /** Internal method to put the contents onto the render queue. */
        virtual void _updateRenderQueue(RenderQueue* queue);

		/// @copydoc MovableObject::visitRenderables
		void visitRenderables(Renderable::Visitor* visitor, 
			bool debugRenderables = false);

        /** Gets the type name of the element. All concrete subclasses must implement this. */
        virtual const String& getTypeName(void) const = 0;

        /** Sets the caption on elements that support it. 
        @remarks
        This property doesn't do something on all elements, just those that support it.
        However, being a common requirement it is in the top-level interface to avoid
        having to set it via the StringInterface all the time.
        */
		virtual void setCaption(const DisplayString& text);
        /** Gets the caption for this element. */
        virtual const DisplayString& getCaption(void) const;
        /** Sets the colour on elements that support it. 
        @remarks
        This property doesn't do something on all elements, just those that support it.
        However, being a common requirement it is in the top-level interface to avoid
        having to set it via the StringInterface all the time.
        */
        virtual void setColour(const ColourValue& col);

        /** Gets the colour for this element. */
        virtual const ColourValue& getColour(void) const;

        /** Tells this element how to interpret the position and dimension values it is given.
        @remarks
        By default, OverlayElements are positioned and sized according to relative dimensions
        of the screen. This is to ensure portability between different resolutions when you
        want things to be positioned and sized the same way across all resolutions. However, 
        sometimes you want things to be sized according to fixed pixels. In order to do this,
        you can call this method with the parameter GMM_PIXELS. Note that if you then want
        to place your element relative to the center, right or bottom of it's parent, you will
        need to use the setHorizontalAlignment and setVerticalAlignment methods.
        */
        virtual void setMetricsMode(GuiMetricsMode gmm);
        /** Retrieves the current settings of how the element metrics are interpreted. */
        virtual GuiMetricsMode getMetricsMode(void) const;
        /** Sets the horizontal origin for this element.
        @remarks
        By default, the horizontal origin for a OverlayElement is the left edge of the parent container
        (or the screen if this is a root element). You can alter this by calling this method, which is
        especially useful when you want to use pixel-based metrics (see setMetricsMode) since in this
        mode you can't use relative positioning.
        @par
        For example, if you were using GMM_PIXELS metrics mode, and you wanted to place a 30x30 pixel
        crosshair in the center of the screen, you would use GHA_CENTER with a 'left' property of -15.
        @par
        Note that neither GHA_CENTER or GHA_RIGHT alter the position of the element based
        on it's width, you have to alter the 'left' to a negative number to do that; all this
        does is establish the origin. This is because this way you can align multiple things
        in the center and right with different 'left' offsets for maximum flexibility.
        */
        virtual void setHorizontalAlignment(GuiHorizontalAlignment gha);
        /** Gets the horizontal alignment for this element. */
        virtual GuiHorizontalAlignment getHorizontalAlignment(void) const;
        /** Sets the vertical origin for this element. 
        @remarks
        By default, the vertical origin for a OverlayElement is the top edge of the parent container
        (or the screen if this is a root element). You can alter this by calling this method, which is
        especially useful when you want to use pixel-based metrics (see setMetricsMode) since in this
        mode you can't use relative positioning.
        @par
        For example, if you were using GMM_PIXELS metrics mode, and you wanted to place a 30x30 pixel
        crosshair in the center of the screen, you would use GHA_CENTER with a 'top' property of -15.
        @par
        Note that neither GVA_CENTER or GVA_BOTTOM alter the position of the element based
        on it's height, you have to alter the 'top' to a negative number to do that; all this
        does is establish the origin. This is because this way you can align multiple things
        in the center and bottom with different 'top' offsets for maximum flexibility.
        */
        virtual void setVerticalAlignment(GuiVerticalAlignment gva);
        /** Gets the vertical alignment for this element. */
        virtual GuiVerticalAlignment getVerticalAlignment(void) const;




        /** Returns true if xy is within the constraints of the component */
        virtual bool contains(Real x, Real y) const;

        /** Returns true if xy is within the constraints of the component */
        virtual OverlayElement* findElementAt(Real x, Real y);		// relative to parent

        /**
        * returns false as this class is not a container type 
        */
        inline virtual bool isContainer() const
        { return false; }

        inline virtual bool isKeyEnabled() const
        { return false; }

        inline virtual bool isCloneable() const
        { return mCloneable; }

        inline virtual void setCloneable(bool c)
        { mCloneable = c; }

        /**
        * Returns the parent container.
        */
        OverlayContainer* getParent() ;
        void _setParent(OverlayContainer* parent) { mParent = parent; }

        /**
        * Returns the zOrder of the element
        */
        inline ushort getZOrder() const
        { return mZOrder; }

        /** Overridden from Renderable */
        Real getSquaredViewDepth(const Camera* cam) const 
        { 
            (void)cam;
            return 10000.0f - (Real)getZOrder(); 
        }

        /** @copydoc Renderable::getLights */
        const LightList& getLights(void) const
        {
            // Overlayelements should not be lit by the scene, this will not get called
            static LightList ll;
            return ll;
        }

        virtual void copyFromTemplate(OverlayElement* templateOverlay);
        virtual OverlayElement* clone(const String& instanceName);

        /// Returns the SourceTemplate for this element
        const OverlayElement* getSourceTemplate () const {
          return mSourceTemplate ;
        }
    };


	/** @} */
	/** @} */

}


#endif