Fix typo in wxStandardPathsBase::ResourceCat description and document it.

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

diff --git a/interface/wx/config.h b/interface/wx/config.h
index b2504846e505e7bd04639e02001163684d0ac992..1aa8db02a3003e15b907b7cae5afcd293c8a6ebe 100644 (file)
--- a/interface/wx/config.h
+++ b/interface/wx/config.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxConfigBase
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxConfigBase
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -16,11 +16,10 @@
     However, usually you don't even need to know the precise nature of the
     class you're working with but you would just use the wxConfigBase methods.
     This allows you to write the same code regardless of whether you're working
     However, usually you don't even need to know the precise nature of the
     class you're working with but you would just use the wxConfigBase methods.
     This allows you to write the same code regardless of whether you're working

-    with the registry under Win32 or text-based config files under Unix (or
-    even Windows 3.1 .INI files if you're really unlucky). To make writing the
-    portable code even easier, wxWidgets provides a typedef wxConfig which is
-    mapped onto the native wxConfigBase implementation on the given platform:
-    i.e. wxRegConfig under Win32 and wxFileConfig otherwise.
+    with the registry under Windows or text-based config files under Unix. 
+    To make writing the portable code even easier, wxWidgets provides a typedef 
+    wxConfig which is mapped onto the native wxConfigBase implementation on the 
+    given platform: i.e. wxRegConfig under Windows and wxFileConfig otherwise.

 
     See @ref overview_config for a description of all features of this class.
 
 
     See @ref overview_config for a description of all features of this class.
 


@@ -255,7 +254,7 @@
 
 
     @library{wxbase}
 
 
     @library{wxbase}

-    @category{misc}
+    @category{cfg}

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


@@ -281,39 +280,39 @@ public:
             Some config classes require a global filename. If this is not
             present, but required, the application name will be used instead.
         @param style
             Some config classes require a global filename. If this is not
             present, but required, the application name will be used instead.
         @param style

-            Can be one of wxCONFIG_USE_LOCAL_FILE and wxCONFIG_USE_GLOBAL_FILE.
-            The style interpretation depends on the config class and is ignored
+            Can be one of @c wxCONFIG_USE_LOCAL_FILE and @c wxCONFIG_USE_GLOBAL_FILE.
+            @n The style interpretation depends on the config class and is ignored

             by some implementations. For wxFileConfig, these styles determine
             whether a local or global config file is created or used: if
             by some implementations. For wxFileConfig, these styles determine
             whether a local or global config file is created or used: if

-            wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the
-            global config file and if wxCONFIG_USE_LOCAL_FILE is used, settings
+            @c wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the
+            global config file and if @c wxCONFIG_USE_LOCAL_FILE is used, settings

             are read from and written to local config file (if they are both
             set, global file is read first, then local file, overwriting global
             settings). If the flag is present but the parameter is empty, the
             parameter will be set to a default. If the parameter is present but
             the style flag not, the relevant flag will be added to the style.
             are read from and written to local config file (if they are both
             set, global file is read first, then local file, overwriting global
             settings). If the flag is present but the parameter is empty, the
             parameter will be set to a default. If the parameter is present but
             the style flag not, the relevant flag will be added to the style.

-            For wxRegConfig, thie GLOBAL flag refers to HKLM key while LOCAL
-            one is for the usual HKCU one.
-            @n For wxFileConfig you can also add wxCONFIG_USE_RELATIVE_PATH by
+            For wxRegConfig, the GLOBAL flag refers to the @c HKLM key while LOCAL
+            one is for the usual @c HKCU one.
+            @n For wxFileConfig you can also add @c wxCONFIG_USE_RELATIVE_PATH by

             logically or'ing it to either of the _FILE options to tell
             wxFileConfig to use relative instead of absolute paths.
             @n On non-VMS Unix systems, the default local configuration file is
             "~/.appname". However, this path may be also used as user data
             directory (see wxStandardPaths::GetUserDataDir()) if the
             application has several data files. In this case
             logically or'ing it to either of the _FILE options to tell
             wxFileConfig to use relative instead of absolute paths.
             @n On non-VMS Unix systems, the default local configuration file is
             "~/.appname". However, this path may be also used as user data
             directory (see wxStandardPaths::GetUserDataDir()) if the
             application has several data files. In this case

-            wxCONFIG_USE_SUBDIR flag, which changes the default local
+            @c wxCONFIG_USE_SUBDIR flag, which changes the default local

             configuration file to "~/.appname/appname" should be used. Notice
             configuration file to "~/.appname/appname" should be used. Notice

-            that this flag is ignored if localFilename is provided.
-            wxCONFIG_USE_SUBDIR is new since wxWidgets version 2.8.2.
+            that this flag is ignored if @a localFilename is provided.
+            @c wxCONFIG_USE_SUBDIR is new since wxWidgets version 2.8.2.

             @n For wxFileConfig, you can also add
             @n For wxFileConfig, you can also add

-            wxCONFIG_USE_NO_ESCAPE_CHARACTERS which will turn off character
+            @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS which will turn off character

             escaping for the values of entries stored in the config file: for
             example a foo key with some backslash characters will be stored as
             "foo=C:\mydir" instead of the usual storage of "foo=C:\\mydir".
             escaping for the values of entries stored in the config file: for
             example a foo key with some backslash characters will be stored as
             "foo=C:\mydir" instead of the usual storage of "foo=C:\\mydir".

-            @n The wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your
+            @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,
             config file must be read or written to by a non-wxWidgets program
             (which might not understand the escape characters). Note, however,

-            that if wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is
+            that if @c wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is 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.


@@ -348,14 +347,14 @@ public:
     /**
         Retrieve the current path (always as absolute path).
     */
     /**
         Retrieve the current path (always as absolute path).
     */

-    const wxString GetPath() const;
+    virtual const wxString& GetPath() const = 0;

 
     /**
         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.
     */
 
     /**
         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.
     */

-    void SetPath(const wxString& strPath);
+    virtual void SetPath(const wxString& strPath) = 0;

 
     //@}
 
 
     //@}
 


@@ -374,8 +373,13 @@ public:
         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
         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).
