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

Classes
class	SDL::Properties
	An ID that represents a properties set. More...
struct	SDL::PropertiesRef
	Reference for Properties. More...
class	SDL::PropertiesLock
	Lock a group of properties. More...

Typedefs
using	SDL::PropertiesID = SDL_PropertiesID
	Alias to raw representation for Properties.
using	SDL::PropertyType = SDL_PropertyType
	SDL property type.
using	SDL::EnumeratePropertiesCallback
	A callback used to enumerate all the properties in a group of properties.
using	SDL::EnumeratePropertiesCB
	A callback used to enumerate all the properties in a group of properties.
using	SDL::CleanupPropertyCallback = void(SDLCALL)(void userdata, void* value)
	A callback used to free resources when a property is deleted.
using	SDL::CleanupPropertyCB = std::function<void(void* value)>
	A callback used to free resources when a property is deleted.

Functions
PropertiesRef	SDL::GetGlobalProperties ()
	Get the global SDL properties.
Properties	SDL::CreateProperties ()
	Create a group of properties.
void	SDL::CopyProperties (PropertiesRef src, PropertiesRef dst)
	Copy a group of properties.
void	SDL::LockProperties (PropertiesRef props)
	Lock a group of properties.
void	SDL::UnlockProperties (PropertiesRef props)
	Unlock a group of properties.
