Wrap properties id. More...

Inheritance diagram for SDL::PropertiesBase:

[legend]

Public Member Functions
void	CopyPropertiesTo (PropertiesBase &dst) const
	Copy a group of properties.

PropertiesLock	Lock () &
	Lock a group of properties.

void	SetPointerWithCleanup (StringParam name, void *value, CleanupPropertyCB cleanup)
	Set a pointer property in a group of properties with a cleanup function that is called when the property is deleted.

void	SetPointerWithCleanup (StringParam name, void value, CleanupPropertyCallback cleanup, void userdata)
	Set a pointer property in a group of properties with a cleanup function that is called when the property is deleted.

void	SetPointer (StringParam name, void *value)
	Set a pointer property in a group of properties.

void	SetString (StringParam name, StringParam value)
	Set a string property in a group of properties.

void	SetNumber (StringParam name, Sint64 value)
	Set an integer property in a group of properties.

void	SetFloat (StringParam name, float value)
	Set a floating point property in a group of properties.

void	SetBoolean (StringParam name, bool value)
	Set a boolean property in a group of properties.

bool	Has (StringParam name) const
	Return whether a property exists in a group of properties.

PropertyType	GetType (StringParam name) const
	Get the type of a property.

void *	GetPointer (StringParam name, void *default_value) const
	Get a pointer property from a group of properties.

const char *	GetString (StringParam name, StringParam default_value) const
	Get a string property from a group of properties.

Sint64	GetNumber (StringParam name, Sint64 default_value) const
	Get a number property from a group of properties.

float	GetFloat (StringParam name, float default_value) const
	Get a floating point property from a group of properties.

bool	GetBoolean (StringParam name, bool default_value) const
	Get a boolean property from a group of properties.

void	Clear (StringParam name)
	Clear a property from a group of properties.

template<std::output_iterator< const char * > IT>
void	Enumerate (IT outputIter) const
	Enumerate the properties contained in a group of properties.

void	Enumerate (EnumeratePropertiesCB callback) const
	Enumerate the properties contained in a group of properties.

void	Enumerate (EnumeratePropertiesCallback callback, void *userdata) const
	Enumerate the properties contained in a group of properties.

Uint64	GetCount () const
	Returns the number of properties this has.

