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

Collaboration diagram for Object Properties:

Classes
struct	SDL::PropertiesParam
	Safely wrap Properties for non owning parameters. More...

class	SDL::Properties
	SDL properties ID. More...

struct	SDL::PropertiesRef
	Semi-safe reference for Properties. More...

Typedefs
using	SDL::PropertiesID = SDL_PropertiesID
	Alias to raw representation for Properties.

using	SDL::PropertyType = SDL_PropertyType
	SDL property type. More...

using	SDL::EnumeratePropertiesCallback = SDL_EnumeratePropertiesCallback
	A callback used to enumerate all the properties in a group of properties. More...

using	SDL::EnumeratePropertiesCB = std::function< void(PropertiesID props, const char *name)>
	A callback used to enumerate all the properties in a group of properties. More...

using	SDL::CleanupPropertyCallback = SDL_CleanupPropertyCallback
	A callback used to free resources when a property is deleted. More...

using	SDL::CleanupPropertyCB = std::function< void(void *)>
	A callback used to free resources when a property is deleted. More...

Functions
PropertiesRef	SDL::GetGlobalProperties ()
	Get the global SDL properties. More...

Properties	SDL::CreateProperties ()
	Create a group of properties. More...

void	SDL::CopyProperties (PropertiesParam src, PropertiesParam dst)
	Copy a group of properties. More...

void	SDL::LockProperties (PropertiesParam props)
	Lock a group of properties. More...

void	SDL::UnlockProperties (PropertiesParam props)
	Unlock a group of properties. More...

