source: OGRE/trunk/ogre_dependencies/Dependencies/include/CEGUI/CEGUIWindow.h @ 692

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

adding ogre 1.2 and dependencies

Line 
1/************************************************************************
2        filename:       CEGUIWindow.h
3        created:        21/2/2004
4        author:         Paul D Turner
5
6        purpose:        Defines abstract base class for Window objects
7*************************************************************************/
8/*************************************************************************
9    Crazy Eddie's GUI System (http://www.cegui.org.uk)
10    Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
11
12    This library is free software; you can redistribute it and/or
13    modify it under the terms of the GNU Lesser General Public
14    License as published by the Free Software Foundation; either
15    version 2.1 of the License, or (at your option) any later version.
16
17    This library is distributed in the hope that it will be useful,
18    but WITHOUT ANY WARRANTY; without even the implied warranty of
19    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
20    Lesser General Public License for more details.
21
22    You should have received a copy of the GNU Lesser General Public
23    License along with this library; if not, write to the Free Software
24    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
25*************************************************************************/
26#ifndef _CEGUIWindow_h_
27#define _CEGUIWindow_h_
28
29#include "CEGUIBase.h"
30#include "CEGUIString.h"
31#include "CEGUIVector.h"
32#include "CEGUIRect.h"
33#include "CEGUISize.h"
34#include "CEGUIEventSet.h"
35#include "CEGUIPropertySet.h"
36#include "CEGUISystem.h"
37#include "CEGUIInputEvent.h"
38#include "CEGUIWindowProperties.h"
39#include "CEGUIUDim.h"
40#include "CEGUIRenderCache.h"
41#include <vector>
42
43
44#if defined(_MSC_VER)
45#       pragma warning(push)
46#       pragma warning(disable : 4251)
47#endif
48
49
50// Start of CEGUI namespace section
51namespace CEGUI
52{
53
54/*!
55\brief
56        Mode used for Window size and position metrics.
57
58        Position information for a Window is always 'relative' to it's parent even in Absolute mode.
59        In Relative mode, layout is maintained for different screen resolutions, and also  offers the
60        ability for child windows to properly adjust their layout as their parent is sized.
61*/
62enum MetricsMode
63{
64        Relative,               //!< Metrics are specified as a decimal fraction of parent Window size.
65        Absolute,               //!< Metrics are specified as whole pixels.
66        Inherited               //!< Metrics are inherited from parent.
67};
68
69/*!
70\brief
71    Enumerated type used when specifying vertical alignments.
72 */
73enum VerticalAlignment
74{
75    VA_TOP,        //!< Elements position specifies an offset of it's top edge from the top edge of it's parent.
76    VA_CENTRE,     //!< Elements position specifies an offset of it's vertical centre from the vertical centre of it's parent.
77    VA_BOTTOM      //!< Elements position specifies an offset of it's bottom edge from the bottom edge of it's parent.
78};
79
80/*!
81\brief
82    Enumerated type used when specifying horizontal alignments.
83 */
84enum HorizontalAlignment
85{
86    HA_LEFT,        //!< Elements position specifies an offset of it's left edge from the left edge of it's parent.
87    HA_CENTRE,      //!< Elements position specifies an offset of it's horizontal centre from the horizontal centre of it's parent.
88    HA_RIGHT        //!< Elements position specifies an offset of it's right edge from the right edge of it's parent.
89};
90
91/*!
92\brief
93        An abstract base class providing common functionality and specifying the required interface for derived classes.
94
95        The Window base class is the only UI object class that the core of the system knows about, for this reason every
96        other window, widget, or similar item within the system must be derived from Window.  The base class provides the
97        common functionality required by all UI objects, and specifies the minimal interface required to be implemented by
98        derived classes.
99*/
100class CEGUIEXPORT Window : public PropertySet, public EventSet
101{
102public:
103        static const String EventNamespace;                             //!< Namespace for global events
104
105        /*************************************************************************
106                Event name constants
107        *************************************************************************/
108        // generated internally by Window
109        static const String EventParentSized;                           //!< Parent of this Window has been re-sized.
110        static const String EventSized;                                 //!< Window size has changed
111        static const String EventMoved;                                 //!< Window position has changed
112        static const String EventTextChanged;                           //!< Text string for the Window has changed
113        static const String EventFontChanged;                           //!< Font object for the Window has been changed
114        static const String EventAlphaChanged;                  //!< Alpha blend value for the Window has changed
115        static const String EventIDChanged;                             //!< Client assigned ID code for the Window has changed
116        static const String EventActivated;                             //!< Window has been activated (has input focus)
117        static const String EventDeactivated;                           //!< Window has been deactivated (loses input focus)
118        static const String EventShown;                                 //!< Window has been made visible
119        static const String EventHidden;                                        //!< Window has been hidden from view
120        static const String EventEnabled;                                       //!< Window has been enabled (interaction is possible)
121        static const String EventDisabled;                              //!< Window has been disabled (interaction is no longer possible)
122        static const String EventMetricsModeChanged;            //!< Active metrics mode has been modified
123        static const String EventClippedByParentChanged;        //!< Clipping by parent mode has been modified
124        static const String EventDestroyedByParentChanged;//!< Destruction by parent mode has been modified
125        static const String EventInheritsAlphaChanged;  //!< Alpha inherited from parent mode has been modified.
126        static const String EventAlwaysOnTopChanged;            //!< Always on top mode has been modified
127        static const String EventInputCaptureGained;            //!< Window has captured all inputs
128        static const String EventInputCaptureLost;              //!< Window has lost it's capture on inputs
129        static const String EventRenderingStarted;              //!< Rendering of the Window has started
130        static const String EventRenderingEnded;                        //!< Rendering for the Window has finished
131        static const String EventChildAdded;                            //!< A child Window has been added
132        static const String EventChildRemoved;                  //!< A child window has been removed
133        static const String EventDestructionStarted;            //!< Destruction of the Window is about to begin.
134        static const String EventZOrderChanged;                 //!< The z-order of the window has changed
135        static const String EventDragDropItemEnters;    //!< A DragContainer has been dragged over this window.
136        static const String EventDragDropItemLeaves;    //!< A DragContainer has left this window.
137        static const String EventDragDropItemDropped;   //!< A DragContainer was dropped on this Window.
138    static const String EventVerticalAlignmentChanged;    //!< The vertical alignment of the window has changed.
139    static const String EventHorizontalAlignmentChanged;  //!< The vertical alignment of the window has changed.
140
141        // generated externally (inputs)
142        static const String EventMouseEnters;                           //!< Mouse cursor has entered the Window.
143        static const String EventMouseLeaves;                           //!< Mouse cursor has left the Window.
144        static const String EventMouseMove;                             //!< Mouse cursor was moved within the area of the Window.
145        static const String EventMouseWheel;                            //!< Mouse wheel was scrolled within the Window.
146        static const String EventMouseButtonDown;                       //!< A mouse button was pressed down within the Window.
147        static const String EventMouseButtonUp;                 //!< A mouse button was released within the Window.
148        static const String EventMouseClick;                            //!< A mouse button was clicked (down then up) within the Window.
149        static const String EventMouseDoubleClick;              //!< A mouse button was double-clicked within the Window.
150        static const String EventMouseTripleClick;              //!< A mouse button was triple-clicked within the Window.
151        static const String EventKeyDown;                                       //!< A key on the keyboard was pressed.
152        static const String EventKeyUp;                                 //!< A key on the keyboard was released.
153        static const String EventCharacterKey;                  //!< A text character was typed on the keyboard.
154
155
156        /*************************************************************************
157                Construction and Destruction
158        *************************************************************************/
159        /*!
160        \brief
161                Constructor for Window base class
162
163        \param type
164                String object holding Window type (usually provided by WindowFactory).
165
166        \param name
167                String object holding unique name for the Window.
168        */
169        Window(const String& type, const String& name);
170
171
172        /*!
173        \brief
174                Destructor for Window base class
175        */
176        virtual ~Window(void);
177
178
179        /*************************************************************************
180                Accessor functions
181        *************************************************************************/
182        /*!
183        \brief
184                return a String object holding the type name for this Window.
185
186        \return
187                String object holding the Window type.
188        */
189        const String& getType(void) const;
190
191
192        /*!
193        \brief
194                return a String object holding the name of this Window.
195
196        \return
197                String object holding the unique Window name.
198        */
199        const String& getName(void) const               {return d_name;}
200
201
202        /*!
203        \brief
204                returns whether or not this Window is set to be destroyed when its parent is destroyed.
205
206        \return
207                true if the Window will be destroyed when its parent is destroyed, false if it will remain.
208        */
209        bool    isDestroyedByParent(void) const         {return d_destroyedByParent;}
210
211
212        /*!
213        \brief
214                returns whether or not this Window is an always on top (a.k.a 'topmost') Window.
215
216        \return
217                true if this Window is always show on top of other normal windows.  false if the Window has normal z-order behaviour.
218        */
219        bool    isAlwaysOnTop(void) const                       {return d_alwaysOnTop;}
220
221
222        /*!
223        \brief
224                return true if the Window is currently disabled
225
226        \param localOnly
227           States whether to only return the state set for this window, and so not factor in
228           inherited state from ancestor windows.
229
230        \return
231                true if the window is disabled, false if the window is enabled.
232        */
233        bool    isDisabled(bool localOnly = false) const;
234
235
236        /*!
237        \brief
238                return true if the Window is currently visible.
239
240                A true return from this function does not mean that the window is not completely obscured by other windows, just that the window
241                is processed when rendering and is not hidden.
242
243        \param localOnly
244           States whether to only return the state set for this window, and so not factor in
245           inherited state from ancestor windows.
246
247        \return
248                true if the window is drawn, false if the window is hidden and therefore ignored when rendering.
249        */
250        bool    isVisible(bool localOnly = false) const;
251
252
253        /*!
254        \brief
255                return true if this is the active Window (the window that receives inputs)
256
257                Mouse events are always sent to the window containing the mouse cursor regardless of what this reports (unless the window has captured
258                inputs).  This mainly refers to where other (keyboard) inputs are sent.
259
260        \return
261                true if this window has input focus, or false if it does not.
262        */
263        bool    isActive(void) const;
264
265
266        /*!
267        \brief
268                return true if this Window is clipped so that its rendering does not pass outside its parent windows area.
269
270        \return
271                true if the window will be clipped by its parent window, or false if this windows rendering may pass outside its parents area
272        */
273        bool    isClippedByParent(void) const           {return d_clippedByParent;}
274
275
276        /*!
277        \brief
278                return the ID code currently assigned to this Window by client code.
279
280        \return
281                uint value equal to the currently assigned ID code for this Window.
282        */
283        uint    getID(void) const               {return d_ID;}
284
285
286        /*!
287        \brief
288                return the number of child Window objects currently attached to this Window.
289
290        \return
291                uint value equal to the number of Window objects directly attached to this Window as children.
292        */
293        uint   getChildCount(void) const      {return (uint)d_children.size();}
294
295
296        /*!
297        \brief
298                returns whether a Window with the specified name is currently attached to this Window as a child.
299
300        \param name
301                String object containing the name of the Window to look for.
302
303        \return
304                true if a Window named \a name is currently attached to this Window as a child, else false.
305        */
306        bool    isChild(const String& name) const;
307
308
309        /*!
310        \brief
311                returns whether at least one window with the given ID code is attached as a child.
312
313        \note
314                ID codes are client assigned and may or may not be unique, and as such, the return from this function
315                will only have meaning to the client code.
316
317        \param ID
318                uint ID code to look for.
319
320        \return
321                true if a child window was found with the ID code \a ID, or false if no child window was found with the ID \a ID.
322        */
323        bool    isChild(uint ID) const;
324
325
326        /*!
327        \brief
328                return true if the given Window is a child of this window.
329
330        \param window
331                Pointer to the Window object to look for.
332
333        \return
334                true if Window object \a window is attached to this window as a child.
335        */
336        bool    isChild(const Window* window) const;
337
338
339        /*!
340        \brief
341                return a pointer to the child window with the specified name.
342
343                This function will throw an exception if no child object with the given name is attached.  This decision
344                was made (over returning NULL if no window was found) so that client code can assume that if the call
345                returns it has a valid window pointer.  We provide the isChild() functions for checking if a given window
346                is attached.
347
348        \param name
349                String object holding the name of the child window to return a pointer to.
350
351        \return
352                Pointer to the Window object attached to this window that has the name \a name.
353
354        \exception UnknownObjectException       thrown if no window named \a name is attached to this Window.
355        */
356        Window* getChild(const String& name) const;
357
358
359        /*!
360        \brief
361                return a pointer to the first attached child window with the specified ID.
362
363                This function will throw an exception if no child object with the given ID is attached.  This decision
364                was made (over returning NULL if no window was found) so that client code can assume that if the call
365                returns it has a valid window pointer.  We provide the isChild() functions for checking if a given window
366                is attached.
367
368        \param ID
369                uint value specifying the ID code of the window to return a pointer to.
370
371        \return
372                Pointer to the (first) Window object attached to this window that has the ID code \a ID.
373
374        \exception UnknownObjectException       thrown if no window with the ID code \a ID is attached to this Window.
375        */
376        Window* getChild(uint ID) const;
377
378
379        /*!
380        \brief
381                return a pointer to the child window that is attached to 'this' at the given index.
382
383        \param idx
384                Index of the child window whos pointer should be returned.  This value is not bounds checked,
385                client code should ensure that this is less than the value returned by getChildCount().
386
387        \return
388                Pointer to the child window currently attached at index position \a idx
389        */
390        Window* getChildAtIdx(uint idx) const           {return d_children[idx];}
391
392
393        /*!
394        \brief
395                return a pointer to the Window that currently has input focus starting with this Window.
396
397        \return
398                Pointer to the window that is active (has input focus) starting at 'this.  Will return 'this' if this Window is active
399                and either no children are attached or if none of the attached children are active.  Returns NULL if this Window (and
400                therefore all children) are not active.
401        */
402        Window* getActiveChild(void);
403        const Window* getActiveChild(void) const;
404
405
406        /*!
407        \brief
408                return true if the specified Window is some ancestor of this Window
409
410        \param name
411                String object holding the name of the Window to check for.
412
413        \return
414                true if a Window named \a name is an ancestor (parent, or parent of parent, etc) of this Window, or false if not.
415        */
416        bool    isAncestor(const String& name) const;
417
418
419        /*!
420        \brief
421                return true if any Window with the given ID is some ancestor of this Window.
422
423        \param ID
424                uint value specifying the ID to look for.
425
426        \return
427                true if an ancestor (parent, or parent of parent, etc) was found with the ID code \a ID, else false.
428        */
429        bool    isAncestor(uint ID) const;
430
431
432        /*!
433        \brief
434                return true if the specified Window is some ancestor of this Window.
435
436        \param window
437                Pointer to the Window object to look for.
438
439        \return
440                true if \a window was found to be an ancestor (parent, or parent of parent, etc) of this Window, otherwise false.
441        */
442        bool    isAncestor(const Window* window) const;
443
444
445        /*!
446        \brief
447                return the Font object active for the Window.
448
449        \param useDefault
450           Sepcifies whether to return the default font if Window has no preference set.
451
452        \return
453                Pointer to the Font being used by this Window.  If the window has no assigned font, the default font is returned.
454        */
455        const Font*             getFont(bool useDefault = true) const;
456
457
458        /*!
459        \brief
460                return the current text for the Window
461
462        \return
463                A String object that holds the current text for this Window.
464        */
465        const String&   getText(void) const             {return d_text;}
466
467
468        /*!
469        \brief
470                return true if the Window inherits alpha from its parent(s).
471
472        \return
473                true if the Window inherits alpha from its parent(s), false if the alpha for this Window is independant.
474        */
475        bool    inheritsAlpha(void) const               {return d_inheritsAlpha;}
476
477
478        /*!
479        \brief
480                return the current alpha value set for this Window
481
482        \note
483                The alpha value set for any given window may or may not be the final alpha value that is used when rendering.  All window
484                objects, by default, inherit alpha from thier parent window(s) - this will blend child windows, relatively, down the line of
485                inheritance.  This behaviour can be overridden via the setInheritsAlpha() method.  To return the true alpha value that will be
486                applied when rendering, use the getEffectiveAlpha() method.
487
488        \return
489                the currently set alpha value for this Window.  Will be between 0.0f and 1.0f.
490        */
491        float   getAlpha(void) const                    {return d_alpha;}
492
493
494        /*!
495        \brief
496                return the effective alpha value that will be used when rendering this window, taking into account inheritance of parent
497                window(s) alpha.
498
499        \return
500                the effective alpha that will be applied to this Window when rendering.  Will be between 0.0f and 1.0f.
501        */
502        float   getEffectiveAlpha(void) const;
503
504
505        /*!
506        \brief
507                return a Rect object that describes the Window area.
508
509        \return
510                Rect object that describes the area covered by the Window.  The values in the returned Rect are in whatever form is set
511                as the current metric type.  The returned Rect is unclipped and relative to the Window objects parent.
512        */
513        Rect    getRect(void) const;
514
515
516        /*!
517        \brief
518                return a Rect object describing the Window area in screen space.
519
520        \return
521                Rect object that describes the area covered by the Window.  The values in the returned Rect are in screen pixels.  The
522                returned Rect is clipped as appropriate and depending upon the 'ClippedByParent' setting.
523
524        \note
525                This has now been made virtual to ease some customisations that require more specialised clipping requirements.
526        */
527        virtual Rect    getPixelRect(void) const;
528
529
530        /*!
531        \brief
532                return a Rect object describing the clipped inner area for this window.
533
534        \return
535                Rect object that describes, in appropriately clipped screen pixel co-ordinates, the window object's inner rect area.
536        */
537        Rect    getInnerRect(void) const;
538
539
540        /*!
541        \brief
542                return a Rect object describing the Window area unclipped, in screen space.
543
544        \return
545                Rect object that describes the area covered by the Window.  The values in the returned Rect are in screen pixels.  The
546                returned rect is fully unclipped.
547        */
548        Rect    getUnclippedPixelRect(void) const;
549
550
551        /*!
552        \brief
553                Return a Rect object that describes, unclipped, the inner rectangle for this window.  The inner rectangle is
554                typically an area that excludes some frame or other rendering that should not be touched by subsequent rendering.
555
556        \return
557                Rect object that describes, in unclipped screen pixel co-ordinates, the window object's inner rect area.
558        */
559        virtual Rect    getUnclippedInnerRect(void) const;
560
561
562        /*!
563        \brief
564                return the Window that currently has inputs captured.
565
566        \return
567                Pointer to the Window object that currently has inputs captured, or NULL if no Window has captured input.
568        */
569        static  Window* getCaptureWindow(void)          {return d_captureWindow;}
570
571
572        /*!
573        \brief
574                return true if this Window has input captured.
575
576        \return
577                true if this Window has captured inputs, or false if some other Window, or no Window, has captured inputs.
578        */
579        bool    isCapturedByThis(void) const            {return getCaptureWindow() == this;}
580
581
582        /*!
583        \brief
584                return true if a child window has captured inputs.
585
586        \return
587                true if inputs are captured by a Window that is attached as a child of this Window, else false.
588        */
589        bool    isCapturedByAncestor(void) const        {return isAncestor(getCaptureWindow());}
590
591
592        /*!
593        \brief
594                return true if an ancestor window has captured inputs.
595
596        \return
597                true if inputs are captured by a Window that is some ancestor (parent, parent of parent, etc) of this Window, else false.
598        */
599        bool    isCapturedByChild(void) const           {return isChild(getCaptureWindow());}
600
601
602        /*!
603        \brief
604                check if the given position would hit this window.
605
606        \param position
607                Point object describing the position to check in screen pixels
608
609        \return
610                true if \a position 'hits' this Window, else false.
611        */
612        virtual bool    isHit(const Point& position) const;
613
614
615        /*!
616        \brief
617                return the child Window that is 'hit' by the given position
618
619        \param position
620                Point object that describes the position to check in screen pixels
621
622        \return
623                Pointer to the child Window that was hit according to the Point \a position, or NULL if no child window was hit.
624        */
625        Window* getChildAtPosition(const Point& position) const;
626
627
628    /*!
629    \brief
630        return the child Window that is 'hit' by the given position, and is allowed to handle mouse events.
631
632    \param position
633        Point object that describes the position to check in screen pixels
634
635    \return
636        Pointer to the child Window that was hit according to the Point \a position, or NULL if no child window was hit.
637    */
638    Window* getTargetChildAtPosition(const Point& position) const;
639
640
641        /*!
642        \brief
643                return the current metrics mode employed by the Window
644
645        \return
646                One of the values of the MectricsMode enumerated type, that describes the current metrics in use by the Window.
647        */
648        MetricsMode     getMetricsMode(void) const;
649
650
651        /*!
652        \brief
653                return the x position of the window.  Interpretation of return value depends upon the metric type in use by this window.
654
655        \return
656                float value that specifies the x position of the Window relative to it's parent, depending on the metrics system in use for this
657                Window, this value will specify either pixels or a decimal fraction of the width of the parent Window.
658        */
659        float   getXPosition(void) const;
660
661
662        /*!
663        \brief
664                return the y position of the window.  Interpretation of return value depends upon the metric type in use by this window.
665
666        \return
667                float value that specifies the y position of the Window relative to it's parent, depending on the metrics system in use for this
668                Window, this value will specify either pixels or a decimal fraction of the height of the parent Window.
669        */
670        float   getYPosition(void) const;
671
672
673        /*!
674        \brief
675                return the position of the window.  Interpretation of return value depends upon the metric type in use by this window.
676
677        \return
678                Point object that describes the position of the Window relative to it's parent, depending on the metrics system in use for this
679                Window, the values in the Point will specify either pixels or decimal fractions of the total width and height of the parent.
680        */
681        Point   getPosition(void) const;
682
683
684        /*!
685        \brief
686                return the width of the Window.  Interpretation of return value depends upon the metric type in use by this window.
687
688        \return
689                float value that specifies the width of the Window.  Depending upon the metrics system in use for this window, the return
690                value will either be in pixels, or as a decimal fraction of the width of the parent Window.
691        */
692        float   getWidth(void) const;
693
694        /*!
695        \brief
696                return the height of the Window.  Interpretation of return value depends upon the metric type in use by this window.
697
698        \return
699                float value that specifies the height of the Window.  Depending upon the metrics system in use for this window, the return
700                value will either be in pixels, or as a decimal fraction of the height of the parent Window.
701        */
702        float   getHeight(void) const;
703
704
705        /*!
706        \brief
707                return the size of the Window.  Interpretation of return value depends upon the metric type in use by this window.
708
709        \return
710                Size object that describes the dimensions of the Window.  Depending upon the metrics system in use for this window, the
711                values will either be in pixels, or as decimal fractions of the width and height of the parent Window.
712        */
713        Size    getSize(void) const;
714
715
716        /*!
717        \brief
718                return the parent of this Window.
719
720        \return
721                Pointer to the Window object that is the parent of this Window.  This value can be NULL, in which case the Window is a GUI
722                Sheet / Root.
723        */
724        Window* getParent(void) const                           {return d_parent;}
725
726
727        /*!
728        \brief
729                Return the current maximum size for this window.
730
731        \return
732                Size object describing the maximum size for this window.  If using absolute co-ordinates the returned object has it's values expressed
733                as screen pixels.  If using relative co-ordinates the returned object has it's values expressed as fractions of the current display size.
734        */
735        Size    getMaximumSize(void) const;
736
737
738        /*!
739        \brief
740                Return the current minimum size for this window.
741
742        \return
743                Size object describing the minimum size for this window.  If using absolute co-ordinates the returned object has it's values expressed
744                as screen pixels.  If using relative co-ordinates the returned object has it's values expressed as fractions of the current display size.
745        */
746        Size    getMinimumSize(void) const;
747
748
749        /*!
750        \brief
751                Return a pointer to the mouse cursor image to use when the mouse is within this window.
752
753        \param useDefault
754           Sepcifies whether to return the default font if Window has no preference set.
755
756        \return
757                Pointer to the mouse cursor image that will be used when the mouse enters this window.  May return NULL indicating no cursor.
758        */
759        const Image*    getMouseCursor(bool useDefault = true) const;
760
761
762        /*!
763        \brief
764                Return the window area rect in relative metrics.
765
766        \return
767                Rect object describing this windows area, relative to the parent window, in parent relative metrics.
768        */
769    Rect        getRelativeRect(void) const                             { return d_area.asRelative(getParentSize()); }
770
771
772        /*!
773        \brief
774                Return the window position in relative metrics.
775
776        \return
777                Point object describing this windows position, relative to the parent window, in parent relative metrics.
778        */
779        Point   getRelativePosition(void) const                 { return d_area.getPosition().asRelative(getParentSize()); }
780
781
782        /*!
783        \brief
784                Return the window X position in relative metrics.
785
786        \return
787                float value describing this windows X position, relative to the parent window, in parent relative metrics.
788        */
789        float   getRelativeXPosition(void) const                { return d_area.d_min.d_x.asRelative(getParentWidth()); }
790
791
792        /*!
793        \brief
794                Return the window Y position in relative metrics.
795
796        \return
797                float value describing this windows Y position, relative to the parent window, in parent relative metrics.
798        */
799        float   getRelativeYPosition(void) const                { return d_area.d_min.d_y.asRelative(getParentHeight()); }
800
801
802        /*!
803        \brief
804                Return the window size in relative metrics.
805
806        \return
807                Size object describing this windows size in parent relative metrics.
808        */
809    Size        getRelativeSize(void) const                             { return d_area.getSize().asRelative(getParentSize()).asSize(); }
810
811
812        /*!
813        \brief
814                Return the window width in relative metrics.
815
816        \return
817                float value describing this windows width in parent relative metrics.
818        */
819        float   getRelativeWidth(void) const                    { return d_area.getWidth().asRelative(getParentWidth()); }
820
821
822        /*!
823        \brief
824                Return the window height in relative metrics.
825
826        \return
827                float value describing this windows height in parent relative metrics.
828        */
829        float   getRelativeHeight(void) const                   { return d_area.getHeight().asRelative(getParentHeight()); }
830
831
832        /*!
833        \brief
834                Return the window area rect in absolute metrics.
835
836        \return
837                Rect object describing this windows area, relative to the parent window, in absolute metrics
838        */
839    Rect        getAbsoluteRect(void) const                             { return Rect(d_area.getPosition().asAbsolute(getParentSize()), d_pixelSize); }
840
841
842        /*!
843        \brief
844                Return the window position in absolute metrics.
845
846        \return
847                Point object describing this windows position, relative to the parent window, in absolute metrics.
848        */
849        Point   getAbsolutePosition(void) const                 { return d_area.getPosition().asAbsolute(getParentSize()); }
850
851
852        /*!
853        \brief
854                Return the window X position in absolute metrics.
855
856        \return
857                float value describing this windows X position, relative to the parent window, in absolute metrics.
858        */
859        float   getAbsoluteXPosition(void) const                { return d_area.d_min.d_x.asAbsolute(getParentWidth()); }
860
861
862        /*!
863        \brief
864                Return the window Y position in absolute metrics.
865
866        \return
867                float value describing this windows Y position, relative to the parent window, in absolute metrics.
868        */
869        float   getAbsoluteYPosition(void) const                { return d_area.d_min.d_y.asAbsolute(getParentHeight()); }
870
871
872        /*!
873        \brief
874                Return the window size in absolute metrics.
875
876        \return
877                Size object describing this windows size in absolute metrics.
878        */
879        Size    getAbsoluteSize(void) const                             { return d_pixelSize; }
880
881
882        /*!
883        \brief
884                Return the window width in absolute metrics.
885
886        \return
887                float value describing this windows width in absolute metrics.
888        */
889        float   getAbsoluteWidth(void) const                    { return d_pixelSize.d_width; }
890
891
892        /*!
893        \brief
894                Return the window height in absolute metrics.
895
896        \return
897        float value describing this windows height in absolute metrics.
898        */
899        float   getAbsoluteHeight(void) const                   { return d_pixelSize.d_height; }
900
901
902        /*!
903        \brief
904                Return the user data set for this Window.
905
906                Each Window can have some client assigned data attached to it, this data is not used by the GUI system
907                in any way.  Interpretation of the data is entirely application specific.
908
909        \return
910                pointer to the user data that is currently set for this window.
911        */
912        void*   getUserData(void) const                 {return d_userData;}
913
914
915        /*!
916        \brief
917                return the x position of the window using the specified metrics system.
918
919        \param mode
920                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
921
922        \return
923                float value that specifies the x position of the Window relative to it's parent, using the specified MetricsMode.
924        */
925        float   getXPosition(MetricsMode mode) const;
926
927
928        /*!
929        \brief
930                return the y position of the window using the specified metrics system.
931
932        \param mode
933                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
934
935        \return
936                float value that specifies the y position of the Window relative to it's parent,  using the specified MetricsMode.
937        */
938        float   getYPosition(MetricsMode mode) const;
939
940
941        /*!
942        \brief
943                return the position of the window using the specified metrics system.
944
945        \param mode
946                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
947
948        \return
949                Point object that describes the position of the Window relative to it's parent, using the specified MetricsMode.
950        */
951        Point   getPosition(MetricsMode mode) const;
952
953
954        /*!
955        \brief
956                return the width of the Window using the specified metrics system.
957
958        \param mode
959                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
960
961        \return
962                float value that specifies the width of the Window using the specified MetricsMode.
963        */
964        float   getWidth(MetricsMode mode) const;
965
966
967        /*!
968        \brief
969                return the height of the Window using the specified metrics system.
970
971        \param mode
972                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
973
974        \return
975                float value that specifies the height of the Window using the specified MetricsMode.
976        */
977        float   getHeight(MetricsMode mode) const;
978
979
980        /*!
981        \brief
982                return the size of the Window using the specified metrics system.
983
984        \param mode
985                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
986
987        \return
988                Size object that describes the dimensions of the Window using the specified MetricsMode.
989        */
990        Size    getSize(MetricsMode mode) const;
991
992
993        /*!
994        \brief
995                return a Rect object that describes the Window area using the specified metrics system.
996
997        \param mode
998                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
999
1000        \return
1001                Rect object that describes the area covered by the Window using the specified MetricsMode.
1002        */
1003        Rect    getRect(MetricsMode mode) const;
1004
1005
1006        /*!
1007        \brief
1008                Return whether this window is set to restore old input capture when it loses input capture.
1009
1010                This is only really useful for certain sub-components for widget writers.
1011
1012        \return
1013                - true if the window will restore the previous capture window when it loses input capture.
1014                - false if the window will set the capture window to NULL when it loses input capture (this is the default behaviour).
1015        */
1016        bool    restoresOldCapture(void) const          {return d_restoreOldCapture;}
1017
1018
1019        /*!
1020        \brief
1021                Return whether z-order changes are enabled or disabled for this Window.
1022
1023        \return
1024                - true if z-order changes are enabled for this window.  moveToFront/moveToBack work normally as expected.
1025                - false: z-order changes are disabled for this window.  moveToFront/moveToBack are ignored for this window.
1026        */
1027        bool    isZOrderingEnabled(void) const;
1028
1029
1030    /*!
1031    \brief
1032        Return whether this window will receive multi-click events or multiple 'down' events instead.
1033
1034    \return
1035        - true if the Window will receive double-click and triple-click events.
1036        - false if the Window will receive multiple mouse button down events instead of double/triple click events.
1037    */
1038    bool    wantsMultiClickEvents(void) const;
1039
1040
1041    /*!
1042    \brief
1043        Return whether mouse button down event autorepeat is enabled for this window.
1044
1045    \return
1046        - true if autorepeat of mouse button down events is enabled for this window.
1047        - false if autorepeat of mouse button down events is not enabled for this window.
1048    */
1049    bool    isMouseAutoRepeatEnabled(void) const;
1050
1051
1052    /*!
1053    \brief
1054        Return the current auto-repeat delay setting for this window.
1055
1056    \return
1057        float value indicating the delay, in seconds, defore the first repeat mouse button down event will be triggered when autorepeat is enabled.
1058    */
1059    float   getAutoRepeatDelay(void) const;
1060
1061
1062    /*!
1063    \brief
1064        Return the current auto-repeat rate setting for this window.
1065
1066    \return
1067        float value indicating the rate, in seconds, at which repeat mouse button down events will be generated after the initial delay has expired.
1068    */
1069    float   getAutoRepeatRate(void) const;
1070
1071
1072    /*!
1073    \brief
1074        Return whether the window wants inputs passed to its attached
1075        child windows when the window has inputs captured.
1076
1077    \return
1078        - true if System should pass captured input events to child windows.
1079        - false if System should pass captured input events to this window only.
1080    */
1081    bool    distributesCapturedInputs(void) const;
1082
1083
1084    /*!
1085    \brief
1086        Return whether this Window is using the system default Tooltip for its Tooltip window.
1087
1088    \return
1089        - true if the Window will use the system default tooltip.
1090        - false if the window has a custom Tooltip object.
1091    */
1092    bool isUsingDefaultTooltip(void) const;
1093
1094    /*!
1095    \brief
1096        Return a pointer to the Tooltip object used by this Window.  The value returned may
1097        point to the system default Tooltip, a custom Window specific Tooltip, or be NULL.
1098
1099    \return
1100        Pointer to a Tooltip based object, or NULL.
1101    */
1102    Tooltip* getTooltip(void) const;
1103
1104    /*!
1105    \brief
1106        Return the custom tooltip type.
1107
1108    \return
1109        String object holding the current custom tooltip window type, or an empty string if no custom tooltip is set.
1110     */
1111    String getTooltipType(void) const;
1112
1113    /*!
1114    \brief
1115        Return the current tooltip text set for this Window.
1116
1117    \return
1118        String object holding the current tooltip text set for this window.
1119     */
1120    const String& getTooltipText(void) const;
1121
1122    /*!
1123    \brief
1124        Return whether this window inherits Tooltip text from its parent when its own tooltip text is not set.
1125
1126    \return
1127        - true if the window inherits tooltip text from its parent when its own text is not set.
1128        - false if the window does not inherit tooltip text from its parent (and shows no tooltip when no text is set).
1129     */
1130    bool inheritsTooltipText(void) const;
1131
1132    /*!
1133    \brief
1134        Return whether this window will rise to the top of the z-order when clicked with the left mouse button.
1135
1136    \return
1137        - true if the window will come to the top of other windows when the left mouse button is pushed within its area.
1138        - false if the window does not change z-order position when the left mouse button is pushed within its area.
1139     */
1140    bool isRiseOnClickEnabled(void) const   { return d_riseOnClick; }
1141
1142        /*!
1143        \brief
1144                Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
1145
1146        \param class_name
1147                The class name that is to be checked.
1148
1149        \return
1150                true if this window was inherited from \a class_name. false if not.
1151        */
1152        bool testClassName(const String& class_name) const              {return testClassName_impl(class_name);}
1153
1154    /*!
1155    \brief
1156        Get the vertical alignment.
1157
1158        Returns the vertical alignment for the window.  This setting affects how the windows position is
1159        interpreted relative to its parent.
1160
1161    \return
1162        One of the VerticalAlignment enumerated values.
1163     */
1164    VerticalAlignment getVerticalAlignment() const  {return d_vertAlign;}
1165
1166    /*!
1167    \brief
1168        Get the horizontal alignment.
1169
1170        Returns the horizontal alignment for the window.  This setting affects how the windows position is
1171        interpreted relative to its parent.
1172
1173    \return
1174        One of the HorizontalAlignment enumerated values.
1175     */
1176    HorizontalAlignment getHorizontalAlignment() const  {return d_horzAlign;}
1177
1178    /*!
1179    \brief
1180        Return the RenderCache object for this Window.
1181
1182    \return
1183        Reference to the RenderCache object for this Window.
1184    */
1185    RenderCache& getRenderCache()   { return d_renderCache; }
1186
1187    /*!
1188    \brief
1189        Get the name of the LookNFeel assigned to this window.
1190
1191    \return
1192        String object holding the name of the look assigned to this window.
1193        Returns the empty string if no look is assigned.
1194    */
1195    const String& getLookNFeel();
1196
1197        /*!
1198        \brief
1199                Get whether or not this Window is the modal target.
1200
1201        \return
1202                Returns true if this Window is the modal target, otherwise false.
1203        */
1204        bool getModalState(void) const  {return (System::getSingleton().getModalTarget() == this);}
1205
1206
1207        /*!
1208        \brief
1209           Returns a named user string.
1210
1211    \param name
1212        String object holding the name of the string to be returned.
1213
1214    \return
1215        String object holding the data stored for the requested user string.
1216
1217    \exception UnknownObjectException thrown if a user string named \a name does not exist.
1218    */
1219    const String& getUserString(const String& name) const;
1220
1221    /*!
1222    \brief
1223        Return whether a user string with the specified name exists.
1224
1225    \param name
1226        String object holding the name of the string to be checked.
1227
1228    \return
1229        - true if a user string named \a name exists.
1230        - false if no such user string exists.
1231    */
1232    bool isUserStringDefined(const String& name) const;
1233
1234    /*!
1235    \brief
1236        Returns the active sibling window.
1237
1238        This searches the immediate children of this window's parent, and returns a pointer
1239        to the active window.  The method will return this if we are the immediate child of our
1240        parent that is active.  If our parent is not active, or if no immediate child of our
1241        parent is active then 0 is returned.  If this window has no parent, and this window is
1242        not active then 0 is returned, else this is returned.
1243
1244    \return
1245        A pointer to the immediate child window attached to our parent that is currently active,
1246        or 0 if no immediate child of our parent is active.
1247    */
1248    Window* getActiveSibling();
1249
1250    /*!
1251    \brief
1252        Returns whether this window should ignore mouse event and pass them through to and other windows behind it.
1253        In effect making the window transparent to the mouse.
1254
1255    \return
1256        true if mouse pass through is enabled.
1257        false if mouse pass through is not enabled.
1258    */
1259    bool isMousePassThroughEnabled(void) const      {return d_mousePassThroughEnabled;}
1260
1261    /*************************************************************************
1262                Manipulator functions
1263        *************************************************************************/
1264        /*!
1265        \brief
1266        Renames the window.
1267
1268    \param new_name
1269        String object holding the new name for the window.
1270
1271    \exception AlreadyExistsException
1272        thrown if a Window named \a new_name already exists in the system.
1273    */
1274    void rename(const String& new_name);
1275
1276    /*!
1277    \brief
1278                Initialises the Window based object ready for use.
1279
1280        \note
1281                This must be called for every window created.  Normally this is handled automatically by the WindowFactory for each Window type.
1282
1283        \return
1284                Nothing
1285        */
1286        virtual void    initialise(void) {}
1287
1288
1289        /*!
1290        \brief
1291                Set whether or not this Window will automatically be destroyed when its parent Window is destroyed.
1292
1293        \param setting
1294                set to true to have the Window auto-destroyed when its parent is destroyed (default), or false to have the Window
1295                remain after its parent is destroyed.
1296
1297        \return
1298                Nothing
1299        */
1300        void    setDestroyedByParent(bool setting);
1301
1302
1303        /*!
1304        \brief
1305                Set whether this window is always on top, or not.
1306
1307        \param setting
1308                true to have the Window appear on top of all other non always on top windows, or false to allow the window to be covered by other windows.
1309
1310        \return
1311                Nothing
1312        */
1313        void    setAlwaysOnTop(bool setting);
1314
1315
1316        /*!
1317        \brief
1318                Set whether this window is enabled or disabled.  A disabled window normally can not be interacted with, and may have different rendering.
1319
1320        \param setting
1321                true to enable the Window, and false to disable the Window.
1322
1323        \return
1324                Nothing
1325        */
1326        void    setEnabled(bool setting);
1327
1328
1329        /*!
1330        \brief
1331                enable the Window to allow interaction.
1332
1333        \return
1334                Nothing
1335        */
1336        void    enable(void)            {setEnabled(true);}
1337
1338
1339        /*!
1340        \brief
1341                disable the Window to prevent interaction.
1342
1343        \return
1344                Nothing
1345        */
1346        void    disable(void)           {setEnabled(false);}
1347
1348
1349        /*!
1350        \brief
1351                Set whether the Window is visible or hidden.
1352
1353        \param setting
1354                true to make the Window visible, or false to make the Window hidden
1355
1356        \return
1357                Nothing
1358        */
1359        void    setVisible(bool setting);
1360
1361
1362        /*!
1363        \brief
1364                show the Window
1365
1366        \return
1367                Nothing
1368        */
1369        void    show(void)                      {setVisible(true);}
1370
1371
1372        /*!
1373        \brief
1374                hide the Window.
1375
1376        \return
1377                Nothing
1378        */
1379        void    hide(void)                      {setVisible(false);}
1380
1381
1382        /*!
1383        \brief
1384                Activate the Window giving it input focus and bringing it to the top of all non always-on-top Windows.
1385
1386        \return
1387                Nothing
1388        */
1389        void    activate(void);
1390
1391
1392        /*!
1393        \brief
1394                Deactivate the window.  No further inputs will be received by the window until it is re-activated either programmatically or
1395                by the user interacting with the gui.
1396
1397        \return
1398                Nothing.
1399        */
1400        void    deactivate(void);
1401
1402
1403        /*!
1404        \brief
1405                Set whether this Window will be clipped by its parent window(s).
1406
1407        \param setting
1408                true to have the Window clipped so that rendering is constrained to within the area of its parent(s), or false to have rendering constrained
1409                to the screen only.
1410
1411        \return
1412                Nothing
1413        */
1414        void    setClippedByParent(bool setting);
1415
1416
1417        /*!
1418        \brief
1419                Set the current ID for the Window.
1420
1421        \param ID
1422                Client assigned ID code for this Window.  The GUI system assigns no meaning to any IDs, they are a device purely for client code usage.
1423
1424        \return
1425                Nothing
1426        */
1427        void    setID(uint ID);
1428
1429
1430        /*!
1431        \brief
1432                Set the current text string for the Window.
1433
1434        \param text
1435                String object containing the text that is to be set as the Window text.
1436
1437        \return
1438                Nothing
1439        */
1440        void    setText(const String& text);
1441
1442
1443        /*!
1444        \brief
1445                Set the current width of the Window.  Interpretation of the input value \a width is dependant upon the current metrics system set for the Window.
1446
1447        \param width
1448                float value that specifies the new width for the window, in units consistent with whatever metrics mode is in operation.
1449
1450        \return
1451                Nothing
1452        */
1453        void    setWidth(float width);
1454
1455
1456        /*!
1457        \brief
1458                Set the current height of the Window.  Interpretation of the input value \a height is dependant upon the current metrics system set for the Window.
1459
1460        \param height
1461                float value that specifies the new height for the window, in units consistent with whatever metrics mode is in operation.
1462
1463        \return
1464                Nothing
1465        */
1466        void    setHeight(float height);
1467
1468
1469        /*!
1470        \brief
1471                Set the current size of the Window.  Interpretation of the input value \a size is dependant upon the current metrics system set for the Window.
1472
1473        \param size
1474                Size object that describes the new dimensions for the window, in units consistent with whatever metrics mode is in operation.
1475
1476        \return
1477                Nothing
1478        */
1479        void    setSize(const Size& size);
1480
1481
1482        /*!
1483        \brief
1484                Set the current 'x' position of the Window.  Interpretation of the input value \a x is dependant upon the current metrics system set for the Window.
1485
1486        \param x
1487                float value that specifies the new x postion of the Window, in units consistent with the current metrics mode.
1488
1489        \return
1490                Nothing
1491        */
1492        void    setXPosition(float x);
1493
1494
1495        /*!
1496        \brief
1497                Set the current 'y' position of the Window.  Interpretation of the input value \a y is dependant upon the current metrics system set for the Window.
1498
1499        \param y
1500                float value that specifies the new y postion of the Window, in units consistent with the current metrics mode.
1501
1502        \return
1503                Nothing
1504        */
1505        void    setYPosition(float y);
1506
1507
1508        /*!
1509        \brief
1510                Set the current position of the Window.  Interpretation of the input value \a position is dependant upon the current metrics system set for the Window.
1511
1512        \param position
1513                Point object that describes the new postion of the Window, in units consistent with the current metrics mode.
1514
1515        \return
1516                Nothing
1517        */
1518        void    setPosition(const Point& position);
1519
1520
1521        /*!
1522        \brief
1523                Set the current area for the Window, this allows for setting of position and size at the same time.
1524                Interpretation of the input value \a area is dependant upon the current metrics system set for the Window.
1525
1526        \param area
1527                Rect object that describes the new area for Window, in units consistent with the current metrics mode.
1528
1529        \return
1530                Nothing
1531        */
1532        void    setAreaRect(const Rect& area);
1533
1534
1535        /*!
1536        \brief
1537                Set the font used by this Window.
1538
1539        \param font
1540                Pointer to the Font object to be used by this Window.  If \a font is NULL, the default font will be used.
1541
1542        \return
1543                Nothing
1544        */
1545        void    setFont(const Font* font);
1546
1547
1548        /*!
1549        \brief
1550                Set the font used by this Window.
1551
1552        \param name
1553                String object holding the name of the Font object to be used by this Window.  If \a name == "", the default font will be used.
1554
1555        \return
1556                Nothing
1557
1558        \exception UnknownObjectException       thrown if the specified Font is unknown within the system.
1559        */
1560        void    setFont(const String& name);
1561
1562
1563        /*!
1564        \brief
1565                Add the named Window as a child of this Window.  If the Window \a name is already attached to a Window, it is detached before
1566                being added to this Window.
1567
1568        \param name
1569                String object holding the name of the Window to be added.
1570
1571        \return
1572                Nothing.
1573
1574        \exception UnknownObjectException       thrown if no Window named \a name exists.
1575        \exception InvalidRequestException      thrown if Window \a name is an ancestor of this Window, to prevent cyclic Window structures.
1576        */
1577        void    addChildWindow(const String& name);
1578
1579
1580        /*!
1581        \brief
1582                Add the specified Window as a child of this Window.  If the Window \a window is already attached to a Window, it is detached before
1583                being added to this Window.
1584
1585        \param window
1586                Pointer to the Window object to be added.
1587
1588        \return
1589                Nothing
1590
1591        \exception InvalidRequestException      thrown if Window \a window is an ancestor of this Window, to prevent cyclic Window structures.
1592        */
1593        void    addChildWindow(Window* window);
1594
1595
1596        /*!
1597        \brief
1598                Remove the named Window from this windows child list.
1599
1600        \param name
1601                String object holding the name of the Window to be removed.  If the Window specified is not attached to this Window, nothing happens.
1602
1603        \return
1604                Nothing.
1605        */
1606        void    removeChildWindow(const String& name);
1607
1608
1609        /*!
1610        \brief
1611                Remove the specified Window form this windows child list.
1612
1613        \param window
1614                Pointer to the Window object to be removed.  If the \a window is not attached to this Window, then nothing happens.
1615
1616        \return
1617                Nothing.
1618        */
1619        void    removeChildWindow(Window* window);
1620
1621
1622        /*!
1623        \brief
1624                Remove the first child Window with the specified ID.  If there is more than one attached Window objects with the specified ID, only the fist
1625                one encountered will be removed.
1626
1627        \param ID
1628                ID number assigned to the Window to be removed.  If no Window with ID code \a ID is attached, nothing happens.
1629
1630        \return
1631                Nothing.
1632        */
1633        void    removeChildWindow(uint ID);
1634
1635
1636        /*!
1637        \brief
1638                Move the Window to the top of the z order.
1639
1640                - If the Window is a non always-on-top window it is moved the the top of all other non always-on-top sibling windows, and the process
1641                        repeated for all ancestors.
1642                - If the Window is an always-on-top window it is moved to the of of all sibling Windows, and the process repeated for all ancestors.
1643
1644        \return
1645                Nothing
1646        */
1647        void    moveToFront();
1648
1649
1650        /*!
1651        \brief
1652                Move the Window to the bottom of the Z order.
1653
1654                - If the window is non always-on-top the Window is sent to the very bottom of its sibling windows and the process repeated for all ancestors.
1655                - If the window is always-on-top, the Window is sent to the bottom of all sibling always-on-top windows and the process repeated for all ancestors.
1656
1657        \return
1658                Nothing
1659        */
1660        void    moveToBack();
1661
1662
1663        /*!
1664        \brief
1665                Captures input to this window
1666
1667        \return
1668                - true if input was successfully captured to this window.
1669                - false if input could not be captured to this window (maybe because the window is not active).
1670        */
1671        bool    captureInput(void);
1672
1673
1674        /*!
1675        \brief
1676                Releases input capture from this Window.  If this Window does not have inputs captured, nothing happens.
1677
1678        \return
1679                Nothing
1680        */
1681        void    releaseInput(void);
1682
1683
1684        /*!
1685        \brief
1686                Set whether this window will remember and restore the previous window that had inputs captured.
1687
1688        \param setting
1689                - true: The window will remember and restore the previous capture window.  The CaptureLost event is not fired
1690                  on the previous window when this window steals input capture.  When this window releases capture, the old capture
1691                  window is silently restored.
1692
1693                - false: Input capture works as normal, each window losing capture is signalled via CaptureLost, and upon the final
1694                  release of capture, no previous setting is restored (this is the default 'normal' behaviour).
1695
1696        \return
1697                Nothing
1698        */
1699        void    setRestoreCapture(bool setting);
1700
1701
1702        /*!
1703        \brief
1704                Set the current alpha value for this window.
1705
1706        \note
1707                The alpha value set for any given window may or may not be the final alpha value that is used when rendering.  All window
1708                objects, by default, inherit alpha from thier parent window(s) - this will blend child windows, relatively, down the line of
1709                inheritance.  This behaviour can be overridden via the setInheritsAlpha() method.  To return the true alpha value that will be
1710                applied when rendering, use the getEffectiveAlpha() method.
1711
1712        \param alpha
1713                The new alpha value for the window.  Value should be between 0.0f and 1.0f.
1714
1715        \return
1716                Nothing
1717        */
1718        void    setAlpha(float alpha);
1719
1720
1721        /*!
1722        \brief
1723                Sets whether this Window will inherit alpha from its parent windows.
1724
1725        \param setting
1726                true if the Window should use inherited alpha, or false if the Window should have an independant alpha value.
1727
1728        \return
1729                Nothing
1730        */
1731        void    setInheritsAlpha(bool setting);
1732
1733
1734        /*!
1735        \brief
1736                Signal the System object to redraw (at least) this Window on the next render cycle.
1737
1738        \return
1739                Nothing
1740        */
1741        void    requestRedraw(void) const;
1742
1743
1744        /*!
1745        \brief
1746                set the current metrics mode employed by the Window
1747
1748        \param mode
1749                One of the values of the MectricsMode enumerated type, that describes the metrics mode to be used by the Window.
1750
1751        \return
1752                Nothing
1753        */
1754        void setMetricsMode(MetricsMode mode);
1755
1756
1757        /*!
1758        \brief
1759                Set the minimum size for this window.
1760
1761        \param sz
1762                Size object describing the minimum size for the window.  For absolute metrics, the Size values are in screen pixels,
1763                for relative metrics the Size values are relative to the display size.
1764        */
1765        void    setMinimumSize(const Size& sz);
1766
1767
1768        /*!
1769        \brief
1770                Set the maximum size for this window.
1771
1772        \param sz
1773                Size object describing the maximum size for the window.  For absolute metrics, the Size values are in screen pixels,
1774                for relative metrics the Size values are relative to the display size.
1775        */
1776        void    setMaximumSize(const Size& sz);
1777
1778
1779        /*!
1780        \brief
1781                Set the mouse cursor image to be used when the mouse enters this window.
1782
1783        \param image
1784                Pointer to the Image object to use as the mouse cursor image when the mouse enters the area for this Window.
1785
1786        \return
1787                Nothing.
1788        */
1789        void    setMouseCursor(const Image* image)              {d_mouseCursor = image;}
1790
1791
1792        /*!
1793        \brief
1794                Set the mouse cursor image to be used when the mouse enters this window.
1795
1796        \param image
1797                One of the MouseCursorImage enumerated values.
1798
1799        \return
1800                Nothing.
1801        */
1802        void    setMouseCursor(MouseCursorImage image)          {d_mouseCursor = (const Image*)image;}
1803
1804
1805        /*!
1806        \brief
1807                Set the mouse cursor image to be used when the mouse enters this window.
1808
1809        \param imageset
1810                String object that contains the name of the Imageset that contains the image to be used.
1811
1812        \param image_name
1813                String object that contains the name of the Image on \a imageset that is to be used.
1814
1815        \return
1816                Nothing.
1817
1818        \exception UnknownObjectException       thrown if \a imageset is not known, or if \a imageset contains no Image named \a image_name.
1819        */
1820        void    setMouseCursor(const String& imageset, const String& image_name);
1821
1822
1823        /*!
1824        \brief
1825                Set the user data set for this Window.
1826
1827                Each Window can have some client assigned data attached to it, this data is not used by the GUI system
1828                in any way.  Interpretation of the data is entirely application specific.
1829
1830        \param user_data
1831                pointer to the user data that is to be set for this window.
1832
1833        \return
1834                Nothing.
1835        */
1836        void    setUserData(void* user_data)            {d_userData = user_data;}
1837
1838
1839        /*!
1840        \brief
1841                set the x position of the window using the specified metrics system.
1842
1843        \param mode
1844                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1845
1846        \param x
1847                float value that specifies the x position of the Window relative to it's parent, using the specified MetricsMode.
1848
1849        \return
1850                Nothing.
1851        */
1852        void    setXPosition(MetricsMode mode, float x);
1853
1854
1855        /*!
1856        \brief
1857                set the y position of the window using the specified metrics system.
1858
1859        \param mode
1860                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1861
1862        \param y
1863                float value that specifies the y position of the Window relative to it's parent,  using the specified MetricsMode.
1864
1865        \return
1866                Nothing.
1867        */
1868        void    setYPosition(MetricsMode mode, float y);
1869
1870
1871        /*!
1872        \brief
1873                set the position of the window using the specified metrics system.
1874
1875        \param mode
1876                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1877
1878        \param position
1879                Point object that describes the position of the Window relative to it's parent, using the specified MetricsMode.
1880
1881        \return
1882                Nothing
1883        */
1884        void    setPosition(MetricsMode mode, const Point& position);
1885
1886
1887        /*!
1888        \brief
1889                set the width of the Window using the specified metrics system.
1890
1891        \param mode
1892                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1893
1894        \param width
1895                float value that specifies the width of the Window using the specified MetricsMode.
1896
1897        \return
1898                Nothing.
1899        */
1900        void    setWidth(MetricsMode mode, float width);
1901
1902
1903        /*!
1904        \brief
1905                set the height of the Window using the specified metrics system.
1906
1907        \param mode
1908                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1909
1910        \param height
1911                float value that specifies the height of the Window using the specified MetricsMode.
1912
1913        \return
1914                Nothing.
1915        */
1916        void    setHeight(MetricsMode mode, float height);
1917
1918
1919        /*!
1920        \brief
1921                set the size of the Window using the specified metrics system.
1922
1923        \param mode
1924                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1925
1926        \param size
1927                Size object that describes the dimensions of the Window using the specified MetricsMode.
1928
1929        \return
1930                Nothing.
1931        */
1932        void    setSize(MetricsMode mode, const Size& size);
1933
1934
1935        /*!
1936        \brief
1937                set the Rect that describes the Window area using the specified metrics system.
1938
1939        \param mode
1940                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1941
1942        \param area
1943                Rect object that describes the area to be covered by the Window using the specified MetricsMode.
1944
1945        \return
1946                Nothing.
1947        */
1948        void    setRect(MetricsMode mode, const Rect& area);
1949
1950
1951        /*!
1952        \brief
1953                Set whether z-order changes are enabled or disabled for this Window.
1954
1955        \param setting
1956                - true if z-order changes are enabled for this window.  moveToFront/moveToBack work normally as expected.
1957                - false: z-order changes are disabled for this window.  moveToFront/moveToBack are ignored for this window.
1958
1959        \return
1960                Nothing.
1961        */
1962        void    setZOrderingEnabled(bool setting);
1963
1964
1965    /*!
1966    \brief
1967        Set whether this window will receive multi-click events or multiple 'down' events instead.
1968
1969    \param setting
1970        - true if the Window will receive double-click and triple-click events.
1971        - false if the Window will receive multiple mouse button down events instead of double/triple click events.
1972
1973    \return
1974        Nothing.
1975    */
1976    void setWantsMultiClickEvents(bool setting);
1977
1978
1979    /*!
1980    \brief
1981        Set whether mouse button down event autorepeat is enabled for this window.
1982
1983    \param setting
1984        - true to enable autorepeat of mouse button down events.
1985        - false to disable autorepeat of mouse button down events.
1986
1987    \return
1988        Nothing.
1989    */
1990    void    setMouseAutoRepeatEnabled(bool setting);
1991
1992
1993    /*!
1994    \brief
1995        Set the current auto-repeat delay setting for this window.
1996
1997    \param delay
1998        float value indicating the delay, in seconds, defore the first repeat mouse button down event should be triggered when autorepeat is enabled.
1999
2000    \return
2001        Nothing.
2002    */
2003    void   setAutoRepeatDelay(float delay);
2004
2005
2006    /*!
2007    \brief
2008        Set the current auto-repeat rate setting for this window.
2009
2010    \param rate
2011        float value indicating the rate, in seconds, at which repeat mouse button down events should be generated after the initial delay has expired.
2012
2013    \return
2014        Nothing.
2015    */
2016    void   setAutoRepeatRate(float rate);
2017
2018
2019    /*!
2020    \brief
2021        Set whether the window wants inputs passed to its attached
2022        child windows when the window has inputs captured.
2023
2024    \param setting
2025        - true if System should pass captured input events to child windows.
2026        - false if System should pass captured input events to this window only.
2027    */
2028    void    setDistributesCapturedInputs(bool setting);
2029
2030    /*!
2031    \brief
2032        Internal support method for drag & drop.  You do not normally call
2033        this directly from client code.  See the DragContainer class.
2034    */
2035    void    notifyDragDropItemEnters(DragContainer* item);
2036
2037    /*!
2038    \brief
2039        Internal support method for drag & drop.  You do not normally call
2040        this directly from client code.  See the DragContainer class.
2041    */
2042    void    notifyDragDropItemLeaves(DragContainer* item);
2043
2044    /*!
2045    \brief
2046        Internal support method for drag & drop.  You do not normally call
2047        this directly from client code.  See the DragContainer class.
2048    */
2049    void    notifyDragDropItemDropped(DragContainer* item);
2050
2051    /*!
2052    \brief
2053        Internal destroy method which actually just adds the window and any
2054        parent destructed child windows to the dead pool.
2055
2056        This is virtual to allow for specialised cleanup which may be required
2057        in some advanced cases.  If you override this for the above reason, you
2058        MUST call this base class version.
2059
2060    \note
2061        You never have to call this method yourself, use WindowManager to
2062        destroy your Window objects (which will call this for you).
2063    */
2064    virtual void    destroy(void);
2065
2066    /*!
2067    \brief
2068        Set the custom Tooltip object for this Window.  This value may be NULL to indicate that the
2069        Window should use the system default Tooltip object.
2070
2071    \param tooltip
2072        Pointer to a valid Tooltip based object which should be used as the tooltip for this Window, or NULL to
2073        indicate that the Window should use the system default Tooltip object.  Note that when passing a pointer
2074        to a Tooltip object, ownership of the Tooltip does not pass to this Window object.
2075
2076    \return
2077        Nothing.
2078    */
2079    void setTooltip(Tooltip* tooltip);
2080
2081    /*!
2082    \brief
2083        Set the custom Tooltip to be used by this Window by specifying a Window type.
2084
2085        The Window will internally attempt to create an instance of the specified window type (which must be
2086        derived from the base Tooltip class).  If the Tooltip creation fails, the error is logged and the
2087        Window will revert to using either the existing custom Tooltip or the system default Tooltip.
2088
2089    \param tooltipType
2090        String object holding the name of the Tooltip based Window type which should be used as the Tooltip for
2091        this Window.
2092
2093    \return
2094        Nothing.
2095    */
2096    void setTooltipType(const String& tooltipType);
2097
2098    /*!
2099    \brief
2100        Set the tooltip text for this window.
2101
2102    \param tip
2103        String object holding the text to be displayed in the tooltip for this Window.
2104
2105    \return
2106        Nothing.
2107    */
2108    void setTooltipText(const String& tip);
2109
2110        /*!
2111    \brief
2112        Set whether this window inherits Tooltip text from its parent when its own tooltip text is not set.
2113
2114    \param setting
2115        - true if the window should inherit tooltip text from its parent when its own text is not set.
2116        - false if the window should not inherit tooltip text from its parent (and so show no tooltip when no text is set).
2117
2118    \return
2119        Nothing.
2120     */
2121    void setInheritsTooltipText(bool setting);
2122
2123    /*!
2124    \brief
2125        Set whether this window will rise to the top of the z-order when clicked with the left mouse button.
2126
2127    \param setting
2128        - true if the window should come to the top of other windows when the left mouse button is pushed within its area.
2129        - false if the window should not change z-order position when the left mouse button is pushed within its area.
2130
2131    \return
2132        Nothing.
2133     */
2134    void setRiseOnClickEnabled(bool setting)    { d_riseOnClick = setting; }
2135
2136    /*!
2137    \brief
2138        Set the vertical alignment.
2139
2140        Modifies the vertical alignment for the window.  This setting affects how the windows position is
2141        interpreted relative to its parent.
2142
2143    \param alignment
2144        One of the VerticalAlignment enumerated values.
2145
2146    \return
2147        Nothing.
2148     */
2149    void setVerticalAlignment(const VerticalAlignment alignment);
2150
2151    /*!
2152    \brief
2153        Set the horizontal alignment.
2154
2155        Modifies the horizontal alignment for the window.  This setting affects how the windows position is
2156        interpreted relative to its parent.
2157
2158    \param alignment
2159        One of the HorizontalAlignment enumerated values.
2160
2161    \return
2162        Nothing.
2163     */
2164    void setHorizontalAlignment(const HorizontalAlignment alignment);
2165
2166    /*!
2167    \brief
2168        Set the LookNFeel that shoule be used for this window.
2169
2170    \param falagardType
2171        String object holding the mapped falagard type name (since actual window type will be "Falagard/something")
2172        and not what was passed to WindowManager.  This will be returned from getType instead of the base type.
2173
2174    \param look
2175        String object holding the name of the look to be assigned to the window.
2176
2177    \return
2178        Nothing.
2179
2180    \exception InvalidRequestException thrown if the window already has a look assigned to it.
2181    */
2182    void setLookNFeel(const String& falagardType, const String& look);
2183
2184        /*!
2185        \brief
2186                Set the modal state for this Window.
2187
2188        \param state
2189                Boolean value defining if this Window should be the modal target.
2190                If true, this Window will be activated and set as the modal target.
2191                If false, the modal target will be cleared if this Window is currently the modal target.
2192
2193        \return
2194                Nothing.
2195        */
2196        void setModalState(bool state);
2197
2198    /*!
2199    \brief
2200        method called to perform extended laying out of attached child windows.
2201
2202        The system may call this at various times (like when it is resized for example), and it
2203        may be invoked directly where required.
2204
2205    \return
2206        Nothing.
2207    */
2208    virtual void performChildWindowLayout();
2209
2210    /*!
2211    \brief
2212       Sets the value a named user string, creating it as required.
2213
2214    \param name
2215        String object holding the name of the string to be returned.
2216
2217    \param value
2218        String object holding the value to be assigned to the user string.
2219
2220    \return
2221        Nothing.
2222    */
2223    void setUserString(const String& name, const String& value);
2224
2225    /*!
2226    \brief
2227        Sets whether this window should ignore mouse events and pass them through to any windows behind it.
2228        In effect making the window transparent to the mouse.
2229
2230    \param setting
2231        true if mouse pass through is enabled.
2232        false if mouse pass through is not enabled.
2233    */
2234    void setMousePassThroughEnabled(bool setting)       {d_mousePassThroughEnabled = setting;}
2235
2236    /*************************************************************************
2237                Co-ordinate and Size Conversion Functions
2238        *************************************************************************/
2239        /*!
2240        \brief
2241                Convert the given X co-ordinate from absolute to relative metrics.
2242
2243        \param val
2244                X co-ordinate specified in pixels relative to this Window (so 0 is this windows left edge).
2245
2246        \return
2247                A relative metric value that is equivalent to \a val, given the Window objects current width.
2248        */
2249        float   absoluteToRelativeX(float val) const;
2250
2251
2252        /*!
2253        \brief
2254                Convert the given Y co-ordinate from absolute to relative metrics.
2255
2256        \param val
2257                Y co-ordinate specified in pixels relative to this Window (so 0 is this windows top edge).
2258
2259        \return
2260                A relative metric value that is equivalent to \a val, given the Window objects current height.
2261        */
2262        float   absoluteToRelativeY(float val) const;
2263
2264
2265        /*!
2266        \brief
2267                Convert the given position from absolute to relative metrics.
2268
2269        \param pt
2270                Point object that describes a position specified in pixels relative to this Window (so 0,0 is this windows top-left corner).
2271
2272        \return
2273                A Point object describing a relative metric position that is equivalent to \a pt, given the Window objects current size.
2274        */
2275        Point   absoluteToRelative(const Point& pt) const;
2276
2277
2278        /*!
2279        \brief
2280                Convert the given size from absolute to relative metrics.
2281
2282        \param sze
2283                Size object that describes a size specified in pixels.
2284
2285        \return
2286                A Size object describing a relative metric size that is equivalent to \a sze, given the Window objects current size.
2287        */
2288        Size    absoluteToRelative(const Size& sze) const;
2289
2290
2291        /*!
2292        \brief
2293                Convert the given area from absolute to relative metrics.
2294
2295        \param rect
2296                Rect object describing the area specified in pixels relative to this Window.
2297
2298        \return
2299                A Rect object describing a relative metric area that is equivalent to \a rect, given the Window objects current size.
2300        */
2301        Rect    absoluteToRelative(const Rect& rect) const;
2302
2303
2304        /*!
2305        \brief
2306                Convert the given X co-ordinate from relative to absolute metrics.
2307
2308        \param val
2309                X co-ordinate specified in relative metrics for this Window (so 0 is this windows left edge).
2310
2311        \return
2312                An absolute metric value that is equivalent to \a val, given the Window objects current width.
2313        */
2314        float   relativeToAbsoluteX(float val) const;
2315
2316
2317        /*!
2318        \brief
2319                Convert the given Y co-ordinate from relative to absolute metrics.
2320
2321        \param val
2322                Y co-ordinate specified in relative metrics for this Window (so 0 is this windows top edge).
2323
2324        \return
2325                An absolute metric value that is equivalent to \a val, given the Window objects current height.
2326        */
2327        float   relativeToAbsoluteY(float val) const;
2328
2329
2330        /*!
2331        \brief
2332                Convert the given position from relative to absolute metrics.
2333
2334        \param pt
2335                Point object describing a position specified in relative metrics for this Window (so 0,0 is this windows top-left corner).
2336
2337        \return
2338                A Point object describing a position in absolute metric values that is equivalent to \a pt, given the Window objects current size.
2339        */
2340        Point   relativeToAbsolute(const Point& pt) const;
2341
2342
2343        /*!
2344        \brief
2345                Convert the given size from relative to absolute metrics.
2346
2347        \param sze
2348                Size object describing a size specified in relative metrics for this Window.
2349
2350        \return
2351                A Size object that describes a size in absolute metric values that is equivalent to \a sze, given the Window objects current size.
2352        */
2353        Size    relativeToAbsolute(const Size& sze) const;
2354
2355
2356        /*!
2357        \brief
2358                Convert the given area from relative to absolute metrics.
2359
2360        \param rect
2361                Rect object describing the area specified in relative metrics for this Window.
2362
2363        \return
2364                A Rect object that describes an area in absolute metric values that is equivalent to \a rect, given the Window objects current size.
2365        */
2366        Rect    relativeToAbsolute(const Rect& rect) const;
2367
2368
2369        /*!
2370        \brief
2371                Convert a window co-ordinate value, specified in whichever metrics mode is active, to a screen relative pixel co-ordinate.
2372
2373        \param x
2374                x co-ordinate value to be converted
2375
2376        \return
2377                float value describing a pixel screen co-ordinate that is equivalent to window co-ordinate \a x.
2378        */
2379        float   windowToScreenX(float x) const;
2380
2381
2382        /*!
2383        \brief
2384                Convert a window co-ordinate value, specified in whichever metrics mode is active, to a screen relative pixel co-ordinate.
2385
2386        \param y
2387                y co-ordinate value to be converted
2388
2389        \return
2390                float value describing a screen co-ordinate that is equivalent to window co-ordinate \a y.
2391        */
2392        float   windowToScreenY(float y) const;
2393
2394
2395        /*!
2396        \brief
2397                Convert a window co-ordinate position, specified in whichever metrics mode is active, to a screen relative pixel co-ordinate position.
2398
2399        \param pt
2400                Point object describing the position to be converted
2401
2402        \return
2403                Point object describing a screen co-ordinate position that is equivalent to window co-ordinate position \a pt.
2404        */
2405        Point   windowToScreen(const Point& pt) const;
2406
2407
2408        /*!
2409        \brief
2410                Convert a window size value, specified in whichever metrics mode is active, to a size in pixels.
2411
2412        \param sze
2413                Size object describing the size to be converted
2414
2415        \return
2416                Size object describing describing a size in pixels that is equivalent to the window based size \a sze.
2417        */
2418        Size    windowToScreen(const Size& sze) const;
2419
2420
2421        /*!
2422        \brief
2423                Convert a window area, specified in whichever metrics mode is active, to a screen area.
2424
2425        \param rect
2426                Rect object describing the area to be converted
2427
2428        \return
2429                Rect object describing a screen area that is equivalent to window area \a rect.
2430        */
2431        Rect    windowToScreen(const Rect& rect) const;
2432
2433
2434        /*!
2435        \brief
2436                Convert a screen relative pixel co-ordinate value to a window co-ordinate value, specified in whichever metrics mode is active.
2437
2438        \param x
2439                x co-ordinate value to be converted
2440
2441        \return
2442                float value describing a window co-ordinate value that is equivalent to screen co-ordinate \a x.
2443        */
2444        float   screenToWindowX(float x) const;
2445
2446
2447        /*!
2448        \brief
2449                Convert a screen relative pixel co-ordinate value to a window co-ordinate value, specified in whichever metrics mode is active.
2450
2451        \param y
2452                y co-ordinate value to be converted
2453
2454        \return
2455                float value describing a window co-ordinate value that is equivalent to screen co-ordinate \a y.
2456        */
2457        float   screenToWindowY(float y) const;
2458
2459
2460        /*!
2461        \brief
2462                Convert a screen relative pixel position to a window co-ordinate position, specified in whichever metrics mode is active.
2463
2464        \param pt
2465                Point object describing the position to be converted
2466
2467        \return
2468                Point object describing a window co-ordinate position that is equivalent to screen co-ordinate \a x.
2469        */
2470        Point   screenToWindow(const Point& pt) const;
2471
2472
2473        /*!
2474        \brief
2475                Convert a pixel screen size to a window based size, specified in whichever metrics mode is active.
2476
2477        \param sze
2478                Size object describing the size to be converted
2479
2480        \return
2481                Size object describing a window based size that is equivalent to screen based size \a sze.
2482        */
2483        Size    screenToWindow(const Size& sze) const;
2484
2485
2486        /*!
2487        \brief
2488                Convert a screen area to a window area, specified in whichever metrics mode is active.
2489
2490        \param rect
2491                Rect object describing the area to be converted
2492
2493        \return
2494                Rect object describing a window area that is equivalent to screen area \a rect.
2495        */
2496        Rect    screenToWindow(const Rect& rect) const;
2497
2498
2499    /*!
2500    \brief
2501        Convert the given X co-ordinate from unified to relative metrics.
2502
2503    \param val
2504        X co-ordinate specified as a UDim relative to this Window (so {0, 0} is this windows left edge).
2505
2506    \return
2507        A relative metric value that is equivalent to \a val, given the Window objects current width.
2508    */
2509    float unifiedToRelativeX(const UDim& val) const;
2510
2511
2512    /*!
2513    \brief
2514        Convert the given Y co-ordinate from unified to relative metrics.
2515
2516    \param val
2517        Y co-ordinate specified in as a UDim relative to this Window (so {0, 0} is this windows top edge).
2518
2519    \return
2520        A relative metric value that is equivalent to \a val, given the Window objects current height.
2521    */
2522    float       unifiedToRelativeY(const UDim& val) const;
2523
2524
2525    /*!
2526    \brief
2527        Convert the given UVector2 value from unified to relative metrics.
2528
2529    \param val
2530        UVector2 object that describes a position specified in unified dimensions relative to this Window (so {{0, 0}, {0, 0}) is this windows top-left corner).
2531
2532    \return
2533        A Vector2 object describing a relative metric point that is equivalent to \a val, given the Window objects current size.
2534    */
2535    Vector2 unifiedToRelative(const UVector2& val) const;
2536
2537
2538    /*!
2539    \brief
2540        Convert the given area from unfied to relative metrics.
2541
2542    \param val
2543        URect object describing the area specified in unified dimensions relative to this Window.
2544
2545    \return
2546        A Rect object describing a relative metric area that is equivalent to \a val, given the Window objects current size.
2547    */
2548    Rect unifiedToRelative(const URect& val) const;
2549
2550
2551    /*!
2552    \brief
2553        Convert the given X co-ordinate from unified to absolute metrics.
2554
2555    \param val
2556        X co-ordinate specified as a UDim relative to this Window (so {0, 0} is this windows left edge).
2557
2558    \return
2559        An absolute metric value that is equivalent to \a val, given the Window objects current width.
2560    */
2561    float unifiedToAbsoluteX(const UDim& val) const;
2562
2563
2564    /*!
2565    \brief
2566        Convert the given Y co-ordinate from unified to absolute metrics.
2567
2568    \param val
2569        Y co-ordinate specified in as a UDim relative to this Window (so {0, 0} is this windows top edge).
2570
2571    \return
2572        An absolute metric value that is equivalent to \a val, given the Window objects current height.
2573    */
2574    float       unifiedToAbsoluteY(const UDim& val) const;
2575
2576
2577    /*!
2578    \brief
2579        Convert the given UVector2 value from unified to absolute metrics.
2580
2581    \param val
2582        UVector2 object that describes a position specified in unified dimensions relative to this Window (so {{0, 0}, {0, 0}) is this windows top-left corner).
2583
2584    \return
2585        A Vector2 object describing a absolute metric point that is equivalent to \a val, given the Window objects current size.
2586    */
2587    Vector2 unifiedToAbsolute(const UVector2& val) const;
2588
2589
2590    /*!
2591    \brief
2592        Convert the given area from unfied to absolute metrics.
2593
2594    \param val
2595        URect object describing the area specified in unified dimensions relative to this Window.
2596
2597    \return
2598        A Rect object describing an absolute metric area that is equivalent to \a val, given the Window objects current size.
2599    */
2600    Rect unifiedToAbsolute(const URect& val) const;
2601
2602
2603    /*!
2604    \brief
2605        Convert a window co-ordinate value, specified as a UDim, to a screen relative pixel co-ordinate.
2606
2607    \param x
2608        UDim x co-ordinate value to be converted
2609
2610    \return
2611        float value describing a pixel screen co-ordinate that is equivalent to window UDim co-ordinate \a x.
2612    */
2613    float windowToScreenX(const UDim& x) const;
2614
2615
2616    /*!
2617    \brief
2618        Convert a window co-ordinate value, specified as a UDim, to a screen relative pixel co-ordinate.
2619
2620    \param y
2621        UDim y co-ordinate value to be converted
2622
2623    \return
2624        float value describing a screen co-ordinate that is equivalent to window UDim co-ordinate \a y.
2625    */
2626    float windowToScreenY(const UDim& y) const;
2627
2628
2629    /*!
2630    \brief
2631        Convert a window co-ordinate point, specified as a UVector2, to a screen relative pixel co-ordinate point.
2632
2633    \param vec
2634        UVector2 object describing the point to be converted
2635
2636    \return
2637        Vector2 object describing a screen co-ordinate position that is equivalent to window based UVector2 \a vec.
2638    */
2639    Vector2 windowToScreen(const UVector2& vec) const;
2640
2641
2642    /*!
2643    \brief
2644        Convert a window area, specified as a URect, to a screen area.
2645
2646    \param rect
2647        URect object describing the area to be converted
2648
2649    \return
2650        Rect object describing a screen area that is equivalent to window area \a rect.
2651    */
2652    Rect windowToScreen(const URect& rect) const;
2653
2654
2655    /*!
2656    \brief
2657        Convert a screen relative UDim co-ordinate value to a window co-ordinate value, specified in whichever metrics mode is active.
2658
2659    \param x
2660        UDim x co-ordinate value to be converted
2661
2662    \return
2663        float value describing a window co-ordinate value that is equivalent to screen UDim co-ordinate \a x.
2664    */
2665    float screenToWindowX(const UDim& x) const;
2666
2667
2668    /*!
2669    \brief
2670        Convert a screen relative UDim co-ordinate value to a window co-ordinate value, specified in whichever metrics mode is active.
2671
2672    \param y
2673        UDim y co-ordinate value to be converted
2674
2675    \return
2676        float value describing a window co-ordinate value that is equivalent to screen UDim co-ordinate \a y.
2677    */
2678    float screenToWindowY(const UDim& y) const;
2679
2680
2681    /*!
2682    \brief
2683        Convert a screen relative UVector2 point to a window co-ordinate point, specified in whichever metrics mode is active.
2684
2685    \param vec
2686        UVector2 object describing the point to be converted
2687
2688    \return
2689        Vector2 object describing a window co-ordinate point that is equivalent to screen based UVector2 point \a vec.
2690    */
2691    Vector2 screenToWindow(const UVector2& vec) const;
2692
2693
2694    /*!
2695    \brief
2696        Convert a URect screen area to a window area, specified in whichever metrics mode is active.
2697
2698    \param rect
2699        URect object describing the area to be converted
2700
2701    \return
2702        Rect object describing a window area that is equivalent to URect screen area \a rect.
2703    */
2704    Rect screenToWindow(const URect& rect) const;
2705
2706
2707    /*************************************************************************
2708        Interface to unified co-ordinate system
2709    *************************************************************************/
2710    /*!
2711    \brief
2712        Set the window area.
2713
2714        Sets the area occupied by this window.  The defined area is offset from the
2715        top-left corner of this windows parent window or from the top-left corner of
2716        the display if this window has no parent (i.e. it is the root window).
2717
2718    \note
2719        This method makes use of "Unified Dimensions".  These contain both parent relative and
2720        absolute pixel components, which are used in determining the final value used.
2721
2722    \param xpos
2723        UDim describing the new x co-ordinate (left edge) of the window area.
2724
2725    \param ypos
2726        UDim describing the new y co-ordinate (top-edge) of the window area.
2727
2728    \param width
2729        UDim describing the new width of the window area.
2730
2731    \param height
2732        UDim describing the new height of the window area.
2733     */
2734    void setWindowArea(const UDim& xpos, const UDim& ypos, const UDim& width, const UDim& height);
2735
2736    /*!
2737    \brief
2738        Set the window area.
2739
2740        Sets the area occupied by this window.  The defined area is offset from the
2741        top-left corner of this windows parent window or from the top-left corner of
2742        the display if this window has no parent (i.e. it is the root window).
2743
2744    \note
2745        This method makes use of "Unified Dimensions".  These contain both parent relative and
2746        absolute pixel components, which are used in determining the final value used.
2747
2748    \param pos
2749        UVector2 describing the new position (top-left corner) of the window area.
2750
2751    \param size
2752        UVector2 describing the new size of the window area.
2753     */
2754    void setWindowArea(const UVector2& pos, const UVector2& size);
2755
2756    /*!
2757    \brief
2758        Set the window area.
2759
2760        Sets the area occupied by this window.  The defined area is offset from the
2761        top-left corner of this windows parent window or from the top-left corner of
2762        the display if this window has no parent (i.e. it is the root window).
2763
2764    \note
2765        This method makes use of "Unified Dimensions".  These contain both parent relative and
2766        absolute pixel components, which are used in determining the final value used.
2767
2768    \param area
2769        URect describing the new area rectangle of the window area.
2770     */
2771    void setWindowArea(const URect& area);
2772
2773    /*!
2774    \brief
2775        Set the window's position.
2776
2777        Sets the position of the area occupied by this window.  The position is offset from the
2778        top-left corner of this windows parent window or from the top-left corner of
2779        the display if this window has no parent (i.e. it is the root window).
2780
2781    \note
2782        This method makes use of "Unified Dimensions".  These contain both parent relative and
2783        absolute pixel components, which are used in determining the final value used.
2784
2785    \param pos
2786        UVector2 describing the new position (top-left corner) of the window area.
2787     */
2788    void setWindowPosition(const UVector2& pos);
2789
2790    /*!
2791    \brief
2792        Set the window's X position.
2793
2794        Sets the x position (left edge) of the area occupied by this window.  The position is
2795        offset from the left edge of this windows parent window or from the left edge of
2796        the display if this window has no parent (i.e. it is the root window).
2797
2798    \note
2799        This method makes use of "Unified Dimensions".  These contain both parent relative and
2800        absolute pixel components, which are used in determining the final value used.
2801
2802    \param x
2803        UDim describing the new x position of the window area.
2804     */
2805    void setWindowXPosition(const UDim& x);
2806
2807    /*!
2808    \brief
2809        Set the window's Y position.
2810
2811        Sets the y position (top edge) of the area occupied by this window.  The position is
2812        offset from the top edge of this windows parent window or from the top edge of
2813        the display if this window has no parent (i.e. it is the root window).
2814
2815    \note
2816        This method makes use of "Unified Dimensions".  These contain both parent relative and
2817        absolute pixel components, which are used in determining the final value used.
2818
2819    \param y
2820        UDim describing the new y position of the window area.
2821     */
2822    void setWindowYPosition(const UDim& y);
2823
2824    /*!
2825    \brief
2826        Set the window's size.
2827
2828        Sets the size of the area occupied by this window.
2829
2830    \note
2831        This method makes use of "Unified Dimensions".  These contain both parent relative and
2832        absolute pixel components, which are used in determining the final value used.
2833
2834    \param size
2835        UVector2 describing the new size of the window area.
2836     */
2837    void setWindowSize(const UVector2& size);
2838
2839    /*!
2840    \brief
2841        Set the window's width.
2842
2843        Sets the width of the area occupied by this window.
2844
2845    \note
2846        This method makes use of "Unified Dimensions".  These contain both parent relative and
2847        absolute pixel components, which are used in determining the final value used.
2848
2849    \param width
2850        UDim describing the new width of the window area.
2851     */
2852    void setWindowWidth(const UDim& width);
2853
2854    /*!
2855    \brief
2856        Set the window's height.
2857
2858        Sets the height of the area occupied by this window.
2859
2860    \note
2861        This method makes use of "Unified Dimensions".  These contain both parent relative and
2862        absolute pixel components, which are used in determining the final value used.
2863
2864    \param height
2865        UDim describing the new height of the window area.
2866     */
2867    void setWindowHeight(const UDim& height);
2868
2869    /*!
2870    \brief
2871        Set the window's maximum size.
2872
2873        Sets the maximum size that this windows area may occupy (whether size changes occur by user
2874        interaction, general system operation, or by direct setting by client code).
2875
2876    \note
2877        This method makes use of "Unified Dimensions".  These contain both parent relative and
2878        absolute pixel components, which are used in determining the final value used.
2879
2880    \param size
2881        UVector2 describing the new maximum size of the window area.
2882     */
2883    void setWindowMaxSize(const UVector2& size);
2884
2885    /*!
2886    \brief
2887        Set the window's minimum size.
2888
2889        Sets the minimum size that this windows area may occupy (whether size changes occur by user
2890        interaction, general system operation, or by direct setting by client code).
2891
2892    \note
2893        This method makes use of "Unified Dimensions".  These contain both parent relative and
2894        absolute pixel components, which are used in determining the final value used.
2895
2896    \param size
2897        UVector2 describing the new minimum size of the window area.
2898     */
2899    void setWindowMinSize(const UVector2& size);
2900
2901    /*!
2902    \brief
2903        Return the windows area.
2904
2905        Returns the area occupied by this window.  The defined area is offset from the
2906        top-left corner of this windows parent window or from the top-left corner of
2907        the display if this window has no parent (i.e. it is the root window).
2908
2909    \note
2910        This method makes use of "Unified Dimensions".  These contain both parent relative and
2911        absolute pixel components, which are used in determining the final value used.
2912
2913    \return
2914        URect describing the rectangle of the window area.
2915     */
2916    const URect& getWindowArea() const;
2917
2918    /*!
2919    \brief
2920        Get the window's position.
2921
2922        Gets the position of the area occupied by this window.  The position is offset from the
2923        top-left corner of this windows parent window or from the top-left corner of
2924        the display if this window has no parent (i.e. it is the root window).
2925
2926    \note
2927        This method makes use of "Unified Dimensions".  These contain both parent relative and
2928        absolute pixel components, which are used in determining the final value used.
2929
2930    \return
2931        UVector2 describing the position (top-left corner) of the window area.
2932     */
2933    const UVector2& getWindowPosition() const;
2934
2935    /*!
2936    \brief
2937        Get the window's X position.
2938
2939        Gets the x position (left edge) of the area occupied by this window.  The position is
2940        offset from the left edge of this windows parent window or from the left edge of
2941        the display if this window has no parent (i.e. it is the root window).
2942
2943    \note
2944        This method makes use of "Unified Dimensions".  These contain both parent relative and
2945        absolute pixel components, which are used in determining the final value used.
2946
2947    \return
2948        UDim describing the x position of the window area.
2949     */
2950    const UDim& getWindowXPosition() const;
2951
2952    /*!
2953    \brief
2954        Get the window's Y position.
2955
2956        Gets the y position (top edge) of the area occupied by this window.  The position is
2957        offset from the top edge of this windows parent window or from the top edge of
2958        the display if this window has no parent (i.e. it is the root window).
2959
2960    \note
2961        This method makes use of "Unified Dimensions".  These contain both parent relative and
2962        absolute pixel components, which are used in determining the final value used.
2963
2964    \return
2965        UDim describing the y position of the window area.
2966     */
2967    const UDim& getWindowYPosition() const;
2968
2969    /*!
2970    \brief
2971        Get the window's size.
2972
2973        Gets the size of the area occupied by this window.
2974
2975    \note
2976        This method makes use of "Unified Dimensions".  These contain both parent relative and
2977        absolute pixel components, which are used in determining the final value used.
2978
2979    \return
2980        UVector2 describing the size of the window area.
2981     */
2982    UVector2 getWindowSize() const;
2983
2984    /*!
2985    \brief
2986        Get the window's width.
2987
2988        Gets the width of the area occupied by this window.
2989
2990    \note
2991        This method makes use of "Unified Dimensions".  These contain both parent relative and
2992        absolute pixel components, which are used in determining the final value used.
2993
2994    \return
2995        UDim describing the width of the window area.
2996     */
2997    UDim getWindowWidth() const;
2998
2999    /*!
3000    \brief
3001        Get the window's height.
3002
3003        Gets the height of the area occupied by this window.
3004
3005    \note
3006        This method makes use of "Unified Dimensions".  These contain both parent relative and
3007        absolute pixel components, which are used in determining the final value used.
3008
3009    \return
3010        UDim describing the height of the window area.
3011     */
3012    UDim getWindowHeight() const;
3013
3014    /*!
3015    \brief
3016        Get the window's maximum size.
3017
3018        Gets the maximum size that this windows area may occupy (whether size changes occur by user
3019        interaction, general system operation, or by direct setting by client code).
3020
3021    \note
3022        This method makes use of "Unified Dimensions".  These contain both parent relative and
3023        absolute pixel components, which are used in determining the final value used.
3024
3025    \return
3026        UVector2 describing the maximum size of the window area.
3027     */
3028    const UVector2& getWindowMaxSize() const;
3029
3030    /*!
3031    \brief
3032        Get the window's minimum size.
3033
3034        Gets the minimum size that this windows area may occupy (whether size changes occur by user
3035        interaction, general system operation, or by direct setting by client code).
3036
3037    \note
3038        This method makes use of "Unified Dimensions".  These contain both parent relative and
3039        absolute pixel components, which are used in determining the final value used.
3040
3041    \return
3042        UVector2 describing the minimum size of the window area.
3043     */
3044    const UVector2& getWindowMinSize() const;
3045
3046
3047        /*************************************************************************
3048                Main render function.
3049        *************************************************************************/
3050        /*!
3051        \brief
3052                Causes the Window object to render itself and all of it's attached children
3053
3054        \return
3055                Nothing
3056        */
3057        void    render(void);
3058
3059
3060        /*!
3061        \brief
3062                Cause window to update itself and any attached children.  Client code does not need to call this method; to
3063                ensure full, and proper updates, call the injectTimePulse methodname method provided by the System class.
3064
3065        \note
3066                The update order is such that 'this' window is updated prior to any child windows, this is so
3067                that child windows that access the parent in their update code get the correct updated state.
3068
3069        \param elapsed
3070                float value indicating the number of seconds passed since the last update.
3071
3072        \return
3073                Nothing.
3074        */
3075        void    update(float elapsed);
3076
3077
3078    /*!
3079    \brief
3080        Writes an xml representation of this window object to \a out_stream.
3081
3082    \param out_stream
3083        Stream where xml data should be output.
3084
3085    \return
3086        Nothing.
3087    */
3088    virtual void writeXMLToStream(OutStream& out_stream) const;
3089
3090protected:
3091        /*************************************************************************
3092                System object can trigger events directly
3093        *************************************************************************/
3094        friend  class System;
3095
3096
3097        /*************************************************************************
3098                Event trigger methods
3099        *************************************************************************/
3100        /*!
3101        \brief
3102                Handler called when the window's size changes.
3103
3104        \param e
3105                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3106                event the trigger window is always 'this'.
3107        */
3108        virtual void    onSized(WindowEventArgs& e);
3109
3110
3111        /*!
3112        \brief
3113                Handler called when the window's position changes.
3114
3115        \param e
3116                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3117                event the trigger window is always 'this'.
3118        */
3119        virtual void    onMoved(WindowEventArgs& e);
3120
3121
3122        /*!
3123        \brief
3124                Handler called when the window's text is changed.
3125
3126        \param e
3127                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3128                event the trigger window is always 'this'.
3129        */
3130        virtual void    onTextChanged(WindowEventArgs& e);
3131
3132
3133        /*!
3134        \brief
3135                Handler called when the window's font is changed.
3136
3137        \param e
3138                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3139                event the trigger window is always 'this'.
3140        */
3141        virtual void    onFontChanged(WindowEventArgs& e);
3142
3143
3144        /*!
3145        \brief
3146                Handler called when the window's alpha blend value is changed.
3147
3148        \param e
3149                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3150                event the trigger window is always 'this'.
3151        */
3152        virtual void    onAlphaChanged(WindowEventArgs& e);
3153
3154
3155        /*!
3156        \brief
3157                Handler called when the window's client assigned ID is changed.
3158
3159        \param e
3160                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3161                event the trigger window is always 'this'.
3162        */
3163        virtual void    onIDChanged(WindowEventArgs& e);
3164
3165
3166        /*!
3167        \brief
3168                Handler called when the window is shown (made visible).
3169
3170        \param e
3171                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3172                event the trigger window is always 'this'.
3173        */
3174        virtual void    onShown(WindowEventArgs& e);
3175
3176
3177        /*!
3178        \brief
3179                Handler called when the window is hidden.
3180
3181        \param e
3182                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3183                event the trigger window is always 'this'.
3184        */
3185        virtual void    onHidden(WindowEventArgs& e);
3186
3187
3188        /*!
3189        \brief
3190                Handler called when the window is enabled.
3191
3192        \param e
3193                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3194                event the trigger window is always 'this'.
3195        */
3196        virtual void    onEnabled(WindowEventArgs& e);
3197
3198
3199        /*!
3200        \brief
3201                Handler called when the window is disabled.
3202
3203        \param e
3204                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3205                event the trigger window is always 'this'.
3206        */
3207        virtual void    onDisabled(WindowEventArgs& e);
3208
3209
3210        /*!
3211        \brief
3212                Handler called when the window's active metrics system is changed.
3213
3214        \param e
3215                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3216                event the trigger window is always 'this'.
3217        */
3218        virtual void    onMetricsChanged(WindowEventArgs& e);
3219
3220
3221        /*!
3222        \brief
3223                Handler called when the window's setting for being clipped by it's parent is changed.
3224
3225        \param e
3226                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3227                event the trigger window is always 'this'.
3228        */
3229        virtual void    onClippingChanged(WindowEventArgs& e);
3230
3231
3232        /*!
3233        \brief
3234                Handler called when the window's setting for being destroyed automatically be it's parent is changed.
3235
3236        \param e
3237                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3238                event the trigger window is always 'this'.
3239        */
3240        virtual void    onParentDestroyChanged(WindowEventArgs& e);
3241
3242
3243        /*!
3244        \brief
3245                Handler called when the window's setting for inheriting alpha-blending is changed.
3246
3247        \param e
3248                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3249                event the trigger window is always 'this'.
3250        */
3251        virtual void    onInheritsAlphaChanged(WindowEventArgs& e);
3252
3253
3254        /*!
3255        \brief
3256                Handler called when the window's always-on-top setting is changed.
3257
3258        \param e
3259                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3260                event the trigger window is always 'this'.
3261        */
3262        virtual void    onAlwaysOnTopChanged(WindowEventArgs& e);
3263
3264
3265        /*!
3266        \brief
3267                Handler called when this window gains capture of mouse inputs.
3268
3269        \param e
3270                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3271                event the trigger window is always 'this'.
3272        */
3273        virtual void    onCaptureGained(WindowEventArgs& e);
3274
3275
3276        /*!
3277        \brief
3278                Handler called when this window loses capture of mouse inputs.
3279
3280        \param e
3281                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3282                event the trigger window is always 'this'.
3283        */
3284        virtual void    onCaptureLost(WindowEventArgs& e);
3285
3286
3287        /*!
3288        \brief
3289                Handler called when rendering for this window has started.
3290
3291        \param e
3292                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3293                event the trigger window is always 'this'.
3294        */
3295        virtual void    onRenderingStarted(WindowEventArgs& e);
3296
3297
3298        /*!
3299        \brief
3300                Handler called when rendering for this window has ended.
3301
3302        \param e
3303                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3304                event the trigger window is always 'this'.
3305        */
3306        virtual void    onRenderingEnded(WindowEventArgs& e);
3307
3308
3309        /*!
3310        \brief
3311                Handler called when the z-order position of this window has changed.
3312
3313        \param e
3314                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3315                event the trigger window is always 'this'.
3316        */
3317        virtual void    onZChanged(WindowEventArgs& e);
3318
3319
3320        /*!
3321        \brief
3322                Handler called when this window's destruction sequence has begun.
3323
3324        \param e
3325                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
3326                event the trigger window is always 'this'.
3327        */
3328        virtual void    onDestructionStarted(WindowEventArgs& e);
3329
3330
3331        /*!
3332        \brief
3333                Handler called when this window has become the active window.
3334
3335        \param e
3336                ActivationEventArgs class whose 'otherWindow' field is set to the window that previously was active, or NULL for none.
3337        */
3338        virtual void    onActivated(ActivationEventArgs& e);
3339
3340
3341        /*!
3342        \brief
3343                Handler called when this window has lost input focus and has been deactivated.
3344
3345        \param e
3346                ActivationEventArgs object whose 'otherWindow' field is set to the window that has now become active, or NULL for none.
3347        */
3348        virtual void    onDeactivated(ActivationEventArgs& e);
3349
3350
3351        /*!
3352        \brief
3353                Handler called when this window's parent window has been resized.  If this window is the root / GUI Sheet
3354                window, this call will be made when the screen size changes.
3355
3356        \param e
3357                WindowEventArgs object whose 'window' pointer field is set the the window that caused the event; this is typically either
3358                this window's parent window, or NULL to indicate the screen size has changed.
3359        */
3360        virtual void    onParentSized(WindowEventArgs& e);
3361
3362
3363        /*!
3364        \brief
3365                Handler called when a child window is added to this window.
3366
3367        \param e
3368                WindowEventArgs object whose 'window' pointer field is set to the window that has been added.
3369        */
3370        virtual void    onChildAdded(WindowEventArgs& e);
3371
3372
3373        /*!
3374        \brief
3375                Handler called when a child window is removed from this window.
3376
3377        \param e
3378                WindowEventArgs object whose 'window' pointer field is set the window that has been removed.
3379        */
3380        virtual void    onChildRemoved(WindowEventArgs& e);
3381
3382
3383        /*!
3384        \brief
3385                Handler called when the mouse cursor has entered this window's area.
3386
3387        \param e
3388                MouseEventArgs object.  All fields are valid.
3389        */
3390        virtual void    onMouseEnters(MouseEventArgs& e);
3391
3392
3393        /*!
3394        \brief
3395                Handler called when the mouse cursor has left this window's area.
3396
3397        \param e
3398                MouseEventArgs object.  All fields are valid.
3399        */
3400        virtual void    onMouseLeaves(MouseEventArgs& e);
3401
3402
3403        /*!
3404        \brief
3405                Handler called when the mouse cursor has been moved within this window's area.
3406
3407        \param e
3408                MouseEventArgs object.  All fields are valid.
3409        */
3410        virtual void    onMouseMove(MouseEventArgs& e);
3411
3412
3413        /*!
3414        \brief
3415                Handler called when the mouse wheel (z-axis) position changes within this window's area.
3416
3417        \param e
3418                MouseEventArgs object.  All fields are valid.
3419        */
3420        virtual void    onMouseWheel(MouseEventArgs& e);
3421
3422
3423        /*!
3424        \brief
3425                Handler called when a mouse button has been depressed within this window's area.
3426
3427        \param e
3428                MouseEventArgs object.  All fields are valid.
3429        */
3430        virtual void    onMouseButtonDown(MouseEventArgs& e);
3431
3432
3433        /*!
3434        \brief
3435                Handler called when a mouse button has been released within this window's area.
3436
3437        \param e
3438                MouseEventArgs object.  All fields are valid.
3439        */
3440        virtual void    onMouseButtonUp(MouseEventArgs& e);
3441
3442
3443        /*!
3444        \brief
3445                Handler called when a mouse button has been clicked (that is depressed and then released, within a specified time)
3446                within this window's area.
3447
3448        \param e
3449                MouseEventArgs object.  All fields are valid.
3450        */
3451        virtual void    onMouseClicked(MouseEventArgs& e);
3452
3453
3454        /*!
3455        \brief
3456                Handler called when a mouse button has been double-clicked within this window's area.
3457
3458        \param e
3459                MouseEventArgs object.  All fields are valid.
3460        */
3461        virtual void    onMouseDoubleClicked(MouseEventArgs& e);
3462
3463
3464        /*!
3465        \brief
3466                Handler called when a mouse button has been triple-clicked within this window's area.
3467
3468        \param e
3469                MouseEventArgs object.  All fields are valid.
3470        */
3471        virtual void    onMouseTripleClicked(MouseEventArgs& e);
3472
3473
3474        /*!
3475        \brief
3476                Handler called when a key as been depressed while this window has input focus.
3477
3478        \param e
3479                KeyEventArgs object whose 'scancode' field is set to the Key::Scan value representing the key that was pressed, and whose
3480                'sysKeys' field represents the combination of SystemKey that were active when the event was generated.
3481        */
3482        virtual void    onKeyDown(KeyEventArgs& e);
3483
3484
3485        /*!
3486        \brief
3487                Handler called when a key as been released while this window has input focus.
3488
3489        \param e
3490                KeyEventArgs object whose 'scancode' field is set to the Key::Scan value representing the key that was released, and whose
3491                'sysKeys' field represents the combination of SystemKey that were active when the event was generated.  All other fields should be
3492                considered as 'junk'.
3493        */
3494        virtual void    onKeyUp(KeyEventArgs& e);
3495
3496
3497        /*!
3498        \brief
3499                Handler called when a character-key has been pressed while this window has input focus.
3500
3501        \param e
3502                KeyEventArgs object whose 'codepoint' field is set to the Unicode code point (encoded as utf32) for the character typed, and whose
3503                'sysKeys' field represents the combination of SystemKey that were active when the event was generated.  All other fields should be
3504                considered as 'junk'.
3505        */
3506        virtual void    onCharacter(KeyEventArgs& e);
3507
3508    /*!
3509    \brief
3510        Handler called when a DragContainer is dragged over this window.
3511
3512    \param e
3513        DragDropEventArgs object initialised as follows:
3514        - window field is normaly set to point to 'this' window.
3515        - dragDropItem is a pointer to a DragContainer window that triggered the event.
3516    */
3517    virtual void    onDragDropItemEnters(DragDropEventArgs& e);
3518
3519
3520    /*!
3521    \brief
3522        Handler called when a DragContainer is dragged over this window.
3523
3524    \param e
3525        DragDropEventArgs object initialised as follows:
3526        - window field is normaly set to point to 'this' window.
3527        - dragDropItem is a pointer to a DragContainer window that triggered the event.
3528    */
3529    virtual void    onDragDropItemLeaves(DragDropEventArgs& e);
3530
3531
3532    /*!
3533    \brief
3534        Handler called when a DragContainer is dragged over this window.
3535
3536    \param e
3537        DragDropEventArgs object initialised as follows:
3538        - window field is normaly set to point to 'this' window.
3539        - dragDropItem is a pointer to a DragContainer window that triggered the event.
3540    */
3541    virtual void    onDragDropItemDropped(DragDropEventArgs& e);
3542
3543
3544    /*!
3545    \brief
3546        Handler called when the vertical alignment setting for the window is changed.
3547
3548    \param e
3549        WindowEventArgs object initialised as follows:
3550        - window field is set to point to the Window object whos alignment has changed (typically 'this').
3551    */
3552    virtual void    onVerticalAlignmentChanged(WindowEventArgs& e);
3553
3554
3555    /*!
3556    \brief
3557        Handler called when the horizontal alignment setting for the window is changed.
3558
3559    \param e
3560        WindowEventArgs object initialised as follows:
3561        - window field is set to point to the Window object whos alignment has changed (typically 'this').
3562    */
3563    virtual void    onHorizontalAlignmentChanged(WindowEventArgs& e);
3564
3565
3566        /*************************************************************************
3567                Implementation Functions
3568        *************************************************************************/
3569        /*!
3570        \brief
3571                Perform actual update processing for this Window.
3572
3573        \param elapsed
3574                float value indicating the number of seconds elapsed since the last update call.
3575
3576        \return
3577                Nothing.
3578        */
3579        virtual void    updateSelf(float elapsed);
3580
3581
3582        /*!
3583        \brief
3584                Perform the actual rendering for this Window.
3585
3586        \param z
3587                float value specifying the base Z co-ordinate that should be used when rendering
3588
3589        \return
3590                Nothing
3591        */
3592        virtual void    drawSelf(float z);
3593
3594
3595        /*!
3596        \brief
3597           Update the rendering cache.
3598
3599           Populates the Window's RenderCache with imagery to be sent to the renderer.
3600    */
3601    virtual void populateRenderCache()  {}
3602
3603
3604        /*!
3605        \brief
3606                Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
3607
3608        \param class_name
3609                The class name that is to be checked.
3610
3611        \return
3612                true if this window was inherited from \a class_name. false if not.
3613        */
3614        virtual bool    testClassName_impl(const String& class_name) const
3615        {
3616                if (class_name==(const utf8*)"Window")  return true;
3617                return false;
3618        }
3619
3620
3621        /*!
3622        \brief
3623                Set the parent window for this window object.
3624
3625        \param parent
3626                Pointer to a Window object that is to be assigned as the parent to this Window.
3627
3628        \return
3629                Nothing
3630        */
3631        void    setParent(Window* parent);
3632
3633
3634        /*!
3635        \brief
3636                Return the pixel Width of the parent element.  This always returns a valid number.
3637
3638        \return
3639                float value that is equal to the pixel width of this Window objects parent
3640        */
3641        float   getParentWidth(void) const;
3642
3643
3644        /*!
3645        \brief
3646                Return the pixel Height of the parent element.  This always returns a valid number.
3647
3648        \return
3649                float value that is equal to the pixel height of this Window objects parent
3650        */
3651        float   getParentHeight(void) const;
3652
3653
3654        /*!
3655        \brief
3656                Return the pixel size of the parent element.  This always returns a valid object.
3657
3658        \return
3659                Size object that describes the pixel dimensions of this Window objects parent
3660        */
3661        Size    getParentSize(void) const;
3662
3663
3664        /*!
3665        \brief
3666                Return a Rect object that describes, in values relative to \a window, the absolute area described by \a rect.
3667
3668        \param window
3669                Pointer to a window object that is to be used as the base for the conversion.  If this is NULL then the size of the
3670                display, as returned by the renderer object, is used.
3671
3672        \param rect
3673                Rect object describing the area, in absolute values, that is to be returned as relative values.
3674
3675        \return
3676                Rect object that describes in values relative to \a window, the same area described as absolute values in \a rect.
3677        */
3678        Rect    absoluteToRelative_impl(const Window* window, const Rect& rect) const;
3679        Size    absoluteToRelative_impl(const Window* window, const Size& sz) const;
3680        Point   absoluteToRelative_impl(const Window* window, const Point& pt) const;
3681        float   absoluteToRelativeX_impl(const Window* window, float x) const;
3682        float   absoluteToRelativeY_impl(const Window* window, float y) const;
3683
3684
3685        /*!
3686        \brief
3687                Return a Rect object that describes, in absolute values offset from \a window, the relative area described by \a rect.
3688
3689        \param window
3690                Pointer to a window object that is to be used as the base for the conversion.  If this is NULL then the size of the
3691                display, as returned by the renderer object, is used.
3692
3693        \param rect
3694                Rect object describing the area, in relative values, that is to be returned as absolute values.
3695
3696        \return
3697                Rect object that describes in absolute values offset from \a window, the same area described as relative values in \a rect.
3698        */
3699        Rect    relativeToAbsolute_impl(const Window* window, const Rect& rect) const;
3700        Size    relativeToAbsolute_impl(const Window* window, const Size& sz) const;
3701        Point   relativeToAbsolute_impl(const Window* window, const Point& pt) const;
3702        float   relativeToAbsoluteX_impl(const Window* window, float x) const;
3703        float   relativeToAbsoluteY_impl(const Window* window, float y) const;
3704
3705        Size    getWindowSize_impl(const Window* window) const;
3706
3707
3708        /*!
3709        \brief
3710                Return the inherited metrics mode.  This is either the metrics mode of our parent, or Relative
3711                if we have no parent.
3712        */
3713        MetricsMode getInheritedMetricsMode(void) const;
3714
3715
3716    /*!
3717    \brief
3718        Fires off a repeated mouse button down event for this window.
3719    */
3720    void    generateAutoRepeatEvent(MouseButton button);
3721
3722
3723        /*************************************************************************
3724                Implementation Data
3725        *************************************************************************/
3726        // child stuff
3727        typedef std::vector<Window*>    ChildList;
3728        ChildList               d_children;                     //!< The list of child Window objects attached to this.
3729    ChildList       d_drawList;         //!< Child window objects arranged in rendering order.
3730
3731        // general data
3732        MetricsMode             d_metricsMode;          //!< Holds the active metrics mode for this window
3733        static Window*  d_captureWindow;        //!< Window that has captured inputs
3734        Window*                 d_oldCapture;           //!< The Window that previously had capture (used for restoreOldCapture mode)
3735        Window*                 d_parent;                       //!< Holds pointer to the parent window.
3736        const Font*             d_font;                         //!< Holds pointer to the Window objects current Font.
3737        String                  d_text;                         //!< Holds the text / label / caption for this Window.
3738        uint                    d_ID;                           //!< User ID assigned to this Window
3739        float                   d_alpha;                        //!< Alpha transparency setting for the Window
3740    URect                       d_area;             //!< This Window objects area as defined by a URect.
3741    Size            d_pixelSize;        //!< Current constrained pixel size of the window.
3742        const Image*    d_mouseCursor;          //!< Holds pointer to the Window objects current mouse cursor image.
3743        void*                   d_userData;                     //!< Holds pointer to some user assigned data.
3744
3745        typedef std::map<String, String>   UserStringMap;
3746        UserStringMap  d_userStrings;      //!< Holds a collection of named user string values.
3747
3748    // positional alignments
3749    HorizontalAlignment d_horzAlign;    //!< Specifies the base for horizontal alignment.
3750    VerticalAlignment   d_vertAlign;    //!< Specifies the base for vertical alignment.
3751
3752        // maximum and minimum sizes
3753        UVector2       d_minSize;          //!< current minimum size for the window.
3754        UVector2       d_maxSize;          //!< current maximum size for the window.
3755
3756        // settings
3757        bool    d_enabled;                                      //!< true when Window is enabled
3758        bool    d_visible;                                      //!< true when Window is visible (that is it will be rendered, but may be obscured so no necesarily really visible)
3759        bool    d_active;                                       //!< true when Window is the active Window (receiving inputs).
3760        bool    d_clippedByParent;                      //!< true when Window will be clipped by parent Window area Rect.
3761        bool    d_destroyedByParent;            //!< true when Window will be auto-destroyed by parent.
3762        bool    d_alwaysOnTop;                          //!< true if Window will be drawn on top of all other Windows
3763        bool    d_inheritsAlpha;                        //!< true if the Window inherits alpha from the parent Window
3764        bool    d_restoreOldCapture;            //!< true if the Window restores capture to the previous window when it releases capture.
3765        bool    d_zOrderingEnabled;                     //!< true if the Window responds to z-order change requests.
3766    bool    d_wantsMultiClicks;         //!< true if the Window wishes to hear about multi-click mouse events.
3767    bool    d_distCapturedInputs;       //!< true if unhandled captured inputs should be distributed to child windows.
3768    bool    d_riseOnClick;              //!< True if the window should come to the front of the z order in respose to a left mouse button down event.
3769
3770    // mouse button autorepeat data
3771    bool    d_autoRepeat;       //!< true if button will auto-repeat mouse button down events while mouse button is held down,
3772    float   d_repeatDelay;      //!< seconds before first repeat event is fired
3773    float   d_repeatRate;       //!< secons between further repeats after delay has expired.
3774    bool    d_repeating;        //!< implements repeating - is true after delay has elapsed,
3775    float   d_repeatElapsed;    //!< implements repeating - tracks time elapsed.
3776    MouseButton d_repeatButton; //!< Button we're tracking (implication of this is that we only support one button at a time).
3777
3778    // Tooltip stuff
3779    String   d_tooltipText;     //!< Text string used as tip for this window.
3780    Tooltip* d_customTip;       //!< Possible custom Tooltip for this window.
3781    bool     d_weOwnTip;        //!< true if this Window created the custom Tooltip.
3782    bool     d_inheritsTipText; //!< true if the Window inherits tooltip text from its parent (when none set for itself).
3783
3784    // rendering
3785    RenderCache d_renderCache;  //!< Object which acts as a cache for Images to be drawn by this Window.
3786    mutable bool d_needsRedraw;      //!< true if window image cache needs to be regenerated.
3787
3788    // Look'N'Feel stuff
3789    String  d_lookName;         //!< Name of the Look assigned to this window (if any).
3790
3791    // Event pass through
3792    bool    d_mousePassThroughEnabled;  //!< true if this window can never be "hit" by the cursor. false for normal mouse event handling.
3793
3794protected:
3795        /*************************************************************************
3796                Properties for Window base class
3797        *************************************************************************/
3798        static  WindowProperties::AbsoluteHeight        d_absHeightProperty;
3799        static  WindowProperties::AbsoluteMaxSize       d_absMaxSizeProperty;
3800        static  WindowProperties::AbsoluteMinSize       d_absMinSizeProperty;
3801        static  WindowProperties::AbsolutePosition      d_absPositionProperty;
3802        static  WindowProperties::AbsoluteRect          d_absRectProperty;
3803        static  WindowProperties::AbsoluteSize          d_absSizeProperty;
3804        static  WindowProperties::AbsoluteWidth         d_absWidthProperty;
3805        static  WindowProperties::AbsoluteXPosition     d_absXPosProperty;
3806        static  WindowProperties::AbsoluteYPosition     d_absYPosProperty;
3807        static  WindowProperties::Alpha                         d_alphaProperty;
3808        static  WindowProperties::AlwaysOnTop           d_alwaysOnTopProperty;
3809        static  WindowProperties::ClippedByParent       d_clippedByParentProperty;
3810        static  WindowProperties::DestroyedByParent     d_destroyedByParentProperty;
3811        static  WindowProperties::Disabled                      d_disabledProperty;
3812        static  WindowProperties::Font                          d_fontProperty;
3813        static  WindowProperties::Height                        d_heightProperty;
3814        static  WindowProperties::ID                            d_IDProperty;
3815        static  WindowProperties::InheritsAlpha         d_inheritsAlphaProperty;
3816        static  WindowProperties::MetricsMode           d_metricsModeProperty;
3817        static  WindowProperties::MouseCursorImage      d_mouseCursorProperty;
3818        static  WindowProperties::Position                      d_positionProperty;
3819        static  WindowProperties::Rect                          d_rectProperty;
3820        static  WindowProperties::RelativeHeight        d_relHeightProperty;
3821        static  WindowProperties::RelativeMaxSize       d_relMaxSizeProperty;
3822        static  WindowProperties::RelativeMinSize       d_relMinSizeProperty;
3823        static  WindowProperties::RelativePosition      d_relPositionProperty;
3824        static  WindowProperties::RelativeRect          d_relRectProperty;
3825        static  WindowProperties::RelativeSize          d_relSizeProperty;
3826        static  WindowProperties::RelativeWidth         d_relWidthProperty;
3827        static  WindowProperties::RelativeXPosition     d_relXPosProperty;
3828        static  WindowProperties::RelativeYPosition     d_relYPosProperty;
3829        static  WindowProperties::RestoreOldCapture     d_restoreOldCaptureProperty;
3830        static  WindowProperties::Size                          d_sizeProperty;
3831        static  WindowProperties::Text                          d_textProperty;
3832        static  WindowProperties::Visible                       d_visibleProperty;
3833        static  WindowProperties::Width                         d_widthProperty;
3834        static  WindowProperties::XPosition                     d_xPosProperty;
3835        static  WindowProperties::YPosition                     d_yPosProperty;
3836        static  WindowProperties::ZOrderChangeEnabled   d_zOrderChangeProperty;
3837    static  WindowProperties::WantsMultiClickEvents d_wantsMultiClicksProperty;
3838    static  WindowProperties::MouseButtonDownAutoRepeat d_autoRepeatProperty;
3839    static  WindowProperties::AutoRepeatDelay   d_autoRepeatDelayProperty;
3840    static  WindowProperties::AutoRepeatRate    d_autoRepeatRateProperty;
3841    static  WindowProperties::DistributeCapturedInputs d_distInputsProperty;
3842    static  WindowProperties::CustomTooltipType d_tooltipTypeProperty;
3843    static  WindowProperties::Tooltip           d_tooltipProperty;
3844    static  WindowProperties::InheritsTooltipText d_inheritsTooltipProperty;
3845    static  WindowProperties::RiseOnClick       d_riseOnClickProperty;
3846    static  WindowProperties::VerticalAlignment   d_vertAlignProperty;
3847    static  WindowProperties::HorizontalAlignment d_horzAlignProperty;
3848    static      WindowProperties::UnifiedAreaRect       d_unifiedAreaRectProperty;
3849    static      WindowProperties::UnifiedPosition       d_unifiedPositionProperty;
3850    static      WindowProperties::UnifiedXPosition      d_unifiedXPositionProperty;
3851    static      WindowProperties::UnifiedYPosition      d_unifiedYPositionProperty;
3852    static      WindowProperties::UnifiedSize           d_unifiedSizeProperty;
3853    static      WindowProperties::UnifiedWidth          d_unifiedWidthProperty;
3854    static      WindowProperties::UnifiedHeight         d_unifiedHeightProperty;
3855    static      WindowProperties::UnifiedMinSize        d_unifiedMinSizeProperty;
3856    static      WindowProperties::UnifiedMaxSize        d_unifiedMaxSizeProperty;
3857    static  WindowProperties::MousePassThroughEnabled   d_mousePassThroughEnabledProperty;
3858
3859
3860        /*************************************************************************
3861                implementation functions
3862        *************************************************************************/
3863        /*!
3864        \brief
3865                Add standard CEGUI::Window events
3866        */
3867        void    addStandardEvents(void);
3868
3869        /*!
3870        \brief
3871                Cleanup child windows
3872        */
3873        virtual void    cleanupChildren(void);
3874
3875        /*!
3876        \brief
3877                Add given window to child list at an appropriate position
3878        */
3879        virtual void    addChild_impl(Window* wnd);
3880
3881        /*!
3882        \brief
3883                Remove given window from child list
3884        */
3885        virtual void    removeChild_impl(Window* wnd);
3886
3887        /*!
3888        \brief
3889                Notify 'this' and all siblings of a ZOrder change event
3890        */
3891        virtual void    onZChange_impl(void);
3892
3893
3894        /*!
3895        \brief
3896                Add standard CEGUI::Window properties.
3897        */
3898        void    addStandardProperties(void);
3899
3900
3901    /*!
3902    \brief
3903        Implements move to fron behavior.
3904     */
3905    virtual void moveToFront_impl(bool wasClicked);
3906
3907
3908    /*!
3909    \brief
3910        Implementation of rise on click functionality.
3911     */
3912    void doRiseOnClick(void);
3913
3914
3915    /*!
3916    \brief
3917        Implementation method to modify window area while correctly applying min / max size processing, and
3918        firing any appropriate events.
3919
3920    /note
3921        This is the implementation function for setting size and position.
3922        In order to simplify area management, from this point on, all modifications to window size and
3923        position (area rect) should come through here.
3924
3925    /param pos
3926        UVector2 object describing the new area position.
3927
3928    /param size
3929        UVector2 object describing the new area size.
3930
3931    /param topLeftSizing
3932        - true to indicate the the operation is a sizing operation on the top and/or left edges of the area,
3933            and so window movement should be inhibited if size is at max or min.
3934        - false to indicate the operation is not a strict sizing operation on the top and/or left edges and
3935            that the window position may change as required
3936
3937    /param fireEvents
3938        - true if events should be fired as normal.
3939        - false to inhibit firing of events (required, for example, if you need to call this from
3940            the onSize/onMove handlers).
3941     */
3942    void setWindowArea_impl(const UVector2& pos, const UVector2& size, bool topLeftSizing = false, bool fireEvents = true);
3943
3944    /*!
3945    \brief
3946        Add the given window to the drawing list at an appropriate position for it's settings and the
3947        required direction.  Basically, when \a at_back is false, the window will appear in front of
3948        all other windows with the same 'always on top' setting.  When \a at_back is true, the window
3949        will appear behind all other windows wih the same 'always on top' setting.
3950
3951    \param wnd
3952        Window object to be added to the drawing list.
3953
3954    \param at_back
3955        Indicates whether the window should be placed at the back of other windows in the same group.
3956        If this is false, the window is place in front of other windows in the group.
3957
3958    \return
3959        Nothing.
3960    */
3961    void addWindowToDrawList(Window& wnd, bool at_back = false);
3962
3963    /*!
3964    \brief
3965        Removes the window from the drawing list.  If the window is not attached to the drawing list
3966        then nothing happens.
3967
3968    \param wnd
3969        Window object to be removed from the drawing list.
3970
3971    \return
3972        Nothing.
3973    */
3974    void removeWindowFromDrawList(const Window& wnd);
3975
3976    virtual int writePropertiesXML(OutStream& out_stream) const;
3977    virtual int writeChildWindowsXML(OutStream& out_stream) const;
3978
3979        /*************************************************************************
3980                May not copy or assign Window objects
3981        *************************************************************************/
3982        Window(const Window& wnd) : PropertySet(), EventSet() {}
3983        Window& operator=(const Window& wnd) {return *this;}
3984
3985        /*************************************************************************
3986                Private implementation Data
3987        *************************************************************************/
3988        const String    d_type;                 //!< String holding the type name for the Window (is also the name of the WindowFactory that created us)
3989        String  d_name;                                 //!< The name of the window (GUI system unique).
3990        String    d_falagardType;       //!< Type name of the window as defined in a Falagard mapping.
3991};
3992
3993} // End of  CEGUI namespace section
3994
3995
3996#if defined(_MSC_VER)
3997#       pragma warning(pop)
3998#endif
3999
4000#endif  // end of guard _CEGUIWindow_h_
Note: See TracBrowser for help on using the repository browser.