Version: 3.1.1

#include <wx/msw/registry.h>

Detailed Description

wxRegKey is a class representing the Windows registry (it is only available under Windows).

One can create, query and delete registry keys using this class.

The Windows registry is easy to understand. There are five registry keys, namely:

  • HKEY_CLASSES_ROOT (HKCR)
  • HKEY_CURRENT_USER (HKCU)
  • HKEY_LOCAL_MACHINE (HKLM)
  • HKEY_CURRENT_CONFIG (HKCC)
  • HKEY_USERS (HKU)

After creating a key, it can hold a value. The values can be:

  • String Value
  • Binary Value
  • DWORD Value
  • Multi String Value
  • Expandable String Value
Availability:  only available for the wxMSW port.

Example:

// This assume that the key already exists, use HasSubKey() to check
// for the key existence if necessary.
wxRegKey key(wxRegKey::HKLM, "Software\\MyKey");
// Create a new value "MyValue" and set it to 12.
key.SetValue("MyValue", 12);
// Read the value back.
long value;
key.QueryValue("MyValue", &value);
wxMessageBox(wxString::Format("%d", value), "Registry Value", wxOK);
// Get the number of subkeys and enumerate them.
size_t subkeys;
key.GetKeyInfo(&subkeys, NULL, NULL, NULL);
wxString key_name;
key.GetFirstKey(key_name, 1);
for(int i = 0; i < subkeys; i++)
{
wxMessageBox(key_name, "Subkey Name", wxOK);
key.GetNextKey(key_name, 1);
}

Library:  wxBase
Category:  Application and System configuration

Public Types

enum  AccessMode {
  Read,
  Write
}
 Access modes for wxRegKey. More...
 
enum  StdKey {
  HKCR,
  HKCU,
  HKLM,
  HKUSR,
  HKPD,
  HKCC,
  HKDD,
  HKMAX
}
 The standard registry key enumerator. More...
 
enum  ValueType {
  Type_None,
  Type_String,
  Type_Expand_String,
  Type_Binary,
  Type_Dword,
  Type_Dword_little_endian,
  Type_Dword_big_endian,
  Type_Link,
  Type_Multi_String,
  Type_Resource_list,
  Type_Full_resource_descriptor,
  Type_Resource_requirements_list
}
 The value type enumerator. More...
 
enum  WOW64ViewMode {
  WOW64ViewMode_Default,
  WOW64ViewMode_32,
  WOW64ViewMode_64
}
 Used to determine how the registry will be viewed, either as 32-bit or 64-bit. More...
 

Public Member Functions

 wxRegKey (WOW64ViewMode viewMode=WOW64ViewMode_Default)
 Default constructor, initializes to HKEY_CLASSES_ROOT. More...
 
 wxRegKey (const wxString &strKey, WOW64ViewMode viewMode=WOW64ViewMode_Default)
 The constructor to set the full name of the key. More...
 
 wxRegKey (StdKey keyParent, const wxString &strKey, WOW64ViewMode viewMode=WOW64ViewMode_Default)
 The constructor to set the full name of the key using one of the standard keys, that is, HKCR, HKCU, HKLM, HKUSR, HKPD (obsolete), HKCC or HKDD (obsolete). More...
 
 wxRegKey (const wxRegKey &keyParent, const wxString &strKey)
 The constructor to set the full name of the key under a previously created parent. More...
 
void Close ()
 Closes the key. More...
 
bool Copy (const wxString &szNewName)
 Copy the entire contents of the key recursively to another location using the name. More...
 
bool Copy (wxRegKey &keyDst)
 Copy the entire contents of the key recursively to another location using the key. More...
 
bool CopyValue (const wxString &szValue, wxRegKey &keyDst, const wxString &szNewName=wxEmptyString)
 Copy the value to another key, possibly changing its name. More...
 
bool Create (bool bOkIfExists=true)
 Creates the key. More...
 
void DeleteKey (const wxString &szKey)
 Deletes the subkey with all its subkeys and values recursively. More...
 
void DeleteSelf ()
 Deletes this key and all its subkeys and values recursively. More...
 
void DeleteValue (const wxString &szKey)
 Deletes the named value or use an empty string argument to remove the default value of the key. More...
 
bool Exists () const
 Returns true if the key exists. More...
 
