DefaultsAPI Struct Reference

The user's defaults storage. More...

#include <VirtualC64.h>

Public Member Functions
Loading and saving the key-value storage
void	load (const std::filesystem::path &path)
	Loads a storage file from disk.
void	load (std::ifstream &stream)
	Loads a storage file from a stream.
void	load (std::stringstream &stream)
	Loads a storage file from a string stream.
void	save (const std::filesystem::path &path)
	Saves a storage file to disk.
void	save (std::ofstream &stream)
	Saves a storage file to stream.
void	save (std::stringstream &stream)
	Saves a storage file to a string stream.
Reading key-value pairs
string	getString (const string &key) const
	Queries a key-value pair.
i64	getInt (const string &key) const
	Queries a key-value pair.
i64	get (Option option) const
	Queries a key-value pair.
i64	get (Option option, isize nr) const
	Queries a key-value pair.
string	getFallbackRaw (const string &key) const
	Queries a fallback key-value pair.
i64	getFallback (const string &key) const
	Queries a fallback key-value pair.
i64	getFallback (Option option) const
	Queries a fallback key-value pair.
i64	getFallback (Option option, isize nr=0) const
	Queries a fallback key-value pair.
Writing key-value pairs
void	set (const string &key, const string &value)
	Writes a key-value pair into the user storage.
void	set (Option opt, const string &value, std::vector< isize > objids={ 0 })
	Writes multiple key-value pairs into the user storage.
void	set (Option opt, i64 value, std::vector< isize > objids={ 0 })
	Writes multiple key-value pairs into the user storage.
void	setFallback (const string &key, const string &value)
	Writes a key-value pair into the fallback storage.
void	setFallback (Option opt, const string &value, std::vector< isize > objids={ 0 })
	Writes multiple key-value pairs into the fallback storage.
void	setFallback (Option opt, i64 value, std::vector< isize > objids={ 0 })
	Writes multiple key-value pairs into the fallback storage.
Deleting key-value pairs
void	remove ()
	Deletes all key-value pairs.
void	remove (const string &key) throws
	Deletes a key-value pair.
void	remove (Option option) throws
	Deletes a key-value pair.
void	remove (Option option, isize nr) throws
	Deletes a key-value pair.
void	remove (Option option, std::vector< isize > nrs) throws
	Deletes multiple key-value pairs.

Detailed Description

The user's defaults storage.

The defaults storage manages all configuration settings that persist across multiple application launches. It provides the following functionality:

• Loading and saving the storage data

  You can persist the user's defaults storage in a file, a stream, or a string stream.

• Reading and writing key-value pairs

  The return value is read from the user's defaults storage for registered keys. For unknown keys, an exception is thrown.

• Registerung fallback values

  The fallback value is used for registered keys with no custom value set.

  Note

  Setting a fallback value for an unknown key is permitted. In this case, a new key is registered together with the provided default value. The GUI utilizes this feature to register additional keys, such as keys storing shader-relevant parameters that are irrelevant to the emulation core.

Member Function Documentation

get() [1/2]

i64 get

(

Option

option

)

const

Queries a key-value pair.

Parameters

option

A config option whose name is used as the key.

Returns

The value as an integer.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

get() [2/2]

i64 get	(	Option	option,
		isize	nr ) const

Queries a key-value pair.

Parameters

option	A config option whose name is used as the prefix of the key.
nr	The key is parameterized by adding the value as suffix.

Returns

The value as an integer.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

getFallback() [1/3]

i64 getFallback

(

const string &

key

)

const

Queries a fallback key-value pair.

Parameters

key

The key.

Returns

The value as an integer. 0 if the value cannot not be parsed.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

getFallback() [2/3]

i64 getFallback

(

Option

option

)

const

Queries a fallback key-value pair.

Parameters

option

A config option whose name is used as the key.

Returns

The value as an integer.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

getFallback() [3/3]

i64 getFallback	(	Option	option,
		isize	nr = 0 ) const

Queries a fallback key-value pair.

Parameters

