Recognize VC12 (a.k.a. MSVS 2013) and define __VISUALC12__ for it.

[wxWidgets.git] / interface / wx / config.h

diff --git a/interface/wx/config.h b/interface/wx/config.h
index 48f0095514cebbeee036a7be58d9ac79f4b3df62..a5c930c7d3691af0806a040461d0ef8d536a687f 100644 (file)
--- a/interface/wx/config.h
+++ b/interface/wx/config.h
@@ -6,6 +6,18 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 

+
+// Flags for constructor style parameter
+enum
+{
+    wxCONFIG_USE_LOCAL_FILE = 1,
+    wxCONFIG_USE_GLOBAL_FILE = 2,
+    wxCONFIG_USE_RELATIVE_PATH = 4,
+    wxCONFIG_USE_NO_ESCAPE_CHARACTERS = 8,
+    wxCONFIG_USE_SUBDIR = 16
+};
+
+

 /**
     @class wxConfigBase
 
 /**
     @class wxConfigBase
 


@@ -240,21 +252,10 @@
     contain an arbitrary path (either relative or absolute), not just the
     key name.
 
     contain an arbitrary path (either relative or absolute), not just the
     key name.
 

-    @beginWxPythonOnly
-    In place of a single overloaded method name, wxPython implements the
-    following methods:
-    - Read(key, default="") - Returns a string.
-    - ReadInt(key, default=0) - Returns an integer.
-    - ReadFloat(key, default=0.0) - Returns a floating point number.
-    - ReadBool(key, default=0) - Returns a boolean.
-    - Write(key, value) - Writes a string.
-    - WriteInt(key, value) - Writes an int.
-    - WriteFloat(key, value) - Writes a floating point number.
-    @endWxPythonOnly
-
-

     @library{wxbase}
     @category{cfg}
     @library{wxbase}
     @category{cfg}

+    
+    @see wxConfigPathChanger

 */
 class wxConfigBase : public wxObject
 {
 */
 class wxConfigBase : public wxObject
 {


@@ -312,7 +313,7 @@ public:
             @n The @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your
             config file must be read or written to by a non-wxWidgets program
             (which might not understand the escape characters). Note, however,
             @n The @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your
             config file must be read or written to by a non-wxWidgets program
             (which might not understand the escape characters). Note, however,

-            that if @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is
+            that if @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is

             now your application's responsibility to ensure that there is no
             newline or other illegal characters in a value, before writing that
             value to the file.
             now your application's responsibility to ensure that there is no
             newline or other illegal characters in a value, before writing that
             value to the file.


@@ -352,7 +353,9 @@ public:
     /**
         Set current path: if the first character is '/', it is the absolute
         path, otherwise it is a relative path. '..' is supported. If @a strPath
     /**
         Set current path: if the first character is '/', it is the absolute
         path, otherwise it is a relative path. '..' is supported. If @a strPath

-        doesn't exist it is created.
+        doesn't exist, it is created.
+        
+        @see wxConfigPathChanger

     */
     virtual void SetPath(const wxString& strPath) = 0;
 
     */
     virtual void SetPath(const wxString& strPath) = 0;
 


@@ -369,11 +372,6 @@ public:
     /**
         Gets the first entry.
 
     /**
         Gets the first entry.
 

-        @beginWxPythonOnly
-        The wxPython version of this method returns a 3-tuple consisting of the
-        continue flag, the value string, and the index for the next call.
-        @endWxPythonOnly
-

         @beginWxPerlOnly
         In wxPerl this method takes no parameters and returns a 3-element
         list (continue_flag, string, index_for_getnextentry).
         @beginWxPerlOnly
         In wxPerl this method takes no parameters and returns a 3-element
         list (continue_flag, string, index_for_getnextentry).


@@ -384,11 +382,6 @@ public:
     /**
         Gets the first group.
 
     /**
         Gets the first group.
 

-        @beginWxPythonOnly
-        The wxPython version of this method returns a 3-tuple consisting of the
-        continue flag, the value string, and the index for the next call.
-        @endWxPythonOnly
-

         @beginWxPerlOnly
         In wxPerl this method takes no parameters and returns a 3-element
         list (continue_flag, string, index_for_getnextentry).
         @beginWxPerlOnly
         In wxPerl this method takes no parameters and returns a 3-element
         list (continue_flag, string, index_for_getnextentry).


@@ -399,11 +392,6 @@ public:
     /**
         Gets the next entry.
 
     /**
         Gets the next entry.
 

-        @beginWxPythonOnly
-        The wxPython version of this method returns a 3-tuple consisting of the
-        continue flag, the value string, and the index for the next call.
-        @endWxPythonOnly
-

         @beginWxPerlOnly
         In wxPerl this method only takes the @a index parameter and
         returns a 3-element list (continue_flag, string,
         @beginWxPerlOnly
         In wxPerl this method only takes the @a index parameter and
         returns a 3-element list (continue_flag, string,


@@ -415,11 +403,6 @@ public:
     /**
         Gets the next group.
 
     /**
         Gets the next group.
 

-        @beginWxPythonOnly
-        The wxPython version of this method returns a 3-tuple consisting of the
-        continue flag, the value string, and the index for the next call.
-        @endWxPythonOnly
-

         @beginWxPerlOnly
         In wxPerl this method only takes the @a index parameter and
         returns a 3-element list (continue_flag, string,
         @beginWxPerlOnly
         In wxPerl this method only takes the @a index parameter and
         returns a 3-element list (continue_flag, string,


@@ -592,8 +575,7 @@ public:
     /**
         Reads a float value, returning @true if the value was found.
 
     /**
         Reads a float value, returning @true if the value was found.
 

-        With the second overload, if the value was not found, @a defaultVal is
-        used instead.
+        If the value was not found, @a f is not changed.

 
         Notice that the value is read as a double but must be in a valid range
         for floats for the function to return @true.
 
         Notice that the value is read as a double but must be in a valid range
         for floats for the function to return @true.


@@ -604,13 +586,25 @@ public:
         Not supported by wxPerl.
         @endWxPerlOnly
     */
         Not supported by wxPerl.
         @endWxPerlOnly
     */

-    //@{

     bool Read(const wxString& key, float* f) const;
     bool Read(const wxString& key, float* f) const;

+    /**
+        Reads a float value, returning @true if the value was found.
+
+        If the value was not found, @a defaultVal is used instead.
+
+        Notice that the value is read as a double but must be in a valid range
+        for floats for the function to return @true.
+
+        @since 2.9.1
+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly
+    */

     bool Read(const wxString& key, float* f, float defaultVal) const;
     bool Read(const wxString& key, float* f, float defaultVal) const;

-    //@}

 
     /**
 
     /**

-        Reads a float value, returning @true if the value was found. If the
+        Reads a boolean value, returning @true if the value was found. If the

         value was not found, @a b is not changed.
 
         @since 2.9.1
         value was not found, @a b is not changed.
 
         @since 2.9.1


@@ -621,7 +615,7 @@ public:
     */
     bool Read(const wxString& key, bool* b) const;
     /**
     */
     bool Read(const wxString& key, bool* b) const;
     /**

-        Reads a bool value, returning @true if the value was found. If the
+        Reads a boolean value, returning @true if the value was found. If the

         value was not found, @a defaultVal is used instead.
 
         @beginWxPerlOnly
         value was not found, @a defaultVal is used instead.
 
         @beginWxPerlOnly


@@ -763,7 +757,7 @@ public:
 
     /**
         Delete the whole underlying object (disk file, registry key, ...).
 
     /**
         Delete the whole underlying object (disk file, registry key, ...).

-        Primarly for use by uninstallation routine.
+        Primarily for use by uninstallation routine.

     */
     virtual bool DeleteAll() = 0;
 
     */
     virtual bool DeleteAll() = 0;
 


@@ -891,3 +885,79 @@ public:
     static wxConfigBase* Set(wxConfigBase* pConfig);
 };
 
     static wxConfigBase* Set(wxConfigBase* pConfig);
 };
 

