source: OGRE/trunk/ogrenew/OgreMain/include/OgreStringInterface.h @ 692

Revision 692, 11.5 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies

Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4    (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2005 The OGRE Team
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://www.gnu.org/copyleft/lesser.txt.
23-----------------------------------------------------------------------------
24*/
25
26#ifndef __StringInterface_H__
27#define __StringInterface_H__
28
29#include "OgrePrerequisites.h"
30#include "OgreString.h"
31#include "OgreCommon.h"
32
33namespace Ogre {
34
35
36    /// List of parameter types available
37    enum ParameterType
38    {
39        PT_BOOL,
40        PT_REAL,
41        PT_INT,
42        PT_UNSIGNED_INT,
43        PT_SHORT,
44        PT_UNSIGNED_SHORT,
45        PT_LONG,
46        PT_UNSIGNED_LONG,
47        PT_STRING,
48        PT_VECTOR3,
49        PT_MATRIX3,
50        PT_MATRIX4,
51        PT_QUATERNION,
52        PT_COLOURVALUE
53    };
54
55    /// Definition of a parameter supported by a StringInterface class, for introspection
56    class _OgreExport ParameterDef
57    {
58    public:
59        String name;
60        String description;
61        ParameterType paramType;
62        ParameterDef(const String& newName, const String& newDescription, ParameterType newType)
63            : name(newName), description(newDescription), paramType(newType) {}
64    };
65    typedef std::vector<ParameterDef> ParameterList;
66
67    /** Abstract class which is command object which gets/sets parameters.*/
68    class _OgreExport ParamCommand
69    {
70    public:
71        virtual String doGet(const void* target) const = 0;
72        virtual void doSet(void* target, const String& val) = 0;
73
74        virtual ~ParamCommand() { }
75    };
76    typedef std::map<String, ParamCommand* > ParamCommandMap;
77
78    /** Class to hold a dictionary of parameters for a single class. */
79    class _OgreExport ParamDictionary
80    {
81        friend class StringInterface;
82    protected:
83        /// Definitions of parameters
84        ParameterList mParamDefs;
85
86        /// Command objects to get/set
87        ParamCommandMap mParamCommands;
88
89        /** Retrieves the parameter command object for a named parameter. */
90        ParamCommand* getParamCommand(const String& name)
91        {
92            ParamCommandMap::iterator i = mParamCommands.find(name);
93            if (i != mParamCommands.end())
94            {
95                return i->second;
96            }
97            else
98            {
99                return 0;
100            }
101        }
102
103                const ParamCommand* getParamCommand(const String& name) const
104        {
105            ParamCommandMap::const_iterator i = mParamCommands.find(name);
106            if (i != mParamCommands.end())
107            {
108                return i->second;
109            }
110            else
111            {
112                return 0;
113            }
114        }
115    public:
116        ParamDictionary()  {}
117        /** Method for adding a parameter definition for this class.
118        @param paramDef A ParameterDef object defining the parameter
119        @param paramCmd Pointer to a ParamCommand subclass to handle the getting / setting of this parameter.
120            NB this class will not destroy this on shutdown, please ensure you do
121
122        */
123        void addParameter(const ParameterDef& paramDef, ParamCommand* paramCmd)
124        {
125            mParamDefs.push_back(paramDef);
126            mParamCommands[paramDef.name] = paramCmd;
127        }
128        /** Retrieves a list of parameters valid for this object.
129        @returns
130            A reference to a static list of ParameterDef objects.
131
132        */
133        const ParameterList& getParameters(void) const
134        {
135            return mParamDefs;
136        }
137
138
139
140    };
141    typedef std::map<String, ParamDictionary> ParamDictionaryMap;
142   
143    /** Class defining the common interface which classes can use to
144        present a reflection-style, self-defining parameter set to callers.
145    @remarks
146        This class also holds a static map of class name to parameter dictionaries
147        for each subclass to use. See ParamDictionary for details.
148    @remarks
149        In order to use this class, each subclass must call createParamDictionary in their constructors
150        which will create a parameter dictionary for the class if it does not exist yet.
151    */
152    class _OgreExport StringInterface
153    {
154    protected:
155
156        /// Dictionary of parameters
157        static ParamDictionaryMap msDictionary;
158
159        /// Class name for this instance to be used as a lookup (must be initialised by subclasses)
160        String mParamDictName;
161
162        /** Internal method for creating a parameter dictionary for the class, if it does not already exist.
163        @remarks
164            This method will check to see if a parameter dictionary exist for this class yet,
165            and if not will create one. NB you must supply the name of the class (RTTI is not
166            used or performance).
167        @param
168            className the name of the class using the dictionary
169        @returns
170            true if a new dictionary was created, false if it was already there
171        */
172        bool createParamDictionary(const String& className)
173        {
174            mParamDictName = className;
175            if (msDictionary.find(className) == msDictionary.end())
176            {
177                msDictionary[className] = ParamDictionary();
178                return true;
179            }
180            return false;
181
182        }
183
184    public:
185
186        /** Virtual desctructor, see Effective C++ */
187        virtual ~StringInterface() {}
188
189        /** Retrieves the parameter dictionary for this class.
190        @remarks
191            Only valid to call this after createParamDictionary.
192        @returns
193            Pointer to ParamDictionary shared by all instances of this class
194            which you can add parameters to, retrieve parameters etc.
195        */
196        ParamDictionary* getParamDictionary(void)
197        {
198            ParamDictionaryMap::iterator i = msDictionary.find(mParamDictName);
199            if (i != msDictionary.end())
200            {
201                return &(i->second);
202            }
203            else
204            {
205                return 0;
206            }
207        }
208
209                const ParamDictionary* getParamDictionary(void) const
210        {
211            ParamDictionaryMap::const_iterator i = msDictionary.find(mParamDictName);
212            if (i != msDictionary.end())
213            {
214                return &(i->second);
215            }
216            else
217            {
218                return 0;
219            }
220        }
221
222        /** Retrieves a list of parameters valid for this object.
223        @returns
224            A reference to a static list of ParameterDef objects.
225
226        */
227        const ParameterList& getParameters(void) const;
228
229        /** Generic parameter setting method.
230        @remarks
231            Call this method with the name of a parameter and a string version of the value
232            to set. The implementor will convert the string to a native type internally.
233            If in doubt, check the parameter definition in the list returned from
234            StringInterface::getParameters.
235        @param
236            name The name of the parameter to set
237        @param
238            value String value. Must be in the right format for the type specified in the parameter definition.
239            See the StringConverter class for more information.
240        @returns
241            true if set was successful, false otherwise (NB no exceptions thrown - tolerant method)
242        */
243        virtual bool setParameter(const String& name, const String& value);
244        /** Generic multiple parameter setting method.
245        @remarks
246            Call this method with a list of name / value pairs
247            to set. The implementor will convert the string to a native type internally.
248            If in doubt, check the parameter definition in the list returned from
249            StringInterface::getParameters.
250        @param
251            paramList Name/value pair list
252        */
253        virtual void setParameterList(const NameValuePairList& paramList);
254        /** Generic parameter retrieval method.
255        @remarks
256            Call this method with the name of a parameter to retrieve a string-format value of
257            the parameter in question. If in doubt, check the parameter definition in the
258            list returned from getParameters for the type of this parameter. If you
259            like you can use StringConverter to convert this string back into a native type.
260        @param
261            name The name of the parameter to get
262        @returns
263            String value of parameter, blank if not found
264        */
265        virtual String getParameter(const String& name) const
266        {
267            // Get dictionary
268            const ParamDictionary* dict = getParamDictionary();
269
270            if (dict)
271            {
272                // Look up command object
273                const ParamCommand* cmd = dict->getParamCommand(name);
274
275                if (cmd)
276                {
277                    return cmd->doGet(this);
278                }
279            }
280
281            // Fallback
282            return "";
283        }
284        /** Method for copying this object's parameters to another object.
285        @remarks
286            This method takes the values of all the object's parameters and tries to set the
287            same values on the destination object. This provides a completely type independent
288            way to copy parameters to other objects. Note that because of the String manipulation
289            involved, this should not be regarded as an efficient process and should be saved for
290            times outside of the rendering loop.
291        @par
292            Any unrecognised parameters will be ignored as with setParameter method.
293        @param dest Pointer to object to have it's parameters set the same as this object.
294
295        */
296        virtual void copyParametersTo(StringInterface* dest) const
297        {
298            // Get dictionary
299            const ParamDictionary* dict = getParamDictionary();
300
301            if (dict)
302            {
303                // Iterate through own parameters
304                ParameterList::const_iterator i;
305           
306                for (i = dict->mParamDefs.begin();
307                i != dict->mParamDefs.end(); ++i)
308                {
309                    dest->setParameter(i->name, getParameter(i->name));
310                }
311            }
312
313
314        }
315
316        /** Cleans up the static 'msDictionary' required to reset Ogre,
317        otherwise the containers are left with invalid pointers, which will lead to a crash
318        as soon as one of the ResourceManager implementers (e.g. MaterialManager) initializes.*/
319        static void cleanupDictionary () ;
320
321    };
322
323
324
325}
326
327#endif
328
Note: See TracBrowser for help on using the repository browser.