+        @endWxPerlOnly

     */
     */

-    bool GetFirstEntry(wxString& str, long& index) const;
+    virtual bool GetFirstEntry(wxString& str, long& index) const = 0;

 
     /**
         Gets the first group.
 
     /**
         Gets the first group.


@@ -384,8 +388,13 @@ public:
         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
         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).
+        @endWxPerlOnly

     */
     */

-    bool GetFirstGroup(wxString& str, long& index) const;
+    virtual bool GetFirstGroup(wxString& str, long& index) const = 0;

 
     /**
         Gets the next entry.
 
     /**
         Gets the next entry.


@@ -394,8 +403,14 @@ public:
         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
         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,
+        index_for_getnextentry).
+        @endWxPerlOnly

     */
     */

-    bool GetNextEntry(wxString& str, long& index) const;
+    virtual bool GetNextEntry(wxString& str, long& index) const = 0;

 
     /**
         Gets the next group.
 
     /**
         Gets the next group.


@@ -404,19 +419,25 @@ public:
         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
         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,
+        index_for_getnextentry).
+        @endWxPerlOnly

     */
     */

-    bool GetNextGroup(wxString& str, long& index) const;
+    virtual bool GetNextGroup(wxString& str, long& index) const = 0;

 
     /**
         Get number of entries in the current group.
     */
 
     /**
         Get number of entries in the current group.
     */

-    uint GetNumberOfEntries(bool bRecursive = false) const;
+    virtual size_t GetNumberOfEntries(bool bRecursive = false) const = 0;

 
     /**
         Get number of entries/subgroups in the current group, with or without
         its subgroups.
     */
 
     /**
         Get number of entries/subgroups in the current group, with or without
         its subgroups.
     */

-    uint GetNumberOfGroups(bool bRecursive = false) const;
+    virtual size_t GetNumberOfGroups(bool bRecursive = false) const = 0;

 
     //@}
 
 
     //@}
 


@@ -438,7 +459,7 @@ public:
     /**
         @return @true if either a group or an entry with a given name exists.
     */
     /**
         @return @true if either a group or an entry with a given name exists.
     */

-    bool Exists(wxString& strName) const;
+    bool Exists(const wxString& strName) const;

 
     /**
         Returns the type of the given entry or @e Unknown if the entry doesn't
 
     /**
         Returns the type of the given entry or @e Unknown if the entry doesn't


@@ -447,17 +468,17 @@ public:
         about type mismatch otherwise: e.g., an attempt to read a string value
         from an integer key with wxRegConfig will fail.
     */
         about type mismatch otherwise: e.g., an attempt to read a string value
         from an integer key with wxRegConfig will fail.
     */

-    wxConfigBase::EntryType GetEntryType(const wxString& name) const;
+    virtual wxConfigBase::EntryType GetEntryType(const wxString& name) const;

 
     /**
         @return @true if the entry by this name exists.
     */
 
     /**
         @return @true if the entry by this name exists.
     */

