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