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