-    bool HasEntry(wxString& strName) const;
+    virtual bool HasEntry(const wxString& strName) const = 0;

 
     /**
         @return @true if the group by this name exists.
     */
 
     /**
         @return @true if the group by this name exists.
     */

-    bool HasGroup(const wxString& strName) const;
+    virtual bool HasGroup(const wxString& strName) const = 0;

 
     //@}
 
 
     //@}
 


@@ -491,11 +512,15 @@ public:
         Permanently writes all changes (otherwise, they're only written from
         object's destructor).
     */
         Permanently writes all changes (otherwise, they're only written from
         object's destructor).
     */

-    bool Flush(bool bCurrentOnly = false);
+    virtual bool Flush(bool bCurrentOnly = false) = 0;

 
     /**
         Read a string from the key, returning @true if the value was read. If
         the key was not found, @a str is not changed.
 
     /**
         Read a string from the key, returning @true if the value was read. If
         the key was not found, @a str is not changed.

+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

     */
     bool Read(const wxString& key, wxString* str) const;
     /**
     */
     bool Read(const wxString& key, wxString* str) const;
     /**


@@ -503,44 +528,107 @@ public:
         was not found.
 
         @return @true if value was really read, @false if the default was used.
         was not found.
 
         @return @true if value was really read, @false if the default was used.

+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

     */
     bool Read(const wxString& key, wxString* str,
               const wxString& defaultVal) const;
     /**
         Another version of Read(), returning the string value directly.
     */
     bool Read(const wxString& key, wxString* str,
               const wxString& defaultVal) const;
     /**
         Another version of Read(), returning the string value directly.

+
+        @beginWxPerlOnly
+        In wxPerl, this can be called as:
+        - Read(key): returns the empty string if no key is found
+        - Read(key, default): returns the default value if no key is found
+        @endWxPerlOnly

     */
     const wxString Read(const wxString& key,
                         const wxString& defaultVal) const;
     /**
         Reads a long value, returning @true if the value was found. If the
         value was not found, @a l is not changed.
     */
     const wxString Read(const wxString& key,
                         const wxString& defaultVal) const;
     /**
         Reads a long value, returning @true if the value was found. If the
         value was not found, @a l is not changed.

+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

     */
     bool Read(const wxString& key, long* l) const;
     /**
         Reads a long value, returning @true if the value was found. If the
         value was not found, @a defaultVal is used instead.
     */
     bool Read(const wxString& key, long* l) const;
     /**
         Reads a long value, returning @true if the value was found. If the
         value was not found, @a defaultVal is used instead.

+
+        @beginWxPerlOnly
+        In wxPerl, this can be called as:
+        - ReadInt(key): returns the 0 if no key is found
+        - ReadInt(key, default): returns the default value if no key is found
+        @endWxPerlOnly

     */
     bool Read(const wxString& key, long* l,
               long defaultVal) const;
     /**
         Reads a double value, returning @true if the value was found. If the
         value was not found, @a d is not changed.
     */
     bool Read(const wxString& key, long* l,
               long defaultVal) const;
     /**
         Reads a double value, returning @true if the value was found. If the
         value was not found, @a d is not changed.

+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

     */
     bool Read(const wxString& key, double* d) const;
     /**
         Reads a double value, returning @true if the value was found. If the
         value was not found, @a defaultVal is used instead.
     */
     bool Read(const wxString& key, double* d) const;
     /**
         Reads a double value, returning @true if the value was found. If the
         value was not found, @a defaultVal is used instead.

+
+        @beginWxPerlOnly
+        In wxPerl, this can be called as:
+        - ReadFloat(key): returns the 0.0 if no key is found
+        - ReadFloat(key, default): returns the default value if no key is found
+        @endWxPerlOnly

     */
     bool Read(const wxString& key, double* d,
                      double defaultVal) const;
     */
     bool Read(const wxString& key, double* d,
                      double defaultVal) const;

+

     /**
     /**

-        Reads a bool value, returning @true if the value was found. If the
+        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.
+
+        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) const;
+    bool Read(const wxString& key, float* f, float defaultVal) const;
+    //@}
+
+    /**
+        Reads a float value, returning @true if the value was found. If the

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

+
+        @since 2.9.1
+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

     */
     bool Read(const wxString& key, bool* b) const;
     /**
         Reads a bool value, returning @true if the value was found. If the
         value was not found, @a defaultVal is used instead.
     */
     bool Read(const wxString& key, bool* b) const;
     /**
         Reads a bool value, returning @true if the value was found. If the
         value was not found, @a defaultVal is used instead.

+
+        @beginWxPerlOnly
+        In wxPerl, this can be called as:
+        - ReadBool(key): returns false if no key is found
+        - ReadBool(key, default): returns the default value if no key is found
+        @endWxPerlOnly

     */
     bool Read(const wxString& key, bool* d,
               bool defaultVal) const;
     */
     bool Read(const wxString& key, bool* d,
               bool defaultVal) const;


@@ -567,13 +655,13 @@ public:
         Reads a bool value from the key and returns it. @a defaultVal is
         returned if the key is not found.
     */
         Reads a bool value from the key and returns it. @a defaultVal is
         returned if the key is not found.
     */

-    long ReadBool(const wxString& key, bool defaultVal) const;
+    bool ReadBool(const wxString& key, bool defaultVal) const;

 
     /**
         Reads a double value from the key and returns it. @a defaultVal is
         returned if the key is not found.
     */
 
     /**
         Reads a double value from the key and returns it. @a defaultVal is
         returned if the key is not found.
     */

-    long ReadDouble(const wxString& key, double defaultVal) const;
+    double ReadDouble(const wxString& key, double defaultVal) const;

 
     /**
         Reads a long value from the key and returns it. @a defaultVal is
 
     /**
         Reads a long value from the key and returns it. @a defaultVal is


@@ -600,6 +688,14 @@ public:
     /**
         Writes the double value to the config file and returns @true on
         success.
     /**
         Writes the double value to the config file and returns @true on
         success.

+
+        Notice that if floating point numbers are saved as strings (as is the
+        case with the configuration files used by wxFileConfig), this function
+        uses the C locale for writing out the number, i.e. it will always use a
+        period as the decimal separator, irrespectively of the current locale.
+        This behaviour is new since wxWidgets 2.9.1 as the current locale was
+        used before, but the change should be transparent because both C and
+        current locales are tried when reading the numbers back.

     */
     bool Write(const wxString& key, double value);
     /**
     */
     bool Write(const wxString& key, double value);
     /**


@@ -639,7 +735,8 @@ public:
         @return @false if @a oldName doesn't exist or if @a newName already
                 exists.
     */
         @return @false if @a oldName doesn't exist or if @a newName already
                 exists.
     */

-    bool RenameEntry(const wxString& oldName, const wxString& newName);
+    virtual bool RenameEntry(const wxString& oldName,
+                             const wxString& newName) = 0;

 
     /**
         Renames a subgroup of the current group. The subgroup names (both the
 
     /**
         Renames a subgroup of the current group. The subgroup names (both the


@@ -649,7 +746,8 @@ public:
         @return @false if @a oldName doesn't exist or if @a newName already
                 exists.
     */
         @return @false if @a oldName doesn't exist or if @a newName already
                 exists.
     */

-    bool RenameGroup(const wxString& oldName, const wxString& newName);
+    virtual bool RenameGroup(const wxString& oldName,
+                             const wxString& newName) = 0;

 
     //@}
 
 
     //@}
 


@@ -667,14 +765,14 @@ public:
         Delete the whole underlying object (disk file, registry key, ...).
         Primarly for use by uninstallation routine.
     */
         Delete the whole underlying object (disk file, registry key, ...).
         Primarly for use by uninstallation routine.
     */

-    bool DeleteAll();
+    virtual bool DeleteAll() = 0;

 
     /**
         Deletes the specified entry and the group it belongs to if it was the
         last key in it and the second parameter is @true.
     */
 
     /**
         Deletes the specified entry and the group it belongs to if it was the
         last key in it and the second parameter is @true.
     */

-    bool DeleteEntry(const wxString& key,
-                     bool bDeleteGroupIfEmpty = true);
+    virtual bool DeleteEntry(const wxString& key,
+                             bool bDeleteGroupIfEmpty = true) = 0;

 
     /**
         Delete the group (with all subgroups). If the current path is under the
 
     /**
         Delete the group (with all subgroups). If the current path is under the


@@ -682,7 +780,7 @@ public:
         component. E.g. if the current path is @c "/A/B/C/D" and the group @c C
         is deleted, the path becomes @c "/A/B".
     */
         component. E.g. if the current path is @c "/A/B/C/D" and the group @c C
         is deleted, the path becomes @c "/A/B".
     */

-    bool DeleteGroup(const wxString& key);
+    virtual bool DeleteGroup(const wxString& key) = 0;

 
     //@}
 
 
     //@}