bool Export (const wxString &filename) const
 Write the contents of this key and all its subkeys to the given file. More...
 
bool Export (wxOutputStream &ostr) const
 Write the contents of this key and all its subkeys to the opened stream. More...
 
bool GetFirstKey (wxString &strKeyName, long &lIndex)
 Gets the first key. More...
 
bool GetFirstValue (wxString &strValueName, long &lIndex)
 Gets the first value of this key. More...
 
bool GetKeyInfo (size_t *pnSubKeys, size_t *pnMaxKeyLen, size_t *pnValues, size_t *pnMaxValueLen) const
 Gets information about the key. More...
 
wxString GetName (bool bShortPrefix=true) const
 Gets the name of the registry key. More...
 
WOW64ViewMode GetView () const
 Retrieves the registry view used by this key. More...
 
bool GetNextKey (wxString &strKeyName, long &lIndex) const
 Gets the next key. More...
 
bool GetNextValue (wxString &strValueName, long &lIndex) const
 Gets the next key value for this key. More...
 
ValueType GetValueType (const wxString &szValue) const
 Gets the value type. More...
 
bool HasSubKey (const wxString &szKey) const
 Returns true if given subkey exists. More...
 
bool HasSubkeys () const
 Returns true if any subkeys exist. More...
 
bool HasValue (const wxString &szValue) const
 Returns true if the value exists. More...
 
bool HasValues () const
 Returns true if any values exist. More...
 
bool IsEmpty () const
 Returns true if this key is empty, nothing under this key. More...
 
bool IsNumericValue (const wxString &szValue) const
 Returns true if the value contains a number. More...
 
bool IsOpened () const
 Returns true if the key is opened. More...
 
bool Open (AccessMode mode=Write)
 Explicitly opens the key. More...
 
wxRegKeyoperator= (const wxString &strValue)
 Assignment operator to set the default value of the key. More...
 
wxString QueryDefaultValue () const
 Return the default value of the key. More...
 
bool QueryRawValue (const wxString &szValue, wxString &strValue) const
 Retrieves the raw string value. More...
 
bool QueryValue (const wxString &szValue, wxString &strValue, bool raw) const
 Retrieves the raw or expanded string value. More...
 
bool QueryValue (const wxString &szValue, long *plValue) const
 Retrieves the numeric value. More...
 
bool QueryValue (const wxString &szValue, wxMemoryBuffer &buf) const
 Retrieves the binary structure. More...
 
bool Rename (const wxString &szNewName)
 Renames the key. More...
 
bool RenameValue (const wxString &szValueOld, const wxString &szValueNew)
 Renames a value. More...
 
void ReserveMemoryForName (size_t bytes)
 Preallocate some memory for the name. More...
 
void SetHkey (WXHKEY hKey)
 Set or change the HKEY handle. More...
 
void SetName (const wxString &strKey)
 Set the full key name. More...
 
void SetName (StdKey keyParent, const wxString &strKey)
 Set the name relative to the parent key. More...
 
void SetName (const wxRegKey &keyParent, const wxString &strKey)
 Set the name relative to the parent key. More...
 
bool SetValue (const wxString &szValue, long lValue)
 Sets the given szValue which must be numeric. More...
 
bool SetValue (const wxString &szValue, const wxString &strValue)
 Sets the given szValue which must be string. More...
 
bool SetValue (const wxString &szValue, const wxMemoryBuffer &buf)
 Sets the given szValue which must be binary. More...
 

Member Enumeration Documentation

Access modes for wxRegKey.

Enumerator
Read 

Read-only.

Write 

Read and Write.

The standard registry key enumerator.

Enumerator
HKCR 

HKEY_CLASSES_ROOT.

HKCU 

HKEY_CURRENT_USER.

HKLM 

HKEY_LOCAL_MACHINE.

HKUSR 

HKEY_USERS.

HKPD 

HKEY_PERFORMANCE_DATA (Obsolete under XP and later)

HKCC 

HKEY_CURRENT_CONFIG.

HKDD 

HKEY_DYN_DATA (Obsolete under XP and later)

HKMAX 

The value type enumerator.

Enumerator
Type_None 

No value type.

Type_String 

Unicode null-terminated string.

Type_Expand_String 

Unicode null-terminated string (with environment variable references)

