move wxDataFormat and wxDataObject docs at the beginning of the file, before the...

[wxWidgets.git] / interface / wx / msw / registry.h

diff --git a/interface/wx/msw/registry.h b/interface/wx/msw/registry.h
index 2a1f149ef7dfc470be11050c6cae0369184b63dd..cf1c200c7e5aef23d20c77a4b7875781c01d86a2 100644 (file)
--- a/interface/wx/msw/registry.h
+++ b/interface/wx/msw/registry.h
@@ -32,9 +32,6 @@
 
     @onlyfor{wxmsw}
 
 
     @onlyfor{wxmsw}
 

-    @library{wxbase}
-    @category{misc}
-

     @b Example:
 
     @code
     @b Example:
 
     @code


@@ -64,6 +61,10 @@
         key->GetNextKey(key_name, 1);
     }
     @endcode
         key->GetNextKey(key_name, 1);
     }
     @endcode

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

 */
 class wxRegKey
 {
 */
 class wxRegKey
 {


@@ -76,6 +77,11 @@ public:
         The constructor to set the full name of the key.
     */
     wxRegKey(const wxString& strKey);
         The constructor to set the full name of the key.
     */
     wxRegKey(const wxString& strKey);

+    /**
+        The constructor to set the full name of the key using one of the
+        standard keys, that is, HKCR, HKCU, HKLM, HKUSR, HKPD, HKCC or HKDD.
+    */
+    wxRegKey(StdKey keyParent, const wxString& strKey);

     /**
         The constructor to set the full name of the key under a previously created
         parent.
     /**
         The constructor to set the full name of the key under a previously created
         parent.


@@ -87,8 +93,43 @@ public:
     */
     enum AccessMode
     {
     */
     enum AccessMode
     {

-        Read,   ///< Read-only
-        Write   ///< Read and Write
+        Read, ///< Read-only
+        Write ///< Read and Write
+    };
+
+    /**
+        The standard registry key enumerator.
+    */
+    enum StdKey
+    {
+    HKCR,  ///< HKEY_CLASSES_ROOT
+    HKCU,  ///< HKEY_CURRENT_USER
+    HKLM,  ///< HKEY_LOCAL_MACHINE
+    HKUSR, ///< HKEY_USERS
+    HKPD,  ///< HKEY_PERFORMANCE_DATA (Windows NT and 2K only)
+    HKCC,  ///< HKEY_CURRENT_CONFIG
+    HKDD,  ///< HKEY_DYN_DATA (Windows 95 and 98 only)
+    HKMAX
+    };
+
+    /**
+        The value type enumerator.
+    */
+    enum ValueType
+    {
+    Type_None,                ///< No value type
+    Type_String,              ///< Unicode null-terminated string
+    Type_Expand_String,       ///< Unicode null-terminated string
+                              ///< (with environment variable references)
+    Type_Binary,              ///< Free form binary
+    Type_Dword,               ///< 32-bit number
+    Type_Dword_little_endian, ///< 32-bit number (same as Type_Dword)
+    Type_Dword_big_endian,    ///< 32-bit number
+    Type_Link,                ///< Symbolic Link (Unicode)
+    Type_Multi_String,        ///< Multiple Unicode strings
+    Type_Resource_list,       ///< Resource list in the resource map
+    Type_Full_resource_descriptor,  ///< Resource list in the hardware description
+    Type_Resource_requirements_list ///<

     };
 
     /**
     };
 
     /**


@@ -97,25 +138,43 @@ public:
     void Close();
 
     /**
     void Close();
 
     /**

-        Creates the key. Will fail if the key already exists and @a bOkIfExists is
-        @false.
+        Copy the entire contents of the key recursively to another location
+        using the name. Returns @true if successful.
+    */
+    bool Copy(const wxString& szNewName);
+    /**
+        Copy the entire contents of the key recursively to another location
+        using the key. Returns @true if successful.
+    */
+    bool Copy(wxRegKey& keyDst);
+
+    /**
+        Copy the value to another key, possibly changing its name. By default
+        it will remain the same. Returns @true if successful.
+    */
+    bool CopyValue(const wxString& szValue, wxRegKey& keyDst,
+                  const wxString& szNewName = wxEmptyString);
+    /**
+        Creates the key. Will fail if the key already exists and @a bOkIfExists
+        is @false. Returns @true if successful.

     */
     bool Create(bool bOkIfExists = true);
 
     /**
     */
     bool Create(bool bOkIfExists = true);
 
     /**

-        Deletes the subkey with all of its subkeys/values recursively.
+        Deletes the subkey with all its subkeys and values recursively.

     */
     */

-    void DeleteKey(const wxChar* szKey);
+    void DeleteKey(const wxString& szKey);

 
     /**
 
     /**

-        Deletes this key and all of its subkeys and values recursively.
+        Deletes this key and all its subkeys and values recursively.

     */
     void DeleteSelf();
 
     /**
     */
     void DeleteSelf();
 
     /**

-        Deletes the named value.
+        Deletes the named value or use an empty string argument to remove the
+        default value of the key.

     */
     */

-    void DeleteValue(const wxChar* szKey);
+    void DeleteValue(const wxString& szKey);

 
     /**
         Returns @true if the key exists.
 
     /**
         Returns @true if the key exists.


@@ -123,17 +182,30 @@ public:
     bool Exists() const;
 
     /**
     bool Exists() const;
 
     /**

-        Gets the first key.
+        Write the contents of this key and all its subkeys to the given file.
+        (The file will not be overwritten; it's an error if it already exists.)
+        Note that we export the key in REGEDIT4 format, not RegSaveKey() binary
+        format nor the newer REGEDIT5. Returns @true if successful.
+    */
+    bool Export(const wxString& filename) const;
+    /**
+        Write the contents of this key and all its subkeys to the opened stream.
+        Returns @true if successful.
+    */
+    bool Export(wxOutputStream& ostr) const;
+
+    /**
+        Gets the first key. Returns @true if successful.

     */
     bool GetFirstKey(wxString& strKeyName, long& lIndex);
 
     /**
     */
     bool GetFirstKey(wxString& strKeyName, long& lIndex);
 
     /**

-        Gets the first value of this key.
+        Gets the first value of this key. Returns @true if successful.

     */
     bool GetFirstValue(wxString& strValueName, long& lIndex);
 
     /**
     */
     bool GetFirstValue(wxString& strValueName, long& lIndex);
 
     /**

-        Gets information about the key.
+        Gets information about the key. Returns @true if successful.

 
         @param pnSubKeys
             The number of subkeys.
 
         @param pnSubKeys
             The number of subkeys.


@@ -153,19 +225,24 @@ public:
     wxString GetName(bool bShortPrefix = true) const;
 
     /**
     wxString GetName(bool bShortPrefix = true) const;
 
     /**

-        Gets the next key.
+        Gets the next key. Returns @true if successful.

     */
     bool GetNextKey(wxString& strKeyName, long& lIndex) const;
 
     /**
     */
     bool GetNextKey(wxString& strKeyName, long& lIndex) const;
 
     /**

-        Gets the next key value for this key.
+        Gets the next key value for this key. Returns @true if successful.

     */
     bool GetNextValue(wxString& strValueName, long& lIndex) const;
 
     */
     bool GetNextValue(wxString& strValueName, long& lIndex) const;
 

+    /**
+        Gets the value type.
+    */
+    ValueType GetValueType(const wxString& szValue) const;
+

     /**
         Returns @true if given subkey exists.
     */
     /**
         Returns @true if given subkey exists.
     */

-    bool HasSubKey(const wxChar* szKey) const;
+    bool HasSubKey(const wxString& szKey) const;

 
     /**
         Returns @true if any subkeys exist.
 
     /**
         Returns @true if any subkeys exist.


@@ -175,7 +252,7 @@ public:
     /**
         Returns @true if the value exists.
     */
     /**
         Returns @true if the value exists.
     */

-    bool HasValue(const wxChar* szValue) const;
+    bool HasValue(const wxString& szValue) const;

 
     /**
         Returns @true if any values exist.
 
     /**
         Returns @true if any values exist.


@@ -187,52 +264,101 @@ public:
     */
     bool IsEmpty() const;
 
     */
     bool IsEmpty() const;
 

+    /**
+        Returns @true if the value contains a number.
+    */
+    bool IsNumericValue(const wxString& szValue) const;
+

     /**
         Returns @true if the key is opened.
     */
     bool IsOpened() const;
 
     /**
     /**
         Returns @true if the key is opened.
     */
     bool IsOpened() const;
 
     /**

-        Explicitly opens the key. This method also allows the key to be opened in
-        read-only mode by passing wxRegKey::Read instead of default
-        wxRegKey::Write parameter.
+        Explicitly opens the key. This method also allows the key to be opened
+        in read-only mode by passing wxRegKey::Read instead of default
+        wxRegKey::Write parameter. Returns @true if successful.

     */
     bool Open(AccessMode mode = Write);
 
     /**
     */
     bool Open(AccessMode mode = Write);
 
     /**

-        Retrieves the string value.
+        Assignment operator to set the default value of the key.
+    */
+    wxRegKey& operator=(const wxString& strValue);
+
+    /**
+        Return the default value of the key.
+    */
+    wxString QueryDefaultValue() const;
+
+    /**
+        Retrieves the raw string value. Returns @true if successful.
+    */
+    bool QueryRawValue(const wxString& szValue, wxString& strValue) const;
+
+    /**
+        Retrieves the raw or expanded string value. Returns @true if successful.
+    */
+    bool QueryValue(const wxString& szValue, wxString& strValue, bool raw) const;
+
+    /**
+        Retrieves the numeric value. Returns @true if successful.
+    */
+    bool QueryValue(const wxString& szValue, long* plValue) const;
+
+    /**
+        Retrieves the binary structure. Returns @true if successful.
+    */
+    bool QueryValue(const wxString& szValue, wxMemoryBuffer& buf) const;
+
+    /**
+        Renames the key. Returns @true if successful.

     */
     */

-    bool QueryValue(const wxChar* szValue, wxString& strValue) const;
+    bool Rename(const wxString& szNewName);

 
     /**
 
     /**

-        Retrieves the numeric value.
+        Renames a value. Returns @true if successful.

     */
     */

-    const bool QueryValue(const wxChar* szValue, long* plValue) const;
+    bool RenameValue(const wxString& szValueOld,
+                     const wxString& szValueNew);

 
     /**
 
     /**

-        Renames the key.
+        Preallocate some memory for the name. For wxRegConfig usage only.

     */
     */

-    bool Rename(const wxChar* szNewName);
+    void ReserveMemoryForName(size_t bytes);

 
     /**
 
     /**

-        Renames a value.
+        Set or change the HKEY handle.
+    */
+    void SetHkey(WXHKEY hKey);
+
+    /**
+        Set the full key name. The name is absolute. It should start with
+        HKEY_xxx.
+    */
+    void SetName(const wxString& strKey);
+    /**
+        Set the name relative to the parent key
+    */
+    void SetName(StdKey keyParent, const wxString& strKey);
+    /**
+        Set the name relative to the parent key

     */
     */

-    bool RenameValue(const wxChar* szValueOld,
-                     const wxChar* szValueNew);
+    void SetName(const wxRegKey& keyParent, const wxString& strKey);

 
     /**
 
     /**

-        Sets the given @a szValue which must be numeric.
-        If the value doesn't exist, it is created.
+        Sets the given @a szValue which must be numeric. If the value doesn't
+        exist, it is created. Returns @true if successful.

     */
     */

-    bool SetValue(const wxChar* szValue, long lValue);
+    bool SetValue(const wxString& szValue, long lValue);

     /**
     /**

-        Sets the given @a szValue which must be string.
-        If the value doesn't exist, it is created.
+        Sets the given @a szValue which must be string. If the value doesn't
+        exist, it is created. Returns @true if successful.

     */
     */

-    bool SetValue(const wxChar* szValue, const wxString& strValue);
+    bool SetValue(const wxString& szValue, const wxString& strValue);

     /**
     /**

-        Sets the given @a szValue which must be binary.
-        If the value doesn't exist, it is created.
+        Sets the given @a szValue which must be binary. If the value doesn't
+        exist, it is created. Returns @true if successful.

     */
     */

-    bool SetValue(const wxChar* szValue, const wxMemoryBuffer& buf);
+    bool SetValue(const wxString& szValue, const wxMemoryBuffer& buf);

 };
 };