source: GTP/trunk/Lib/Geom/OgreStuff/include/CEGUI/CEGUIWindowFactoryManager.h @ 1809

Revision 1809, 13.5 KB checked in by gumbau, 18 years ago (diff)
Line 
1/************************************************************************
2        filename:       CEGUIWindowFactoryManager.h
3        created:        22/2/2004
4        author:         Paul D Turner
5       
6        purpose:        Defines interface for WindowFactoryManager class
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 _CEGUIWindowFactoryManager_h_
27#define _CEGUIWindowFactoryManager_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        Class that manages WindowFactory objects
50*/
51class CEGUIEXPORT WindowFactoryManager : public Singleton<WindowFactoryManager>
52{
53public:
54    /*!
55    \brief
56        struct used to hold mapping information required to create a falagard based window.
57    */
58    struct CEGUIEXPORT FalagardWindowMapping
59    {
60        String  d_windowType;
61        String  d_lookName;
62        String  d_baseType;
63    };
64
65    /*!
66    \brief
67        Class used to track active alias targets for Window factory types.
68    */
69        class CEGUIEXPORT AliasTargetStack
70        {
71        public:
72                /*!
73                \brief
74                        Constructor for WindowAliasTargetStack objects
75                */
76                AliasTargetStack(void) {}
77
78
79                /*!
80                \brief
81                        Destructor for WindowAliasTargetStack objects
82                */
83                ~AliasTargetStack(void) {}
84
85
86                /*!
87                \brief
88                        Return a String holding the current target type for this stack
89
90                \return
91                        reference to a String object holding the currently active target type name for this stack.
92                */
93                const String&   getActiveTarget(void) const;
94
95                /*!
96                \brief
97                        Return the number of stacked target types in the stack
98
99                \return
100                        number of target types stacked for this alias.
101                */
102                uint    getStackedTargetCount(void) const;
103
104
105        private:
106                friend class WindowFactoryManager;
107                typedef std::vector<String>     TargetTypeStack;                //!< Type used to implement stack of target type names.
108
109                TargetTypeStack d_targetStack;          //!< Container holding the target types.
110        };
111
112
113        /*************************************************************************
114                Construction and Destruction
115        *************************************************************************/
116        /*!
117        \brief
118                Constructs a new WindowFactoryManager object.
119        */
120        WindowFactoryManager(void)
121        {
122                Logger::getSingleton().logEvent((utf8*)"CEGUI::WindowFactoryManager singleton created");
123        }
124
125
126        /*!
127        \brief
128                Destructor for WindowFactoryManager objects
129        */
130        ~WindowFactoryManager(void)
131        {
132                Logger::getSingleton().logEvent((utf8*)"CEGUI::WindowFactoryManager singleton destroyed");
133        }
134
135
136        /*************************************************************************
137                Public Interface
138        *************************************************************************/
139        /*!
140        \brief
141                Return singleton WindowFactoryManager object
142
143        \return
144                Singleton WindowFactoryManager object
145        */
146        static  WindowFactoryManager&   getSingleton(void);
147
148
149        /*!
150        \brief
151                Return pointer to singleton WindowFactoryManager object
152
153        \return
154                Pointer to singleton WindowFactoryManager object
155        */
156        static  WindowFactoryManager*   getSingletonPtr(void);
157
158
159        /*!
160        \brief
161                Adds a new WindowFactory to the list of registered factories.
162
163        \param factory
164                Pointer to the WindowFactory to be added to the WindowManager.
165
166        \return
167                Nothing
168       
169        \exception NullObjectException          \a factory was null.
170        \exception AlreadyExistsException       \a factory provided a Window type name which is in use by another registered WindowFactory.
171        */
172        void    addFactory(WindowFactory* factory);
173
174
175        /*!
176        \brief
177                Removes a WindowFactory from the list of registered factories.
178               
179        \note
180                The WindowFactory object is not destroyed (since it was created externally), instead it is just removed from the list.
181
182        \param name
183                String which holds the name (technically, Window type name) of the WindowFactory to be removed.  If \a name is not
184                in the list, no error occurs (nothing happens).
185
186        \return
187                Nothing
188        */
189        void    removeFactory(const String& name);
190
191
192        /*!
193        \brief
194                Removes a WindowFactory from the list of registered factories.
195
196        \note
197                The WindowFactory object is not destroyed (since it was created externally), instead it is just removed from the list.
198
199        \param factory
200                Pointer to the factory object to be removed.  If \a factory is null, or if no such WindowFactory is in the list, no
201                error occurs (nothing happens).
202
203        \return
204                Nothing
205        */
206        void    removeFactory(WindowFactory* factory);
207
208
209        /*!
210        \brief
211                Remove all WindowFactory objects from the list.
212
213        \return
214                Nothing
215        */
216        void    removeAllFactories(void)                {d_factoryRegistry.clear();}
217
218
219        /*!
220        \brief
221                Return a pointer to the specified WindowFactory object.
222
223        \param type
224                String holding the Window object type to return the WindowFactory for.
225
226        \return
227                Pointer to the WindowFactory object that creates Windows of the type \a type.
228
229        \exception UnknownObjectException       No WindowFactory object for Window objects of type \a type was found.
230        */
231        WindowFactory*  getFactory(const String& type) const;
232
233
234    /*!
235    \brief
236        Checks the list of registered WindowFactory objects, aliases, and
237        falagard mapped types for one which can create Window objects of the
238        specified type.
239
240    \param name
241        String containing the Window type name to check for.
242
243    \return
244        - true if a WindowFactory, alias, or falagard mapping for Window objects
245          of type \a name is registered.
246        - false if the system knows nothing about windows of type \a name.
247    */
248    bool        isFactoryPresent(const String& name) const;
249
250
251        /*!
252        \brief
253                Adds an alias for a current window type.
254
255                This method allows you to create an alias for a specified window type.  This means that you can then use
256                either name as the type parameter when creating a window.
257
258        \note
259                You need to be careful using this system.  Creating an alias using a name that already exists will replace the previous
260                mapping for that alias.  Each alias name maintains a stack, which means that it is possible to remove an alias and have the
261                previous alias restored.  The windows created via an alias use the real type, so removing an alias after window creation is always
262                safe (i.e. it is not the same as removing a real factory, which would cause an exception when trying to destroy a window with a missing
263                factory).
264
265        \param aliasName
266                String object holding the alias name.  That is the name that \a targetType will also be known as from no on.
267
268        \param targetType
269                String object holding the type window type name that is to be aliased.  This type must already exist.
270
271        \return
272                Nothing.
273
274        \exception UnknownObjectException       thrown if \a targetType is not known within the system.
275        */
276        void    addWindowTypeAlias(const String& aliasName, const String& targetType);
277
278
279        /*!
280        \brief
281                Remove the specified alias mapping.  If the alias mapping does not exist, nothing happens.
282
283        \note
284                You are required to supply both the alias and target names because there may exist more than one entry for a given
285                alias - therefore you are required to be explicit about which alias is to be removed.
286
287        \param aliasName
288                String object holding the alias name.
289
290        \param targetType
291                String object holding the type window type name that was aliased.
292
293        \return
294                Nothing.
295        */
296        void    removeWindowTypeAlias(const String& aliasName, const String& targetType);
297
298    /*!
299    \brief
300        Add a mapping for a falagard based window.
301
302        This function creates maps a target window type and target 'look' name onto a registered window type, thus allowing
303        the ususal window creation interface to be used to create windows that require extra information to full initialise
304        themselves.
305    \note
306        These mappings support 'late binding' to the target window type, as such the type indicated by \a targetType need not
307        exist in the system until attempting to create a Window using the type.
308    \par
309        Also note that creating a mapping for an existing type will replace any previous mapping for that same type.
310
311    \param newType
312        The type name that will be used to create windows using the target type and look.
313
314    \param targetType
315        The base window type.
316
317    \param lookName
318        The name of the 'look' that will be used by windows of this type.
319
320    \return
321        Nothing.
322    */
323    void addFalagardWindowMapping(const String& newType, const String& targetType, const String& lookName);
324
325    /*!
326    \brief
327        Remove the specified falagard type mapping if it exists.
328
329    \return
330        Nothing.
331    */
332    void removeFalagardWindowMapping(const String& type);
333
334    /*!
335    \brief
336        Return whether the given type is a falagard mapped type.
337
338    \param type
339        Name of a window type.
340
341    \return
342        - true if the requested type is a Falagard mapped window type.
343        - false if the requested type is a normal WindowFactory (or alias), or if the type does not exist.
344    */
345    bool isFalagardMappedType(const String& type) const;
346
347    /*!
348    \brief
349        Return the name of the LookN'Feel assigned to the specified window mapping.
350
351    \param type
352        Name of a window type.  The window type referenced should be a falagard mapped type.
353
354    \return
355        String object holding the name of the look mapped for the requested type.
356
357    \exception InvalidRequestException thrown if \a type is not a falagard mapping type (or maybe the type didn't exist).
358    */
359    const String& getMappedLookForType(const String& type) const;
360
361
362    /*!
363    \brief
364        Use the alias system, where required, to 'de-reference' the specified
365        type to an actual window type that can be created directly (that being
366        either a concrete window type, or a falagard mapped type).
367
368    \note
369        Even though implied by the above description, this method does not
370        check that a factory for the final type exists; we simply say that the
371        returned type is not an alias for some other type.
372
373    \param type
374        String describing the type to be de-referenced.
375
376    \return
377        String object holding a type for a window that can be created directly;
378        that is, a type that does not describe an alias to some other type.
379    */
380    String getDereferencedAliasType(const String& type) const;
381
382private:
383        /*************************************************************************
384                Implementation Data
385        *************************************************************************/
386        typedef std::map<String, WindowFactory*>        WindowFactoryRegistry;          //!< Type used to implement registry of WindowFactory objects
387        typedef std::map<String, AliasTargetStack>      TypeAliasRegistry;              //!< Type used to implement registry of window type aliases.
388    typedef std::map<String, FalagardWindowMapping> FalagardMapRegistry;    //!< Type used to implement registry of falagard window mappings.
389
390        WindowFactoryRegistry   d_factoryRegistry;                      //!< The container that forms the WindowFactory registry
391        TypeAliasRegistry               d_aliasRegistry;                        //!< The container that forms the window type alias registry.
392    FalagardMapRegistry     d_falagardRegistry;         //!< Container that hold all the falagard window mappings.
393
394public:
395        /*************************************************************************
396                Iterator stuff
397        *************************************************************************/
398        typedef ConstBaseIterator<WindowFactoryRegistry>        WindowFactoryIterator;
399        typedef ConstBaseIterator<TypeAliasRegistry>            TypeAliasIterator;
400    typedef ConstBaseIterator<FalagardMapRegistry>      FalagardMappingIterator;
401
402        /*!
403        \brief
404                Return a WindowFactoryManager::WindowFactoryIterator object to iterate over the available WindowFactory types.
405        */
406        WindowFactoryIterator   getIterator(void) const;
407
408
409        /*!
410        \brief
411                Return a WindowFactoryManager::TypeAliasIterator object to iterate over the defined aliases for window types.
412        */
413        TypeAliasIterator       getAliasIterator(void) const;
414
415
416    /*!
417    \brief
418        Return a WindowFactoryManager::FalagardMappingIterator object to iterate over the defined falagard window mappings.
419    */
420    FalagardMappingIterator getFalagardMappingIterator() const;
421};
422
423} // End of  CEGUI namespace section
424
425
426#if defined(_MSC_VER)
427#       pragma warning(pop)
428#endif
429
430#endif  // end of guard _CEGUIWindowFactoryManager_h_
Note: See TracBrowser for help on using the repository browser.