interface/msw/registry.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        msw/registry.h
   3 // Purpose:     documentation for wxRegKey class
   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 @e 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();
  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
  98         @param pnMaxKeyLen
  99         The maximum length of the subkey name.
 100
 101         @param pnValues
 102         The number of values.
 103
 104         @param pnMaxValueLen
 105         The maximum length of a value.
 106     */
 107     bool GetKeyInfo(size_t * pnSubKeys, size_t * pnValues,
 108                     size_t * pnMaxValueLen);
 109
 110     /**
 111         Gets the name of the registry key.
 112     */
 113     wxString GetName(bool bShortPrefix = @true);
 114
 115     /**
 116         Gets the next key.
 117     */
 118     bool GetNextKey(wxString& strKeyName, long& lIndex);
 119
 120     /**
 121         Gets the next key value for this key.
 122     */
 123     bool GetNextValue(wxString& strValueName, long& lIndex);
 124
 125     /**
 126         Returns @true if given subkey exists.
 127     */
 128     bool HasSubKey(const wxChar * szKey);
 129
 130     /**
 131         Returns @true if any subkeys exist.
 132     */
 133     bool HasSubKeys();
 134
 135     /**
 136         Returns @true if the value exists.
 137     */
 138     bool HasValue(const wxChar * szValue);
 139
 140     /**
 141         Returns @true if any values exist.
 142     */
 143     bool HasValues();
 144
 145     /**
 146         Returns @true if this key is empty, nothing under this key.
 147     */
 148     bool IsEmpty();
 149
 150     /**
 151         Returns @true if the key is opened.
 152     */
 153     bool IsOpened();
 154
 155     /**
 156         Explicitly opens the key. This method also allows the key to be opened in
 157         read-only mode by passing @c Read() instead of default
 158         @c Write() parameter.
 159     */
 160     bool Open(AccessMode mode = Write);
 161
 162     //@{
 163     /**
 164         Retrieves the numeric value.
 165     */
 166     bool QueryValue(const wxChar * szValue, wxString& strValue);
 167     bool QueryValue(const wxChar * szValue, long * plValue);
 168     //@}
 169
 170     /**
 171         Renames the key.
 172     */
 173     bool Rename(const wxChar * szNewName);
 174
 175     /**
 176         Renames a value.
 177     */
 178     bool RenameValue(const wxChar * szValueOld,
 179                      const wxChar * szValueNew);
 180
 181     //@{
 182     /**
 183         Sets the given @e szValue which must be numeric, string or binary depending
 184         on the overload used. If the value doesn't exist, it is created.
 185     */
 186     bool SetValue(const wxChar * szValue, long lValue);
 187     bool SetValue(const wxChar * szValue,
 188                   const wxString& strValue);
 189     bool SetValue(const wxChar * szValue,
 190                   const wxMemoryBuffer& buf);
 191     //@}
 192 };