+
+/**
+    @class wxConfigPathChanger
+
+    A handy little class which changes the current path in a wxConfig object and restores it in dtor.
+    Declaring a local variable of this type, it's possible to work in a specific directory 
+    and ensure that the path is automatically restored when the function returns.
+
+    For example:
+    @code
+    // this function loads somes settings from the given wxConfig object;
+    // the path selected inside it is left unchanged
+    bool LoadMySettings(wxConfigBase* cfg)
+    {
+        wxConfigPathChanger changer(cfg, "/Foo/Data/SomeString");
+        wxString str;
+        if ( !config->Read("SomeString", &str) ) {
+            wxLogError("Couldn't read SomeString!");
+            return false;     
+                // NOTE: without wxConfigPathChanger it would be easy to forget to
+                //       set the old path back into the wxConfig object before this return!
+        }
+        
+        // do something useful with SomeString...
+        
+        return true;    // again: wxConfigPathChanger dtor will restore the original wxConfig path
+    }
+    @endcode
+
+    @library{wxbase}
+    @category{cfg}
+*/
+class wxConfigPathChanger
+{
+public:
+
+    /**
+        Changes the path of the given wxConfigBase object so that the key @a strEntry is accessible
+        (for read or write).
+        
+        In other words, the ctor uses wxConfigBase::SetPath() with everything which precedes the 
+        last slash of @a strEntry, so that:
+        @code
+        wxConfigPathChanger(wxConfigBase::Get(), "/MyProgram/SomeKeyName");
+        @endcode        
+        has the same effect of:
+        @code
+        wxConfigPathChanger(wxConfigBase::Get(), "/MyProgram/");
+        @endcode        
+    */
+    wxConfigPathChanger(const wxConfigBase *pContainer, const wxString& strEntry);
+
+    /**
+        Restores the path selected, inside the wxConfig object passed to the ctor, to the path which was 
+        selected when the wxConfigPathChanger ctor was called.
+    */
+    ~wxConfigPathChanger();
+
+    /**
+        Returns the name of the key which was passed to the ctor.
+        The "name" is just anything which follows the last slash of the string given to the ctor.
+    */
+    const wxString& Name() const;
+
+    /**
+        This method must be called if the original path inside the wxConfig object 
+        (i.e. the current path at the moment of creation of this wxConfigPathChanger object) 
+        could have been deleted, thus preventing wxConfigPathChanger from restoring the not 
+        existing (any more) path.
+
+        If the original path doesn't exist any more, the path will be restored to
+        the deepest still existing component of the old path.
+    */
+    void UpdateIfDeleted();
+};
+