source: GTP/trunk/App/Demos/Geom/OgreStuff/include/CEGUI/CEGUIWindowManager.h @ 1812

Revision 1812, 12.9 KB checked in by gumbau, 18 years ago (diff)
RevLine 
[1812]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        Public static data
61    *************************************************************************/
62    static const String GeneratedWindowNameBase;      //!< Base name to use for generated window names.
63
64        /*!
65        \brief
66                Function type that is used as a callback when loading layouts from XML; the function is called
67                for each Property element encountered.
68
69        \param window
70                Window object that the property is to be applied to.
71
72        \param propname
73                String holding the name of the property that is being set.
74
75        \param propvalue
76                String holding the new value that will be applied to the property specified by /a propname.
77
78        \param userdata
79                Some client code supplied data.
80
81        \return
82                - true if the property should be set.
83                - false if the property should not be set,
84        */
85        typedef bool PropertyCallback(Window* window, String& propname, String& propvalue, void* userdata);
86       
87        /*************************************************************************
88                Construction and Destruction
89        *************************************************************************/
90        /*!
91        \brief
92                Constructs a new WindowManager object.
93
94                NB: Client code should not create WindowManager objects - they are of limited use to you!  The
95                intended pattern of access is to get a pointer to the GUI system's WindowManager via the System
96                object, and use that.
97        */
98        WindowManager(void);
99
100
101        /*!
102        \brief
103                Destructor for WindowManager objects
104
105                This will properly destry all remaining Window objects.  Note that WindowFactory objects will not
106                be destroyed (since they are owned by whoever created them).
107        */
108        ~WindowManager(void);
109
110
111        /*!
112        \brief
113                Return singleton WindowManager object
114
115        \return
116                Singleton WindowManager object
117        */
118        static  WindowManager&  getSingleton(void);
119
120
121        /*!
122        \brief
123                Return pointer to singleton WindowManager object
124
125        \return
126                Pointer to singleton WindowManager object
127        */
128        static  WindowManager*  getSingletonPtr(void);
129
130
131        /*************************************************************************
132                Window Related Methods
133        *************************************************************************/
134        /*!
135        \brief
136                Creates a new Window object of the specified type, and gives it the specified unique name.
137
138        \param type
139                String that describes the type of Window to be created.  A valid WindowFactory for the specified type must be registered.
140
141        \param name
142                String that holds a unique name that is to be given to the new window.  If this string is empty (""), a name
143                will be generated for the window.
144
145        \return
146                Pointer to the newly created Window object.
147
148        \exception      AlreadyExistsException          A Window object with the name \a name already exists.
149        \exception      UnknownObjectException          No WindowFactory is registered for \a type Window objects.
150        \exception      GenericException                        Some other error occurred (Exception message has details).
151        */
152        Window* createWindow(const String& type, const String& name = "");
153
154
155        /*!
156        \brief
157                Destroy the specified Window object.
158
159        \param window
160                Pointer to the Window object to be destroyed.  If the \a window is null, or is not recognised, nothing happens.
161
162        \return
163                Nothing
164
165        \exception      InvalidRequestException         Can be thrown if the WindowFactory for \a window's object type was removed.
166        */
167        void    destroyWindow(Window* window);
168
169
170        /*!
171        \brief
172                Destroy the specified Window object.
173
174        \param
175                window  String containing the name of the Window object to be destroyed.  If \a window is not recognised, nothing happens.
176
177        \return
178                Nothing.
179
180        \exception      InvalidRequestException         Can be thrown if the WindowFactory for \a window's object type was removed.
181        */
182        void    destroyWindow(const String& window);
183
184
185        /*!
186        \brief
187                Return a pointer to the specified Window object.
188
189        \param name
190                String holding the name of the Window object to be returned.
191
192        \return
193                Pointer to the Window object with the name \a name.
194
195        \exception UnknownObjectException       No Window object with a name matching \a name was found.
196        */
197        Window* getWindow(const String& name) const;
198
199
200        /*!
201        \brief
202                Examines the list of Window objects to see if one exists with the given name
203
204        \param name
205                String holding the name of the Window object to look for.
206
207        \return
208                true if a Window object was found with a name matching \a name.  false if no matching Window object was found.
209        */
210        bool    isWindowPresent(const String& name) const;
211
212
213        /*!
214        \brief
215                Destroys all Window objects within the system
216
217        \return
218                Nothing.
219
220        \exception      InvalidRequestException         Thrown if the WindowFactory for any Window object type has been removed.
221        */
222        void    destroyAllWindows(void);
223
224
225        /*!
226        \brief
227                Creates a set of windows (a Gui layout) from the information in the specified XML file.
228
229        \param filename
230                String object holding the filename of the XML file to be processed.
231
232        \param name_prefix
233                String object holding the prefix that is to be used when creating the windows in the layout file, this
234                function allows a layout to be loaded multiple times without having name clashes.  Note that if you use
235                this facility, then all windows defined within the layout must have names assigned; you currently can not
236                use this feature in combination with automatically generated window names.
237
238    \param resourceGroup
239        Resource group identifier to be passed to the resource provider when loading the layout file.
240
241        \param callback
242                PropertyCallback function to be called for each Property element loaded from the layout.  This is
243                called prior to the property value being applied to the window enabling client code manipulation of
244                properties.
245
246        \param userdata
247                Client code data pointer passed to the PropertyCallback function.
248
249        \return
250                Pointer to the root Window object defined in the layout.
251
252        \exception FileIOException                      thrown if something goes wrong while processing the file \a filename.
253        \exception InvalidRequestException      thrown if \a filename appears to be invalid.
254        */
255        Window* loadWindowLayout(const String& filename, const String& name_prefix = "", const String& resourceGroup = "", PropertyCallback* callback = NULL, void* userdata = NULL);
256
257    /*!
258    \brief
259        Return whether the window dead pool is empty.
260
261    \return
262        - true if there are no windows in the dead pool.
263        - false if the dead pool contains >=1 window awaiting destruction.
264    */
265    bool isDeadPoolEmpty(void) const;
266
267    /*!
268    \brief
269        Permanently destroys any windows placed in the dead pool.
270
271    \note
272        It is probably not a good idea to call this from a Window based event handler
273        if the specific window has been or is being destroyed.
274
275    \return
276        Nothing.
277    */
278    void cleanDeadPool(void);
279
280    /*!
281    \brief
282        Writes a full XML window layout, starting at the given Window to the given OutStream.
283
284    \param window
285        Window object to become the root of the layout.
286
287    \param out_stream
288        OutStream (std::ostream based) object where data is to be sent.
289
290    \param writeParent
291        If the starting window has a parent window, specifies whether to write the parent name into
292        the Parent attribute of the GUILayout XML element.
293
294    \return
295        Nothing.
296    */
297    void writeWindowLayoutToStream(const Window& window, OutStream& out_stream, bool writeParent = false) const;
298
299    /*!
300    \brief
301        Writes a full XML window layout, starting at the given Window to the given OutStream.
302
303    \param window
304        String holding the name of the Window object to become the root of the layout.
305
306    \param out_stream
307        OutStream (std::ostream based) object where data is to be sent.
308
309    \param writeParent
310        If the starting window has a parent window, specifies whether to write the parent name into
311        the Parent attribute of the GUILayout XML element.
312
313    \return
314        Nothing.
315    */
316    void writeWindowLayoutToStream(const String& window, OutStream& out_stream, bool writeParent = false) const;
317
318    /*!
319    \brief
320        Rename a window.
321
322    \param window
323        String holding the current name of the window to be renamed.
324
325    \param new_name
326        String holding the new name for the window
327
328    \exception UnknownObjectException
329        thrown if \a window is not known in the system.
330
331    \exception AlreadyExistsException
332        thrown if a Window named \a new_name already exists.
333    */
334    void renameWindow(const String& window, const String& new_name);
335
336    /*!
337    \brief
338        Rename a window.
339
340    \param window
341        Pointer to the window to be renamed.
342
343    \param new_name
344        String holding the new name for the window
345
346    \exception AlreadyExistsException
347        thrown if a Window named \a new_name already exists.
348    */
349    void renameWindow(Window* window, const String& new_name);
350
351private:
352    /*************************************************************************
353        Implementation Methods
354    *************************************************************************/
355    /*!
356    \brief
357        Implementation method to generate a unique name to use for a window.
358    */
359    String generateUniqueWindowName();
360
361        /*************************************************************************
362                Implementation Constants
363        *************************************************************************/
364        static const char       GUILayoutSchemaName[];                  //!< Filename of the XML schema used for validating GUILayout files.
365
366
367        /*************************************************************************
368                Implementation Data
369        *************************************************************************/
370        typedef std::map<String, Window*>                       WindowRegistry;                         //!< Type used to implement registry of Window objects
371    typedef std::vector<Window*>    WindowVector;   //!< Type to use for a collection of Window pointers.
372
373        WindowRegistry                  d_windowRegistry;                       //!< The container that forms the Window registry
374    WindowVector    d_deathrow;     //!< Collection of 'destroyed' windows.
375
376    unsigned long   d_uid_counter;  //!< Counter used to generate unique window names.
377
378public:
379        /*************************************************************************
380                Iterator stuff
381        *************************************************************************/
382        typedef ConstBaseIterator<WindowRegistry>       WindowIterator;
383
384        /*!
385        \brief
386                Return a WindowManager::WindowIterator object to iterate over the currently defined Windows.
387        */
388        WindowIterator  getIterator(void) const;
389};
390
391} // End of  CEGUI namespace section
392
393#if defined(_MSC_VER)
394#       pragma warning(pop)
395#endif
396
397#endif  // end of guard _CEGUIWindowManager_h_
Note: See TracBrowser for help on using the repository browser.