Type_Binary 

Free form binary.

Type_Dword 

32-bit number

Type_Dword_little_endian 

32-bit number (same as Type_Dword)

Type_Dword_big_endian 

32-bit number

Type_Link 

Symbolic Link (Unicode)

Type_Multi_String 

Multiple Unicode strings.

Type_Resource_list 

Resource list in the resource map.

Type_Full_resource_descriptor 

Resource list in the hardware description.

Type_Resource_requirements_list 

Used to determine how the registry will be viewed, either as 32-bit or 64-bit.

Since
2.9.2
Enumerator
WOW64ViewMode_Default 

Uses 32-bit registry for 32-bit applications and 64-bit registry for 64-bit ones.

WOW64ViewMode_32 

Can be used in 64-bit apps to access the 32-bit registry, has no effect (i.e.

treated as default) in 32-bit apps.

WOW64ViewMode_64 

Can be used in 32-bit apps to access the 64-bit registry, has no effect (i.e.

treated as default) in 64-bit apps.

Constructor & Destructor Documentation

wxRegKey::wxRegKey ( WOW64ViewMode  viewMode = WOW64ViewMode_Default)

Default constructor, initializes to HKEY_CLASSES_ROOT.

The viewMode parameter is new since wxWidgets 2.9.2.

wxRegKey::wxRegKey ( const wxString strKey,
WOW64ViewMode  viewMode = WOW64ViewMode_Default 
)

The constructor to set the full name of the key.

The viewMode parameter is new since wxWidgets 2.9.2.

wxRegKey::wxRegKey ( StdKey  keyParent,
const wxString strKey,
WOW64ViewMode  viewMode = WOW64ViewMode_Default 
)

The constructor to set the full name of the key using one of the standard keys, that is, HKCR, HKCU, HKLM, HKUSR, HKPD (obsolete), HKCC or HKDD (obsolete).

The viewMode parameter is new since wxWidgets 2.9.2.

wxRegKey::wxRegKey ( const wxRegKey keyParent,
const wxString strKey 
)

The constructor to set the full name of the key under a previously created parent.

The registry view is inherited from the parent.

Member Function Documentation

void wxRegKey::Close ( )

Closes the key.

bool wxRegKey::Copy ( const wxString szNewName)

Copy the entire contents of the key recursively to another location using the name.

Returns true if successful.

bool wxRegKey::Copy ( wxRegKey keyDst)

Copy the entire contents of the key recursively to another location using the key.

Returns true if successful.

bool wxRegKey::CopyValue ( const wxString szValue,
wxRegKey keyDst,
const wxString szNewName = wxEmptyString 
)

Copy the value to another key, possibly changing its name.

By default it will remain the same. Returns true if successful.

bool wxRegKey::Create ( bool  bOkIfExists = true)

Creates the key.

Will fail if the key already exists and bOkIfExists is false. Returns true if successful.

void wxRegKey::DeleteKey ( const wxString szKey)

Deletes the subkey with all its subkeys and values recursively.

void wxRegKey::DeleteSelf ( )

Deletes this key and all its subkeys and values recursively.

void wxRegKey::DeleteValue ( const wxString szKey)

Deletes the named value or use an empty string argument to remove the default value of the key.

bool wxRegKey::Exists ( ) const

Returns true if the key exists.

bool wxRegKey::Export ( const wxString filename) const

Write the contents of this key and all its subkeys to the given file.