constexpr	Resource (T resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Public Member Functions inherited from SDL::Resource< SDL_PropertiesID >
constexpr	Resource (SDL_PropertiesID resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Resource &	operator= (const Resource &other)=delete

Resource &	operator= (Resource &&other)=delete

constexpr	operator bool () const
	True if contains a valid resource.

constexpr bool	operator== (const Resource &other) const=default
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr SDL_PropertiesID	get () const
	Return contained resource;.

constexpr SDL_PropertiesID	release (SDL_PropertiesID newResource={})
	Return contained resource and empties or replace value.

constexpr const SDL_PropertiesID	operator-> () const
	Access to fields.

constexpr SDL_PropertiesID	operator-> ()
	Access to fields.

Detailed Description

A property is a variable that can be created and retrieved by name at runtime.

All properties are part of a property group (Properties). A property group can be created with the Properties constructor and destroyed with this goes out of scope.

Properties can be added to and retrieved from a property group through the following functions:

SetPointer() and GetPointer() operate on void* pointer types.
SetString() and GetString() operate on string types.
SetNumber() and GetNumber() operate on signed 64-bit integer types.
SetFloat() and GetFloat() operate on floating point types.
SetBoolean() and GetBoolean() operate on boolean types.

Properties can be removed from a group by using SDL_ClearProperty.

To create a new properties group use CreateProperties() or Properties.Properties().

Since: This datatype is available since SDL 3.2.0.

Category:: Resource

See also: Properties.Properties; Properties; PropertiesRef

Member Function Documentation

◆ Clear()

void SDL::PropertiesBase::Clear ( StringParam name )

inline

Parameters

name	the name of the property to clear.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ CopyPropertiesTo()

void SDL::PropertiesBase::CopyPropertiesTo ( PropertiesBase & dst ) const

inline

Copy all the properties from one group of properties to another, with the exception of properties requiring cleanup (set using PropertiesBase.SetPointerWithCleanup()), which will not be copied. Any property that already exists on dst will be overwritten.

Parameters

dst	the destination properties.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ Enumerate() [1/3]

void SDL::PropertiesBase::Enumerate	(	EnumeratePropertiesCallback	callback,
		void *	userdata
	)		const

inline

The callback function is called for each property in the group of properties. The properties are locked during enumeration.

Parameters

callback	the function to call for each property.
userdata	a pointer that is passed to `callback`.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ Enumerate() [2/3]

void SDL::PropertiesBase::Enumerate ( EnumeratePropertiesCB callback ) const

inline

The callback function is called for each property in the group of properties. The properties are locked during enumeration.

Parameters

callback the function to call for each property.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Category:: Immediate callback

See also: immediate-callback

◆ Enumerate() [3/3]

template<std::output_iterator< const char * > IT>

void SDL::PropertiesBase::Enumerate ( IT outputIter ) const

inline

Parameters

outputIter an output iterator to be assigned to each property name.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

◆ GetBoolean()

bool SDL::PropertiesBase::GetBoolean	(	StringParam	name,
		bool	default_value
	)		const

inline

You can use PropertiesBase.GetType() to query whether the property exists and is a boolean property.

By convention, the names of properties that SDL exposes on objects will start with "SDL.", and properties that SDL uses internally will start with "SDL.internal.". These should be considered read-only and should not be modified by applications.

Parameters

name	the name of the property to query.
default_value	the default value of the property.

Returns: the value of the property, or default_value if it is not set or not a boolean property.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetType; PropertiesBase.Has; PropertiesBase.SetBoolean

◆ GetCount()

Uint64 SDL::PropertiesBase::GetCount ( ) const

inline

This uses Enumerate() internally, so might not be so fast

◆ GetFloat()

float SDL::PropertiesBase::GetFloat	(	StringParam	name,
		float	default_value
	)		const

inline

You can use PropertiesBase.GetType() to query whether the property exists and is a floating point property.

By convention, the names of properties that SDL exposes on objects will start with "SDL.", and properties that SDL uses internally will start with "SDL.internal.". These should be considered read-only and should not be modified by applications.

Parameters

name	the name of the property to query.
default_value	the default value of the property.

Returns: the value of the property, or default_value if it is not set or not a float property.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetType; PropertiesBase.Has; PropertiesBase.SetFloat

◆ GetNumber()

Sint64 SDL::PropertiesBase::GetNumber	(	StringParam	name,
		Sint64	default_value
	)		const

inline

You can use PropertiesBase.GetType() to query whether the property exists and is a number property.

By convention, the names of properties that SDL exposes on objects will start with "SDL.", and properties that SDL uses internally will start with "SDL.internal.". These should be considered read-only and should not be modified by applications.

Parameters

name	the name of the property to query.
default_value	the default value of the property.

Returns: the value of the property, or default_value if it is not set or not a number property.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetType; PropertiesBase.Has; PropertiesBase.SetNumber

◆ GetPointer()

void * SDL::PropertiesBase::GetPointer	(	StringParam	name,
		void *	default_value
	)		const

inline

You can use SDL_GetPropertyType() to query whether the property exists and is a pointer property.

By convention, the names of properties that SDL exposes on objects will start with "SDL.", and properties that SDL uses internally will start with "SDL.internal.". These should be considered read-only and should not be modified by applications.

Parameters

name	the name of the property to query.
default_value	the default value of the property.

Returns: the value of the property, or default_value if it is not set or not a pointer property.

Thread safety:: It is safe to call this function from any thread, although the data returned is not protected and could potentially be freed if you call PropertiesBase.SetPointer() or PropertiesBase.Clear() on these properties from another thread. If you need to avoid this, use PropertiesBase.Lock() and PropertiesLock.Unlock().

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetBoolean; PropertiesBase.GetFloat; PropertiesBase.GetNumber; PropertiesBase.GetType; PropertiesBase.GetString; PropertiesBase.Has; PropertiesBase.SetPointer

◆ GetString()

const char * SDL::PropertiesBase::GetString	(	StringParam	name,
		StringParam	default_value
	)		const

inline

You can use SDL_GetPropertyType() to query whether the property exists and is a string property.

By convention, the names of properties that SDL exposes on objects will start with "SDL.", and properties that SDL uses internally will start with "SDL.internal.". These should be considered read-only and should not be modified by applications.

Parameters

name	the name of the property to query.
default_value	the default value of the property.

Returns: the value of the property, or default_value if it is not set or not a string property.

Thread safety:: It is safe to call this function from any thread, although the data returned is not protected and could potentially be freed if you call PropertiesBase.SetString() or PropertiesBase.Clear() on these properties from another thread. If you need to avoid this, use PropertiesBase.Lock() and PropertiesLock.Unlock().

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetType; PropertiesBase.Has; PropertiesBase.SetString

◆ GetType()

PropertyType SDL::PropertiesBase::GetType ( StringParam name ) const

inline

Parameters

name	the name of the property to query.

Returns: the type of the property, or PROPERTY_TYPE_INVALID if it is not set.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.Has

◆ Has()

bool SDL::PropertiesBase::Has ( StringParam name ) const

inline

Parameters

name	the name of the property to query.

Returns: true if the property exists, or false if it doesn't.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetType

◆ SetBoolean()

void SDL::PropertiesBase::SetBoolean	(	StringParam	name,
		bool	value
	)

inline

Parameters

name	the name of the property to modify.
value	the new value of the property.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetBoolean

◆ SetFloat()

void SDL::PropertiesBase::SetFloat	(	StringParam	name,
		float	value
	)

inline

Parameters

name	the name of the property to modify.
value	the new value of the property.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetFloat

◆ SetNumber()

void SDL::PropertiesBase::SetNumber	(	StringParam	name,
		Sint64	value
	)

inline

Parameters

name	the name of the property to modify.
value	the new value of the property.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetNumber

◆ SetPointer()

void SDL::PropertiesBase::SetPointer	(	StringParam	name,
		void *	value
	)

inline

Parameters

name	the name of the property to modify.
value	the new value of the property, or nullptr to delete the property.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetPointer; PropertiesBase.Has; PropertiesBase.SetBoolean; PropertiesBase.SetFloat; PropertiesBase.SetNumber; PropertiesBase.SetPointerWithCleanup; PropertiesBase.SetString

◆ SetPointerWithCleanup() [1/2]

void SDL::PropertiesBase::SetPointerWithCleanup	(	StringParam	name,
		void *	value,
		CleanupPropertyCallback	cleanup,
		void *	userdata
	)

inline

The cleanup function is also called if setting the property fails for any reason.

For simply setting basic data types, like numbers, bools, or strings, use PropertiesBase.SetNumber, PropertiesBase.SetBoolean, or PropertiesBase.SetString instead, as those functions will handle cleanup on your behalf. This function is only for more complex, custom data.

Parameters

name	the name of the property to modify.
value	the new value of the property, or nullptr to delete the property.
cleanup	the function to call when this property is deleted, or nullptr if no cleanup is necessary.
userdata	a pointer that is passed to the cleanup function.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetPointer; PropertiesBase.SetPointer; CleanupPropertyCallback

◆ SetPointerWithCleanup() [2/2]

void SDL::PropertiesBase::SetPointerWithCleanup	(	StringParam	name,
		void *	value,
		CleanupPropertyCB	cleanup
	)

inline

The cleanup function is also called if setting the property fails for any reason.

For simply setting basic data types, like numbers, bools, or strings, use SetNumber(), SetBoolean(), or SetString() instead, as those functions will handle cleanup on your behalf. This function is only for more complex, custom data.

Parameters

name	the name of the property to modify.
value	the new value of the property, or NULL to delete the property.
cleanup	the function to call when this property is deleted.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

See also: result-callback

Category:: Result callback

◆ SetString()

void SDL::PropertiesBase::SetString	(	StringParam	name,
		StringParam	value
	)

inline

This function makes a copy of the string; the caller does not have to preserve the data after this call completes.

Parameters

name	the name of the property to modify.
value	the new value of the property, or nullptr to delete the property.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PropertiesBase.GetString

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

SDL3pp/SDL3pp_properties.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ Clear()

◆ CopyPropertiesTo()

◆ Enumerate() [1/3]

◆ Enumerate() [2/3]

◆ Enumerate() [3/3]

◆ GetBoolean()

◆ GetCount()

◆ GetFloat()

◆ GetNumber()

◆ GetPointer()

◆ GetString()

◆ GetType()

◆ Has()

◆ SetBoolean()

◆ SetFloat()

◆ SetNumber()

◆ SetPointer()

◆ SetPointerWithCleanup() [1/2]

◆ SetPointerWithCleanup() [2/2]

◆ SetString()