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     @headerfile registry.h wx/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      HKEY_CLASSES_ROOT (HKCR)
  21      HKEY_CURRENT_USER (HKCU)
  22      HKEY_LOCAL_MACHINE (HKLM)
  23      HKEY_CURRENT_CONFIG (HKCC)
  24      HKEY_USERS (HKU)
  25
  26     After creating a key, it can hold a value. The values can be:
  27
  28      String Value
  29      Binary Value
  30      DWORD Value
  31      Multi String Value
  32      Expandable String Value
  33
  34
  35     @library{wxbase}
  36     @category{FIXME}
  37 */
  38 class wxRegKey
  39 {
  40 public:
  41     //@{
  42     /**
  43         The constructor to set the full name of the key under a previously created
  44         parent.
  45     */
  46     wxRegKey();
  47     wxRegKey(const wxString& strKey);
  48     wxRegKey(const wxRegKey& keyParent, const wxString& strKey);
  49     //@}
  50
  51     /**
  52         Closes the key.
  53     */
  54     void Close();
  55
  56     /**
  57         Creates the key. Will fail if the key already exists and @a bOkIfExists is
  58         @false.
  59     */
  60     bool Create(bool bOkIfExists = true);
  61
  62     /**
  63         Deletes the subkey with all of its subkeys/values recursively.
  64     */
  65     void DeleteKey(const wxChar* szKey);
  66
  67     /**
  68         Deletes this key and all of its subkeys and values recursively.
  69     */
  70     void DeleteSelf();
  71
  72     /**
  73         Deletes the named value.
  74     */
  75     void DeleteValue(const wxChar* szKey);
  76
  77     /**
  78         Returns @true if the key exists.
  79     */
  80     static bool Exists() const;
  81
  82     /**
  83         Gets the first key.
  84     */
  85     bool GetFirstKey(wxString& strKeyName, long& lIndex);
  86
  87     /**
  88         Gets the first value of this key.
  89     */
  90     bool GetFirstValue(wxString& strValueName, long& lIndex);
  91
  92     /**
  93         Gets information about the key.
  94
  95         @param pnSubKeys
  96             The number of subkeys.
  97         @param pnMaxKeyLen
  98             The maximum length of the subkey name.
  99         @param pnValues
 100             The number of values.
 101         @param pnMaxValueLen
 102             The maximum length of a value.
 103     */
 104     bool GetKeyInfo(size_t* pnSubKeys, size_t* pnValues,
 105                     size_t* pnMaxValueLen) const;
 106
 107     /**
 108         Gets the name of the registry key.
 109     */
 110     wxString GetName(bool bShortPrefix = true) const;
 111
 112     /**
 113         Gets the next key.
 114     */
 115     bool GetNextKey(wxString& strKeyName, long& lIndex) const;
 116
 117     /**
 118         Gets the next key value for this key.
 119     */
 120     bool GetNextValue(wxString& strValueName, long& lIndex) const;
 121
 122     /**
 123         Returns @true if given subkey exists.
 124     */
 125     bool HasSubKey(const wxChar* szKey) const;
 126
 127     /**
 128         Returns @true if any subkeys exist.
 129     */
 130     bool HasSubKeys() const;
 131
 132     /**
 133         Returns @true if the value exists.
 134     */
 135     bool HasValue(const wxChar* szValue) const;
 136
 137     /**
 138         Returns @true if any values exist.
 139     */
 140     bool HasValues() const;
 141
 142     /**
 143         Returns @true if this key is empty, nothing under this key.
 144     */
 145     bool IsEmpty() const;
 146
 147     /**
 148         Returns @true if the key is opened.
 149     */
 150     bool IsOpened() const;
 151
 152     /**
 153         Explicitly opens the key. This method also allows the key to be opened in
 154         read-only mode by passing @c Read() instead of default
 155         @c Write() parameter.
 156     */
 157     bool Open(AccessMode mode = Write);
 158
 159     //@{
 160     /**
 161         Retrieves the numeric value.
 162     */
 163     bool QueryValue(const wxChar* szValue, wxString& strValue) const;
 164     const bool QueryValue(const wxChar* szValue, long* plValue) const;
 165     //@}
 166
 167     /**
 168         Renames the key.
 169     */
 170     bool Rename(const wxChar* szNewName);
 171
 172     /**
 173         Renames a value.
 174     */
 175     bool RenameValue(const wxChar* szValueOld,
 176                      const wxChar* szValueNew);
 177
 178     //@{
 179     /**
 180         Sets the given @a szValue which must be numeric, string or binary depending
 181         on the overload used. If the value doesn't exist, it is created.
 182     */
 183     bool SetValue(const wxChar* szValue, long lValue);
 184     bool SetValue(const wxChar* szValue,
 185                   const wxString& strValue);
 186     bool SetValue(const wxChar* szValue,
 187                   const wxMemoryBuffer& buf);
 188     //@}
 189 };
 190