source: GTP/trunk/App/Demos/Geom/OgreStuff/include/OgreOverlayElement.h @ 1812

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