source: OGRE/trunk/ogrenew/Dependencies/include/CEGUI/CEGUIWindow.h @ 657

Revision 657, 92.0 KB checked in by mattausch, 19 years ago (diff)

added ogre dependencies and patched ogre sources

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 <vector>
40
41
42#if defined(_MSC_VER)
43#       pragma warning(push)
44#       pragma warning(disable : 4251)
45#endif
46
47
48// Start of CEGUI namespace section
49namespace CEGUI
50{
51
52/*!
53\brief
54        Mode used for Window size and position metrics.
55
56        Position information for a Window is always 'relative' to it's parent even in Absolute mode.
57        In Relative mode, layout is maintained for different screen resolutions, and also  offers the
58        ability for child windows to properly adjust their layout as their parent is sized.
59*/
60enum MetricsMode
61{
62        Relative,               //!< Metrics are specified as a decimal fraction of parent Window size.
63        Absolute,               //!< Metrics are specified as whole pixels.
64        Inherited               //!< Metrics are inherited from parent.
65};
66
67
68/*!
69\brief
70        An abstract base class providing common functionality and specifying the required interface for derived classes.
71
72        The Window base class is the only UI object class that the core of the system knows about, for this reason every
73        other window, widget, or similar item within the system must be derived from Window.  The base class provides the
74        common functionality required by all UI objects, and specifies the minimal interface required to be implemented by
75        derived classes.
76*/
77class CEGUIEXPORT Window : public PropertySet, public EventSet
78{
79public:
80        static const String EventNamespace;                             //!< Namespace for global events
81
82        /*************************************************************************
83                Event name constants
84        *************************************************************************/
85        // generated internally by Window
86        static const String EventParentSized;                           //!< Parent of this Window has been re-sized.
87        static const String EventSized;                                 //!< Window size has changed
88        static const String EventMoved;                                 //!< Window position has changed
89        static const String EventTextChanged;                           //!< Text string for the Window has changed
90        static const String EventFontChanged;                           //!< Font object for the Window has been changed
91        static const String EventAlphaChanged;                  //!< Alpha blend value for the Window has changed
92        static const String EventIDChanged;                             //!< Client assigned ID code for the Window has changed
93        static const String EventActivated;                             //!< Window has been activated (has input focus)
94        static const String EventDeactivated;                           //!< Window has been deactivated (loses input focus)
95        static const String EventShown;                                 //!< Window has been made visible
96        static const String EventHidden;                                        //!< Window has been hidden from view
97        static const String EventEnabled;                                       //!< Window has been enabled (interaction is possible)
98        static const String EventDisabled;                              //!< Window has been disabled (interaction is no longer possible)
99        static const String EventMetricsModeChanged;            //!< Active metrics mode has been modified
100        static const String EventClippedByParentChanged;        //!< Clipping by parent mode has been modified
101        static const String EventDestroyedByParentChanged;//!< Destruction by parent mode has been modified
102        static const String EventInheritsAlphaChanged;  //!< Alpha inherited from parent mode has been modified.
103        static const String EventAlwaysOnTopChanged;            //!< Always on top mode has been modified
104        static const String EventInputCaptureGained;            //!< Window has captured all inputs
105        static const String EventInputCaptureLost;              //!< Window has lost it's capture on inputs
106        static const String EventRenderingStarted;              //!< Rendering of the Window has started
107        static const String EventRenderingEnded;                        //!< Rendering for the Window has finished
108        static const String EventChildAdded;                            //!< A child Window has been added
109        static const String EventChildRemoved;                  //!< A child window has been removed
110        static const String EventDestructionStarted;            //!< Destruction of the Window is about to begin.
111        static const String EventZOrderChanged;                 //!< The z-order of the window has changed
112        static const String EventDragDropItemEnters;    //!< A DragContainer has been dragged over this window.
113        static const String EventDragDropItemLeaves;    //!< A DragContainer has left this window.
114        static const String EventDragDropItemDropped;   //!< A DragContainer was dropped on this Window.
115
116        // generated externally (inputs)
117        static const String EventMouseEnters;                           //!< Mouse cursor has entered the Window.
118        static const String EventMouseLeaves;                           //!< Mouse cursor has left the Window.
119        static const String EventMouseMove;                             //!< Mouse cursor was moved within the area of the Window.
120        static const String EventMouseWheel;                            //!< Mouse wheel was scrolled within the Window.
121        static const String EventMouseButtonDown;                       //!< A mouse button was pressed down within the Window.
122        static const String EventMouseButtonUp;                 //!< A mouse button was released within the Window.
123        static const String EventMouseClick;                            //!< A mouse button was clicked (down then up) within the Window.
124        static const String EventMouseDoubleClick;              //!< A mouse button was double-clicked within the Window.
125        static const String EventMouseTripleClick;              //!< A mouse button was triple-clicked within the Window.
126        static const String EventKeyDown;                                       //!< A key on the keyboard was pressed.
127        static const String EventKeyUp;                                 //!< A key on the keyboard was released.
128        static const String EventCharacterKey;                  //!< A text character was typed on the keyboard.
129
130
131        /*************************************************************************
132                Construction and Destruction
133        *************************************************************************/
134        /*!
135        \brief
136                Constructor for Window base class
137
138        \param type
139                String object holding Window type (usually provided by WindowFactory).
140
141        \param name
142                String object holding unique name for the Window.
143        */
144        Window(const String& type, const String& name);
145
146
147        /*!
148        \brief
149                Destructor for Window base class
150        */
151        virtual ~Window(void);
152
153
154        /*************************************************************************
155                Accessor functions
156        *************************************************************************/
157        /*!
158        \brief
159                return a String object holding the type name for this Window.
160
161        \return
162                String object holding the Window type.
163        */
164        const String& getType(void) const               {return d_type;}
165
166
167        /*!
168        \brief
169                return a String object holding the name of this Window.
170
171        \return
172                String object holding the unique Window name.
173        */
174        const String& getName(void) const               {return d_name;}
175
176
177        /*!
178        \brief
179                returns whether or not this Window is set to be destroyed when its parent is destroyed.
180
181        \return
182                true if the Window will be destroyed when its parent is destroyed, false if it will remain.
183        */
184        bool    isDestroyedByParent(void) const         {return d_destroyedByParent;}
185
186
187        /*!
188        \brief
189                returns whether or not this Window is an always on top (a.k.a 'topmost') Window.
190
191        \return
192                true if this Window is always show on top of other normal windows.  false if the Window has normal z-order behaviour.
193        */
194        bool    isAlwaysOnTop(void) const                       {return d_alwaysOnTop;}
195
196
197        /*!
198        \brief
199                return true if the Window is currently disabled
200
201        \return
202                true if the window is disabled, false if the window is enabled.
203        */
204        bool    isDisabled(void) const;
205
206
207        /*!
208        \brief
209                return true if the Window is currently visible.
210
211                A true return from this function does not mean that the window is not completely obscured by other windows, just that the window
212                is processed when rendering and is not hidden.
213
214        \return
215                true if the window is drawn, false if the window is hidden and therefore ignored when rendering.
216        */
217        bool    isVisible(void) const;
218
219
220        /*!
221        \brief
222                return true if this is the active Window (the window that receives inputs)
223
224                Mouse events are always sent to the window containing the mouse cursor regardless of what this reports (unless the window has captured
225                inputs).  This mainly refers to where other (keyboard) inputs are sent.
226
227        \return
228                true if this window has input focus, or false if it does not.
229        */
230        bool    isActive(void) const;
231
232
233        /*!
234        \brief
235                return true if this Window is clipped so that its rendering does not pass outside its parent windows area.
236
237        \return
238                true if the window will be clipped by its parent window, or false if this windows rendering may pass outside its parents area
239        */
240        bool    isClippedByParent(void) const           {return d_clippedByParent;}
241
242
243        /*!
244        \brief
245                return the ID code currently assigned to this Window by client code.
246
247        \return
248                uint value equal to the currently assigned ID code for this Window.
249        */
250        uint    getID(void) const               {return d_ID;}
251
252
253        /*!
254        \brief
255                return the number of child Window objects currently attached to this Window.
256
257        \return
258                uint value equal to the number of Window objects directly attached to this Window as children.
259        */
260        uint   getChildCount(void) const      {return (uint)d_children.size();}
261
262
263        /*!
264        \brief
265                returns whether a Window with the specified name is currently attached to this Window as a child.
266
267        \param name
268                String object containing the name of the Window to look for.
269
270        \return
271                true if a Window named \a name is currently attached to this Window as a child, else false.
272        */
273        bool    isChild(const String& name) const;
274
275
276        /*!
277        \brief
278                returns whether at least one window with the given ID code is attached as a child.
279
280        \note
281                ID codes are client assigned and may or may not be unique, and as such, the return from this function
282                will only have meaning to the client code.
283
284        \param ID
285                uint ID code to look for.
286
287        \return
288                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.
289        */
290        bool    isChild(uint ID) const;
291
292
293        /*!
294        \brief
295                return true if the given Window is a child of this window.
296
297        \param window
298                Pointer to the Window object to look for.
299
300        \return
301                true if Window object \a window is attached to this window as a child.
302        */
303        bool    isChild(const Window* window) const;
304
305
306        /*!
307        \brief
308                return a pointer to the child window with the specified name.
309
310                This function will throw an exception if no child object with the given name is attached.  This decision
311                was made (over returning NULL if no window was found) so that client code can assume that if the call
312                returns it has a valid window pointer.  We provide the isChild() functions for checking if a given window
313                is attached.
314
315        \param name
316                String object holding the name of the child window to return a pointer to.
317
318        \return
319                Pointer to the Window object attached to this window that has the name \a name.
320
321        \exception UnknownObjectException       thrown if no window named \a name is attached to this Window.
322        */
323        Window* getChild(const String& name) const;
324
325
326        /*!
327        \brief
328                return a pointer to the first attached child window with the specified ID.
329
330                This function will throw an exception if no child object with the given ID is attached.  This decision
331                was made (over returning NULL if no window was found) so that client code can assume that if the call
332                returns it has a valid window pointer.  We provide the isChild() functions for checking if a given window
333                is attached.
334
335        \param ID
336                uint value specifying the ID code of the window to return a pointer to.
337
338        \return
339                Pointer to the (first) Window object attached to this window that has the ID code \a ID.
340
341        \exception UnknownObjectException       thrown if no window with the ID code \a ID is attached to this Window.
342        */
343        Window* getChild(uint ID) const;
344
345
346        /*!
347        \brief
348                return a pointer to the child window that is attached to 'this' at the given index.
349
350        \note
351                Window indeces are of limited value to client code, since any time a window is added, removed, or
352                it's z-order is changed the indeces all change.
353
354        \param idx
355                Index of the child window whos pointer should be returned.  This value is not bounds checked,
356                client code should ensure that this is less than the value returned by getChildCount().
357
358        \return
359                Pointer to the child window currently attached at index position \a idx
360        */
361        Window* getChildAtIdx(uint idx) const           {return d_children[idx];}
362
363
364        /*!
365        \brief
366                return a pointer to the Window that currently has input focus starting with this Window.
367
368        \return
369                Pointer to the window that is active (has input focus) starting at 'this.  Will return 'this' if this Window is active
370                and either no children are attached or if none of the attached children are active.  Returns NULL if this Window (and
371                therefore all children) are not active.
372        */
373        Window* getActiveChild(void);
374        const Window* getActiveChild(void) const;
375
376
377        /*!
378        \brief
379                return true if the specified Window is some ancestor of this Window
380
381        \param name
382                String object holding the name of the Window to check for.
383
384        \return
385                true if a Window named \a name is an ancestor (parent, or parent of parent, etc) of this Window, or false if not.
386        */
387        bool    isAncestor(const String& name) const;
388
389
390        /*!
391        \brief
392                return true if any Window with the given ID is some ancestor of this Window.
393
394        \param ID
395                uint value specifying the ID to look for.
396
397        \return
398                true if an ancestor (parent, or parent of parent, etc) was found with the ID code \a ID, else false.
399        */
400        bool    isAncestor(uint ID) const;
401
402
403        /*!
404        \brief
405                return true if the specified Window is some ancestor of this Window.
406
407        \param window
408                Pointer to the Window object to look for.
409
410        \return
411                true if \a window was found to be an ancestor (parent, or parent of parent, etc) of this Window, otherwise false.
412        */
413        bool    isAncestor(const Window* window) const;
414
415
416        /*!
417        \brief
418                return the Font object active for the Window.
419
420        \return
421                Pointer to the Font being used by this Window.  If the window has no assigned font, the default font is returned.
422        */
423        const Font*             getFont(void) const;
424
425
426        /*!
427        \brief
428                return the current text for the Window
429
430        \return
431                A String object that holds the current text for this Window.
432        */
433        const String&   getText(void) const             {return d_text;}
434
435
436        /*!
437        \brief
438                return true if the Window inherits alpha from its parent(s).
439
440        \return
441                true if the Window inherits alpha from its parent(s), false if the alpha for this Window is independant.
442        */
443        bool    inheritsAlpha(void) const               {return d_inheritsAlpha;}
444
445
446        /*!
447        \brief
448                return the current alpha value set for this Window
449
450        \note
451                The alpha value set for any given window may or may not be the final alpha value that is used when rendering.  All window
452                objects, by default, inherit alpha from thier parent window(s) - this will blend child windows, relatively, down the line of
453                inheritance.  This behaviour can be overridden via the setInheritsAlpha() method.  To return the true alpha value that will be
454                applied when rendering, use the getEffectiveAlpha() method.
455
456        \return
457                the currently set alpha value for this Window.  Will be between 0.0f and 1.0f.
458        */
459        float   getAlpha(void) const                    {return d_alpha;}
460
461
462        /*!
463        \brief
464                return the effective alpha value that will be used when rendering this window, taking into account inheritance of parent
465                window(s) alpha.
466
467        \return
468                the effective alpha that will be applied to this Window when rendering.  Will be between 0.0f and 1.0f.
469        */
470        float   getEffectiveAlpha(void) const;
471
472
473        /*!
474        \brief
475                return a Rect object that describes the Window area.
476
477        \return
478                Rect object that describes the area covered by the Window.  The values in the returned Rect are in whatever form is set
479                as the current metric type.  The returned Rect is unclipped and relative to the Window objects parent.
480        */
481        Rect    getRect(void) const;
482
483
484        /*!
485        \brief
486                return a Rect object describing the Window area in screen space.
487
488        \return
489                Rect object that describes the area covered by the Window.  The values in the returned Rect are in screen pixels.  The
490                returned Rect is clipped as appropriate and depending upon the 'ClippedByParent' setting.
491
492        \note
493                This has now been made virtual to ease some customisations that require more specialised clipping requirements.
494        */
495        virtual Rect    getPixelRect(void) const;
496
497
498        /*!
499        \brief
500                return a Rect object describing the clipped inner area for this window.
501
502        \return
503                Rect object that describes, in appropriately clipped screen pixel co-ordinates, the window object's inner rect area.
504        */
505        Rect    getInnerRect(void) const;
506
507
508        /*!
509        \brief
510                return a Rect object describing the Window area unclipped, in screen space.
511
512        \return
513                Rect object that describes the area covered by the Window.  The values in the returned Rect are in screen pixels.  The
514                returned rect is fully unclipped.
515        */
516        Rect    getUnclippedPixelRect(void) const;
517
518
519        /*!
520        \brief
521                Return a Rect object that describes, unclipped, the inner rectangle for this window.  The inner rectangle is
522                typically an area that excludes some frame or other rendering that should not be touched by subsequent rendering.
523
524        \return
525                Rect object that describes, in unclipped screen pixel co-ordinates, the window object's inner rect area.
526        */
527        virtual Rect    getUnclippedInnerRect(void) const;
528
529
530        /*!
531        \brief
532                return the Window that currently has inputs captured.
533
534        \return
535                Pointer to the Window object that currently has inputs captured, or NULL if no Window has captured input.
536        */
537        static  Window* getCaptureWindow(void)          {return d_captureWindow;}
538
539
540        /*!
541        \brief
542                return true if this Window has input captured.
543
544        \return
545                true if this Window has captured inputs, or false if some other Window, or no Window, has captured inputs.
546        */
547        bool    isCapturedByThis(void) const            {return getCaptureWindow() == this;}
548
549
550        /*!
551        \brief
552                return true if a child window has captured inputs.
553
554        \return
555                true if inputs are captured by a Window that is attached as a child of this Window, else false.
556        */
557        bool    isCapturedByAncestor(void) const        {return isAncestor(getCaptureWindow());}
558
559
560        /*!
561        \brief
562                return true if an ancestor window has captured inputs.
563
564        \return
565                true if inputs are captured by a Window that is some ancestor (parent, parent of parent, etc) of this Window, else false.
566        */
567        bool    isCapturedByChild(void) const           {return isChild(getCaptureWindow());}
568
569
570        /*!
571        \brief
572                check if the given position would hit this window.
573
574        \param position
575                Point object describing the position to check in screen pixels
576
577        \return
578                true if \a position 'hits' this Window, else false.
579        */
580        virtual bool    isHit(const Point& position) const;
581
582
583        /*!
584        \brief
585                return the child Window that is 'hit' by the given position
586
587        \param position
588                Point object that describes the position to check in screen pixels
589
590        \return
591                Pointer to the child Window that was hit according to the Point \a position, or NULL if no child window was hit.
592        */
593        Window* getChildAtPosition(const Point& position) const;
594
595
596        /*!
597        \brief
598                return the current metrics mode employed by the Window
599
600        \return
601                One of the values of the MectricsMode enumerated type, that describes the current metrics in use by the Window.
602        */
603        MetricsMode     getMetricsMode(void) const;
604
605
606        /*!
607        \brief
608                return the x position of the window.  Interpretation of return value depends upon the metric type in use by this window.
609
610        \return
611                float value that specifies the x position of the Window relative to it's parent, depending on the metrics system in use for this
612                Window, this value will specify either pixels or a decimal fraction of the width of the parent Window.
613        */
614        float   getXPosition(void) const;
615
616
617        /*!
618        \brief
619                return the y position of the window.  Interpretation of return value depends upon the metric type in use by this window.
620
621        \return
622                float value that specifies the y position of the Window relative to it's parent, depending on the metrics system in use for this
623                Window, this value will specify either pixels or a decimal fraction of the height of the parent Window.
624        */
625        float   getYPosition(void) const;
626
627
628        /*!
629        \brief
630                return the position of the window.  Interpretation of return value depends upon the metric type in use by this window.
631
632        \return
633                Point object that describes the position of the Window relative to it's parent, depending on the metrics system in use for this
634                Window, the values in the Point will specify either pixels or decimal fractions of the total width and height of the parent.
635        */
636        Point   getPosition(void) const;
637
638
639        /*!
640        \brief
641                return the width of the Window.  Interpretation of return value depends upon the metric type in use by this window.
642
643        \return
644                float value that specifies the width of the Window.  Depending upon the metrics system in use for this window, the return
645                value will either be in pixels, or as a decimal fraction of the width of the parent Window.
646        */
647        float   getWidth(void) const;
648
649        /*!
650        \brief
651                return the height of the Window.  Interpretation of return value depends upon the metric type in use by this window.
652
653        \return
654                float value that specifies the height of the Window.  Depending upon the metrics system in use for this window, the return
655                value will either be in pixels, or as a decimal fraction of the height of the parent Window.
656        */
657        float   getHeight(void) const;
658
659
660        /*!
661        \brief
662                return the size of the Window.  Interpretation of return value depends upon the metric type in use by this window.
663
664        \return
665                Size object that describes the dimensions of the Window.  Depending upon the metrics system in use for this window, the
666                values will either be in pixels, or as decimal fractions of the width and height of the parent Window.
667        */
668        Size    getSize(void) const;
669
670
671        /*!
672        \brief
673                return the parent of this Window.
674
675        \return
676                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
677                Sheet / Root.
678        */
679        Window* getParent(void) const                           {return d_parent;}
680
681
682        /*!
683        \brief
684                Return the current maximum size for this window.
685
686        \return
687                Size object describing the maximum size for this window.  If using absolute co-ordinates the returned object has it's values expressed
688                as screen pixels.  If using relative co-ordinates the returned object has it's values expressed as fractions of the current display size.
689        */
690        Size    getMaximumSize(void) const;
691
692
693        /*!
694        \brief
695                Return the current minimum size for this window.
696
697        \return
698                Size object describing the minimum size for this window.  If using absolute co-ordinates the returned object has it's values expressed
699                as screen pixels.  If using relative co-ordinates the returned object has it's values expressed as fractions of the current display size.
700        */
701        Size    getMinimumSize(void) const;
702
703
704        /*!
705        \brief
706                Return a pointer to the mouse cursor image to use when the mouse is within this window.
707
708        \return
709                Pointer to the mouse cursor image that will be used when the mouse enters this window.  May return NULL indicating no cursor.
710        */
711        const Image*    getMouseCursor(void) const;
712
713
714        /*!
715        \brief
716                Return the window area rect in relative metrics.
717
718        \return
719                Rect object describing this windows area, relative to the parent window, in parent relative metrics.
720        */
721        Rect    getRelativeRect(void) const                             {return d_rel_area;}
722
723
724        /*!
725        \brief
726                Return the window position in relative metrics.
727
728        \return
729                Point object describing this windows position, relative to the parent window, in parent relative metrics.
730        */
731        Point   getRelativePosition(void) const                 {return d_rel_area.getPosition();}
732
733
734        /*!
735        \brief
736                Return the window X position in relative metrics.
737
738        \return
739                float value describing this windows X position, relative to the parent window, in parent relative metrics.
740        */
741        float   getRelativeXPosition(void) const                {return d_rel_area.d_left;}
742
743
744        /*!
745        \brief
746                Return the window Y position in relative metrics.
747
748        \return
749                float value describing this windows Y position, relative to the parent window, in parent relative metrics.
750        */
751        float   getRelativeYPosition(void) const                {return d_rel_area.d_top;}
752
753
754        /*!
755        \brief
756                Return the window size in relative metrics.
757
758        \return
759                Size object describing this windows size in parent relative metrics.
760        */
761        Size    getRelativeSize(void) const                             {return d_rel_area.getSize();}
762
763
764        /*!
765        \brief
766                Return the window width in relative metrics.
767
768        \return
769                float value describing this windows width in parent relative metrics.
770        */
771        float   getRelativeWidth(void) const                    {return d_rel_area.getWidth();}
772
773
774        /*!
775        \brief
776                Return the window height in relative metrics.
777
778        \return
779                float value describing this windows height in parent relative metrics.
780        */
781        float   getRelativeHeight(void) const                   {return d_rel_area.getHeight();}
782
783
784        /*!
785        \brief
786                Return the window area rect in absolute metrics.
787
788        \return
789                Rect object describing this windows area, relative to the parent window, in absolute metrics
790        */
791        Rect    getAbsoluteRect(void) const                             {return d_abs_area;}
792
793
794        /*!
795        \brief
796                Return the window position in absolute metrics.
797
798        \return
799                Point object describing this windows position, relative to the parent window, in absolute metrics.
800        */
801        Point   getAbsolutePosition(void) const                 {return d_abs_area.getPosition();}
802
803
804        /*!
805        \brief
806                Return the window X position in absolute metrics.
807
808        \return
809                float value describing this windows X position, relative to the parent window, in absolute metrics.
810        */
811        float   getAbsoluteXPosition(void) const                {return d_abs_area.d_left;}
812
813
814        /*!
815        \brief
816                Return the window Y position in absolute metrics.
817
818        \return
819                float value describing this windows Y position, relative to the parent window, in absolute metrics.
820        */
821        float   getAbsoluteYPosition(void) const                {return d_abs_area.d_top;}
822
823
824        /*!
825        \brief
826                Return the window size in absolute metrics.
827
828        \return
829                Size object describing this windows size in absolute metrics.
830        */
831        Size    getAbsoluteSize(void) const                             {return d_abs_area.getSize();}
832
833
834        /*!
835        \brief
836                Return the window width in absolute metrics.
837
838        \return
839                float value describing this windows width in absolute metrics.
840        */
841        float   getAbsoluteWidth(void) const                    {return d_abs_area.getWidth();}
842
843
844        /*!
845        \brief
846                Return the window height in absolute metrics.
847
848        \return
849        float value describing this windows height in absolute metrics.
850        */
851        float   getAbsoluteHeight(void) const                   {return d_abs_area.getHeight();}
852
853
854        /*!
855        \brief
856                Return the user data set for this Window.
857
858                Each Window can have some client assigned data attached to it, this data is not used by the GUI system
859                in any way.  Interpretation of the data is entirely application specific.
860
861        \return
862                pointer to the user data that is currently set for this window.
863        */
864        void*   getUserData(void) const                 {return d_userData;}
865
866
867        /*!
868        \brief
869                return the x position of the window using the specified metrics system.
870
871        \param mode
872                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
873
874        \return
875                float value that specifies the x position of the Window relative to it's parent, using the specified MetricsMode.
876        */
877        float   getXPosition(MetricsMode mode) const;
878
879
880        /*!
881        \brief
882                return the y position of the window using the specified metrics system.
883
884        \param mode
885                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
886
887        \return
888                float value that specifies the y position of the Window relative to it's parent,  using the specified MetricsMode.
889        */
890        float   getYPosition(MetricsMode mode) const;
891
892
893        /*!
894        \brief
895                return the position of the window using the specified metrics system.
896
897        \param mode
898                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
899
900        \return
901                Point object that describes the position of the Window relative to it's parent, using the specified MetricsMode.
902        */
903        Point   getPosition(MetricsMode mode) const;
904
905
906        /*!
907        \brief
908                return the width of the Window using the specified metrics system.
909
910        \param mode
911                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
912
913        \return
914                float value that specifies the width of the Window using the specified MetricsMode.
915        */
916        float   getWidth(MetricsMode mode) const;
917
918
919        /*!
920        \brief
921                return the height of the Window using the specified metrics system.
922
923        \param mode
924                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
925
926        \return
927                float value that specifies the height of the Window using the specified MetricsMode.
928        */
929        float   getHeight(MetricsMode mode) const;
930
931
932        /*!
933        \brief
934                return the size of the Window using the specified metrics system.
935
936        \param mode
937                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
938
939        \return
940                Size object that describes the dimensions of the Window using the specified MetricsMode.
941        */
942        Size    getSize(MetricsMode mode) const;
943
944
945        /*!
946        \brief
947                return a Rect object that describes the Window area using the specified metrics system.
948
949        \param mode
950                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
951
952        \return
953                Rect object that describes the area covered by the Window using the specified MetricsMode.
954        */
955        Rect    getRect(MetricsMode mode) const;
956
957
958        /*!
959        \brief
960                Return whether this window is set to restore old input capture when it loses input capture.
961
962                This is only really useful for certain sub-components for widget writers.
963
964        \return
965                - true if the window will restore the previous capture window when it loses input capture.
966                - false if the window will set the capture window to NULL when it loses input capture (this is the default behaviour).
967        */
968        bool    restoresOldCapture(void) const          {return d_restoreOldCapture;}
969
970
971        /*!
972        \brief
973                Return whether z-order changes are enabled or disabled for this Window.
974
975        \return
976                - true if z-order changes are enabled for this window.  moveToFront/moveToBack work normally as expected.
977                - false: z-order changes are disabled for this window.  moveToFront/moveToBack are ignored for this window.
978        */
979        bool    isZOrderingEnabled(void) const;
980
981
982    /*!
983    \brief
984        Return whether this window will receive multi-click events or multiple 'down' events instead.
985
986    \return
987        - true if the Window will receive double-click and triple-click events.
988        - false if the Window will receive multiple mouse button down events instead of double/triple click events.
989    */
990    bool    wantsMultiClickEvents(void) const;
991
992
993    /*!
994    \brief
995        Return whether mouse button down event autorepeat is enabled for this window.
996
997    \return
998        - true if autorepeat of mouse button down events is enabled for this window.
999        - false if autorepeat of mouse button down events is not enabled for this window.
1000    */
1001    bool    isMouseAutoRepeatEnabled(void) const;
1002
1003
1004    /*!
1005    \brief
1006        Return the current auto-repeat delay setting for this window.
1007
1008    \return
1009        float value indicating the delay, in seconds, defore the first repeat mouse button down event will be triggered when autorepeat is enabled.
1010    */
1011    float   getAutoRepeatDelay(void) const;
1012
1013   
1014    /*!
1015    \brief
1016        Return the current auto-repeat rate setting for this window.
1017
1018    \return
1019        float value indicating the rate, in seconds, at which repeat mouse button down events will be generated after the initial delay has expired.
1020    */
1021    float   getAutoRepeatRate(void) const;
1022
1023
1024    /*!
1025    \brief
1026        Return whether the window wants inputs passed to its attached
1027        child windows when the window has inputs captured.
1028
1029    \return
1030        - true if System should pass captured input events to child windows.
1031        - false if System should pass captured input events to this window only.
1032    */
1033    bool    distributesCapturedInputs(void) const;
1034
1035
1036    /*!
1037    \brief
1038        Return whether this Window is using the system default Tooltip for its Tooltip window.
1039
1040    \return
1041        - true if the Window will use the system default tooltip.
1042        - false if the window has a custom Tooltip object.
1043    */
1044    bool isUsingDefaultTooltip(void) const;
1045
1046    /*!
1047    \brief
1048        Return a pointer to the Tooltip object used by this Window.  The value returned may
1049        point to the system default Tooltip, a custom Window specific Tooltip, or be NULL.
1050
1051    \return
1052        Pointer to a Tooltip based object, or NULL.
1053    */
1054    Tooltip* getTooltip(void) const;
1055
1056    /*!
1057    \brief
1058        Return the custom tooltip type.
1059
1060    \return
1061        String object holding the current custom tooltip window type, or an empty string if no custom tooltip is set.
1062     */
1063    String getTooltipType(void) const;
1064
1065    /*!
1066    \brief
1067        Return the current tooltip text set for this Window.
1068
1069    \return
1070        String object holding the current tooltip text set for this window.
1071     */
1072    const String& getTooltipText(void) const;
1073
1074    /*!
1075    \brief
1076        Return whether this window inherits Tooltip text from its parent when its own tooltip text is not set.
1077
1078    \return
1079        - true if the window inherits tooltip text from its parent when its own text is not set.
1080        - false if the window does not inherit tooltip text from its parent (and shows no tooltip when no text is set).
1081     */
1082    bool inheritsTooltipText(void) const;
1083
1084    /*!
1085    \brief
1086        Return whether this window will rise to the top of the z-order when clicked with the left mouse button.
1087
1088    \return
1089        - true if the window will come to the top of other windows when the left mouse button is pushed within its area.
1090        - false if the window does not change z-order position when the left mouse button is pushed within its area.
1091     */
1092    bool isRiseOnClickEnabled(void) const   { return d_riseOnClick; }
1093
1094        /*!
1095        \brief
1096                Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
1097
1098        \param class_name
1099                The class name that is to be checked.
1100
1101        \return
1102                true if this window was inherited from \a class_name. false if not.
1103        */
1104        bool testClassName(const String& class_name) const              {return testClassName_impl(class_name);}
1105
1106    /*************************************************************************
1107                Manipulator functions
1108        *************************************************************************/
1109        /*!
1110        \brief
1111                Initialises the Window based object ready for use.
1112
1113        \note
1114                This must be called for every window created.  Normally this is handled automatically by the WindowFactory for each Window type.
1115
1116        \return
1117                Nothing
1118        */
1119        virtual void    initialise(void) {}
1120
1121
1122        /*!
1123        \brief
1124                Set whether or not this Window will automatically be destroyed when its parent Window is destroyed.
1125
1126        \param setting
1127                set to true to have the Window auto-destroyed when its parent is destroyed (default), or false to have the Window
1128                remain after its parent is destroyed.
1129
1130        \return
1131                Nothing
1132        */
1133        void    setDestroyedByParent(bool setting);
1134
1135
1136        /*!
1137        \brief
1138                Set whether this window is always on top, or not.
1139
1140        \param setting
1141                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.
1142
1143        \return
1144                Nothing
1145        */
1146        void    setAlwaysOnTop(bool setting);
1147
1148
1149        /*!
1150        \brief
1151                Set whether this window is enabled or disabled.  A disabled window normally can not be interacted with, and may have different rendering.
1152
1153        \param setting
1154                true to enable the Window, and false to disable the Window.
1155
1156        \return
1157                Nothing
1158        */
1159        void    setEnabled(bool setting);
1160
1161
1162        /*!
1163        \brief
1164                enable the Window to allow interaction.
1165
1166        \return
1167                Nothing
1168        */
1169        void    enable(void)            {setEnabled(true);}
1170
1171
1172        /*!
1173        \brief
1174                disable the Window to prevent interaction.
1175
1176        \return
1177                Nothing
1178        */
1179        void    disable(void)           {setEnabled(false);}
1180
1181
1182        /*!
1183        \brief
1184                Set whether the Window is visible or hidden.
1185
1186        \param setting
1187                true to make the Window visible, or false to make the Window hidden
1188
1189        \return
1190                Nothing
1191        */
1192        void    setVisible(bool setting);
1193
1194
1195        /*!
1196        \brief
1197                show the Window
1198
1199        \return
1200                Nothing
1201        */
1202        void    show(void)                      {setVisible(true);}
1203
1204
1205        /*!
1206        \brief
1207                hide the Window.
1208
1209        \return
1210                Nothing
1211        */
1212        void    hide(void)                      {setVisible(false);}
1213
1214
1215        /*!
1216        \brief
1217                Activate the Window giving it input focus and bringing it to the top of all non always-on-top Windows.
1218
1219        \return
1220                Nothing
1221        */
1222        void    activate(void);
1223
1224
1225        /*!
1226        \brief
1227                Deactivate the window.  No further inputs will be received by the window until it is re-activated either programmatically or
1228                by the user interacting with the gui.
1229       
1230        \return
1231                Nothing.
1232        */
1233        void    deactivate(void);
1234
1235
1236        /*!
1237        \brief
1238                Set whether this Window will be clipped by its parent window(s).
1239
1240        \param setting
1241                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
1242                to the screen only.
1243
1244        \return
1245                Nothing
1246        */
1247        void    setClippedByParent(bool setting);
1248       
1249
1250        /*!
1251        \brief
1252                Set the current ID for the Window.
1253
1254        \param ID
1255                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.
1256
1257        \return
1258                Nothing
1259        */
1260        void    setID(uint ID);
1261
1262
1263        /*!
1264        \brief
1265                Set the current text string for the Window.
1266
1267        \param text
1268                String object containing the text that is to be set as the Window text.
1269
1270        \return
1271                Nothing
1272        */
1273        void    setText(const String& text);
1274
1275
1276        /*!
1277        \brief
1278                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.
1279
1280        \param width
1281                float value that specifies the new width for the window, in units consistent with whatever metrics mode is in operation.
1282
1283        \return
1284                Nothing
1285        */
1286        void    setWidth(float width);
1287
1288
1289        /*!
1290        \brief
1291                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.
1292
1293        \param height
1294                float value that specifies the new height for the window, in units consistent with whatever metrics mode is in operation.
1295
1296        \return
1297                Nothing
1298        */
1299        void    setHeight(float height);
1300
1301
1302        /*!
1303        \brief
1304                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.
1305
1306        \param size
1307                Size object that describes the new dimensions for the window, in units consistent with whatever metrics mode is in operation.
1308
1309        \return
1310                Nothing
1311        */
1312        void    setSize(const Size& size);
1313
1314
1315        /*!
1316        \brief
1317                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.
1318
1319        \param x
1320                float value that specifies the new x postion of the Window, in units consistent with the current metrics mode.
1321
1322        \return
1323                Nothing
1324        */
1325        void    setXPosition(float x);
1326
1327
1328        /*!
1329        \brief
1330                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.
1331
1332        \param y
1333                float value that specifies the new y postion of the Window, in units consistent with the current metrics mode.
1334
1335        \return
1336                Nothing
1337        */
1338        void    setYPosition(float y);
1339
1340
1341        /*!
1342        \brief
1343                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.
1344
1345        \param position
1346                Point object that describes the new postion of the Window, in units consistent with the current metrics mode.
1347
1348        \return
1349                Nothing
1350        */
1351        void    setPosition(const Point& position);
1352
1353
1354        /*!
1355        \brief
1356                Set the current area for the Window, this allows for setting of position and size at the same time. 
1357                Interpretation of the input value \a area is dependant upon the current metrics system set for the Window.
1358
1359        \param area
1360                Rect object that describes the new area for Window, in units consistent with the current metrics mode.
1361
1362        \return
1363                Nothing
1364        */
1365        void    setAreaRect(const Rect& area);
1366
1367       
1368        /*!
1369        \brief
1370                Set the font used by this Window.
1371
1372        \param font
1373                Pointer to the Font object to be used by this Window.  If \a font is NULL, the default font will be used.
1374
1375        \return
1376                Nothing
1377        */
1378        void    setFont(const Font* font);
1379
1380
1381        /*!
1382        \brief
1383                Set the font used by this Window.
1384
1385        \param name
1386                String object holding the name of the Font object to be used by this Window.  If \a name == "", the default font will be used.
1387
1388        \return
1389                Nothing
1390
1391        \exception UnknownObjectException       thrown if the specified Font is unknown within the system.
1392        */
1393        void    setFont(const String& name);
1394
1395
1396        /*!
1397        \brief
1398                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
1399                being added to this Window.
1400
1401        \param name
1402                String object holding the name of the Window to be added.
1403
1404        \return
1405                Nothing.
1406
1407        \exception UnknownObjectException       thrown if no Window named \a name exists.
1408        \exception InvalidRequestException      thrown if Window \a name is an ancestor of this Window, to prevent cyclic Window structures.
1409        */
1410        void    addChildWindow(const String& name);
1411
1412
1413        /*!
1414        \brief
1415                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
1416                being added to this Window.
1417
1418        \param window
1419                Pointer to the Window object to be added.
1420
1421        \return
1422                Nothing
1423
1424        \exception InvalidRequestException      thrown if Window \a window is an ancestor of this Window, to prevent cyclic Window structures.
1425        */
1426        void    addChildWindow(Window* window);
1427
1428
1429        /*!
1430        \brief
1431                Remove the named Window from this windows child list.
1432
1433        \param name
1434                String object holding the name of the Window to be removed.  If the Window specified is not attached to this Window, nothing happens.
1435
1436        \return
1437                Nothing.
1438        */
1439        void    removeChildWindow(const String& name);
1440
1441
1442        /*!
1443        \brief
1444                Remove the specified Window form this windows child list.
1445
1446        \param window
1447                Pointer to the Window object to be removed.  If the \a window is not attached to this Window, then nothing happens.
1448
1449        \return
1450                Nothing.
1451        */
1452        void    removeChildWindow(Window* window);
1453
1454
1455        /*!
1456        \brief
1457                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
1458                one encountered will be removed.
1459
1460        \param ID
1461                ID number assigned to the Window to be removed.  If no Window with ID code \a ID is attached, nothing happens.
1462
1463        \return
1464                Nothing.
1465        */
1466        void    removeChildWindow(uint ID);
1467
1468
1469        /*!
1470        \brief
1471                Move the Window to the top of the z order.
1472
1473                - 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
1474                        repeated for all ancestors.
1475                - 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.
1476
1477        \return
1478                Nothing
1479        */
1480        void    moveToFront();
1481
1482
1483        /*!
1484        \brief
1485                Move the Window to the bottom of the Z order.
1486
1487                - 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.
1488                - 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.
1489
1490        \return
1491                Nothing
1492        */
1493        void    moveToBack();
1494
1495
1496        /*!
1497        \brief
1498                Captures input to this window
1499
1500        \return
1501                - true if input was successfully captured to this window.
1502                - false if input could not be captured to this window (maybe because the window is not active).
1503        */
1504        bool    captureInput(void);
1505
1506
1507        /*!
1508        \brief
1509                Releases input capture from this Window.  If this Window does not have inputs captured, nothing happens.
1510
1511        \return
1512                Nothing
1513        */
1514        void    releaseInput(void);
1515
1516
1517        /*!
1518        \brief
1519                Set whether this window will remember and restore the previous window that had inputs captured.
1520
1521        \param setting
1522                - true: The window will remember and restore the previous capture window.  The CaptureLost event is not fired
1523                  on the previous window when this window steals input capture.  When this window releases capture, the old capture
1524                  window is silently restored.
1525
1526                - false: Input capture works as normal, each window losing capture is signalled via CaptureLost, and upon the final
1527                  release of capture, no previous setting is restored (this is the default 'normal' behaviour).
1528
1529        \return
1530                Nothing
1531        */
1532        void    setRestoreCapture(bool setting);
1533
1534
1535        /*!
1536        \brief
1537                Set the current alpha value for this window.
1538
1539        \note
1540                The alpha value set for any given window may or may not be the final alpha value that is used when rendering.  All window
1541                objects, by default, inherit alpha from thier parent window(s) - this will blend child windows, relatively, down the line of
1542                inheritance.  This behaviour can be overridden via the setInheritsAlpha() method.  To return the true alpha value that will be
1543                applied when rendering, use the getEffectiveAlpha() method.
1544
1545        \param alpha
1546                The new alpha value for the window.  Value should be between 0.0f and 1.0f.
1547
1548        \return
1549                Nothing
1550        */
1551        void    setAlpha(float alpha);
1552
1553
1554        /*!
1555        \brief
1556                Sets whether this Window will inherit alpha from its parent windows.
1557
1558        \param setting
1559                true if the Window should use inherited alpha, or false if the Window should have an independant alpha value.
1560
1561        \return
1562                Nothing
1563        */
1564        void    setInheritsAlpha(bool setting);
1565
1566
1567        /*!
1568        \brief
1569                Signal the System object to redraw (at least) this Window on the next render cycle.
1570
1571        \return
1572                Nothing
1573        */
1574        void    requestRedraw(void) const;
1575
1576
1577        /*!
1578        \brief
1579                set the current metrics mode employed by the Window
1580
1581        \param mode
1582                One of the values of the MectricsMode enumerated type, that describes the metrics mode to be used by the Window.
1583
1584        \return
1585                Nothing
1586        */
1587        void setMetricsMode(MetricsMode mode);
1588
1589
1590        /*!
1591        \brief
1592                Set the minimum size for this window.
1593
1594        \param sz
1595                Size object describing the minimum size for the window.  For absolute metrics, the Size values are in screen pixels,
1596                for relative metrics the Size values are relative to the display size.
1597        */
1598        void    setMinimumSize(const Size& sz);
1599
1600
1601        /*!
1602        \brief
1603                Set the maximum size for this window.
1604
1605        \param sz
1606                Size object describing the maximum size for the window.  For absolute metrics, the Size values are in screen pixels,
1607                for relative metrics the Size values are relative to the display size.
1608        */
1609        void    setMaximumSize(const Size& sz);
1610
1611
1612        /*!
1613        \brief
1614                Set the mouse cursor image to be used when the mouse enters this window.
1615
1616        \param image
1617                Pointer to the Image object to use as the mouse cursor image when the mouse enters the area for this Window.
1618
1619        \return
1620                Nothing.
1621        */
1622        void    setMouseCursor(const Image* image)              {d_mouseCursor = image;}
1623
1624
1625        /*!
1626        \brief
1627                Set the mouse cursor image to be used when the mouse enters this window.
1628
1629        \param image
1630                One of the MouseCursorImage enumerated values.
1631
1632        \return
1633                Nothing.
1634        */
1635        void    setMouseCursor(MouseCursorImage image)          {d_mouseCursor = (const Image*)image;}
1636
1637
1638        /*!
1639        \brief
1640                Set the mouse cursor image to be used when the mouse enters this window.
1641
1642        \param imageset
1643                String object that contains the name of the Imageset that contains the image to be used.
1644
1645        \param image_name
1646                String object that contains the name of the Image on \a imageset that is to be used.
1647
1648        \return
1649                Nothing.
1650
1651        \exception UnknownObjectException       thrown if \a imageset is not known, or if \a imageset contains no Image named \a image_name.
1652        */
1653        void    setMouseCursor(const String& imageset, const String& image_name);
1654
1655
1656        /*!
1657        \brief
1658                Set the user data set for this Window.
1659
1660                Each Window can have some client assigned data attached to it, this data is not used by the GUI system
1661                in any way.  Interpretation of the data is entirely application specific.
1662
1663        \param user_data
1664                pointer to the user data that is to be set for this window.
1665
1666        \return
1667                Nothing.
1668        */
1669        void    setUserData(void* user_data)            {d_userData = user_data;}
1670
1671
1672        /*!
1673        \brief
1674                set the x position of the window using the specified metrics system.
1675
1676        \param mode
1677                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1678
1679        \param x
1680                float value that specifies the x position of the Window relative to it's parent, using the specified MetricsMode.
1681
1682        \return
1683                Nothing.
1684        */
1685        void    setXPosition(MetricsMode mode, float x);
1686
1687
1688        /*!
1689        \brief
1690                set the y position of the window using the specified metrics system.
1691
1692        \param mode
1693                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1694
1695        \param y
1696                float value that specifies the y position of the Window relative to it's parent,  using the specified MetricsMode.
1697
1698        \return
1699                Nothing.
1700        */
1701        void    setYPosition(MetricsMode mode, float y);
1702
1703
1704        /*!
1705        \brief
1706                set the position of the window using the specified metrics system.
1707
1708        \param mode
1709                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1710
1711        \param position
1712                Point object that describes the position of the Window relative to it's parent, using the specified MetricsMode.
1713
1714        \return
1715                Nothing
1716        */
1717        void    setPosition(MetricsMode mode, const Point& position);
1718
1719
1720        /*!
1721        \brief
1722                set the width of the Window using the specified metrics system.
1723
1724        \param mode
1725                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1726
1727        \param width
1728                float value that specifies the width of the Window using the specified MetricsMode.
1729
1730        \return
1731                Nothing.
1732        */
1733        void    setWidth(MetricsMode mode, float width);
1734
1735
1736        /*!
1737        \brief
1738                set the height of the Window using the specified metrics system.
1739
1740        \param mode
1741                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1742
1743        \param height
1744                float value that specifies the height of the Window using the specified MetricsMode.
1745
1746        \return
1747                Nothing.
1748        */
1749        void    setHeight(MetricsMode mode, float height);
1750
1751
1752        /*!
1753        \brief
1754                set the size of the Window using the specified metrics system.
1755
1756        \param mode
1757                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1758
1759        \param size
1760                Size object that describes the dimensions of the Window using the specified MetricsMode.
1761
1762        \return
1763                Nothing.
1764        */
1765        void    setSize(MetricsMode mode, const Size& size);
1766
1767
1768        /*!
1769        \brief
1770                set the Rect that describes the Window area using the specified metrics system.
1771
1772        \param mode
1773                One of the MetricsMode enumerated values specifying the metrics system to be used for the return value.
1774
1775        \param area
1776                Rect object that describes the area to be covered by the Window using the specified MetricsMode.
1777
1778        \return
1779                Nothing.
1780        */
1781        void    setRect(MetricsMode mode, const Rect& area);
1782
1783
1784        /*!
1785        \brief
1786                Set whether z-order changes are enabled or disabled for this Window.
1787
1788        \param setting
1789                - true if z-order changes are enabled for this window.  moveToFront/moveToBack work normally as expected.
1790                - false: z-order changes are disabled for this window.  moveToFront/moveToBack are ignored for this window.
1791
1792        \return
1793                Nothing.
1794        */
1795        void    setZOrderingEnabled(bool setting);
1796
1797
1798    /*!
1799    \brief
1800        Set whether this window will receive multi-click events or multiple 'down' events instead.
1801
1802    \param setting
1803        - true if the Window will receive double-click and triple-click events.
1804        - false if the Window will receive multiple mouse button down events instead of double/triple click events.
1805
1806    \return
1807        Nothing.
1808    */
1809    void setWantsMultiClickEvents(bool setting);
1810
1811   
1812    /*!
1813    \brief
1814        Set whether mouse button down event autorepeat is enabled for this window.
1815
1816    \param setting
1817        - true to enable autorepeat of mouse button down events.
1818        - false to disable autorepeat of mouse button down events.
1819
1820    \return
1821        Nothing.
1822    */
1823    void    setMouseAutoRepeatEnabled(bool setting);
1824
1825
1826    /*!
1827    \brief
1828        Set the current auto-repeat delay setting for this window.
1829
1830    \param delay
1831        float value indicating the delay, in seconds, defore the first repeat mouse button down event should be triggered when autorepeat is enabled.
1832
1833    \return
1834        Nothing.
1835    */
1836    void   setAutoRepeatDelay(float delay);
1837
1838   
1839    /*!
1840    \brief
1841        Set the current auto-repeat rate setting for this window.
1842
1843    \param rate
1844        float value indicating the rate, in seconds, at which repeat mouse button down events should be generated after the initial delay has expired.
1845
1846    \return
1847        Nothing.
1848    */
1849    void   setAutoRepeatRate(float rate);
1850
1851
1852    /*!
1853    \brief
1854        Set whether the window wants inputs passed to its attached
1855        child windows when the window has inputs captured.
1856
1857    \param setting
1858        - true if System should pass captured input events to child windows.
1859        - false if System should pass captured input events to this window only.
1860    */
1861    void    setDistributesCapturedInputs(bool setting);
1862
1863    /*!
1864    \brief
1865        Internal support method for drag & drop.  You do not normally call
1866        this directly from client code.  See the DragContainer class.
1867    */
1868    void    notifyDragDropItemEnters(DragContainer* item);
1869
1870    /*!
1871    \brief
1872        Internal support method for drag & drop.  You do not normally call
1873        this directly from client code.  See the DragContainer class.
1874    */
1875    void    notifyDragDropItemLeaves(DragContainer* item);
1876
1877    /*!
1878    \brief
1879        Internal support method for drag & drop.  You do not normally call
1880        this directly from client code.  See the DragContainer class.
1881    */
1882    void    notifyDragDropItemDropped(DragContainer* item);
1883
1884    /*!
1885    \brief
1886        Internal destroy method which actually just adds the window and any
1887        parent destructed child windows to the dead pool.
1888
1889        This is virtual to allow for specialised cleanup which may be required
1890        in some advanced cases.  If you override this for the above reason, you
1891        MUST call this base class version.
1892       
1893    \note
1894        You never have to call this method yourself, use WindowManager to
1895        destroy your Window objects (which will call this for you).
1896    */
1897    virtual void    destroy(void);
1898
1899    /*!
1900    \brief
1901        Set the custom Tooltip object for this Window.  This value may be NULL to indicate that the
1902        Window should use the system default Tooltip object.
1903
1904    \param tooltip
1905        Pointer to a valid Tooltip based object which should be used as the tooltip for this Window, or NULL to
1906        indicate that the Window should use the system default Tooltip object.  Note that when passing a pointer
1907        to a Tooltip object, ownership of the Tooltip does not pass to this Window object.
1908
1909    \return
1910        Nothing.
1911    */
1912    void setTooltip(Tooltip* tooltip);
1913
1914    /*!
1915    \brief
1916        Set the custom Tooltip to be used by this Window by specifying a Window type.
1917
1918        The Window will internally attempt to create an instance of the specified window type (which must be
1919        derived from the base Tooltip class).  If the Tooltip creation fails, the error is logged and the
1920        Window will revert to using either the existing custom Tooltip or the system default Tooltip.
1921
1922    \param tooltipType
1923        String object holding the name of the Tooltip based Window type which should be used as the Tooltip for
1924        this Window.
1925
1926    \return
1927        Nothing.
1928    */
1929    void setTooltipType(const String& tooltipType);
1930
1931    /*!
1932    \brief
1933        Set the tooltip text for this window.
1934
1935    \param tip
1936        String object holding the text to be displayed in the tooltip for this Window.
1937
1938    \return
1939        Nothing.
1940    */
1941    void setTooltipText(const String& tip);
1942
1943        /*!
1944    \brief
1945        Set whether this window inherits Tooltip text from its parent when its own tooltip text is not set.
1946
1947    \param setting
1948        - true if the window should inherit tooltip text from its parent when its own text is not set.
1949        - false if the window should not inherit tooltip text from its parent (and so show no tooltip when no text is set).
1950
1951    \return
1952        Nothing.
1953     */
1954    void setInheritsTooltipText(bool setting);
1955
1956    /*!
1957    \brief
1958        Set whether this window will rise to the top of the z-order when clicked with the left mouse button.
1959
1960    \param setting
1961        - true if the window should come to the top of other windows when the left mouse button is pushed within its area.
1962        - false if the window should not change z-order position when the left mouse button is pushed within its area.
1963
1964    \return
1965        Nothing.
1966     */
1967    void setRiseOnClickEnabled(bool setting)    { d_riseOnClick = setting; }
1968
1969
1970    /*************************************************************************
1971                Co-ordinate and Size Conversion Functions
1972        *************************************************************************/
1973        /*!
1974        \brief
1975                Convert the given X co-ordinate from absolute to relative metrics.
1976
1977        \param val
1978                X co-ordinate specified in pixels relative to this Window (so 0 is this windows left edge).
1979
1980        \return
1981                A relative metric value that is equivalent to \a val, given the Window objects current width.
1982        */
1983        float   absoluteToRelativeX(float val) const;
1984
1985
1986        /*!
1987        \brief
1988                Convert the given Y co-ordinate from absolute to relative metrics.
1989
1990        \param val
1991                Y co-ordinate specified in pixels relative to this Window (so 0 is this windows top edge).
1992
1993        \return
1994                A relative metric value that is equivalent to \a val, given the Window objects current height.
1995        */
1996        float   absoluteToRelativeY(float val) const;
1997
1998
1999        /*!
2000        \brief
2001                Convert the given position from absolute to relative metrics.
2002
2003        \param pt
2004                Point object that describes a position specified in pixels relative to this Window (so 0,0 is this windows top-left corner).
2005
2006        \return
2007                A Point object describing a relative metric position that is equivalent to \a pt, given the Window objects current size.
2008        */
2009        Point   absoluteToRelative(const Point& pt) const;
2010
2011
2012        /*!
2013        \brief
2014                Convert the given size from absolute to relative metrics.
2015
2016        \param sze
2017                Size object that describes a size specified in pixels.
2018
2019        \return
2020                A Size object describing a relative metric size that is equivalent to \a sze, given the Window objects current size.
2021        */
2022        Size    absoluteToRelative(const Size& sze) const;
2023
2024
2025        /*!
2026        \brief
2027                Convert the given area from absolute to relative metrics.
2028
2029        \param rect
2030                Rect object describing the area specified in pixels relative to this Window.
2031
2032        \return
2033                A Rect object describing a relative metric area that is equivalent to \a rect, given the Window objects current size.
2034        */
2035        Rect    absoluteToRelative(const Rect& rect) const;
2036
2037
2038        /*!
2039        \brief
2040                Convert the given X co-ordinate from relative to absolute metrics.
2041
2042        \param val
2043                X co-ordinate specified in relative metrics for this Window (so 0 is this windows left edge).
2044
2045        \return
2046                An absolute metric value that is equivalent to \a val, given the Window objects current width.
2047        */
2048        float   relativeToAbsoluteX(float val) const;
2049
2050
2051        /*!
2052        \brief
2053                Convert the given Y co-ordinate from relative to absolute metrics.
2054
2055        \param val
2056                Y co-ordinate specified in relative metrics for this Window (so 0 is this windows top edge).
2057
2058        \return
2059                An absolute metric value that is equivalent to \a val, given the Window objects current height.
2060        */
2061        float   relativeToAbsoluteY(float val) const;
2062
2063
2064        /*!
2065        \brief
2066                Convert the given position from relative to absolute metrics.
2067
2068        \param pt
2069                Point object describing a position specified in relative metrics for this Window (so 0,0 is this windows top-left corner).
2070
2071        \return
2072                A Point object describing a position in absolute metric values that is equivalent to \a pt, given the Window objects current size.
2073        */
2074        Point   relativeToAbsolute(const Point& pt) const;
2075
2076
2077        /*!
2078        \brief
2079                Convert the given size from relative to absolute metrics.
2080
2081        \param sze
2082                Size object describing a size specified in relative metrics for this Window.
2083
2084        \return
2085                A Size object that describes a size in absolute metric values that is equivalent to \a sze, given the Window objects current size.
2086        */
2087        Size    relativeToAbsolute(const Size& sze) const;
2088
2089
2090        /*!
2091        \brief
2092                Convert the given area from relative to absolute metrics.
2093
2094        \param rect
2095                Rect object describing the area specified in relative metrics for this Window.
2096
2097        \return
2098                A Rect object that describes an area in absolute metric values that is equivalent to \a rect, given the Window objects current size.
2099        */
2100        Rect    relativeToAbsolute(const Rect& rect) const;
2101
2102
2103        /*!
2104        \brief
2105                Convert a window co-ordinate value, specified in whichever metrics mode is active, to a screen relative pixel co-ordinate.
2106
2107        \param x
2108                x co-ordinate value to be converted
2109
2110        \return
2111                float value describing a pixel screen co-ordinate that is equivalent to window co-ordinate \a x.
2112        */
2113        float   windowToScreenX(float x) const;
2114
2115
2116        /*!
2117        \brief
2118                Convert a window co-ordinate value, specified in whichever metrics mode is active, to a screen relative pixel co-ordinate.
2119
2120        \param y
2121                y co-ordinate value to be converted
2122
2123        \return
2124                float value describing a screen co-ordinate that is equivalent to window co-ordinate \a y.
2125        */
2126        float   windowToScreenY(float y) const;
2127       
2128       
2129        /*!
2130        \brief
2131                Convert a window co-ordinate position, specified in whichever metrics mode is active, to a screen relative pixel co-ordinate position.
2132
2133        \param pt
2134                Point object describing the position to be converted
2135
2136        \return
2137                Point object describing a screen co-ordinate position that is equivalent to window co-ordinate position \a pt.
2138        */
2139        Point   windowToScreen(const Point& pt) const;
2140
2141
2142        /*!
2143        \brief
2144                Convert a window size value, specified in whichever metrics mode is active, to a size in pixels.
2145
2146        \param sze
2147                Size object describing the size to be converted
2148
2149        \return
2150                Size object describing describing a size in pixels that is equivalent to the window based size \a sze.
2151        */
2152        Size    windowToScreen(const Size& sze) const;
2153
2154
2155        /*!
2156        \brief
2157                Convert a window area, specified in whichever metrics mode is active, to a screen area.
2158
2159        \param rect
2160                Rect object describing the area to be converted
2161
2162        \return
2163                Rect object describing a screen area that is equivalent to window area \a rect.
2164        */
2165        Rect    windowToScreen(const Rect& rect) const;
2166
2167
2168        /*!
2169        \brief
2170                Convert a screen relative pixel co-ordinate value to a window co-ordinate value, specified in whichever metrics mode is active.
2171
2172        \param x
2173                x co-ordinate value to be converted
2174
2175        \return
2176                float value describing a window co-ordinate value that is equivalent to screen co-ordinate \a x.
2177        */
2178        float   screenToWindowX(float x) const;
2179
2180
2181        /*!
2182        \brief
2183                Convert a screen relative pixel co-ordinate value to a window co-ordinate value, specified in whichever metrics mode is active.
2184
2185        \param y
2186                y co-ordinate value to be converted
2187
2188        \return
2189                float value describing a window co-ordinate value that is equivalent to screen co-ordinate \a y.
2190        */
2191        float   screenToWindowY(float y) const;
2192
2193
2194        /*!
2195        \brief
2196                Convert a screen relative pixel position to a window co-ordinate position, specified in whichever metrics mode is active.
2197
2198        \param pt
2199                Point object describing the position to be converted
2200
2201        \return
2202                Point object describing a window co-ordinate position that is equivalent to screen co-ordinate \a x.
2203        */
2204        Point   screenToWindow(const Point& pt) const;
2205
2206
2207        /*!
2208        \brief
2209                Convert a pixel screen size to a window based size, specified in whichever metrics mode is active.
2210
2211        \param sze
2212                Size object describing the size to be converted
2213
2214        \return
2215                Size object describing a window based size that is equivalent to screen based size \a sze.
2216        */
2217        Size    screenToWindow(const Size& sze) const;
2218
2219
2220        /*!
2221        \brief
2222                Convert a screen area to a window area, specified in whichever metrics mode is active.
2223
2224        \param rect
2225                Rect object describing the area to be converted
2226
2227        \return
2228                Rect object describing a window area that is equivalent to screen area \a rect.
2229        */
2230        Rect    screenToWindow(const Rect& rect) const;
2231
2232
2233        /*************************************************************************
2234                Main render function.
2235        *************************************************************************/
2236        /*!
2237        \brief
2238                Causes the Window object to render itself and all of it's attached children
2239
2240        \return
2241                Nothing
2242        */
2243        void    render(void);
2244
2245
2246        /*!
2247        \brief
2248                Cause window to update itself and any attached children.  Client code does not need to call this method; to
2249                ensure full, and proper updates, call the injectTimePulse methodname method provided by the System class.
2250
2251        \note
2252                The update order is such that 'this' window is updated prior to any child windows, this is so
2253                that child windows that access the parent in their update code get the correct updated state.
2254
2255        \param elapsed
2256                float value indicating the number of seconds passed since the last update.
2257
2258        \return
2259                Nothing.
2260        */
2261        void    update(float elapsed);
2262
2263
2264protected:
2265        /*************************************************************************
2266                System object can trigger events directly
2267        *************************************************************************/
2268        friend  class System;
2269
2270
2271        /*************************************************************************
2272                Event trigger methods
2273        *************************************************************************/
2274        /*!
2275        \brief
2276                Handler called when the window's size changes.
2277
2278        \param e
2279                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2280                event the trigger window is always 'this'.
2281        */
2282        virtual void    onSized(WindowEventArgs& e);
2283
2284
2285        /*!
2286        \brief
2287                Handler called when the window's position changes.
2288
2289        \param e
2290                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2291                event the trigger window is always 'this'.
2292        */
2293        virtual void    onMoved(WindowEventArgs& e);
2294
2295
2296        /*!
2297        \brief
2298                Handler called when the window's text is changed.
2299
2300        \param e
2301                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2302                event the trigger window is always 'this'.
2303        */
2304        virtual void    onTextChanged(WindowEventArgs& e);
2305
2306
2307        /*!
2308        \brief
2309                Handler called when the window's font is changed.
2310
2311        \param e
2312                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2313                event the trigger window is always 'this'.
2314        */
2315        virtual void    onFontChanged(WindowEventArgs& e);
2316
2317
2318        /*!
2319        \brief
2320                Handler called when the window's alpha blend value is changed.
2321
2322        \param e
2323                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2324                event the trigger window is always 'this'.
2325        */
2326        virtual void    onAlphaChanged(WindowEventArgs& e);
2327
2328
2329        /*!
2330        \brief
2331                Handler called when the window's client assigned ID is changed.
2332
2333        \param e
2334                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2335                event the trigger window is always 'this'.
2336        */
2337        virtual void    onIDChanged(WindowEventArgs& e);
2338
2339
2340        /*!
2341        \brief
2342                Handler called when the window is shown (made visible).
2343
2344        \param e
2345                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2346                event the trigger window is always 'this'.
2347        */
2348        virtual void    onShown(WindowEventArgs& e);
2349
2350
2351        /*!
2352        \brief
2353                Handler called when the window is hidden.
2354
2355        \param e
2356                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2357                event the trigger window is always 'this'.
2358        */
2359        virtual void    onHidden(WindowEventArgs& e);
2360
2361
2362        /*!
2363        \brief
2364                Handler called when the window is enabled.
2365
2366        \param e
2367                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2368                event the trigger window is always 'this'.
2369        */
2370        virtual void    onEnabled(WindowEventArgs& e);
2371
2372
2373        /*!
2374        \brief
2375                Handler called when the window is disabled.
2376
2377        \param e
2378                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2379                event the trigger window is always 'this'.
2380        */
2381        virtual void    onDisabled(WindowEventArgs& e);
2382
2383
2384        /*!
2385        \brief
2386                Handler called when the window's active metrics system is changed.
2387
2388        \param e
2389                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2390                event the trigger window is always 'this'.
2391        */
2392        virtual void    onMetricsChanged(WindowEventArgs& e);
2393
2394
2395        /*!
2396        \brief
2397                Handler called when the window's setting for being clipped by it's parent is changed.
2398
2399        \param e
2400                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2401                event the trigger window is always 'this'.
2402        */
2403        virtual void    onClippingChanged(WindowEventArgs& e);
2404
2405
2406        /*!
2407        \brief
2408                Handler called when the window's setting for being destroyed automatically be it's parent is changed.
2409
2410        \param e
2411                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2412                event the trigger window is always 'this'.
2413        */
2414        virtual void    onParentDestroyChanged(WindowEventArgs& e);
2415
2416
2417        /*!
2418        \brief
2419                Handler called when the window's setting for inheriting alpha-blending is changed.
2420
2421        \param e
2422                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2423                event the trigger window is always 'this'.
2424        */
2425        virtual void    onInheritsAlphaChanged(WindowEventArgs& e);
2426
2427
2428        /*!
2429        \brief
2430                Handler called when the window's always-on-top setting is changed.
2431
2432        \param e
2433                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2434                event the trigger window is always 'this'.
2435        */
2436        virtual void    onAlwaysOnTopChanged(WindowEventArgs& e);
2437
2438
2439        /*!
2440        \brief
2441                Handler called when this window gains capture of mouse inputs.
2442
2443        \param e
2444                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2445                event the trigger window is always 'this'.
2446        */
2447        virtual void    onCaptureGained(WindowEventArgs& e);
2448
2449
2450        /*!
2451        \brief
2452                Handler called when this window loses capture of mouse inputs.
2453
2454        \param e
2455                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2456                event the trigger window is always 'this'.
2457        */
2458        virtual void    onCaptureLost(WindowEventArgs& e);
2459
2460
2461        /*!
2462        \brief
2463                Handler called when rendering for this window has started.
2464
2465        \param e
2466                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2467                event the trigger window is always 'this'.
2468        */
2469        virtual void    onRenderingStarted(WindowEventArgs& e);
2470
2471
2472        /*!
2473        \brief
2474                Handler called when rendering for this window has ended.
2475
2476        \param e
2477                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2478                event the trigger window is always 'this'.
2479        */
2480        virtual void    onRenderingEnded(WindowEventArgs& e);
2481
2482
2483        /*!
2484        \brief
2485                Handler called when the z-order position of this window has changed.
2486
2487        \param e
2488                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2489                event the trigger window is always 'this'.
2490        */
2491        virtual void    onZChanged(WindowEventArgs& e);
2492
2493
2494        /*!
2495        \brief
2496                Handler called when this window's destruction sequence has begun.
2497
2498        \param e
2499                WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event.  For this
2500                event the trigger window is always 'this'.
2501        */
2502        virtual void    onDestructionStarted(WindowEventArgs& e);
2503
2504
2505        /*!
2506        \brief
2507                Handler called when this window has become the active window.
2508
2509        \param e
2510                ActivationEventArgs class whose 'otherWindow' field is set to the window that previously was active, or NULL for none.
2511        */
2512        virtual void    onActivated(ActivationEventArgs& e);
2513
2514
2515        /*!
2516        \brief
2517                Handler called when this window has lost input focus and has been deactivated.
2518
2519        \param e
2520                ActivationEventArgs object whose 'otherWindow' field is set to the window that has now become active, or NULL for none.
2521        */
2522        virtual void    onDeactivated(ActivationEventArgs& e);
2523
2524
2525        /*!
2526        \brief
2527                Handler called when this window's parent window has been resized.  If this window is the root / GUI Sheet
2528                window, this call will be made when the screen size changes.
2529
2530        \param e
2531                WindowEventArgs object whose 'window' pointer field is set the the window that caused the event; this is typically either
2532                this window's parent window, or NULL to indicate the screen size has changed.
2533        */
2534        virtual void    onParentSized(WindowEventArgs& e);
2535
2536
2537        /*!
2538        \brief
2539                Handler called when a child window is added to this window.
2540
2541        \param e
2542                WindowEventArgs object whose 'window' pointer field is set to the window that has been added.
2543        */
2544        virtual void    onChildAdded(WindowEventArgs& e);
2545
2546
2547        /*!
2548        \brief
2549                Handler called when a child window is removed from this window.
2550
2551        \param e
2552                WindowEventArgs object whose 'window' pointer field is set the window that has been removed.
2553        */
2554        virtual void    onChildRemoved(WindowEventArgs& e);
2555
2556
2557        /*!
2558        \brief
2559                Handler called when the mouse cursor has entered this window's area.
2560
2561        \param e
2562                MouseEventArgs object.  All fields are valid.
2563        */
2564        virtual void    onMouseEnters(MouseEventArgs& e);
2565
2566
2567        /*!
2568        \brief
2569                Handler called when the mouse cursor has left this window's area.
2570
2571        \param e
2572                MouseEventArgs object.  All fields are valid.
2573        */
2574        virtual void    onMouseLeaves(MouseEventArgs& e);
2575
2576
2577        /*!
2578        \brief
2579                Handler called when the mouse cursor has been moved within this window's area.
2580
2581        \param e
2582                MouseEventArgs object.  All fields are valid.
2583        */
2584        virtual void    onMouseMove(MouseEventArgs& e);
2585
2586
2587        /*!
2588        \brief
2589                Handler called when the mouse wheel (z-axis) position changes within this window's area.
2590
2591        \param e
2592                MouseEventArgs object.  All fields are valid.
2593        */
2594        virtual void    onMouseWheel(MouseEventArgs& e);
2595
2596
2597        /*!
2598        \brief
2599                Handler called when a mouse button has been depressed within this window's area.
2600
2601        \param e
2602                MouseEventArgs object.  All fields are valid.
2603        */
2604        virtual void    onMouseButtonDown(MouseEventArgs& e);
2605
2606
2607        /*!
2608        \brief
2609                Handler called when a mouse button has been released within this window's area.
2610
2611        \param e
2612                MouseEventArgs object.  All fields are valid.
2613        */
2614        virtual void    onMouseButtonUp(MouseEventArgs& e);
2615
2616
2617        /*!
2618        \brief
2619                Handler called when a mouse button has been clicked (that is depressed and then released, within a specified time)
2620                within this window's area.
2621
2622        \param e
2623                MouseEventArgs object.  All fields are valid.
2624        */
2625        virtual void    onMouseClicked(MouseEventArgs& e);
2626
2627
2628        /*!
2629        \brief
2630                Handler called when a mouse button has been double-clicked within this window's area.
2631
2632        \param e
2633                MouseEventArgs object.  All fields are valid.
2634        */
2635        virtual void    onMouseDoubleClicked(MouseEventArgs& e);
2636
2637
2638        /*!
2639        \brief
2640                Handler called when a mouse button has been triple-clicked within this window's area.
2641
2642        \param e
2643                MouseEventArgs object.  All fields are valid.
2644        */
2645        virtual void    onMouseTripleClicked(MouseEventArgs& e);
2646
2647
2648        /*!
2649        \brief
2650                Handler called when a key as been depressed while this window has input focus.
2651
2652        \param e
2653                KeyEventArgs object whose 'scancode' field is set to the Key::Scan value representing the key that was pressed, and whose
2654                'sysKeys' field represents the combination of SystemKey that were active when the event was generated.
2655        */
2656        virtual void    onKeyDown(KeyEventArgs& e);
2657
2658
2659        /*!
2660        \brief
2661                Handler called when a key as been released while this window has input focus.
2662
2663        \param e
2664                KeyEventArgs object whose 'scancode' field is set to the Key::Scan value representing the key that was released, and whose
2665                'sysKeys' field represents the combination of SystemKey that were active when the event was generated.  All other fields should be
2666                considered as 'junk'.
2667        */
2668        virtual void    onKeyUp(KeyEventArgs& e);
2669
2670
2671        /*!
2672        \brief
2673                Handler called when a character-key has been pressed while this window has input focus.
2674
2675        \param e
2676                KeyEventArgs object whose 'codepoint' field is set to the Unicode code point (encoded as utf32) for the character typed, and whose
2677                'sysKeys' field represents the combination of SystemKey that were active when the event was generated.  All other fields should be
2678                considered as 'junk'.
2679        */
2680        virtual void    onCharacter(KeyEventArgs& e);
2681
2682    /*!
2683    \brief
2684        Handler called when a DragContainer is dragged over this window.
2685
2686    \param e
2687        DragDropEventArgs object initialised as follows:
2688        - window field is normaly set to point to 'this' window.
2689        - dragDropItem is a pointer to a DragContainer window that triggered the event.
2690    */
2691    virtual void    onDragDropItemEnters(DragDropEventArgs& e);
2692
2693
2694    /*!
2695    \brief
2696        Handler called when a DragContainer is dragged over this window.
2697
2698    \param e
2699        DragDropEventArgs object initialised as follows:
2700        - window field is normaly set to point to 'this' window.
2701        - dragDropItem is a pointer to a DragContainer window that triggered the event.
2702    */
2703    virtual void    onDragDropItemLeaves(DragDropEventArgs& e);
2704
2705
2706    /*!
2707    \brief
2708        Handler called when a DragContainer is dragged over this window.
2709
2710    \param e
2711        DragDropEventArgs object initialised as follows:
2712        - window field is normaly set to point to 'this' window.
2713        - dragDropItem is a pointer to a DragContainer window that triggered the event.
2714    */
2715    virtual void    onDragDropItemDropped(DragDropEventArgs& e);
2716
2717
2718        /*************************************************************************
2719                Implementation Functions
2720        *************************************************************************/
2721        /*!
2722        \brief
2723                Perform actual update processing for this Window.
2724
2725        \param elapsed
2726                float value indicating the number of seconds elapsed since the last update call.
2727
2728        \return
2729                Nothing.
2730        */
2731        virtual void    updateSelf(float elapsed);
2732
2733
2734        /*!
2735        \brief
2736                Perform the actual rendering for this Window.
2737
2738        \param z
2739                float value specifying the base Z co-ordinate that should be used when rendering
2740
2741        \return
2742                Nothing
2743        */
2744        virtual void    drawSelf(float z)       = 0;
2745
2746
2747        /*!
2748        \brief
2749                Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
2750
2751        \param class_name
2752                The class name that is to be checked.
2753
2754        \return
2755                true if this window was inherited from \a class_name. false if not.
2756        */
2757        virtual bool    testClassName_impl(const String& class_name) const
2758        {
2759                if (class_name==(const utf8*)"Window")  return true;
2760                return false;
2761        }
2762
2763
2764        /*!
2765        \brief
2766                Set the parent window for this window object.
2767
2768        \param parent
2769                Pointer to a Window object that is to be assigned as the parent to this Window.
2770
2771        \return
2772                Nothing
2773        */
2774        void    setParent(Window* parent);
2775
2776
2777        /*!
2778        \brief
2779                Return the pixel Width of the parent element.  This always returns a valid number.
2780
2781        \return
2782                float value that is equal to the pixel width of this Window objects parent
2783        */
2784        float   getParentWidth(void) const;
2785
2786
2787        /*!
2788        \brief
2789                Return the pixel Height of the parent element.  This always returns a valid number.
2790
2791        \return
2792                float value that is equal to the pixel height of this Window objects parent
2793        */
2794        float   getParentHeight(void) const;
2795
2796
2797        /*!
2798        \brief
2799                Return the pixel size of the parent element.  This always returns a valid object.
2800
2801        \return
2802                Size object that describes the pixel dimensions of this Window objects parent
2803        */
2804        Size    getParentSize(void) const;
2805
2806
2807        /*!
2808        \brief
2809                Return a Rect object that describes, in values relative to \a window, the absolute area described by \a rect.
2810
2811        \param window
2812                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
2813                display, as returned by the renderer object, is used.
2814
2815        \param rect
2816                Rect object describing the area, in absolute values, that is to be returned as relative values.
2817
2818        \return
2819                Rect object that describes in values relative to \a window, the same area described as absolute values in \a rect.
2820        */
2821        Rect    absoluteToRelative_impl(const Window* window, const Rect& rect) const;
2822        Size    absoluteToRelative_impl(const Window* window, const Size& sz) const;
2823        Point   absoluteToRelative_impl(const Window* window, const Point& pt) const;
2824        float   absoluteToRelativeX_impl(const Window* window, float x) const;
2825        float   absoluteToRelativeY_impl(const Window* window, float y) const;
2826
2827
2828        /*!
2829        \brief
2830                Return a Rect object that describes, in absolute values offset from \a window, the relative area described by \a rect.
2831
2832        \param window
2833                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
2834                display, as returned by the renderer object, is used.
2835
2836        \param rect
2837                Rect object describing the area, in relative values, that is to be returned as absolute values.
2838
2839        \return
2840                Rect object that describes in absolute values offset from \a window, the same area described as relative values in \a rect.
2841        */
2842        Rect    relativeToAbsolute_impl(const Window* window, const Rect& rect) const;
2843        Size    relativeToAbsolute_impl(const Window* window, const Size& sz) const;
2844        Point   relativeToAbsolute_impl(const Window* window, const Point& pt) const;
2845        float   relativeToAbsoluteX_impl(const Window* window, float x) const;
2846        float   relativeToAbsoluteY_impl(const Window* window, float y) const;
2847
2848        Size    getWindowSize_impl(const Window* window) const;
2849
2850
2851        /*!
2852        \brief
2853                Return the inherited metrics mode.  This is either the metrics mode of our parent, or Relative
2854                if we have no parent.
2855        */
2856        MetricsMode getInheritedMetricsMode(void) const;
2857
2858   
2859    /*!
2860    \brief
2861        Fires off a repeated mouse button down event for this window.
2862    */
2863    void    generateAutoRepeatEvent(MouseButton button);
2864
2865
2866        /*************************************************************************
2867                Implementation Data
2868        *************************************************************************/
2869        // child stuff
2870        typedef std::vector<Window*>    ChildList;
2871        ChildList               d_children;                     //!< The list of child Window objects attached to this.
2872
2873        // general data
2874        MetricsMode             d_metricsMode;          //!< Holds the active metrics mode for this window
2875        static Window*  d_captureWindow;        //!< Window that has captured inputs
2876        Window*                 d_oldCapture;           //!< The Window that previously had capture (used for restoreOldCapture mode)
2877        Window*                 d_parent;                       //!< Holds pointer to the parent window.
2878        const Font*             d_font;                         //!< Holds pointer to the Window objects current Font.
2879        String                  d_text;                         //!< Holds the text / label / caption for this Window.
2880        uint                    d_ID;                           //!< User ID assigned to this Window
2881        float                   d_alpha;                        //!< Alpha transparency setting for the Window
2882        Rect                    d_abs_area;                     //!< This Window objects area (pixels relative to parent)
2883        Rect                    d_rel_area;                     //!< This Window objects area (decimal fractions relative to parent)
2884        const Image*    d_mouseCursor;          //!< Holds pointer to the Window objects current mouse cursor image.
2885        void*                   d_userData;                     //!< Holds pointer to some user assigned data.
2886
2887        // maximum and minimum sizes
2888        Size    d_minSize;                                      //!< current minimum size for the window (this is always stored in pixels).
2889        Size    d_maxSize;                                      //!< current maximum size for the window (this is always stored in pixels).
2890
2891        // settings
2892        bool    d_enabled;                                      //!< true when Window is enabled
2893        bool    d_visible;                                      //!< true when Window is visible (that is it will be rendered, but may be obscured so no necesarily really visible)
2894        bool    d_active;                                       //!< true when Window is the active Window (receiving inputs).
2895        bool    d_clippedByParent;                      //!< true when Window will be clipped by parent Window area Rect.
2896        bool    d_destroyedByParent;            //!< true when Window will be auto-destroyed by parent.
2897        bool    d_alwaysOnTop;                          //!< true if Window will be drawn on top of all other Windows
2898        bool    d_inheritsAlpha;                        //!< true if the Window inherits alpha from the parent Window
2899        bool    d_restoreOldCapture;            //!< true if the Window restores capture to the previous window when it releases capture.
2900        bool    d_zOrderingEnabled;                     //!< true if the Window responds to z-order change requests.
2901    bool    d_wantsMultiClicks;         //!< true if the Window wishes to hear about multi-click mouse events.
2902    bool    d_distCapturedInputs;       //!< true if unhandled captured inputs should be distributed to child windows.
2903    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.
2904
2905    // mouse button autorepeat data
2906    bool    d_autoRepeat;       //!< true if button will auto-repeat mouse button down events while mouse button is held down,
2907    float   d_repeatDelay;      //!< seconds before first repeat event is fired
2908    float   d_repeatRate;       //!< secons between further repeats after delay has expired.
2909    bool    d_repeating;        //!< implements repeating - is true after delay has elapsed,
2910    float   d_repeatElapsed;    //!< implements repeating - tracks time elapsed.
2911    MouseButton d_repeatButton; //!< Button we're tracking (implication of this is that we only support one button at a time).
2912
2913    // Tooltip stuff
2914    String   d_tooltipText;     //!< Text string used as tip for this window.
2915    Tooltip* d_customTip;       //!< Possible custom Tooltip for this window.
2916    bool     d_weOwnTip;        //!< true if this Window created the custom Tooltip.
2917    bool     d_inheritsTipText; //!< true if the Window inherits tooltip text from its parent (when none set for itself).
2918
2919protected:
2920        /*************************************************************************
2921                Properties for Window base class
2922        *************************************************************************/
2923        static  WindowProperties::AbsoluteHeight        d_absHeightProperty;
2924        static  WindowProperties::AbsoluteMaxSize       d_absMaxSizeProperty;
2925        static  WindowProperties::AbsoluteMinSize       d_absMinSizeProperty;
2926        static  WindowProperties::AbsolutePosition      d_absPositionProperty;
2927        static  WindowProperties::AbsoluteRect          d_absRectProperty;
2928        static  WindowProperties::AbsoluteSize          d_absSizeProperty;
2929        static  WindowProperties::AbsoluteWidth         d_absWidthProperty;
2930        static  WindowProperties::AbsoluteXPosition     d_absXPosProperty;
2931        static  WindowProperties::AbsoluteYPosition     d_absYPosProperty;
2932        static  WindowProperties::Alpha                         d_alphaProperty;
2933        static  WindowProperties::AlwaysOnTop           d_alwaysOnTopProperty;
2934        static  WindowProperties::ClippedByParent       d_clippedByParentProperty;
2935        static  WindowProperties::DestroyedByParent     d_destroyedByParentProperty;
2936        static  WindowProperties::Disabled                      d_disabledProperty;
2937        static  WindowProperties::Font                          d_fontProperty;
2938        static  WindowProperties::Height                        d_heightProperty;
2939        static  WindowProperties::ID                            d_IDProperty;
2940        static  WindowProperties::InheritsAlpha         d_inheritsAlphaProperty;
2941        static  WindowProperties::MetricsMode           d_metricsModeProperty;
2942        static  WindowProperties::MouseCursorImage      d_mouseCursorProperty;
2943        static  WindowProperties::Position                      d_positionProperty;
2944        static  WindowProperties::Rect                          d_rectProperty;
2945        static  WindowProperties::RelativeHeight        d_relHeightProperty;
2946        static  WindowProperties::RelativeMaxSize       d_relMaxSizeProperty;
2947        static  WindowProperties::RelativeMinSize       d_relMinSizeProperty;
2948        static  WindowProperties::RelativePosition      d_relPositionProperty;
2949        static  WindowProperties::RelativeRect          d_relRectProperty;
2950        static  WindowProperties::RelativeSize          d_relSizeProperty;
2951        static  WindowProperties::RelativeWidth         d_relWidthProperty;
2952        static  WindowProperties::RelativeXPosition     d_relXPosProperty;
2953        static  WindowProperties::RelativeYPosition     d_relYPosProperty;
2954        static  WindowProperties::RestoreOldCapture     d_restoreOldCaptureProperty;
2955        static  WindowProperties::Size                          d_sizeProperty;
2956        static  WindowProperties::Text                          d_textProperty;
2957        static  WindowProperties::Visible                       d_visibleProperty;
2958        static  WindowProperties::Width                         d_widthProperty;
2959        static  WindowProperties::XPosition                     d_xPosProperty;
2960        static  WindowProperties::YPosition                     d_yPosProperty;
2961        static  WindowProperties::ZOrderChangeEnabled   d_zOrderChangeProperty;
2962    static  WindowProperties::WantsMultiClickEvents d_wantsMultiClicksProperty;
2963    static  WindowProperties::MouseButtonDownAutoRepeat d_autoRepeatProperty;
2964    static  WindowProperties::AutoRepeatDelay   d_autoRepeatDelayProperty;
2965    static  WindowProperties::AutoRepeatRate    d_autoRepeatRateProperty;
2966    static  WindowProperties::DistributeCapturedInputs d_distInputsProperty;
2967    static  WindowProperties::CustomTooltipType d_tooltipTypeProperty;
2968    static  WindowProperties::Tooltip           d_tooltipProperty;
2969    static  WindowProperties::InheritsTooltipText d_inheritsTooltipProperty;
2970    static  WindowProperties::RiseOnClick       d_riseOnClickProperty;
2971
2972
2973        /*************************************************************************
2974                Private implementation functions
2975        *************************************************************************/
2976        /*!
2977        \brief
2978                Add standard CEGUI::Window events
2979        */
2980        void    addStandardEvents(void);
2981
2982        /*!
2983        \brief
2984                Cleanup child windows
2985        */
2986        virtual void    cleanupChildren(void);
2987
2988        /*!
2989        \brief
2990                Add given window to child list at an appropriate position
2991        */
2992        virtual void    addChild_impl(Window* wnd);
2993
2994        /*!
2995        \brief
2996                Remove given window from child list
2997        */
2998        virtual void    removeChild_impl(Window* wnd);
2999
3000        /*!
3001        \brief
3002                Notify 'this' and all siblings of a ZOrder change event
3003        */
3004        virtual void    onZChange_impl(void);
3005
3006
3007        /*!
3008        \brief
3009                Add standard CEGUI::Window properties.
3010        */
3011        void    addStandardProperties(void);
3012
3013
3014    /*!
3015    \brief
3016        Implements move to fron behavior.
3017     */
3018    virtual void moveToFront_impl(bool wasClicked);
3019
3020
3021    /*!
3022    \brief
3023        Implementation of rise on click functionality.
3024     */
3025    void doRiseOnClick(void);
3026
3027       
3028        /*************************************************************************
3029                May not copy or assign Window objects
3030        *************************************************************************/
3031        Window(const Window& wnd) {}
3032        Window& operator=(const Window& wnd) {return *this;}
3033
3034        /*************************************************************************
3035                Private implementation Data
3036        *************************************************************************/
3037        const String    d_type;                 //!< String holding the type name for the Window (is also the name of the WindowFactory that created us)
3038        const String    d_name;                 //!< The name of the window (GUI system unique).
3039};
3040
3041} // End of  CEGUI namespace section
3042
3043
3044#if defined(_MSC_VER)
3045#       pragma warning(pop)
3046#endif
3047
3048#endif  // end of guard _CEGUIWindow_h_
Note: See TracBrowser for help on using the repository browser.