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

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

added ogre dependencies and patched ogre sources
Line 
1/************************************************************************
2        filename:       CEGUIWindowManager.h
3        created:        21/2/2004
4        author:         Paul D Turner
5       
6        purpose:        Defines the interface for the WindowManager object
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 _CEGUIWindowManager_h_
27#define _CEGUIWindowManager_h_
28
29#include "CEGUIBase.h"
30#include "CEGUIString.h"
31#include "CEGUISingleton.h"
32#include "CEGUILogger.h"
33#include "CEGUIIteratorBase.h"
34#include <map>
35#include <vector>
36
37#if defined(_MSC_VER)
38#       pragma warning(push)
39#       pragma warning(disable : 4275)
40#       pragma warning(disable : 4251)
41#endif
42
43
44// Start of CEGUI namespace section
45namespace CEGUI
46{
47/*!
48\brief
49        The WindowManager class describes an object that manages creation and lifetime of Window objects.
50
51        The WindowManager is the means by which Window objects are created and destroyed.  For each sub-class
52        of Window that is to be created, there must exist a WindowFactory object which is registered with the
53        WindowFactoryManager.  Additionally, the WindowManager tracks every Window object created, and can be
54        used to access those Window objects by name.
55*/
56class CEGUIEXPORT WindowManager : public Singleton <WindowManager>
57{
58public:
59        /*!
60        \brief
61                Function type that is used as a callback when loading layouts from XML; the function is called
62                for each Property element encountered.
63
64        \param window
65                Window object that the property is to be applied to.
66
67        \param propname
68                String holding the name of the property that is being set.
69
70        \param propvalue
71                String holding the new value that will be applied to the property specified by /a propname.
72
73        \param userdata
74                Some client code supplied data.
75
76        \return
77                - true if the property should be set.
78                - false if the property should not be set,
79        */
80        typedef bool PropertyCallback(Window* window, String& propname, String& propvalue, void* userdata);
81       
82        /*************************************************************************
83                Construction and Destruction
84        *************************************************************************/
85        /*!
86        \brief
87                Constructs a new WindowManager object.
88
89                NB: Client code should not create WindowManager objects - they are of limited use to you!  The
90                intended pattern of access is to get a pointer to the GUI system's WindowManager via the System
91                object, and use that.
92        */
93        WindowManager(void) { Logger::getSingleton().logEvent((utf8*)"CEGUI::WindowManager singleton created"); }
94
95
96        /*!
97        \brief
98                Destructor for WindowManager objects
99
100                This will properly destry all remaining Window objects.  Note that WindowFactory objects will not
101                be destroyed (since they are owned by whoever created them).
102        */
103        ~WindowManager(void);
104
105
106        /*!
107        \brief
108                Return singleton WindowManager object
109
110        \return
111                Singleton WindowManager object
112        */
113        static  WindowManager&  getSingleton(void);
114
115
116        /*!
117        \brief
118                Return pointer to singleton WindowManager object
119
120        \return
121                Pointer to singleton WindowManager object
122        */
123        static  WindowManager*  getSingletonPtr(void);
124
125
126        /*************************************************************************
127                Window Related Methods
128        *************************************************************************/
129        /*!
130        \brief
131                Creates a new Window object of the specified type, and gives it the specified unique name.
132
133        \param type
134                String that describes the type of Window to be created.  A valid WindowFactory for the specified type must be registered.
135
136        \param name
137                String that holds a unique name that is to be given to the new window.
138
139        \return
140                Pointer to the newly created Window object.
141
142        \exception      AlreadyExistsException          A Window object with the name \a name already exists.
143        \exception      UnknownObjectException          No WindowFactory is registered for \a type Window objects.
144        \exception      GenericException                        Some other error occurred (Exception message has details).
145        */
146        Window* createWindow(const String& type, const String& name);
147
148
149        /*!
150        \brief
151                Destroy the specified Window object.
152
153        \param window
154                Pointer to the Window object to be destroyed.  If the \a window is null, or is not recognised, nothing happens.
155
156        \return
157                Nothing
158
159        \exception      InvalidRequestException         Can be thrown if the WindowFactory for \a window's object type was removed.
160        */
161        void    destroyWindow(Window* window);
162
163
164        /*!
165        \brief
166                Destroy the specified Window object.
167
168        \param
169                window  String containing the name of the Window object to be destroyed.  If \a window is not recognised, nothing happens.
170
171        \return
172                Nothing.
173
174        \exception      InvalidRequestException         Can be thrown if the WindowFactory for \a window's object type was removed.
175        */
176        void    destroyWindow(const String& window);
177
178
179        /*!
180        \brief
181                Return a pointer to the specified Window object.
182
183        \param name
184                String holding the name of the Window object to be returned.
185
186        \return
187                Pointer to the Window object with the name \a name.
188
189        \exception UnknownObjectException       No Window object with a name matching \a name was found.
190        */
191        Window* getWindow(const String& name) const;
192
193
194        /*!
195        \brief
196                Examines the list of Window objects to see if one exists with the given name
197
198        \param name
199                String holding the name of the Window object to look for.
200
201        \return
202                true if a Window object was found with a name matching \a name.  false if no matching Window object was found.
203        */
204        bool    isWindowPresent(const String& name) const;
205
206
207        /*!
208        \brief
209                Destroys all Window objects within the system
210
211        \return
212                Nothing.
213
214        \exception      InvalidRequestException         Thrown if the WindowFactory for any Window object type has been removed.
215        */
216        void    destroyAllWindows(void);
217
218
219        /*!
220        \brief
221                Creates a set of windows (a Gui layout) from the information in the specified XML file.
222
223        \param filename
224                String object holding the filename of the XML file to be processed.
225
226        \param name_prefix
227                String object holding the prefix that is to be used when creating the windows in the layout file, this
228                function allows a layout to be loaded multiple times without having name clashes.
229
230    \param resourceGroup
231        Resource group identifier to be passed to the resource provider when loading the layout file.
232
233        \param callback
234                PropertyCallback function to be called for each Property element loaded from the layout.  This is
235                called prior to the property value being applied to the window enabling client code manipulation of
236                properties.
237
238        \param userdata
239                Client code data pointer passed to the PropertyCallback function.
240
241        \return
242                Pointer to the root Window object defined in the layout.
243
244        \exception FileIOException                      thrown if something goes wrong while processing the file \a filename.
245        \exception InvalidRequestException      thrown if \a filename appears to be invalid.
246        */
247        Window* loadWindowLayout(const String& filename, const String& name_prefix = "", const String& resourceGroup = "", PropertyCallback* callback = NULL, void* userdata = NULL);
248
249    /*!
250    \brief
251        Return whether the window dead pool is empty.
252
253    \return
254        - true if there are no windows in the dead pool.
255        - false if the dead pool contains >=1 window awaiting destruction.
256    */
257    bool isDeadPoolEmpty(void) const;
258
259    /*!
260    \brief
261        Permanently destroys any windows placed in the dead pool.
262
263    \note
264        It is probably not a good idea to call this from a Window based event handler
265        if the specific window has been or is being destroyed.
266
267    \return
268        Nothing.
269    */
270    void cleanDeadPool(void);
271
272private:
273        /*************************************************************************
274                Implementation Constants
275        *************************************************************************/
276        static const char       GUILayoutSchemaName[];                  //!< Filename of the XML schema used for validating GUILayout files.
277
278
279        /*************************************************************************
280                Implementation Data
281        *************************************************************************/
282        typedef std::map<String, Window*>                       WindowRegistry;                         //!< Type used to implement registry of Window objects
283    typedef std::vector<Window*>    WindowVector;   //!< Type to use for a collection of Window pointers.
284
285        WindowRegistry                  d_windowRegistry;                       //!< The container that forms the Window registry
286    WindowVector    d_deathrow;     //!< Collection of 'destroyed' windows.
287
288public:
289        /*************************************************************************
290                Iterator stuff
291        *************************************************************************/
292        typedef ConstBaseIterator<WindowRegistry>       WindowIterator;
293
294        /*!
295        \brief
296                Return a WindowManager::WindowIterator object to iterate over the currently defined Windows.
297        */
298        WindowIterator  getIterator(void) const;
299};
300
301} // End of  CEGUI namespace section
302
303#if defined(_MSC_VER)
304#       pragma warning(pop)
305#endif
306
307#endif  // end of guard _CEGUIWindowManager_h_
Note: See TracBrowser for help on using the repository browser.