Context Navigation

CEGUIWindow.h @ 692

Revision 692, 124.8 KB checked in by mattausch, 19 years ago (diff)
adding ogre 1.2 and dependencies

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

Note: See TracBrowser for help on using the repository browser.

Context Navigation

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

Download in other formats: