source: OGRE/trunk/ogrenew/OgreMain/include/OgreOverlayElement.h @ 692

Revision 692, 20.3 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies

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-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 clipping region of the element */
315        virtual void _getClippingRegion(Rectangle &clippingRegion);
316
317        /** Internal method to notify the element when Zorder of parent overlay
318        has changed.
319        @remarks
320        Overlays have explicit Z orders. OverlayElements do not, they inherit the
321        ZOrder of the overlay, and the Zorder is incremented for every container
322        nested within this to ensure that containers are displayed behind contained
323        items. This method is used internally to notify the element of a change in
324        final zorder which is used to render the element.
325        */
326        virtual void _notifyZOrder(ushort newZOrder);
327
328        /** Internal method to notify the element when it's world transform
329         of parent overlay has changed.
330        */
331        virtual void _notifyWorldTransforms(const Matrix4& xform);
332
333        /** Internal method to notify the element when the viewport
334         of parent overlay has changed.
335        */
336        virtual void _notifyViewport();
337
338        /** Internal method to put the contents onto the render queue. */
339        virtual void _updateRenderQueue(RenderQueue* queue);
340
341        /** Gets the type name of the element. All concrete subclasses must implement this. */
342        virtual const String& getTypeName(void) const = 0;
343
344        /** Sets the caption on elements that support it.
345        @remarks
346        This property doesn't do something on all elements, just those that support it.
347        However, being a common requirement it is in the top-level interface to avoid
348        having to set it via the StringInterface all the time.
349        */
350        virtual void setCaption(const String& text);
351
352        /** Gets the caption for this element. */
353        virtual const String& getCaption(void) const;
354
355        /** Sets the colour on elements that support it.
356        @remarks
357        This property doesn't do something on all elements, just those that support it.
358        However, being a common requirement it is in the top-level interface to avoid
359        having to set it via the StringInterface all the time.
360        */
361        virtual void setColour(const ColourValue& col);
362
363        /** Gets the colour for this element. */
364        virtual const ColourValue& getColour(void) const;
365
366        /** Tells this element how to interpret the position and dimension values it is given.
367        @remarks
368        By default, OverlayElements are positioned and sized according to relative dimensions
369        of the screen. This is to ensure portability between different resolutions when you
370        want things to be positioned and sized the same way across all resolutions. However,
371        sometimes you want things to be sized according to fixed pixels. In order to do this,
372        you can call this method with the parameter GMM_PIXELS. Note that if you then want
373        to place your element relative to the center, right or bottom of it's parent, you will
374        need to use the setHorizontalAlignment and setVerticalAlignment methods.
375        */
376        virtual void setMetricsMode(GuiMetricsMode gmm);
377        /** Retrieves the current settings of how the element metrics are interpreted. */
378        virtual GuiMetricsMode getMetricsMode(void) const;
379        /** Sets the horizontal origin for this element.
380        @remarks
381        By default, the horizontal origin for a OverlayElement is the left edge of the parent container
382        (or the screen if this is a root element). You can alter this by calling this method, which is
383        especially useful when you want to use pixel-based metrics (see setMetricsMode) since in this
384        mode you can't use relative positioning.
385        @par
386        For example, if you were using GMM_PIXELS metrics mode, and you wanted to place a 30x30 pixel
387        crosshair in the center of the screen, you would use GHA_CENTER with a 'left' property of -15.
388        @par
389        Note that neither GHA_CENTER or GHA_RIGHT alter the position of the element based
390        on it's width, you have to alter the 'left' to a negative number to do that; all this
391        does is establish the origin. This is because this way you can align multiple things
392        in the center and right with different 'left' offsets for maximum flexibility.
393        */
394        virtual void setHorizontalAlignment(GuiHorizontalAlignment gha);
395        /** Gets the horizontal alignment for this element. */
396        virtual GuiHorizontalAlignment getHorizontalAlignment(void) const;
397        /** Sets the vertical origin for this element.
398        @remarks
399        By default, the vertical origin for a OverlayElement is the top edge of the parent container
400        (or the screen if this is a root element). You can alter this by calling this method, which is
401        especially useful when you want to use pixel-based metrics (see setMetricsMode) since in this
402        mode you can't use relative positioning.
403        @par
404        For example, if you were using GMM_PIXELS metrics mode, and you wanted to place a 30x30 pixel
405        crosshair in the center of the screen, you would use GHA_CENTER with a 'top' property of -15.
406        @par
407        Note that neither GVA_CENTER or GVA_BOTTOM alter the position of the element based
408        on it's height, you have to alter the 'top' to a negative number to do that; all this
409        does is establish the origin. This is because this way you can align multiple things
410        in the center and bottom with different 'top' offsets for maximum flexibility.
411        */
412        virtual void setVerticalAlignment(GuiVerticalAlignment gva);
413        /** Gets the vertical alignment for this element. */
414        virtual GuiVerticalAlignment getVerticalAlignment(void) const;
415
416
417
418
419        /** Returns true if xy is within the constraints of the component */
420        virtual bool contains(Real x, Real y) const;
421
422        /** Returns true if xy is within the constraints of the component */
423        virtual OverlayElement* findElementAt(Real x, Real y);          // relative to parent
424
425        /**
426        * returns false as this class is not a container type
427        */
428        inline virtual bool isContainer() const
429        { return false; }
430
431        inline virtual bool isKeyEnabled() const
432        { return false; }
433
434        inline virtual bool isCloneable() const
435        { return mCloneable; }
436
437        inline virtual void setCloneable(bool c)
438        { mCloneable = c; }
439
440        /**
441        * Returns the parent container.
442        */
443        OverlayContainer* getParent() ;
444        void _setParent(OverlayContainer* parent) { mParent = parent; }
445
446        /**
447        * Returns the zOrder of the element
448        */
449        inline ushort getZOrder() const
450        { return mZOrder; }
451
452        /** Overridden from Renderable */
453        Real getSquaredViewDepth(const Camera* cam) const
454        {
455            return 10000 - getZOrder();
456        }
457
458        /** @copydoc Renderable::getLights */
459        const LightList& getLights(void) const
460        {
461            // Overlayelements should not be lit by the scene, this will not get called
462            static LightList ll;
463            return ll;
464        }
465
466        void copyFromTemplate(OverlayElement* templateOverlay);
467        virtual OverlayElement* clone(const String& instanceName);
468
469        // Returns the SourceTemplate for this element
470        const OverlayElement* getSourceTemplate () const {
471          return mSourceTemplate ;
472        }
473    };
474
475
476
477}
478
479
480#endif
481
Note: See TracBrowser for help on using the repository browser.