Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/ogre_src_v1-9-0/OgreMain/include/Overlay/OgreOverlayElement.h @ 148

Last change on this file since 148 was 148, checked in by patricwi, 6 years ago

Added new dependencies for ogre1.9 and cegui0.8

File size: 20.7 KB
Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4(Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2013 Torus Knot Software Ltd
8
9Permission is hereby granted, free of charge, to any person obtaining a copy
10of this software and associated documentation files (the "Software"), to deal
11in the Software without restriction, including without limitation the rights
12to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13copies of the Software, and to permit persons to whom the Software is
14furnished to do so, subject to the following conditions:
15
16The above copyright notice and this permission notice shall be included in
17all copies or substantial portions of the Software.
18
19THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25THE SOFTWARE.
26-----------------------------------------------------------------------------
27*/
28
29#ifndef __OverlayElement_H__
30#define __OverlayElement_H__
31
32#include "OgreOverlayPrerequisites.h"
33#include "OgreString.h"
34#include "OgreRenderable.h"
35#include "OgreUTFString.h"
36#include "OgreStringInterface.h"
37#include "OgreOverlayElementCommands.h"
38
39#include "OgreColourValue.h"
40
41namespace Ogre {
42        /** \addtogroup Core
43        *  @{
44        */
45        /** \addtogroup Overlays
46        *  @{
47        */
48
49#if OGRE_UNICODE_SUPPORT
50        typedef UTFString DisplayString;
51#       define OGRE_DEREF_DISPLAYSTRING_ITERATOR(it) it.getCharacter()
52#else
53        typedef String DisplayString;
54#       define OGRE_DEREF_DISPLAYSTRING_ITERATOR(it) *it
55#endif
56    /** Enum describing how the position / size of an element is to be recorded.
57    */
58    enum GuiMetricsMode
59    {
60        /// 'left', 'top', 'height' and 'width' are parametrics from 0.0 to 1.0
61        GMM_RELATIVE,
62        /// Positions & sizes are in absolute pixels
63        GMM_PIXELS,
64        /// Positions & sizes are in virtual pixels
65        GMM_RELATIVE_ASPECT_ADJUSTED
66    };
67
68    /** Enum describing where '0' is in relation to the parent in the horizontal dimension.
69    @remarks Affects how 'left' is interpreted.
70    */
71    enum GuiHorizontalAlignment
72    {
73        GHA_LEFT,
74        GHA_CENTER,
75        GHA_RIGHT
76    };
77    /** Enum describing where '0' is in relation to the parent in the vertical dimension.
78    @remarks Affects how 'top' is interpreted.
79    */
80    enum GuiVerticalAlignment
81    {
82        GVA_TOP,
83        GVA_CENTER,
84        GVA_BOTTOM
85    };
86
87    /** Abstract definition of a 2D element to be displayed in an Overlay.
88    @remarks
89    This class abstracts all the details of a 2D element which will appear in
90    an overlay. In fact, not all OverlayElement instances can be directly added to an
91    Overlay, only those which are OverlayContainer instances (a subclass of this class).
92    OverlayContainer objects can contain any OverlayElement however. This is just to
93    enforce some level of grouping on widgets.
94    @par
95    OverlayElements should be managed using OverlayManager. This class is responsible for
96    instantiating / deleting elements, and also for accepting new types of element
97    from plugins etc.
98    @par
99    Note that positions / dimensions of 2D screen elements are expressed as parametric
100    values (0.0 - 1.0) because this makes them resolution-independent. However, most
101    screen resolutions have an aspect ratio of 1.3333:1 (width : height) so note that
102    in physical pixels 0.5 is wider than it is tall, so a 0.5x0.5 panel will not be
103    square on the screen (but it will take up exactly half the screen in both dimensions).
104    @par
105    Because this class is designed to be extensible, it subclasses from StringInterface
106    so its parameters can be set in a generic way.
107    */
108    class _OgreOverlayExport OverlayElement : public StringInterface, public Renderable, public OverlayAlloc
109    {
110    public:
111
112    protected:
113        // Command object for setting / getting parameters
114        static OverlayElementCommands::CmdLeft msLeftCmd;
115        static OverlayElementCommands::CmdTop msTopCmd;
116        static OverlayElementCommands::CmdWidth msWidthCmd;
117        static OverlayElementCommands::CmdHeight msHeightCmd;
118        static OverlayElementCommands::CmdMaterial msMaterialCmd;
119        static OverlayElementCommands::CmdCaption msCaptionCmd;
120        static OverlayElementCommands::CmdMetricsMode msMetricsModeCmd;
121        static OverlayElementCommands::CmdHorizontalAlign msHorizontalAlignCmd;
122        static OverlayElementCommands::CmdVerticalAlign msVerticalAlignCmd;
123        static OverlayElementCommands::CmdVisible msVisibleCmd;
124
125
126        String mName;
127        bool mVisible;
128        bool mCloneable;
129        Real mLeft;
130        Real mTop;
131        Real mWidth;
132        Real mHeight;
133        String mMaterialName;
134        MaterialPtr mMaterial;
135        DisplayString mCaption;
136        ColourValue mColour;
137        RealRect mClippingRegion;
138
139        GuiMetricsMode mMetricsMode;
140        GuiHorizontalAlignment mHorzAlign;
141        GuiVerticalAlignment mVertAlign;
142
143        // metric-mode positions, used in GMM_PIXELS & GMM_RELATIVE_ASPECT_ADJUSTED mode.
144        Real mPixelTop;
145        Real mPixelLeft;
146        Real mPixelWidth;
147        Real mPixelHeight;
148        Real mPixelScaleX;
149        Real mPixelScaleY;
150
151        /// Parent pointer
152        OverlayContainer* mParent;
153        /// Overlay attached to
154        Overlay* mOverlay;
155
156        // Derived positions from parent
157        Real mDerivedLeft;
158        Real mDerivedTop;
159        bool mDerivedOutOfDate;
160
161        /// Flag indicating if the vertex positions need recalculating
162        bool mGeomPositionsOutOfDate;
163                /// Flag indicating if the vertex uvs need recalculating
164                bool mGeomUVsOutOfDate;
165
166        /** Zorder for when sending to render queue.
167            Derived from parent */
168        ushort mZOrder;
169
170        /// World transforms
171        Matrix4 mXForm;
172
173        /// Is element enabled?
174        bool mEnabled;
175
176                /// Is element initialised?
177                bool mInitialised;
178
179        /// Used to see if this element is created from a Template
180        OverlayElement* mSourceTemplate ;
181
182        /** Internal method which is triggered when the positions of the element get updated,
183        meaning the element should be rebuilding it's mesh positions. Abstract since
184        subclasses must implement this.
185        */
186        virtual void updatePositionGeometry(void) = 0;
187                /** Internal method which is triggered when the UVs of the element get updated,
188                meaning the element should be rebuilding it's mesh UVs. Abstract since
189                subclasses must implement this.
190                */
191                virtual void updateTextureGeometry(void) = 0;
192
193        /** Internal method for setting up the basic parameter definitions for a subclass.
194        @remarks
195        Because StringInterface holds a dictionary of parameters per class, subclasses need to
196        call this to ask the base class to add it's parameters to their dictionary as well.
197        Can't do this in the constructor because that runs in a non-virtual context.
198        @par
199        The subclass must have called it's own createParamDictionary before calling this method.
200        */
201        virtual void addBaseParameters(void);
202
203    public:
204        /// Constructor: do not call direct, use OverlayManager::createElement
205        OverlayElement(const String& name);
206        virtual ~OverlayElement();
207
208        /** Initialise gui element */
209        virtual void initialise(void) = 0;
210
211        /** Gets the name of this overlay. */
212        const String& getName(void) const;
213
214
215        /** Shows this element if it was hidden. */
216        virtual void show(void);
217
218        /** Hides this element if it was visible. */
219        virtual void hide(void);
220
221        /** Returns whether or not the element is visible. */
222        bool isVisible(void) const;
223
224        bool isEnabled() const;
225        virtual void setEnabled(bool b);
226
227
228        /** Sets the dimensions of this element in relation to the screen (1.0 = screen width/height). */
229        void setDimensions(Real width, Real height);
230
231        /** Sets the position of the top-left corner of the element, relative to the screen size
232        (1.0 = screen width / height) */
233        void setPosition(Real left, Real top);
234
235        /** Sets the width of this element in relation to the screen (where 1.0 = screen width) */
236        void setWidth(Real width);
237        /** Gets the width of this element in relation to the screen (where 1.0 = screen width) */
238        Real getWidth(void) const;
239
240        /** Sets the height of this element in relation to the screen (where 1.0 = screen height) */
241        void setHeight(Real height);
242        /** Gets the height of this element in relation to the screen (where 1.0 = screen height) */
243        Real getHeight(void) const;
244
245        /** Sets the left of this element in relation to the screen (where 0 = far left, 1.0 = far right) */
246        void setLeft(Real left);
247        /** Gets the left of this element in relation to the screen (where 0 = far left, 1.0 = far right)  */
248        Real getLeft(void) const;
249
250        /** Sets the top of this element in relation to the screen (where 0 = top, 1.0 = bottom) */
251        void setTop(Real Top);
252        /** Gets the top of this element in relation to the screen (where 0 = top, 1.0 = bottom)  */
253        Real getTop(void) const;
254
255        /** Gets the left of this element in relation to the screen (where 0 = far left, 1.0 = far right)  */
256        Real _getLeft(void) const { return mLeft; }
257        /** Gets the top of this element in relation to the screen (where 0 = far left, 1.0 = far right)  */
258        Real _getTop(void) const { return mTop; }
259        /** Gets the width of this element in relation to the screen (where 1.0 = screen width)  */
260        Real _getWidth(void) const { return mWidth; }
261        /** Gets the height of this element in relation to the screen (where 1.0 = screen height)  */
262        Real _getHeight(void) const { return mHeight; }
263        /** Sets the left of this element in relation to the screen (where 1.0 = screen width) */
264        void _setLeft(Real left);
265        /** Sets the top of this element in relation to the screen (where 1.0 = screen width) */
266        void _setTop(Real top);
267        /** Sets the width of this element in relation to the screen (where 1.0 = screen width) */
268        void _setWidth(Real width);
269        /** Sets the height of this element in relation to the screen (where 1.0 = screen width) */
270        void _setHeight(Real height);
271        /** Sets the left and top of this element in relation to the screen (where 1.0 = screen width) */
272        void _setPosition(Real left, Real top);
273        /** Sets the width and height of this element in relation to the screen (where 1.0 = screen width) */
274        void _setDimensions(Real width, Real height);
275
276        /** Gets the name of the material this element uses. */
277        virtual const String& getMaterialName(void) const;
278
279        /** Sets the name of the material this element will use.
280        @remarks
281        Different elements will use different materials. One constant about them
282        all though is that a Material used for a OverlayElement must have it's depth
283        checking set to 'off', which means it always gets rendered on top. OGRE
284        will set this flag for you if necessary. What it does mean though is that
285        you should not use the same Material for rendering OverlayElements as standard
286        scene objects. It's fine to use the same textures, just not the same
287        Material.
288        */
289        virtual void setMaterialName(const String& matName);
290
291
292        // --- Renderable Overrides ---
293        /** See Renderable */
294        const MaterialPtr& getMaterial(void) const;
295
296        // NB getRenderOperation not implemented, still abstract here
297
298        /** See Renderable */
299        void getWorldTransforms(Matrix4* xform) const;
300
301        /** Tell the object to recalculate */
302        virtual void _positionsOutOfDate(void);
303
304        /** Internal method to update the element based on transforms applied. */
305        virtual void _update(void);
306
307        /** Updates this elements transform based on it's parent. */
308        virtual void _updateFromParent(void);
309
310        /** Internal method for notifying the GUI element of it's parent and ultimate overlay. */
311        virtual void _notifyParent(OverlayContainer* parent, Overlay* overlay);
312
313        /** Gets the 'left' position as derived from own left and that of parents. */
314        virtual Real _getDerivedLeft(void);
315
316        /** Gets the 'top' position as derived from own left and that of parents. */
317        virtual Real _getDerivedTop(void);
318
319                /** Gets the 'width' as derived from own width and metrics mode. */
320                virtual Real _getRelativeWidth(void);
321                /** Gets the 'height' as derived from own height and metrics mode. */
322                virtual Real _getRelativeHeight(void);
323
324
325        /** Gets the clipping region of the element */
326        virtual void _getClippingRegion(RealRect &clippingRegion);
327
328        /** Internal method to notify the element when Z-order of parent overlay
329        has changed.
330        @remarks
331        Overlays have explicit Z-orders. OverlayElements do not, they inherit the
332        Z-order of the overlay, and the Z-order is incremented for every container
333        nested within this to ensure that containers are displayed behind contained
334        items. This method is used internally to notify the element of a change in
335        final Z-order which is used to render the element.
336                @return Return the next Z-ordering number available. For single elements, this
337                is simply 'newZOrder + 1', except for containers. They increment it once for each
338                child (or even more if those children are also containers with their own elements).
339        */
340        virtual ushort _notifyZOrder(ushort newZOrder);
341
342        /** Internal method to notify the element when it's world transform
343         of parent overlay has changed.
344        */
345        virtual void _notifyWorldTransforms(const Matrix4& xform);
346
347        /** Internal method to notify the element when the viewport
348         of parent overlay has changed.
349        */
350        virtual void _notifyViewport();
351
352        /** Internal method to put the contents onto the render queue. */
353        virtual void _updateRenderQueue(RenderQueue* queue);
354
355                /// @copydoc MovableObject::visitRenderables
356                void visitRenderables(Renderable::Visitor* visitor, 
357                        bool debugRenderables = false);
358
359        /** Gets the type name of the element. All concrete subclasses must implement this. */
360        virtual const String& getTypeName(void) const = 0;
361
362        /** Sets the caption on elements that support it.
363        @remarks
364        This property doesn't do something on all elements, just those that support it.
365        However, being a common requirement it is in the top-level interface to avoid
366        having to set it via the StringInterface all the time.
367        */
368                virtual void setCaption(const DisplayString& text);
369        /** Gets the caption for this element. */
370        virtual const DisplayString& getCaption(void) const;
371        /** Sets the colour on elements that support it.
372        @remarks
373        This property doesn't do something on all elements, just those that support it.
374        However, being a common requirement it is in the top-level interface to avoid
375        having to set it via the StringInterface all the time.
376        */
377        virtual void setColour(const ColourValue& col);
378
379        /** Gets the colour for this element. */
380        virtual const ColourValue& getColour(void) const;
381
382        /** Tells this element how to interpret the position and dimension values it is given.
383        @remarks
384        By default, OverlayElements are positioned and sized according to relative dimensions
385        of the screen. This is to ensure portability between different resolutions when you
386        want things to be positioned and sized the same way across all resolutions. However,
387        sometimes you want things to be sized according to fixed pixels. In order to do this,
388        you can call this method with the parameter GMM_PIXELS. Note that if you then want
389        to place your element relative to the center, right or bottom of it's parent, you will
390        need to use the setHorizontalAlignment and setVerticalAlignment methods.
391        */
392        virtual void setMetricsMode(GuiMetricsMode gmm);
393        /** Retrieves the current settings of how the element metrics are interpreted. */
394        virtual GuiMetricsMode getMetricsMode(void) const;
395        /** Sets the horizontal origin for this element.
396        @remarks
397        By default, the horizontal origin for a OverlayElement is the left edge of the parent container
398        (or the screen if this is a root element). You can alter this by calling this method, which is
399        especially useful when you want to use pixel-based metrics (see setMetricsMode) since in this
400        mode you can't use relative positioning.
401        @par
402        For example, if you were using GMM_PIXELS metrics mode, and you wanted to place a 30x30 pixel
403        crosshair in the center of the screen, you would use GHA_CENTER with a 'left' property of -15.
404        @par
405        Note that neither GHA_CENTER or GHA_RIGHT alter the position of the element based
406        on it's width, you have to alter the 'left' to a negative number to do that; all this
407        does is establish the origin. This is because this way you can align multiple things
408        in the center and right with different 'left' offsets for maximum flexibility.
409        */
410        virtual void setHorizontalAlignment(GuiHorizontalAlignment gha);
411        /** Gets the horizontal alignment for this element. */
412        virtual GuiHorizontalAlignment getHorizontalAlignment(void) const;
413        /** Sets the vertical origin for this element.
414        @remarks
415        By default, the vertical origin for a OverlayElement is the top edge of the parent container
416        (or the screen if this is a root element). You can alter this by calling this method, which is
417        especially useful when you want to use pixel-based metrics (see setMetricsMode) since in this
418        mode you can't use relative positioning.
419        @par
420        For example, if you were using GMM_PIXELS metrics mode, and you wanted to place a 30x30 pixel
421        crosshair in the center of the screen, you would use GHA_CENTER with a 'top' property of -15.
422        @par
423        Note that neither GVA_CENTER or GVA_BOTTOM alter the position of the element based
424        on it's height, you have to alter the 'top' to a negative number to do that; all this
425        does is establish the origin. This is because this way you can align multiple things
426        in the center and bottom with different 'top' offsets for maximum flexibility.
427        */
428        virtual void setVerticalAlignment(GuiVerticalAlignment gva);
429        /** Gets the vertical alignment for this element. */
430        virtual GuiVerticalAlignment getVerticalAlignment(void) const;
431
432
433
434
435        /** Returns true if xy is within the constraints of the component */
436        virtual bool contains(Real x, Real y) const;
437
438        /** Returns true if xy is within the constraints of the component */
439        virtual OverlayElement* findElementAt(Real x, Real y);          // relative to parent
440
441        /**
442        * returns false as this class is not a container type
443        */
444        inline virtual bool isContainer() const
445        { return false; }
446
447        inline virtual bool isKeyEnabled() const
448        { return false; }
449
450        inline virtual bool isCloneable() const
451        { return mCloneable; }
452
453        inline virtual void setCloneable(bool c)
454        { mCloneable = c; }
455
456        /**
457        * Returns the parent container.
458        */
459        OverlayContainer* getParent() ;
460        void _setParent(OverlayContainer* parent) { mParent = parent; }
461
462        /**
463        * Returns the zOrder of the element
464        */
465        inline ushort getZOrder() const
466        { return mZOrder; }
467
468        /** Overridden from Renderable */
469        Real getSquaredViewDepth(const Camera* cam) const 
470        { 
471            (void)cam;
472            return 10000.0f - (Real)getZOrder(); 
473        }
474
475        /** @copydoc Renderable::getLights */
476        const LightList& getLights(void) const
477        {
478            // Overlayelements should not be lit by the scene, this will not get called
479            static LightList ll;
480            return ll;
481        }
482
483        virtual void copyFromTemplate(OverlayElement* templateOverlay);
484        virtual OverlayElement* clone(const String& instanceName);
485
486        /// Returns the SourceTemplate for this element
487        const OverlayElement* getSourceTemplate () const {
488          return mSourceTemplate ;
489        }
490    };
491
492
493        /** @} */
494        /** @} */
495
496}
497
498
499#endif
500
Note: See TracBrowser for help on using the repository browser.