MezzanineEngine 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
objectsettings.h
1 // © Copyright 2010 - 2014 BlackTopp Studios Inc.
2 /* This file is part of The Mezzanine Engine.
3 
4  The Mezzanine Engine is free software: you can redistribute it and/or modify
5  it under the terms of the GNU General Public License as published by
6  the Free Software Foundation, either version 3 of the License, or
7  (at your option) any later version.
8 
9  The Mezzanine Engine is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  GNU General Public License for more details.
13 
14  You should have received a copy of the GNU General Public License
15  along with The Mezzanine Engine. If not, see <http://www.gnu.org/licenses/>.
16 */
17 /* The original authors have included a copy of the license specified above in the
18  'Docs' folder. See 'gpl.txt'
19 */
20 /* We welcome the use of the Mezzanine engine to anyone, including companies who wish to
21  Build professional software and charge for their product.
22 
23  However there are some practical restrictions, so if your project involves
24  any of the following you should contact us and we will try to work something
25  out:
26  - DRM or Copy Protection of any kind(except Copyrights)
27  - Software Patents You Do Not Wish to Freely License
28  - Any Kind of Linking to Non-GPL licensed Works
29  - Are Currently In Violation of Another Copyright Holder's GPL License
30  - If You want to change our code and not add a few hundred MB of stuff to
31  your distribution
32 
33  These and other limitations could cause serious legal problems if you ignore
34  them, so it is best to simply contact us or the Free Software Foundation, if
35  you have any questions.
36 
37  Joseph Toppi - toppij@gmail.com
38  John Blackwood - makoenergy02@gmail.com
39 */
40 #ifndef _objectsettings_h
41 #define _objectsettings_h
42 
43 #include "datatypes.h"
44 #include "vector2.h"
45 #include "vector3.h"
46 #include "quaternion.h"
47 #include "colourvalue.h"
48 #include "countedptr.h"
49 #ifndef SWIG
50  #include "XML/xml.h"
51 #endif
52 
53 namespace Mezzanine
54 {
55  class ObjectSettingSet;
56  class ObjectSettingFile;
57  class ObjectSettingGroup;
58  ///////////////////////////////////////////////////////////////////////////////
59  /// @class ObjectSettingSetContainer
60  /// @headerfile objectsettings.h
61  /// @brief A base class for other classes that store ObjectSettingSet's.
62  /// @details
63  ///////////////////////////////////////
65  {
66  public:
67  /// @brief Basic container type for @ref ObjectSettingSet storage by this class.
68  typedef std::vector<ObjectSettingSet*> SubSetVector;
69  /// @brief Iterator type for @ref ObjectSettingSet instances stored by this class.
70  typedef SubSetVector::iterator SubSetIterator;
71  /// @brief Const Iterator type for @ref ObjectSettingSet instances stored by this class.
72  typedef SubSetVector::const_iterator ConstSubSetIterator;
73  protected:
74  /// @internal
75  /// @brief The name of this container.
77  /// @internal
78  /// @brief A container of @ref ObjectSettingSet instances owned by this container.
80  public:
81  /// @brief Class constructor.
82  /// @param Name The name of this container.
83  ObjectSettingSetContainer(const String& Name);
84  /// @brief Class destructor.
85  virtual ~ObjectSettingSetContainer();
86 
87  ///////////////////////////////////////////////////////////////////////////////
88  // Utility
89 
90  /// @brief Sets the name of this container.
91  /// @param Name The name to be given to this container.
92  void SetName(const String& Name);
93  /// @brief Gets the name of this container.
94  /// @return Returns a const reference to the name of this container.
95  ConstString& GetName() const;
96 
97  ///////////////////////////////////////////////////////////////////////////////
98  // Sub-Set Methods
99 
100  /// @brief Creates a new SettingSet as a child of this container.
101  /// @param Name The name of the new set to be created.
102  /// @return Returns a pointer to the created SettingSet.
103  virtual ObjectSettingSet* CreateChildObjectSettingSet(const String& Name);
104  /// @brief Adds a SettingSet as a child of this container.
105  /// @param ToBeAdded Pointer to the SettingSet to be added.
106  virtual void AddChildObjectSettingSet(ObjectSettingSet* ToBeAdded);
107  /// @brief Gets a Sub-Set of this container by name.
108  /// @remarks This class does not enforce unique names for child sets. Only settings are forced
109  /// to have unique names. So when searching for an object by name there can be multiples. Which
110  /// one you get is determined by the Which parameter.
111  /// @param Name The name of the desired Sub-Set.
112  /// @param Which Which named SettingSet to get. 0 for the first, 1 for the second, and so on.
113  /// @return Returns a pointer to the named Sub-Set, or NULL if it doesn't exist.
114  ObjectSettingSet* GetChildObjectSettingSet(const String& Name, UInt16 Which = 0) const;
115  /// @brief Gets a Sub-Set of this container by index.
116  /// @param Index The index of the Sub-Set to get.
117  /// @return Returns a pointer to the Sub-Set at the specified index.
118  ObjectSettingSet* GetChildObjectSettingSet(const Whole& Index) const;
119  /// @brief Removes a Sub-Set of this container.
120  /// @param ToBeRemoved The Sub-Set to be removed.
121  virtual void RemoveChildObjectSettingSet(ObjectSettingSet* ToBeRemoved);
122  /// @brief Destroys a Sub-Set of this container.
123  /// @param Name The name of the Sub-Set to be destroyed.
124  void DestroyChildObjectSettingSet(const String& Name);
125  /// @brief Destroys all child Sub-Sets of this container.
126  void DestroyAllObjectSettingSets();
127 
128  ///////////////////////////////////////////////////////////////////////////////
129  // Iterator Access
130 
131  /// @brief Gets an iterator to the first subset of settings in this set.
132  SubSetIterator SubSetBegin();
133  /// @brief Gets a const iterator to the first subset of settings in this set.
134  ConstSubSetIterator SubSetBegin() const;
135  /// @brief Gets an iterator to one passed the last subset of settings in this set.
136  SubSetIterator SubSetEnd();
137  /// @brief Gets a const iterator to one passed the last subset of settings in this set.
138  ConstSubSetIterator SubSetEnd() const;
139 
140  ///////////////////////////////////////////////////////////////////////////////
141  // Internal Methods
142 
143  /// @internal
144  /// @brief Marks this container and relevant parent containers as updated.
145  virtual void _MarkUpdated() = 0;
146  };//ObjectSettingSetContainer
147 
148  ///////////////////////////////////////////////////////////////////////////////
149  /// @class ObjectSettingSet
150  /// @headerfile objectsettings.h
151  /// @brief A class that store's a named set of settings for an object.
152  /// @details
153  ///////////////////////////////////////
155  {
156  public:
157  /// @brief Basic container type for settings stored as name-value pairs in this class.
158  typedef std::map<String,String> SettingsMap;
159  /// @brief Iterator type for settings stored by this class.
160  typedef SettingsMap::iterator SettingsIterator;
161  /// @brief Const Iterator type for settings stored by this class.
162  typedef SettingsMap::const_iterator ConstSettingsIterator;
163  protected:
164  friend class ObjectSettingSetContainer;
165  /// @internal
166  /// @brief A map container storing the settings owned by this set and their values.
168  /// @internal
169  /// @brief A pointer to the parent container of this ObjectSettingSet.
171  public:
172  /// @brief Class constructor.
173  /// @param Name The name of this set.
174  ObjectSettingSet(const String& Name);
175  /// @brief Class destructor.
176  virtual ~ObjectSettingSet();
177 
178  ///////////////////////////////////////////////////////////////////////////////
179  // Utility
180 
181  /// @brief Gets the Parent SettingsSet to this set.
182  /// @return Returns a pointer to this object's parent, or NULL if it doesn't have one.
183  ObjectSettingSetContainer* GetParentSetOrGroup() const;
184 
185  ///////////////////////////////////////////////////////////////////////////////
186  // Setting Methods
187 
188  /// @brief Sets a setting in this set...of settings.
189  /// @param SettingName The name of the new setting.
190  /// @param StringValue A String containing the value to be given to this setting.
191  void SetSettingValue(const String& SettingName, const String& StringValue);
192  /// @brief Gets a String representing the Value currently assigned to the existing setting.
193  /// @param SettingName The name of the setting desired.
194  /// @return Returns an String containing the requested setting. If the setting does not exist then the String will be empty.
195  String GetSettingValue(const String& SettingName) const;
196 
197  ///////////////////////////////////////////////////////////////////////////////
198  // Iterator Access
199 
200  /// @brief Gets an iterator to the first setting in this set.
201  SettingsIterator SettingsBegin();
202  /// @brief Gets a const iterator to the first setting in this set.
203  ConstSettingsIterator SettingsBegin() const;
204  /// @brief Gets an iterator to one passed the last setting in this set.
205  SettingsIterator SettingsEnd();
206  /// @brief Gets a const iterator to one passed the last setting in this set.
207  ConstSettingsIterator SettingsEnd() const;
208 
209  ///////////////////////////////////////////////////////////////////////////////
210  // Internal Methods
211 
212  /// @copydoc ObjectSettingSetContainer::_MarkUpdated()
213  void _MarkUpdated();
214  };//ObjectSettingSet
215 
216  ///////////////////////////////////////////////////////////////////////////////
217  /// @class ObjectSettingGroup
218  /// @headerfile objectsettings.h
219  /// @brief A class that store's a collection of SettingSets that can be applied together.
220  /// @details
221  ///////////////////////////////////////
223  {
224  protected:
225  /// @internal
226  /// @brief A pointer to the @ref ObjectSettingFile instance this setting group will be saved to.
228  public:
229  /// @brief Class constructor.
230  /// @param Name The name to be given to this group.
231  ObjectSettingGroup(const String& Name);
232  /// @brief Class destructor.
233  virtual ~ObjectSettingGroup();
234 
235  ///////////////////////////////////////////////////////////////////////////////
236  // Optional File config
237 
238  /// @brief Gets the Setting file instance this group will be saved to.
239  /// @return Returns a pointer to the setting file this group belongs to.
240  ObjectSettingFile* GetOptionalFile() const;
241  /// @brief Gets the file name this group will be saved to.
242  /// @return Returns a const reference to the currently set file name. String will be empty if this is not set.
243  const String& GetOptionalFileName() const;
244 
245  ///////////////////////////////////////////////////////////////////////////////
246  // Internal Methods
247 
248  /// @copydoc ObjectSettingSetContainer::_MarkUpdated()
249  void _MarkUpdated();
250  /// @brief Sets the file this group will be saved to.
251  /// @param File The file this group should be saved to when saving the configuration.
252  void _SetOptionalFile(ObjectSettingFile* File);
253  };//ObjectSettingGroup
254 
255  ///////////////////////////////////////////////////////////////////////////////
256  /// @class ObjectSettingFile
257  /// @headerfile objectsettings.h
258  /// @brief This class represents a file to be saved containing one or more OhjectSettingGroup's.
259  /// @details
260  ///////////////////////////////////////
262  {
263  public:
264  /// @brief Basic container type for @ref ObjectSettingGroup storage by this class.
265  typedef std::vector< ObjectSettingGroup* > SaveGroupsContainer;
266  /// @brief Iterator type for @ref ObjectSettingGroup instances stored by this class.
267  typedef SaveGroupsContainer::iterator SaveGroupsIterator;
268  /// @brief Const Iterator type for @ref ObjectSettingGroup instances stored by this class.
269  typedef SaveGroupsContainer::const_iterator ConstSaveGroupsIterator;
270  protected:
271  /// @internal
272  /// @brief A container of @ref ObjectSettingGroup instances that will be saved to the file representing by this.
274  /// @internal
275  /// @brief The name of the file the stored @ref ObjectSettingGroup instances will be saved to.
277  /// @internal
278  /// @brief Stores whether or not the settings have been updated and this file needs to be saved/refreshed.
279  Boolean NeedsSave;
280  public:
281  /// @brief Class constructor.
282  /// @param FileName The name of the file the groups in this class will be saved to.
283  ObjectSettingFile(const String& FileName);
284  /// @brief Class destructor.
286 
287  ///////////////////////////////////////////////////////////////////////////////
288  // File and Group Management
289 
290  /// @brief Gets the name of the file.
291  /// @return Returns a const reference to the name of this file.
292  const String& GetFileName() const;
293  /// @brief Sets whether or not this file needs saving.
294  /// @param Save Whetehr or not this file has been updated and needs to be saved.
295  void SetNeedsSave(Boolean Save);
296  /// @brief Gets whether or not this file has been updated and needs to be saved.
297  /// @return Returns true if this file needs to be saved, false otherwise.
298  Boolean GetNeedsSave() const;
299 
300  /// @brief Adds a group to be saved to this file.
301  /// @param Group The group to be added to this file.
302  void AddGroup(ObjectSettingGroup* Group);
303  /// @brief Gets a group being saved to this file.
304  /// @param Name The name of the group to get.
305  /// @return Returns a pointer to the named group in this file, or NULL if it does not exist in this file.
306  ObjectSettingGroup* GetGroup(const String& Name) const;
307  /// @brief Removes a group from this file.
308  /// @param Group The group to be removed.
309  void RemoveGroup(ObjectSettingGroup* Group);
310  /// @brief Gets the container with the groups to be saved to this file.
311  /// @return Returns a reference to the container containing all the groups that are to be saved to this file.
312  SaveGroupsContainer& GetGroups();
313 
314  /// @brief Gets an iterator to the first group in this file.
315  SaveGroupsIterator SaveGroupsBegin();
316  /// @brief Gets a const iterator to the first group in this file.
317  ConstSaveGroupsIterator SaveGroupsBegin() const;
318  /// @brief Gets an iterator to one-passed the last group in this file.
319  SaveGroupsIterator SaveGroupsEnd();
320  /// @brief Gets a const iterator to one-passed the last group in this file.
321  ConstSaveGroupsIterator SaveGroupsEnd() const;
322  };//ObjectSettingsFile
323 
324  ///////////////////////////////////////////////////////////////////////////////
325  /// @class ObjectSettingsHandler
326  /// @headerfile objectsettings.h
327  /// @brief An abstract class for other classes that manage groups of settings.
328  /// @details
329  ///////////////////////////////////////
331  {
332  public:
333  /// @brief Basic container type for @ref ObjectSettingGroup storage by this class.
334  typedef std::map<String,ObjectSettingGroup*> SettingGroupContainer;
335  /// @brief Iterator type for @ref ObjectSettingGroup instances stored by this class.
336  typedef SettingGroupContainer::iterator SettingGroupIterator;
337  /// @brief Const Iterator type for @ref ObjectSettingGroup instances stored by this class.
338  typedef SettingGroupContainer::const_iterator ConstSettingGroupIterator;
339  /// @brief Basic container type for @ref ObjectSettingFile storage by this class.
340  typedef std::map<String,ObjectSettingFile*> SettingFilesContainer;
341  /// @brief Iterator type for @ref ObjectSettingGroup instances stored by this class.
342  typedef SettingFilesContainer::iterator SettingFilesIterator;
343  /// @brief Const Iterator type for @ref ObjectSettingGroup instances stored by this class.
344  typedef SettingFilesContainer::const_iterator ConstSettingFilesIterator;
345  /// @brief Convenience typedef for Load method returns.
346  typedef std::vector<ObjectSettingGroup*> SettingGroupVector;
347  protected:
348  /// @internal
349  /// @brief A container storing all the SettingGroups owned by this handler.
351  /// @internal
352  /// @brief A container storing all the file saving configuration used by this handler.
354  /// @internal
355  /// @brief Stores whether or not this handler will attempt to automatically generate a path to a file if it doesn't exist.
356  Boolean AutoGenPath;
357  /// @internal
358  /// @brief Stores whether or not this handler will attempt to automatically generate a file if it doesn't exist.
359  Boolean AutoGenFiles;
360  /// @internal
361  /// @brief Stores the path to be used for file IO operations done by this handler.
363  /// @internal
364  /// @brief Stores the name of the file where the "Current" settings group will be saved to.
366 
367  /// @internal
368  /// @brief Loads all @ref ObjectSettingGroup instances serialized to a XML file into usable @ref ObjectSettingGroup instances.
369  /// @param FileName The name of the file to be loaded.
370  /// @param Path The path to the file to be loaded.
371  /// @return Returns a CountedPtr to a container of the loaded @ref ObjectSettingGroup instances.
372  CountedPtr<SettingGroupVector> LoadSettingsFromFile(const String& FileName, const String& Path);
373  /// @internal
374  /// @brief Saves a collection of ObjectSettingGroups stored by this handler to a file as XML.
375  /// @param GroupNames A container storing all the names of of the @ref ObjectSettingGroup instances to be saved.
376  /// @param FileName The name of the file to be saved at.
377  /// @param Path The path to the file being saved.
378  void SaveSettingsToFile(StringVector& GroupNames, const String& FileName, const String& Path);
379  /// @internal
380  /// @brief Populates an ObjectSettingSet with settings stored in XML.
381  /// @param XMLNode The XML node storing the serialized ObjectSettingSet.
382  /// @param Set The ObjectSettingSet to be populated with usable settings.
383  void LoadSettingSetFromXML(XML::Node& XMLNode, ObjectSettingSet* Set);
384  /// @internal
385  /// @brief Saves an ObjectSettingSet to an XML node.
386  /// @param XMLNode The XML node to be written with the settings of the provided set.
387  /// @param Set The ObjectSettingSet to be written to XML.
388  void SaveSettingSetToXML(XML::Node& XMLNode, ObjectSettingSet* Set);
389  /// @internal
390  /// @brief Gets the name to be given to a Node with this handlers serialized data.
391  /// @return Returns a String containing the name to be given to the XML::Node storing this handlers data.
392  virtual String GetObjectRootNodeName() const = 0;
393  /// @internal
394  /// @brief Takes all the current settings of this handler and serializes them to an XML::Node.
395  /// @param CurrentNode The XML::Node to be populated with this handlers current settings.
396  virtual void AppendCurrentSettings(XML::Node& CurrentNode) = 0;
397  /// @internal
398  /// @brief Applies all the settings stored by a @ref ObjectSettingGroup.
399  /// @param Group The @ref ObjectSettingGroup to have all of it's settings applied.
400  virtual void ApplySettingGroupImpl(ObjectSettingGroup* Group) = 0;
401  public:
402  /// @brief Class constructor.
404  /// @brief Class destructor.
405  virtual ~ObjectSettingsHandler();
406 
407  ///////////////////////////////////////////////////////////////////////////////
408  // Setting Group Handling
409 
410  /// @brief Applies all the settings (and their values) defined in a setting group.
411  /// @param GroupName The name of the setting group to apply.
412  void ApplySettingGroup(const String& GroupName);
413  /// @brief Creates a new blank setting group that can have it's settings populated.
414  /// @param Name The name to be given to the new settings group.
415  /// @return Returns a pointer to the newly created setting group.
416  ObjectSettingGroup* CreateSettingGroup(const String& Name);
417  /// @brief Gets a setting group by name.
418  /// @param Name The name of the setting group to get.
419  /// @return Returns a pointer to the named setting group.
420  ObjectSettingGroup* GetSettingGroup(const String& Name) const;
421  /// @brief Destroys a setting group by name.
422  /// @param Name The name of the setting group to destroy.
423  void DestroySettingGroup(const String& Name);
424  /// @brief Destroys a setting group.
425  /// @param ToBeDestroyed A pointer to the group that will be destroyed.
426  void DestroySettingGroup(ObjectSettingGroup* ToBeDestroyed);
427  /// @brief Destroys all setting groups stored in this handler.
428  void DestroyAllSettingGroups();
429 
430  ///////////////////////////////////////////////////////////////////////////////
431  // Setting File Handling
432 
433  /// @brief Creates a new Setting file that will track which groups are a part of it.
434  /// @param FileName The name of the file this instance cooresponds to.
435  /// @return Returns a pointer to the created ObjectSettingFile.
436  ObjectSettingFile* CreateSettingFile(const String& FileName);
437  /// @brief Gets a Setting file by name.
438  /// @param FileName The name of the setting file to get.
439  /// @return Returns a pointer to the named setting file.
440  ObjectSettingFile* GetSettingFile(const String& FileName);
441  /// @brief Destroys a Setting file by name.
442  /// @note This does not destroy any saved files on disk, only the helper class(es) that have been allocated in memory.
443  /// @param FileName The name of the setting file to be destroyed.
444  void DestroySettingFile(const String& FileName);
445  /// @brief Destroys a Setting file.
446  /// @note This does not destroy any saved files on disk, only the helper class(es) that have been allocated in memory.
447  /// @param ToBeDestroyed The setting file to be destroyed.
448  void DestroySettingFile(ObjectSettingFile* ToBeDestroyed);
449  /// @brief Destroys all Setting files in this handler.
450  /// @note This does not destroy any saved files on disk, only the helper class(es) that have been allocated in memory.
451  void DestroyAllSettingFiles();
452  /// @brief Assigns a SettingGroup to a file name that will be used when settings are saved.
453  /// @param Group The setting group getting it's optional file name updated.
454  /// @param FileName The name of the file the provided group will be added to.
455  void AddGroupToFile(ObjectSettingGroup* Group, const String& FileName);
456  /// @brief Removes a previously assigned group from a save file name.
457  /// @param Group The setting group getting removed from it's current optional file name.
458  /// @param FileName The name of the file the provided group will be removed from.
459  void RemoveGroupFromFile(ObjectSettingGroup* Group, const String& FileName);
460 
461  ///////////////////////////////////////////////////////////////////////////////
462  // Setting Saving/Path Handling
463 
464  /// @brief Sets the path to be assumed when saving/loading settings to files.
465  /// @param Path The path to be assumed.
466  void SetSettingsFilePath(const String& Path);
467  /// @brief Gets the currently set settings file path.
468  /// @return Returns a string containing the path to use when a save/load path isn't specified.
469  const String& GetSettingsFilePath() const;
470  /// @brief Sets the name of the file that will have this object's "current" settings saved to.
471  /// @details Any group labeled "Current" (case sensative) will be used and immediately applied upon loading. @n
472  /// If this is enabled and no group specifiers are used, then the Current settings will automatically be saved any time the groups are saved.
473  /// When using functions with group specifiers, you can include a string "Current" to save the current settings. @n
474  /// It's also important to note that the "Current" settings group, although it'll be present in saved files, is not a group traversible in code.
475  /// It is solely intended to save the existing state at shutdown, and resume with that exact config.
476  /// @param FileName Name of the file to save the current settings to.
477  void SetCurrentSettingsSaveFile(const String& FileName);
478  /// @brief Gets the name of the file the "Current" setting group is saved to.
479  /// @return Returns string ref to the name of the file current settings are being saved to, or an empty string if one is not set.
480  ConstString& GetCurrentSettingsSaveFile() const;
481 
482  ///////////////////////////////////////////////////////////////////////////////
483  // Loading Utilities
484 
485  /// @brief Loads settings from a settings file.
486  /// @param FileName The name of the file to load and parse.
487  /// @param Group The asset group where the file can be found.
488  /// @return Returns a vector containing all the setting groups that were created while loading settings.
489  CountedPtr<SettingGroupVector> LoadSettingsFromGroup(const String& FileName, const String& Group);
490  /// @brief Loads settings from a settings file.
491  /// @param FileName The name of the file to load and parse.
492  /// @param Path The filesystem path where the file can be found.
493  /// @return Returns a vector containing all the setting groups that were created while loading settings.
494  CountedPtr<SettingGroupVector> LoadSettings(const String& FileName, const String& Path);
495  /// @brief Loads settings from a settings file using the specified settings path.
496  /// @note Using this function means it will use the preset settings file path stored in this handler.
497  /// The path must be set before calling this.
498  /// @param FileName The name of the file to load and parse.
499  /// @return Returns a vector containing all the setting groups that were created while loading settings.
500  CountedPtr<SettingGroupVector> LoadSettings(const String& FileName);
501  /// @brief Loads settings from an xml node.
502  /// @param RootSettings The node that reprsents the root of the settings group or groups.
503  /// @return Returns a vector containing all the setting groups that were created while loading settings.
504  CountedPtr<SettingGroupVector> LoadSettingsFromXML(XML::Node& RootSettings);
505 
506  ///////////////////////////////////////////////////////////////////////////////
507  // Saving Utilities
508 
509  /// @brief Enables or disables the automatic creation of a directory path when saving.
510  /// @param Enable True to allow this object to create folders in the intended save path allowing the path to be valid, false otherwise.
511  void SetAutoGenPath(Boolean Enable);
512  /// @brief Gets whether or not this object is currently allowed to create folders when saving.
513  /// @return Returns true if this object will create folders in paths it uses to force the path to be valid.
514  Boolean GetAutoGenPath() const;
515  /// @brief Enables or disables the automatic creation of settings files on initialization and destruction of this object.
516  /// @param Enable True to allow this object to save it's settings sets to a file on initialization and destruction.
517  void SetAutoGenFiles(Boolean Enable);
518  /// @brief Gets whether or not this object is currently allowed to create/update settings files upon initialization and destruction.
519  /// @return Returns true if this object will generate or update settings files when it is initialized and destruction.
520  Boolean GetAutoGenFiles() const;
521 
522  /// @brief Saves all settings that need saving.
523  /// @remarks This function does a few things. First it will only save the setting groups which have their optional setting
524  /// files specified, which is automatically set if they are loaded from a file. Second, it will only save the files(and
525  /// their collection of Setting Groups) that are marked as needing saving to prevent unnessessary IO.
526  void SaveAllSettings();
527  /// @brief Saves all settings that have their optional filename set to the specified file.
528  /// @param Filename The optional filename that will be used to determine which groups will be saved, and to what file.
529  /// @param Path The path to place the file being saved.
530  void SaveSettingsByFile(const String& FileName, const String& Path);
531  /// @brief Saves all settings that have their optional filename set to the specified file.
532  /// @note Using this function means it will use the preset settings file path stored in this handler.
533  /// The path must be set before calling this.
534  /// @param Filename The optional filename that will be used to determine which groups will be saved, and to what file.
535  void SaveSettingsByFile(const String& FileName);
536  /// @brief Saves all settings to a settings file.
537  /// @remarks This function bypasses the file utilities offered by this class and just writes the specified groups to the named
538  /// file. It will not make a coresponding file class and this file will not be auto saved at any point later. This is just an
539  /// explicit utility function for writing groups to the disk should you need it. In general it is better to create a file class
540  /// and populate it with groups yourself.
541  /// @param GroupNames A string vector containing the names for all the settings groups to save.
542  /// @param Filename The name of the file to save the current settings to.
543  /// @param Path The path to place the file being saved.
544  void SaveSettingGroups(StringVector& GroupNames, const String& FileName, const String& Path);
545  /// @brief Saves all settings to a settings file using the specified settings path.
546  /// @note Using this function means it will use the preset settings file path stored in this handler.
547  /// The path must be set before calling this otherwise an exception will be thrown.
548  /// @remarks This function bypasses the file utilities offered by this class and just writes the specified groups to the named
549  /// file. It will not make a coresponding file class and this file will not be auto saved at any point later. This is just an
550  /// explicit utility function for writing groups to the disk should you need it. In general it is better to create a file class
551  /// and populate it with groups yourself.
552  /// @param GroupNames A string vector containing the names for all the settings groups to save.
553  /// @param Filename The name of the file to save the current settings to.
554  void SaveSettingGroups(StringVector& GroupNames, const String& FileName);
555  /// @brief Saves all the current setting groups as children of the provided XML node.
556  /// @param SaveCurrent Whether or not to also save the current settings to XML.
557  /// @param RootSettings The node to populate with all currently loaded settings groups.
558  void SaveSettingsToXML(XML::Node& RootSettings, Boolean SaveCurrent = true);
559  /// @brief Saves the named settings groups as children of the provided XML node.
560  /// @param GroupNames A string vector containing the names for all the settings groups to save.
561  /// @param RootSettings The node to populate with all currently loaded settings groups.
562  void SaveSettingsToXML(StringVector& GroupNames, XML::Node& RootSettings);
563  };//ObjectSettingsHandler
564 }//Mezzanine
565 
566 #endif