(The file will not be overwritten; it's an error if it already exists.) Note that we export the key in REGEDIT4 format, not RegSaveKey() binary format nor the newer REGEDIT5. Returns true if successful.

bool wxRegKey::Export ( wxOutputStream ostr) const

Write the contents of this key and all its subkeys to the opened stream.

Returns true if successful.

bool wxRegKey::GetFirstKey ( wxString strKeyName,
long &  lIndex 
)

Gets the first key.

Returns true if successful.

bool wxRegKey::GetFirstValue ( wxString strValueName,
long &  lIndex 
)

Gets the first value of this key.

Returns true if successful.

bool wxRegKey::GetKeyInfo ( size_t *  pnSubKeys,
size_t *  pnMaxKeyLen,
size_t *  pnValues,
size_t *  pnMaxValueLen 
) const

Gets information about the key.

Returns true if successful.

Parameters
pnSubKeysThe number of subkeys.
pnMaxKeyLenThe maximum length of the subkey name.
pnValuesThe number of values.
pnMaxValueLenThe maximum length of a value.
wxString wxRegKey::GetName ( bool  bShortPrefix = true) const

Gets the name of the registry key.

bool wxRegKey::GetNextKey ( wxString strKeyName,
long &  lIndex 
) const

Gets the next key.

Returns true if successful.

bool wxRegKey::GetNextValue ( wxString strValueName,
long &  lIndex 
) const

Gets the next key value for this key.

Returns true if successful.

ValueType wxRegKey::GetValueType ( const wxString szValue) const

Gets the value type.

WOW64ViewMode wxRegKey::GetView ( ) const
inline

Retrieves the registry view used by this key.

Since
2.9.2
Returns
The registry view given at the object's construction.
bool wxRegKey::HasSubKey ( const wxString szKey) const

Returns true if given subkey exists.

bool wxRegKey::HasSubkeys ( ) const

Returns true if any subkeys exist.

bool wxRegKey::HasValue ( const wxString szValue) const

Returns true if the value exists.

bool wxRegKey::HasValues ( ) const

Returns true if any values exist.

bool wxRegKey::IsEmpty ( ) const

Returns true if this key is empty, nothing under this key.

bool wxRegKey::IsNumericValue ( const wxString szValue) const

Returns true if the value contains a number.

bool wxRegKey::IsOpened ( ) const

Returns true if the key is opened.

bool wxRegKey::Open ( AccessMode  mode = Write)

Explicitly opens the key.

This method also allows the key to be opened in read-only mode by passing wxRegKey::Read instead of default wxRegKey::Write parameter. Returns true if successful.

wxRegKey& wxRegKey::operator= ( const wxString strValue)

Assignment operator to set the default value of the key.

wxString wxRegKey::QueryDefaultValue ( ) const

Return the default value of the key.

bool wxRegKey::QueryRawValue ( const wxString szValue,
wxString strValue 
) const

Retrieves the raw string value.

Returns true if successful. An empty szValue queries the default/unnamed key value.

bool wxRegKey::QueryValue ( const wxString szValue,
wxString strValue,
bool  raw 
) const

Retrieves the raw or expanded string value.

Returns true if successful. An empty szValue queries the default/unnamed key value.

bool wxRegKey::QueryValue ( const wxString szValue,
long *  plValue 
) const

Retrieves the numeric value.

Returns true if successful. An empty szValue queries the default/unnamed key value.

bool wxRegKey::QueryValue ( const wxString szValue,
wxMemoryBuffer buf 
) const

Retrieves the binary structure.

Returns true if successful. An empty szValue queries the default/unnamed key value.

bool wxRegKey::Rename ( const wxString szNewName)

Renames the key.

Returns true if successful.

bool wxRegKey::RenameValue ( const wxString szValueOld,
const wxString szValueNew 
)

Renames a value.

Returns true if successful.

void wxRegKey::ReserveMemoryForName ( size_t  bytes)

Preallocate some memory for the name.

For wxRegConfig usage only.

void wxRegKey::SetHkey ( WXHKEY  hKey)

Set or change the HKEY handle.

void wxRegKey::SetName ( const wxString strKey)

Set the full key name.

The name is absolute. It should start with HKEY_xxx.

void wxRegKey::SetName ( StdKey  keyParent,
const wxString strKey 
)

Set the name relative to the parent key.

void wxRegKey::SetName ( const wxRegKey keyParent,
const wxString strKey 
)

Set the name relative to the parent key.

bool wxRegKey::SetValue ( const wxString szValue,
long  lValue 
)

Sets the given szValue which must be numeric.

If the value doesn't exist, it is created. Returns true if successful. An empty szValue sets the default/unnamed key value.

bool wxRegKey::SetValue ( const wxString szValue,
const wxString strValue 
)

Sets the given szValue which must be string.

If the value doesn't exist, it is created. Returns true if successful. An empty szValue sets the default/unnamed key value.

bool wxRegKey::SetValue ( const wxString szValue,
const wxMemoryBuffer buf 
)

Sets the given szValue which must be binary.

If the value doesn't exist, it is created. Returns true if successful. An empty szValue sets the default/unnamed key value.