| Version: 3.3.1

Public Types | Public Member Functions | List of all members
wxRegKey Class Reference
Class List by Category » Application and System configuration

`#include <wx/msw/registry.h>`

## Detailed Description

wxRegKey is a class representing the Windows registry (it is only available under Windows) which can be used to create, query, set and delete registry keys.

The Windows registry contains data stored by Windows and the applications. The data are stored in a tree structure, where a tree node is called a key. Each key can contain subkeys as well as values. There are several predefined keys that are used as main entry points to the registry, the most commonly used being:

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

The values can be in these formats:

- String Value
- Binary Value
- DWORD Value
- Multi String Value
- Expandable String Value

Availability: only available for the wxMSW port.

Example:

// This assumes that the key already exists, use HasSubKey() to check
// for the key existence if necessary.
wxRegKey key(wxRegKey::HKCU, "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);
wxLogMessage("Registry value: %ld", value);
// Enumerate the subkeys.
wxString keyName;
long index = 0;
for ( bool cont = key.GetFirstKey(keyName, index);
cont;
cont = key.GetNextKey(keyName, index) )
{
wxLogMessage("Subkey name: %s", keyName);
}
wxRegKey
wxRegKey is a class representing the Windows registry (it is only available under Windows) which can ...
Definition: registry.h:67
wxRegKey::HKCU
@ HKCU
HKEY_CURRENT_USER.
Definition: registry.h:111
wxString
String class for passing textual data to or receiving it from wxWidgets.
Definition: string.h:372
wxLogMessage
void wxLogMessage(const char *formatString,...)
For all normal, informational messages.

##

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...
WXHKEY | GetHkey () const
| Return the associated HKEY handle. 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...
wxRegKey & | operator= (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 | QueryValue64 (const wxString &szValue, wxLongLong_t *plValue) const
| Retrieves the 64-bit 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 | SetValue64 (const wxString &szValue, wxLongLong_t lValue)
| Sets a 64-bit value. 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

## ◆ AccessMode

enum wxRegKey::AccessMode

Access modes for wxRegKey.

Enumerator
Read | Read-only.
Write | Read and Write.

## ◆ StdKey

enum wxRegKey::StdKey

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 |

## ◆ ValueType

enum wxRegKey::ValueType

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 |

## ◆ WOW64ViewMode

enum wxRegKey::WOW64ViewMode

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() [1/4]

wxRegKey::wxRegKey | ( | WOW64ViewMode | viewMode = `WOW64ViewMode_Default` | ) |

Default constructor, initializes to `HKEY_CLASSES_ROOT`.

The viewMode parameter is new since wxWidgets 2.9.2.

## ◆ wxRegKey() [2/4]

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() [3/4]

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() [4/4]

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

## ◆ Close()

void wxRegKey::Close | ( |  | ) |

Closes the key.

## ◆ Copy() [1/2]

bool wxRegKey::Copy | ( | const wxString & | szNewName | ) |

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

Returns true if successful.

## ◆ Copy() [2/2]

bool wxRegKey::Copy | ( | wxRegKey & | keyDst | ) |

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

Returns true if successful.

## ◆ CopyValue()

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.

## ◆ Create()

bool wxRegKey::Create | ( | bool | bOkIfExists = `true` | ) |

Creates the key.

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

## ◆ DeleteKey()

void wxRegKey::DeleteKey | ( | const wxString & | szKey | ) |

Deletes the subkey with all its subkeys and values recursively.

## ◆ DeleteSelf()

void wxRegKey::DeleteSelf | ( |  | ) |

Deletes this key and all its subkeys and values recursively.

## ◆ DeleteValue()

void wxRegKey::DeleteValue | ( | const wxString & | szKey | ) |

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

## ◆ Exists()

bool wxRegKey::Exists | ( |  | ) | const

Returns true if the key exists.

## ◆ Export() [1/2]

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.

## ◆ Export() [2/2]

bool wxRegKey::Export | ( | wxOutputStream & | ostr | ) | const

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

Returns true if successful.

## ◆ GetFirstKey()

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

Gets the first key.

Returns true if successful.

## ◆ GetFirstValue()

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

Gets the first value of this key.

Returns true if successful.

## ◆ GetHkey()

WXHKEY wxRegKey::GetHkey | ( |  | ) | const

Return the associated HKEY handle.

It may be null if the key is not opened.

Since
  3.3.1

## ◆ GetKeyInfo()

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

  pnSubKeys | The number of subkeys.
  pnMaxKeyLen | The maximum length of the subkey name.
  pnValues | The number of values.
  pnMaxValueLen | The maximum length of a value.

## ◆ GetName()

wxString wxRegKey::GetName | ( | bool | bShortPrefix = `true` | ) | const

Gets the name of the registry key.

## ◆ GetNextKey()

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

Gets the next key.

Returns true if successful.

## ◆ GetNextValue()

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

Gets the next key value for this key.

Returns true if successful.

## ◆ GetValueType()

ValueType wxRegKey::GetValueType | ( | const wxString & | szValue | ) | const

Gets the value type.

## ◆ GetView()

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.

## ◆ HasSubKey()

bool wxRegKey::HasSubKey | ( | const wxString & | szKey | ) | const

Returns true if given subkey exists.

## ◆ HasSubkeys()

bool wxRegKey::HasSubkeys | ( |  | ) | const

Returns true if any subkeys exist.

## ◆ HasValue()

bool wxRegKey::HasValue | ( | const wxString & | szValue | ) | const

Returns true if the value exists.

## ◆ HasValues()

bool wxRegKey::HasValues | ( |  | ) | const

Returns true if any values exist.

## ◆ IsEmpty()

bool wxRegKey::IsEmpty | ( |  | ) | const

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

## ◆ IsNumericValue()

bool wxRegKey::IsNumericValue | ( | const wxString & | szValue | ) | const

Returns true if the value contains a number.

## ◆ IsOpened()

bool wxRegKey::IsOpened | ( |  | ) | const

Returns true if the key is opened.

## ◆ Open()

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.

## ◆ operator=()

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

Assignment operator to set the default value of the key.

## ◆ QueryDefaultValue()

wxString wxRegKey::QueryDefaultValue | ( |  | ) | const

Return the default value of the key.

## ◆ QueryRawValue()

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.

## ◆ QueryValue() [1/3]

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.

## ◆ QueryValue() [2/3]

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.

## ◆ QueryValue() [3/3]

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.

## ◆ QueryValue64()

bool wxRegKey::QueryValue64 | ( | const wxString & | szValue,
|  | wxLongLong_t * | plValue
| ) |  | const

Retrieves the 64-bit value.

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

Since
  3.1.5

## ◆ Rename()

bool wxRegKey::Rename | ( | const wxString & | szNewName | ) |

Renames the key.

Returns true if successful.

## ◆ RenameValue()

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

Renames a value.

Returns true if successful.

## ◆ ReserveMemoryForName()

void wxRegKey::ReserveMemoryForName | ( | size_t | bytes | ) |

Preallocate some memory for the name.

For wxRegConfig usage only.

## ◆ SetHkey()

void wxRegKey::SetHkey | ( | WXHKEY | hKey | ) |

Set or change the HKEY handle.

## ◆ SetName() [1/3]

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

Set the name relative to the parent key.

## ◆ SetName() [2/3]

void wxRegKey::SetName | ( | const wxString & | strKey | ) |

Set the full key name.

The name is absolute. It should start with HKEY_xxx.

## ◆ SetName() [3/3]

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

Set the name relative to the parent key.

## ◆ SetValue() [1/3]

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.

## ◆ SetValue() [2/3]

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.

## ◆ SetValue() [3/3]

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.

## ◆ SetValue64()

bool wxRegKey::SetValue64 | ( | const wxString & | szValue,
|  | wxLongLong_t | lValue
| ) |  |

Sets a 64-bit value.

This function creates or modifies a field of `QWORD` type in the registry.

Since
  3.1.5