void	SDL::SetPointerPropertyWithCleanup (PropertiesParam 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. More...

void	SDL::SetPointerPropertyWithCleanup (PropertiesParam 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. More...

void	SDL::SetPointerProperty (PropertiesParam props, StringParam name, void *value)
	Set a pointer property in a group of properties. More...

void	SDL::SetStringProperty (PropertiesParam props, StringParam name, StringParam value)
	Set a string property in a group of properties. More...

void	SDL::SetNumberProperty (PropertiesParam props, StringParam name, Sint64 value)
	Set an integer property in a group of properties. More...

void	SDL::SetFloatProperty (PropertiesParam props, StringParam name, float value)
	Set a floating point property in a group of properties. More...

void	SDL::SetBooleanProperty (PropertiesParam props, StringParam name, bool value)
	Set a boolean property in a group of properties. More...

bool	SDL::HasProperty (PropertiesParam props, StringParam name)
	Return whether a property exists in a group of properties. More...

PropertyType	SDL::GetPropertyType (PropertiesParam props, StringParam name)
	Get the type of a property in a group of properties. More...

void *	SDL::GetPointerProperty (PropertiesParam props, StringParam name, void *default_value)
	Get a pointer property from a group of properties. More...

const char *	SDL::GetStringProperty (PropertiesParam props, StringParam name, StringParam default_value)
	Get a string property from a group of properties. More...

Sint64	SDL::GetNumberProperty (PropertiesParam props, StringParam name, Sint64 default_value)
	Get a number property from a group of properties. More...

float	SDL::GetFloatProperty (PropertiesParam props, StringParam name, float default_value)
	Get a floating point property from a group of properties. More...

bool	SDL::GetBooleanProperty (PropertiesParam props, StringParam name, bool default_value)
	Get a boolean property from a group of properties. More...

void	SDL::ClearProperty (PropertiesParam props, StringParam name)
	Clear a property from a group of properties. More...

void	SDL::EnumerateProperties (PropertiesParam props, EnumeratePropertiesCallback callback, void *userdata)
	Enumerate the properties contained in a group of properties. More...

void	SDL::EnumerateProperties (PropertiesParam props, EnumeratePropertiesCB callback)
	Enumerate the properties contained in a group of properties. More...

Uint64	SDL::CountProperties (PropertiesParam props)
	Returns the number of properties this has. More...

void	SDL::DestroyProperties (PropertiesID props)
	Destroy a group of properties. More...

static Properties	SDL::Properties::Create ()
	Create a group of properties. More...

void	SDL::Properties::Copy (PropertiesParam dst)
	Copy a group of properties. More...

void	SDL::Properties::Lock ()
	Lock a group of properties. More...

void	SDL::Properties::Unlock ()
	Unlock a group of properties. More...

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. More...

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. More...

void	SDL::Properties::SetPointerProperty (StringParam name, void *value)
	Set a pointer property in a group of properties. More...

void	SDL::Properties::SetStringProperty (StringParam name, StringParam value)
	Set a string property in a group of properties. More...

void	SDL::Properties::SetNumberProperty (StringParam name, Sint64 value)
	Set an integer property in a group of properties. More...

void	SDL::Properties::SetFloatProperty (StringParam name, float value)
	Set a floating point property in a group of properties. More...

void	SDL::Properties::SetBooleanProperty (StringParam name, bool value)
	Set a boolean property in a group of properties. More...

bool	SDL::Properties::HasProperty (StringParam name)
	Return whether a property exists in a group of properties. More...

PropertyType	SDL::Properties::GetPropertyType (StringParam name)
	Get the type of a property in a group of properties. More...

void *	SDL::Properties::GetPointerProperty (StringParam name, void *default_value)
	Get a pointer property from a group of properties. More...

const char *	SDL::Properties::GetStringProperty (StringParam name, StringParam default_value)
	Get a string property from a group of properties. More...

Sint64	SDL::Properties::GetNumberProperty (StringParam name, Sint64 default_value)
	Get a number property from a group of properties. More...

float	SDL::Properties::GetFloatProperty (StringParam name, float default_value)
	Get a floating point property from a group of properties. More...

bool	SDL::Properties::GetBooleanProperty (StringParam name, bool default_value)
	Get a boolean property from a group of properties. More...

void	SDL::Properties::ClearProperty (StringParam name)
	Clear a property from a group of properties. More...

void	SDL::Properties::Enumerate (EnumeratePropertiesCallback callback, void *userdata)
	Enumerate the properties contained in a group of properties. More...

void	SDL::Properties::Enumerate (EnumeratePropertiesCB callback)
	Enumerate the properties contained in a group of properties. More...

Uint64	SDL::Properties::GetCount ()
	Returns the number of properties this has. More...

void	SDL::Properties::Destroy ()
	Destroy a group of properties. More...

Variables
constexpr PropertyType	SDL::PROPERTY_TYPE_INVALID
	INVALID. More...

constexpr PropertyType	SDL::PROPERTY_TYPE_POINTER
	POINTER. More...

constexpr PropertyType	SDL::PROPERTY_TYPE_STRING
	STRING. More...

constexpr PropertyType	SDL::PROPERTY_TYPE_NUMBER
	NUMBER. More...

constexpr PropertyType	SDL::PROPERTY_TYPE_FLOAT = SDL_PROPERTY_TYPE_FLOAT
	FLOAT.

constexpr PropertyType	SDL::PROPERTY_TYPE_BOOLEAN
	BOOLEAN. More...

Detailed Description

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 = typedef SDL_CleanupPropertyCallback

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 = typedef std::function<void(void*)>

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 = typedef SDL_EnumeratePropertiesCallback

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 = typedef std::function<void(PropertiesID props, const char* name)>

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 = typedef SDL_PropertyType

Since: This enum is available since SDL 3.2.0.

Function Documentation

◆ ClearProperty() [1/2]

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

inline

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

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 ( PropertiesParam dst )

inline

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.

Since: This function is available since SDL 3.2.0.

◆ CopyProperties()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ CountProperties()

Uint64 SDL::CountProperties ( PropertiesParam props )

inline

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

Parameters

props

Returns: Uint64

◆ Create()

Properties SDL::Properties::Create ( )

inlinestatic

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

Returns: a valid 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

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

Returns: a valid 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

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

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

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

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	(	PropertiesParam	props,
		EnumeratePropertiesCallback	callback,
		void *	userdata
	)

inline

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	(	PropertiesParam	props,
		EnumeratePropertiesCB	callback
	)

inline

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	(	PropertiesParam	props,
		StringParam	name,
		bool	default_value
	)

inline

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

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

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

Returns: Uint64

◆ GetFloatProperty() [1/2]

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

inline

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

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

Returns: a valid property ID on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetNumberProperty() [1/2]

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

inline

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

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	(	PropertiesParam	props,
		StringParam	name,
		void *	default_value
	)

inline

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

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	(	PropertiesParam	props,
		StringParam	name
	)

inline

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

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	(	PropertiesParam	props,
		StringParam	name,
		StringParam	default_value
	)

inline

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

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	(	PropertiesParam	props,
		StringParam	name
	)

inline

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

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()

void SDL::Properties::Lock ( )

inline

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 ( PropertiesParam props )

inline

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

◆ SetBooleanProperty() [1/2]

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

inline

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

◆ SetBooleanProperty() [2/2]

void SDL::Properties::SetBooleanProperty	(	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: Properties.GetBooleanProperty

◆ SetFloatProperty() [1/2]

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

inline

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

◆ SetFloatProperty() [2/2]

void SDL::Properties::SetFloatProperty	(	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: Properties.GetFloatProperty

◆ SetNumberProperty() [1/2]

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

inline

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

◆ SetNumberProperty() [2/2]

void SDL::Properties::SetNumberProperty	(	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: Properties.GetNumberProperty

◆ SetPointerProperty() [1/2]

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

inline

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

◆ SetPointerProperty() [2/2]

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

◆ SetPointerPropertyWithCleanup() [1/4]

void SDL::SetPointerPropertyWithCleanup	(	PropertiesParam	props,
		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 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() [2/4]

void SDL::SetPointerPropertyWithCleanup	(	PropertiesParam	props,
		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 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

◆ SetPointerPropertyWithCleanup() [3/4]

void SDL::Properties::SetPointerPropertyWithCleanup	(	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 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() [4/4]

void SDL::Properties::SetPointerPropertyWithCleanup	(	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 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

◆ SetStringProperty() [1/2]

void SDL::SetStringProperty	(	PropertiesParam	props,
		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

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

◆ SetStringProperty() [2/2]

void SDL::Properties::SetStringProperty	(	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: Properties.GetStringProperty

◆ Unlock()

void SDL::Properties::Unlock ( )

inline

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 ( PropertiesParam props )

inline

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

SDL_PROPERTY_TYPE_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()

◆ 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

◆ PROPERTY_TYPE_BOOLEAN

◆ PROPERTY_TYPE_INVALID

◆ PROPERTY_TYPE_NUMBER

◆ PROPERTY_TYPE_POINTER

◆ PROPERTY_TYPE_STRING