void	SDL::SetPointerPropertyWithCleanup (PropertiesRef props, 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	SDL::SetPointerPropertyWithCleanup (PropertiesRef props, 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	SDL::SetPointerProperty (PropertiesRef props, StringParam name, void *value)
	Set a pointer property in a group of properties.
void	SDL::SetStringProperty (PropertiesRef props, StringParam name, StringParam value)
	Set a string property in a group of properties.
void	SDL::SetNumberProperty (PropertiesRef props, StringParam name, Sint64 value)
	Set an integer property in a group of properties.
void	SDL::SetFloatProperty (PropertiesRef props, StringParam name, float value)
	Set a floating point property in a group of properties.
void	SDL::SetBooleanProperty (PropertiesRef props, StringParam name, bool value)
	Set a boolean property in a group of properties.
bool	SDL::HasProperty (PropertiesRef props, StringParam name)
	Return whether a property exists in a group of properties.
PropertyType	SDL::GetPropertyType (PropertiesRef props, StringParam name)
	Get the type of a property in a group of properties.
void *	SDL::GetPointerProperty (PropertiesRef props, StringParam name, void *default_value)
	Get a pointer property from a group of properties.
const char *	SDL::GetStringProperty (PropertiesRef props, StringParam name, StringParam default_value)
	Get a string property from a group of properties.
Sint64	SDL::GetNumberProperty (PropertiesRef props, StringParam name, Sint64 default_value)
	Get a number property from a group of properties.
float	SDL::GetFloatProperty (PropertiesRef props, StringParam name, float default_value)
	Get a floating point property from a group of properties.
bool	SDL::GetBooleanProperty (PropertiesRef props, StringParam name, bool default_value)
	Get a boolean property from a group of properties.
void	SDL::ClearProperty (PropertiesRef props, StringParam name)
	Clear a property from a group of properties.
void	SDL::EnumerateProperties (PropertiesRef props, EnumeratePropertiesCallback callback, void *userdata)
	Enumerate the properties contained in a group of properties.
void	SDL::EnumerateProperties (PropertiesRef props, EnumeratePropertiesCB callback)
	Enumerate the properties contained in a group of properties.
Uint64	SDL::CountProperties (PropertiesRef props)
	Returns the number of properties this has.
void	SDL::DestroyProperties (PropertiesID props)
	Destroy a group of properties.
static Properties	SDL::Properties::Create ()
	Create a group of properties.
void	SDL::Properties::Copy (PropertiesRef dst)
	Copy a group of properties.
PropertiesLock	SDL::Properties::Lock ()
	Lock a group of properties.
	SDL::PropertiesLock::PropertiesLock (PropertiesRef resource)
	Lock a group of properties.
void	SDL::Properties::Unlock (PropertiesLock &&lock)
	Unlock a group of properties.
void	SDL::PropertiesLock::reset ()
	Unlock a group of properties.
void	SDL::Properties::SetPointerPropertyWithCleanup (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	SDL::Properties::SetPointerPropertyWithCleanup (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	SDL::Properties::SetPointerProperty (StringParam name, void *value)
	Set a pointer property in a group of properties.
void	SDL::Properties::SetStringProperty (StringParam name, StringParam value)
	Set a string property in a group of properties.
void	SDL::Properties::SetNumberProperty (StringParam name, Sint64 value)
	Set an integer property in a group of properties.
void	SDL::Properties::SetFloatProperty (StringParam name, float value)
	Set a floating point property in a group of properties.
void	SDL::Properties::SetBooleanProperty (StringParam name, bool value)
	Set a boolean property in a group of properties.
bool	SDL::Properties::HasProperty (StringParam name)
	Return whether a property exists in a group of properties.
PropertyType	SDL::Properties::GetPropertyType (StringParam name)
	Get the type of a property in a group of properties.
void *	SDL::Properties::GetPointerProperty (StringParam name, void *default_value)
	Get a pointer property from a group of properties.
const char *	SDL::Properties::GetStringProperty (StringParam name, StringParam default_value)
	Get a string property from a group of properties.
Sint64	SDL::Properties::GetNumberProperty (StringParam name, Sint64 default_value)
	Get a number property from a group of properties.
float	SDL::Properties::GetFloatProperty (StringParam name, float default_value)
	Get a floating point property from a group of properties.
bool	SDL::Properties::GetBooleanProperty (StringParam name, bool default_value)
	Get a boolean property from a group of properties.
void	SDL::Properties::ClearProperty (StringParam name)
	Clear a property from a group of properties.
void	SDL::Properties::Enumerate (EnumeratePropertiesCallback callback, void *userdata)
	Enumerate the properties contained in a group of properties.
void	SDL::Properties::Enumerate (EnumeratePropertiesCB callback)
	Enumerate the properties contained in a group of properties.
Uint64	SDL::Properties::GetCount ()
	Returns the number of properties this has.
void	SDL::Properties::Destroy ()
	Destroy a group of properties.

Variables
constexpr PropertyType	SDL::PROPERTY_TYPE_INVALID
	INVALID.
constexpr PropertyType	SDL::PROPERTY_TYPE_POINTER
	POINTER.
constexpr PropertyType	SDL::PROPERTY_TYPE_STRING
	STRING.
constexpr PropertyType	SDL::PROPERTY_TYPE_NUMBER
	NUMBER.
constexpr PropertyType	SDL::PROPERTY_TYPE_FLOAT = SDL_PROPERTY_TYPE_FLOAT
	FLOAT.
constexpr PropertyType	SDL::PROPERTY_TYPE_BOOLEAN
	BOOLEAN.
constexpr const char *	SDL::PROP_NAME_STRING = SDL_PROP_NAME_STRING
	A generic property for naming things.

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.Create function and destroyed with the Properties.Destroy function, but the Properties destructor probably will do what you want to, automatically.

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

Properties.SetPointerProperty and Properties.GetPointerProperty operate on void* pointer types.
Properties.SetStringProperty and Properties.GetStringProperty operate on string types.
Properties.SetNumberProperty and Properties.GetNumberProperty operate on signed 64-bit integer types.
Properties.SetFloatProperty and Properties.GetFloatProperty operate on floating point types.
Properties.SetBooleanProperty and Properties.GetBooleanProperty operate on boolean types.

Properties can be removed from a group by using Properties.ClearProperty.

Typedef Documentation

◆ CleanupPropertyCallback

using SDL::CleanupPropertyCallback = void(SDLCALL*)(void* userdata, void* value)

A callback used to free resources when a property is deleted.

This should release any resources associated with value that are no longer needed.

This callback is set per-property. Different properties in the same group can have different cleanup callbacks.

This callback will be called during Properties.SetPointerPropertyWithCleanup if the function fails for any reason.

Parameters

userdata	an app-defined pointer passed to the callback.
value	the pointer assigned to the property to clean up.

Thread safety:: This callback may fire without any locks held; if this is a concern, the app should provide its own locking.

Since: This datatype is available since SDL 3.2.0.

See also: Properties.SetPointerPropertyWithCleanup

◆ CleanupPropertyCB

using SDL::CleanupPropertyCB = std::function<void(void* value)>

A callback used to free resources when a property is deleted.

This should release any resources associated with value that are no longer needed.

This callback is set per-property. Different properties in the same group can have different cleanup callbacks.

This callback will be called during Properties.SetPointerPropertyWithCleanup if the function fails for any reason.

Parameters

value the pointer assigned to the property to clean up.

Thread safety:: This callback may fire without any locks held; if this is a concern, the app should provide its own locking.

Since: This datatype is available since SDL 3.2.0.

See also: Properties.SetPointerPropertyWithCleanup; CleanupPropertyCallback

◆ EnumeratePropertiesCallback

using SDL::EnumeratePropertiesCallback

Initial value:

void(SDLCALL*)(void* userdata,
                                                  PropertiesID props,
                                                  const char* name)

A callback used to enumerate all the properties in a group of properties.

This callback is called from Properties.Enumerate(), and is called once per property in the set.

Parameters

userdata	an app-defined pointer passed to the callback.
props	the Properties that is being enumerated.
name	the next property name in the enumeration.

Thread safety:: Properties.Enumerate holds a lock on props during this callback.

Since: This datatype is available since SDL 3.2.0.

See also: Properties.Enumerate

◆ EnumeratePropertiesCB

using SDL::EnumeratePropertiesCB

Initial value:

std::function<void(PropertiesID props, const char* name)>

A callback used to enumerate all the properties in a group of properties.

This callback is called from Properties.Enumerate(), and is called once per property in the set.

Parameters

props	the Properties that is being enumerated.
name	the next property name in the enumeration.

Thread safety:: Properties.Enumerate holds a lock on props during this callback.

Since: This datatype is available since SDL 3.2.0.

See also: Properties.Enumerate

◆ PropertyType

using SDL::PropertyType = SDL_PropertyType

SDL property type.

Since: This enum is available since SDL 3.2.0.

Function Documentation

◆ ClearProperty() [1/2]

void SDL::ClearProperty	(	PropertiesRef	props,
		StringParam	name )

inline

Clear a property from a group of properties.

Parameters

props	the properties to modify.
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.

◆ ClearProperty() [2/2]

void SDL::Properties::ClearProperty ( StringParam name )

inline

Clear a property from a group of properties.

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.

◆ Copy()

void SDL::Properties::Copy ( PropertiesRef dst )

inline

Copy a group of properties.

Copy all the properties from one group of properties to another, with the exception of properties requiring cleanup (set using Properties.SetPointerPropertyWithCleanup()), 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. This function acquires simultaneous mutex locks on both the source and destination property sets.

Since: This function is available since SDL 3.2.0.

◆ CopyProperties()

void SDL::CopyProperties	(	PropertiesRef	src,
		PropertiesRef	dst )

inline

Copy a group of properties.

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

Parameters

src	the properties to copy.
dst	the destination properties.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread. This function acquires simultaneous mutex locks on both the source and destination property sets.

Since: This function is available since SDL 3.2.0.

◆ CountProperties()

Uint64 SDL::CountProperties ( PropertiesRef props )

inline

Returns the number of properties this has.

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

Parameters

props

Returns: Uint64

◆ Create()

Properties SDL::Properties::Create ( )

inlinestatic

Create a group of properties.

All properties are automatically destroyed when Quit() is called.

Returns: an ID for a new group of properties on success.

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: Properties.Destroy

◆ CreateProperties()

Properties SDL::CreateProperties ( )

inline

Create a group of properties.

All properties are automatically destroyed when Quit() is called.

Returns: an ID for a new group of properties on success.

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: Properties.Destroy

◆ Destroy()

void SDL::Properties::Destroy ( )

inline

Destroy a group of properties.

All properties are deleted and their cleanup functions will be called, if any.

Thread safety:: This function should not be called while these properties are locked or other threads might be setting or getting values from these properties.

Since: This function is available since SDL 3.2.0.

See also: Properties.Create

◆ DestroyProperties()

void SDL::DestroyProperties ( PropertiesID props )

inline

Destroy a group of properties.

All properties are deleted and their cleanup functions will be called, if any.

Parameters

props the properties to destroy.

Thread safety:: This function should not be called while these properties are locked or other threads might be setting or getting values from these properties.

Since: This function is available since SDL 3.2.0.

See also: Properties.Create

◆ Enumerate() [1/2]

void SDL::Properties::Enumerate	(	EnumeratePropertiesCallback	callback,
		void *	userdata )

inline

Enumerate the properties contained in a group of properties.

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/2]

void SDL::Properties::Enumerate ( EnumeratePropertiesCB callback )

inline

Enumerate the properties contained in a group of properties.

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.

Since: This function is available since SDL 3.2.0.

◆ EnumerateProperties() [1/2]

void SDL::EnumerateProperties	(	PropertiesRef	props,
		EnumeratePropertiesCallback	callback,
		void *	userdata )

inline

Enumerate the properties contained in a group of properties.

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

Parameters

props	the properties to query.
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.

◆ EnumerateProperties() [2/2]

void SDL::EnumerateProperties	(	PropertiesRef	props,
		EnumeratePropertiesCB	callback )

inline

Enumerate the properties contained in a group of properties.

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

Parameters

props	the properties to query.
callback	the function to call for each 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.

◆ GetBooleanProperty() [1/2]

bool SDL::GetBooleanProperty	(	PropertiesRef	props,
		StringParam	name,
		bool	default_value )

inline

Get a boolean property from a group of properties.

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

Parameters

props	the properties to query.
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: Properties.GetPropertyType; Properties.HasProperty; Properties.SetBooleanProperty

◆ GetBooleanProperty() [2/2]

bool SDL::Properties::GetBooleanProperty	(	StringParam	name,
		bool	default_value )

inline

Get a boolean property from a group of properties.

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

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: Properties.GetPropertyType; Properties.HasProperty; Properties.SetBooleanProperty

◆ GetCount()

Uint64 SDL::Properties::GetCount ( )

inline

Returns the number of properties this has.

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

Returns: Uint64

◆ GetFloatProperty() [1/2]

float SDL::GetFloatProperty	(	PropertiesRef	props,
		StringParam	name,
		float	default_value )

inline

Get a floating point property from a group of properties.

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

Parameters

props	the properties to query.
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: Properties.GetPropertyType; Properties.HasProperty; Properties.SetFloatProperty

◆ GetFloatProperty() [2/2]

float SDL::Properties::GetFloatProperty	(	StringParam	name,
		float	default_value )

inline

Get a floating point property from a group of properties.

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

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: Properties.GetPropertyType; Properties.HasProperty; Properties.SetFloatProperty

◆ GetGlobalProperties()

PropertiesRef SDL::GetGlobalProperties ( )

inline

Get the global SDL properties.

Returns: a valid property ID on success.

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.

◆ GetNumberProperty() [1/2]

Sint64 SDL::GetNumberProperty	(	PropertiesRef	props,
		StringParam	name,
		Sint64	default_value )

inline

Get a number property from a group of properties.

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

Parameters

props	the properties to query.
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: Properties.GetPropertyType; Properties.HasProperty; Properties.SetNumberProperty

◆ GetNumberProperty() [2/2]

Sint64 SDL::Properties::GetNumberProperty	(	StringParam	name,
		Sint64	default_value )

inline

Get a number property from a group of properties.

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

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: Properties.GetPropertyType; Properties.HasProperty; Properties.SetNumberProperty

◆ GetPointerProperty() [1/2]

void * SDL::GetPointerProperty	(	PropertiesRef	props,
		StringParam	name,
		void *	default_value )

inline

Get a pointer property from a group of properties.

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

props	the properties to query.
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 Properties.SetPointerProperty() or Properties.ClearProperty() on these properties from another thread. If you need to avoid this, use Properties.Lock() and Properties.Unlock().

Since: This function is available since SDL 3.2.0.

See also: Properties.GetBooleanProperty; Properties.GetFloatProperty; Properties.GetNumberProperty; Properties.GetPropertyType; Properties.GetStringProperty; Properties.HasProperty; Properties.SetPointerProperty

◆ GetPointerProperty() [2/2]

void * SDL::Properties::GetPointerProperty	(	StringParam	name,
		void *	default_value )

inline

Get a pointer property from a group of properties.

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 Properties.SetPointerProperty() or Properties.ClearProperty() on these properties from another thread. If you need to avoid this, use Properties.Lock() and Properties.Unlock().

Since: This function is available since SDL 3.2.0.

See also: Properties.GetBooleanProperty; Properties.GetFloatProperty; Properties.GetNumberProperty; Properties.GetPropertyType; Properties.GetStringProperty; Properties.HasProperty; Properties.SetPointerProperty

◆ GetPropertyType() [1/2]

PropertyType SDL::GetPropertyType	(	PropertiesRef	props,
		StringParam	name )

inline

Get the type of a property in a group of properties.

Parameters

props	the properties to query.
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: Properties.HasProperty

◆ GetPropertyType() [2/2]

PropertyType SDL::Properties::GetPropertyType ( StringParam name )

inline

Get the type of a property in a group of properties.

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: Properties.HasProperty

◆ GetStringProperty() [1/2]

const char * SDL::GetStringProperty	(	PropertiesRef	props,
		StringParam	name,
		StringParam	default_value )

inline

Get a string property from a group of properties.

Parameters

props	the properties to query.
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 Properties.SetStringProperty() or Properties.ClearProperty() on these properties from another thread. If you need to avoid this, use Properties.Lock() and Properties.Unlock().

Since: This function is available since SDL 3.2.0.

See also: Properties.GetPropertyType; Properties.HasProperty; Properties.SetStringProperty

◆ GetStringProperty() [2/2]

const char * SDL::Properties::GetStringProperty	(	StringParam	name,
		StringParam	default_value )

inline

Get a string property from a group of properties.

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 Properties.SetStringProperty() or Properties.ClearProperty() on these properties from another thread. If you need to avoid this, use Properties.Lock() and Properties.Unlock().

Since: This function is available since SDL 3.2.0.

See also: Properties.GetPropertyType; Properties.HasProperty; Properties.SetStringProperty

◆ HasProperty() [1/2]

bool SDL::HasProperty	(	PropertiesRef	props,
		StringParam	name )

inline

Return whether a property exists in a group of properties.

Parameters

props	the properties to query.
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: Properties.GetPropertyType

◆ HasProperty() [2/2]

bool SDL::Properties::HasProperty ( StringParam name )

inline

Return whether a property exists in a group of properties.

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: Properties.GetPropertyType

◆ Lock()

PropertiesLock SDL::Properties::Lock ( )

inline

Lock a group of properties.

Obtain a multi-threaded lock for these properties. Other threads will wait while trying to lock these properties until they are unlocked. Properties must be unlocked before they are destroyed.

The lock is automatically taken when setting individual properties, this function is only needed when you want to set several properties atomically or want to guarantee that properties being queried aren't freed in another thread.

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: Properties.Unlock

◆ LockProperties()

void SDL::LockProperties ( PropertiesRef props )

inline

Lock a group of properties.

Obtain a multi-threaded lock for these properties. Other threads will wait while trying to lock these properties until they are unlocked. Properties must be unlocked before they are destroyed.

The lock is automatically taken when setting individual properties, this function is only needed when you want to set several properties atomically or want to guarantee that properties being queried aren't freed in another thread.

Parameters

props the properties to lock.

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: Properties.Unlock

◆ PropertiesLock()

SDL::PropertiesLock::PropertiesLock ( PropertiesRef resource )

inline

Lock a group of properties.

Obtain a multi-threaded lock for these properties. Other threads will wait while trying to lock these properties until they are unlocked. Properties must be unlocked before they are destroyed.

The lock is automatically taken when setting individual properties, this function is only needed when you want to set several properties atomically or want to guarantee that properties being queried aren't freed in another thread.

Parameters

resource the properties to lock.

Postcondition: true on success or false on failure; call GetError() for more information.

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

Since: This function is available since SDL 3.2.0.

See also: Properties.Unlock

◆ reset()

void SDL::PropertiesLock::reset ( )

inline

Unlock a group of properties.

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

Since: This function is available since SDL 3.2.0.

See also: Properties.Lock

◆ SetBooleanProperty() [1/2]

void SDL::Properties::SetBooleanProperty	(	StringParam	name,
		bool	value )

inline

Set a boolean property in a group of properties.

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: Properties.GetBooleanProperty

◆ SetBooleanProperty() [2/2]

void SDL::SetBooleanProperty	(	PropertiesRef	props,
		StringParam	name,
		bool	value )

inline

Set a boolean property in a group of properties.

Parameters

props	the properties to modify.
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: Properties.GetBooleanProperty

◆ SetFloatProperty() [1/2]

void SDL::Properties::SetFloatProperty	(	StringParam	name,
		float	value )

inline

Set a floating point property in a group of properties.

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: Properties.GetFloatProperty

◆ SetFloatProperty() [2/2]

void SDL::SetFloatProperty	(	PropertiesRef	props,
		StringParam	name,
		float	value )

inline

Set a floating point property in a group of properties.

Parameters

props	the properties to modify.
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: Properties.GetFloatProperty

◆ SetNumberProperty() [1/2]

void SDL::Properties::SetNumberProperty	(	StringParam	name,
		Sint64	value )

inline

Set an integer property in a group of properties.

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: Properties.GetNumberProperty

◆ SetNumberProperty() [2/2]

void SDL::SetNumberProperty	(	PropertiesRef	props,
		StringParam	name,
		Sint64	value )

inline

Set an integer property in a group of properties.

Parameters

props	the properties to modify.
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: Properties.GetNumberProperty

◆ SetPointerProperty() [1/2]

void SDL::Properties::SetPointerProperty	(	StringParam	name,
		void *	value )

inline

Set a pointer property in a group of properties.

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: Properties.GetPointerProperty; Properties.HasProperty; Properties.SetBooleanProperty; Properties.SetFloatProperty; Properties.SetNumberProperty; Properties.SetPointerPropertyWithCleanup; Properties.SetStringProperty

◆ SetPointerProperty() [2/2]

void SDL::SetPointerProperty	(	PropertiesRef	props,
		StringParam	name,
		void *	value )

inline

Set a pointer property in a group of properties.

Parameters

props	the properties to modify.
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: Properties.GetPointerProperty; Properties.HasProperty; Properties.SetBooleanProperty; Properties.SetFloatProperty; Properties.SetNumberProperty; Properties.SetPointerPropertyWithCleanup; Properties.SetStringProperty

◆ SetPointerPropertyWithCleanup() [1/4]

void SDL::Properties::SetPointerPropertyWithCleanup	(	StringParam	name,
		void *	value,
		CleanupPropertyCallback	cleanup,
		void *	userdata )

inline

Set a pointer property in a group of properties with a cleanup function that is called when the property is deleted.

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 Properties.SetNumberProperty, Properties.SetBooleanProperty, or Properties.SetStringProperty 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: Properties.GetPointerProperty; Properties.SetPointerProperty; CleanupPropertyCallback

◆ SetPointerPropertyWithCleanup() [2/4]

void SDL::Properties::SetPointerPropertyWithCleanup	(	StringParam	name,
		void *	value,
		CleanupPropertyCB	cleanup )

inline

Set a pointer property in a group of properties with a cleanup function that is called when the property is deleted.

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 Properties.SetNumberProperty, Properties.SetBooleanProperty, or Properties.SetStringProperty 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.

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: Properties.GetPointerProperty; Properties.SetPointerProperty; CleanupPropertyCallback

◆ SetPointerPropertyWithCleanup() [3/4]

void SDL::SetPointerPropertyWithCleanup	(	PropertiesRef	props,
		StringParam	name,
		void *	value,
		CleanupPropertyCallback	cleanup,
		void *	userdata )

inline

Set a pointer property in a group of properties with a cleanup function that is called when the property is deleted.

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 Properties.SetNumberProperty, Properties.SetBooleanProperty, or Properties.SetStringProperty instead, as those functions will handle cleanup on your behalf. This function is only for more complex, custom data.

Parameters

props	the properties to modify.
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: Properties.GetPointerProperty; Properties.SetPointerProperty; CleanupPropertyCallback

◆ SetPointerPropertyWithCleanup() [4/4]

void SDL::SetPointerPropertyWithCleanup	(	PropertiesRef	props,
		StringParam	name,
		void *	value,
		CleanupPropertyCB	cleanup )

inline

Set a pointer property in a group of properties with a cleanup function that is called when the property is deleted.

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 Properties.SetNumberProperty, Properties.SetBooleanProperty, or Properties.SetStringProperty instead, as those functions will handle cleanup on your behalf. This function is only for more complex, custom data.

Parameters

props	the properties to modify.
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.

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: Properties.GetPointerProperty; Properties.SetPointerProperty; CleanupPropertyCallback

◆ SetStringProperty() [1/2]

void SDL::Properties::SetStringProperty	(	StringParam	name,
		StringParam	value )

inline

Set a string property in a group of properties.

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: Properties.GetStringProperty

◆ SetStringProperty() [2/2]

void SDL::SetStringProperty	(	PropertiesRef	props,
		StringParam	name,
		StringParam	value )

inline

Set a string property in a group of properties.

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

Parameters

props	the properties to modify.
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: Properties.GetStringProperty

◆ Unlock()

void SDL::Properties::Unlock ( PropertiesLock && lock )

inline

Unlock a group of properties.

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

Since: This function is available since SDL 3.2.0.

See also: Properties.Lock

◆ UnlockProperties()

void SDL::UnlockProperties ( PropertiesRef props )

inline

Unlock a group of properties.

Parameters

props the properties to unlock.

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

Since: This function is available since SDL 3.2.0.

See also: Properties.Lock

Variable Documentation

◆ PROP_NAME_STRING

const char* SDL::PROP_NAME_STRING = SDL_PROP_NAME_STRING

constexpr

A generic property for naming things.

This property is intended to be added to any Properties that needs a generic name associated with the property set. It is not guaranteed that any property set will include this key, but it is convenient to have a standard key that any piece of code could reasonably agree to use.

For example, the properties associated with an Texture might have a name string of "player sprites", or an AudioStream might have "background music", etc. This might also be useful for an IOStream to list the path to its asset.

There is no format for the value set with this key; it is expected to be human-readable and informational in nature, possibly for logging or debugging purposes.

SDL does not currently set this property on any objects it creates, but this may change in later versions; it is currently expected that apps and external libraries will take advantage of it, when appropriate.

Since: This constant is available since SDL 3.4.0.

◆ PROPERTY_TYPE_BOOLEAN

PropertyType SDL::PROPERTY_TYPE_BOOLEAN

constexpr

Initial value:

=

SDL_PROPERTY_TYPE_BOOLEAN

BOOLEAN.

◆ PROPERTY_TYPE_INVALID

PropertyType SDL::PROPERTY_TYPE_INVALID

constexpr

Initial value:

=

SDL_PROPERTY_TYPE_INVALID

INVALID.

◆ PROPERTY_TYPE_NUMBER

PropertyType SDL::PROPERTY_TYPE_NUMBER

constexpr

Initial value:

=

SDL_PROPERTY_TYPE_NUMBER

NUMBER.

◆ PROPERTY_TYPE_POINTER

PropertyType SDL::PROPERTY_TYPE_POINTER

constexpr

Initial value:

=

SDL_PROPERTY_TYPE_POINTER

POINTER.

◆ PROPERTY_TYPE_STRING

PropertyType SDL::PROPERTY_TYPE_STRING

constexpr

Initial value:

=

SDL_PROPERTY_TYPE_STRING

STRING.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ CleanupPropertyCallback

◆ CleanupPropertyCB

◆ EnumeratePropertiesCallback

◆ EnumeratePropertiesCB

◆ PropertyType

Function Documentation

◆ ClearProperty() [1/2]

◆ ClearProperty() [2/2]

◆ Copy()

◆ CopyProperties()

◆ CountProperties()

◆ Create()

◆ CreateProperties()

◆ Destroy()

◆ DestroyProperties()

◆ Enumerate() [1/2]

◆ Enumerate() [2/2]

◆ EnumerateProperties() [1/2]

◆ EnumerateProperties() [2/2]

◆ GetBooleanProperty() [1/2]

◆ GetBooleanProperty() [2/2]

◆ GetCount()

◆ GetFloatProperty() [1/2]

◆ GetFloatProperty() [2/2]

◆ GetGlobalProperties()

◆ GetNumberProperty() [1/2]

◆ GetNumberProperty() [2/2]

◆ GetPointerProperty() [1/2]

◆ GetPointerProperty() [2/2]

◆ GetPropertyType() [1/2]

◆ GetPropertyType() [2/2]

◆ GetStringProperty() [1/2]

◆ GetStringProperty() [2/2]

◆ HasProperty() [1/2]

◆ HasProperty() [2/2]

◆ Lock()

◆ LockProperties()

◆ PropertiesLock()

◆ reset()

◆ SetBooleanProperty() [1/2]

◆ SetBooleanProperty() [2/2]

◆ SetFloatProperty() [1/2]

◆ SetFloatProperty() [2/2]

◆ SetNumberProperty() [1/2]

◆ SetNumberProperty() [2/2]

◆ SetPointerProperty() [1/2]

◆ SetPointerProperty() [2/2]

◆ SetPointerPropertyWithCleanup() [1/4]

◆ SetPointerPropertyWithCleanup() [2/4]

◆ SetPointerPropertyWithCleanup() [3/4]

◆ SetPointerPropertyWithCleanup() [4/4]

◆ SetStringProperty() [1/2]

◆ SetStringProperty() [2/2]

◆ Unlock()

◆ UnlockProperties()

Variable Documentation

◆ PROP_NAME_STRING

◆ PROPERTY_TYPE_BOOLEAN

◆ PROPERTY_TYPE_INVALID

◆ PROPERTY_TYPE_NUMBER

◆ PROPERTY_TYPE_POINTER

◆ PROPERTY_TYPE_STRING