interface/msw/registry.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        msw/registry.h
   3 // Purpose:     interface of wxRegKey
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRegKey
  11     @wxheader{msw/registry.h}
  12
  13     wxRegKey is a class representing the Windows registry (it is only available
  14     under Windows). One can create, query and delete registry keys using this
  15     class.
  16
  17     The Windows registry is easy to understand. There are five registry keys,
  18     namely:
  19
  20     @li HKEY_CLASSES_ROOT (HKCR)
  21     @li HKEY_CURRENT_USER (HKCU)
  22     @li HKEY_LOCAL_MACHINE (HKLM)
  23     @li HKEY_CURRENT_CONFIG (HKCC)
  24     @li HKEY_USERS (HKU)
  25
  26     After creating a key, it can hold a value. The values can be:
  27
  28     @li String Value
  29     @li Binary Value
  30     @li DWORD Value
  31     @li Multi String Value
  32     @li Expandable String Value
  33
  34     @onlyfor{wxmsw}
  35
  36     @library{wxbase}
  37     @category{misc}
  38
  39     @b Example:
  40
  41     @code
  42     wxRegKey *key = new wxRegKey("HKEY_LOCAL_MACHINE\\Software\\MyKey");
  43
  44     // Create the key if it does not exist.
  45     if( !key->Exists() )
  46         key->Create();
  47
  48     // Create a new value "MYVALUE" and set it to 12.
  49     key->SetValue("MYVALUE", 12);
  50
  51     // Read the value back.
  52     long value;
  53     key->QueryValue("MYVALUE", &value);
  54     wxMessageBox(wxString::Format("%d", value), "Registry Value", wxOK);
  55
  56     // Get the number of subkeys and enumerate them.
  57     size_t subkeys;
  58     key->GetKeyInfo(&subkeys, NULL, NULL, NULL);
  59
  60     wxString key_name;
  61     key->GetFirstKey(key_name, 1);
  62     for(int i = 0; i < subkeys; i++)
  63     {
  64         wxMessageBox(key_name, "Subkey Name", wxOK);
  65         key->GetNextKey(key_name, 1);
  66     }
  67     @endcode
  68 */
  69 class wxRegKey
  70 {
  71 public:
  72     /**
  73         Default constructor, initializes to HKCR.
  74     */
  75     wxRegKey();
  76     /**
  77         The constructor to set the full name of the key.
  78     */
  79     wxRegKey(const wxString& strKey);
  80     /**
  81         The constructor to set the full name of the key under a previously created
  82         parent.
  83     */
  84     wxRegKey(const wxRegKey& keyParent, const wxString& strKey);
  85
  86     /**
  87         Access modes for wxRegKey.
  88     */
  89     enum AccessMode
  90     {
  91         Read,   ///< Read-only
  92         Write   ///< Read and Write
  93     };
  94
  95     /**
  96         Closes the key.
  97     */
  98     void Close();
  99
 100     /**
 101         Creates the key. Will fail if the key already exists and @a bOkIfExists is
 102         @false.
 103     */
 104     bool Create(bool bOkIfExists = true);
 105
 106     /**
 107         Deletes the subkey with all of its subkeys/values recursively.
 108     */
 109     void DeleteKey(const wxChar* szKey);
 110
 111     /**
 112         Deletes this key and all of its subkeys and values recursively.
 113     */
 114     void DeleteSelf();
 115
 116     /**
 117         Deletes the named value.
 118     */
 119     void DeleteValue(const wxChar* szKey);
 120
 121     /**
 122         Returns @true if the key exists.
 123     */
 124     bool Exists() const;
 125
 126     /**
 127         Gets the first key.
 128     */
 129     bool GetFirstKey(wxString& strKeyName, long& lIndex);
 130
 131     /**
 132         Gets the first value of this key.
 133     */
 134     bool GetFirstValue(wxString& strValueName, long& lIndex);
 135
 136     /**
 137         Gets information about the key.
 138
 139         @param pnSubKeys
 140             The number of subkeys.
 141         @param pnMaxKeyLen
 142             The maximum length of the subkey name.
 143         @param pnValues
 144             The number of values.
 145         @param pnMaxValueLen
 146             The maximum length of a value.
 147     */
 148     bool GetKeyInfo(size_t* pnSubKeys, size_t* pnMaxKeyLen,
 149                     size_t* pnValues, size_t* pnMaxValueLen) const;
 150
 151     /**
 152         Gets the name of the registry key.
 153     */
 154     wxString GetName(bool bShortPrefix = true) const;
 155
 156     /**
 157         Gets the next key.
 158     */
 159     bool GetNextKey(wxString& strKeyName, long& lIndex) const;
 160
 161     /**
 162         Gets the next key value for this key.
 163     */
 164     bool GetNextValue(wxString& strValueName, long& lIndex) const;
 165
 166     /**
 167         Returns @true if given subkey exists.
 168     */
 169     bool HasSubKey(const wxChar* szKey) const;
 170
 171     /**
 172         Returns @true if any subkeys exist.
 173     */
 174     bool HasSubKeys() const;
 175
 176     /**
 177         Returns @true if the value exists.
 178     */
 179     bool HasValue(const wxChar* szValue) const;
 180
 181     /**
 182         Returns @true if any values exist.
 183     */
 184     bool HasValues() const;
 185
 186     /**
 187         Returns @true if this key is empty, nothing under this key.
 188     */
 189     bool IsEmpty() const;
 190
 191     /**
 192         Returns @true if the key is opened.
 193     */
 194     bool IsOpened() const;
 195
 196     /**
 197         Explicitly opens the key. This method also allows the key to be opened in
 198         read-only mode by passing wxRegKey::Read instead of default
 199         wxRegKey::Write parameter.
 200     */
 201     bool Open(AccessMode mode = Write);
 202
 203     /**
 204         Retrieves the string value.
 205     */
 206     bool QueryValue(const wxChar* szValue, wxString& strValue) const;
 207
 208     /**
 209         Retrieves the numeric value.
 210     */
 211     const bool QueryValue(const wxChar* szValue, long* plValue) const;
 212
 213     /**
 214         Renames the key.
 215     */
 216     bool Rename(const wxChar* szNewName);
 217
 218     /**
 219         Renames a value.
 220     */
 221     bool RenameValue(const wxChar* szValueOld,
 222                      const wxChar* szValueNew);
 223
 224     /**
 225         Sets the given @a szValue which must be numeric.
 226         If the value doesn't exist, it is created.
 227     */
 228     bool SetValue(const wxChar* szValue, long lValue);
 229     /**
 230         Sets the given @a szValue which must be string.
 231         If the value doesn't exist, it is created.
 232     */
 233     bool SetValue(const wxChar* szValue, const wxString& strValue);
 234     /**
 235         Sets the given @a szValue which must be binary.
 236         If the value doesn't exist, it is created.
 237     */
 238     bool SetValue(const wxChar* szValue, const wxMemoryBuffer& buf);
 239 };