option	A config option whose name is used as the key.
nr	Optional number that is appened to the key as suffix.

Returns

The value as an integer.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

getFallbackRaw()

string getFallbackRaw

(

const string &

key

)

const

Queries a fallback key-value pair.

Parameters

key

The key.

Returns

The value as a string.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

getInt()

i64 getInt

(

const string &

key

)

const

Queries a key-value pair.

Parameters

key

The key.

Returns

The value as an integer. 0 if the value cannot not be parsed.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

getString()

string getString

(

const string &

key

)

const

Queries a key-value pair.

Parameters

key

The key.

Returns

The value as a string.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

load() [1/3]

void load

(

const std::filesystem::path &

path

)

Loads a storage file from disk.

Exceptions

VC64Error	(ERROR_FILE_NOT_FOUND)
VC64Error	(ERROR_SYNTAX)

load() [2/3]

void load

(

std::ifstream &

stream

)

Loads a storage file from a stream.

Exceptions

VC64Error

(ERROR_SYNTAX)

load() [3/3]

void load

(

std::stringstream &

stream

)

Loads a storage file from a string stream.

Exceptions

VC64Error

(ERROR_SYNTAX)

remove() [1/4]

void remove

(

const string &

key

)

Deletes a key-value pair.

Parameters

key	The key of the key-value pair.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

remove() [2/4]

void remove

(

Option

option

)

Deletes a key-value pair.

Parameters

option

The option's name forms the key.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

remove() [3/4]

void remove	(	Option	option,
		isize	nr )

Deletes a key-value pair.

Parameters

option	The option's name forms the prefix of the key.
nr	The key is parameterized by adding this value as suffix.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

remove() [4/4]

void remove	(	Option	option,
		std::vector< isize >	nrs )

Deletes multiple key-value pairs.

Parameters

option	The option's name forms the prefix of the keys.
nrs	The keys are parameterized by adding the vector values as suffixes.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

save()

void save

(

const std::filesystem::path &

path

)

Saves a storage file to disk.

Exceptions

VC64Error

(ERROR_FILE_CANT_WRITE)

set() [1/3]

void set	(	const string &	key,
		const string &	value )

Writes a key-value pair into the user storage.

Parameters

key	The key, given as a string.
value	The value, given as a string.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

set() [2/3]

void set	(	Option	opt,
		const string &	value,
		std::vector< isize >	objids = { 0 } )

Writes multiple key-value pairs into the user storage.

Parameters

opt	The option's name forms the prefix of the keys.
value	The value for all pairs, given as a string.
objids	The keys are parameterized by adding the vector values as suffixes.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

set() [3/3]

void set	(	Option	opt,
		i64	value,
		std::vector< isize >	objids = { 0 } )

Writes multiple key-value pairs into the user storage.

Parameters

opt	The option's name forms the prefix of the keys.
value	The value for all pairs, given as an integer.
objids	The keys are parameterized by adding the vector values as suffixes.

Exceptions

VC64Error

(ERROR_INVALID_KEY)

setFallback() [1/3]

void setFallback	(	const string &	key,
		const string &	value )

Writes a key-value pair into the fallback storage.

Parameters

key	The key, given as a string.
value	The value, given as a string.

setFallback() [2/3]

void setFallback	(	Option	opt,
		const string &	value,
		std::vector< isize >	objids = { 0 } )

Writes multiple key-value pairs into the fallback storage.

Parameters

opt	The option's name forms the prefix of the keys.
value	The shared value for all pairs, given as a string.
objids	The keys are parameterized by adding the vector values as suffixes.

setFallback() [3/3]

void setFallback	(	Option	opt,
		i64	value,
		std::vector< isize >	objids = { 0 } )

Writes multiple key-value pairs into the fallback storage.

Parameters

opt	The option's name forms the prefix of the keys.
value	The shared value for all pairs, given as an integer.
objids	The keys are parameterized by adding the vector values as suffixes.

---

The documentation for this struct was generated from the following files:

• VirtualC64.h
• VirtualC64.cpp