Object Properties

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

Classes
struct	SDL::PropertiesBase
	Wrap properties id. More...
struct	SDL::PropertiesRef
	Handle to a non owned properties. More...
struct	SDL::Properties
	Handle to an owned properties. More...
class	SDL::PropertiesLock
	Wrap the lock state for PropertiesBase. More...

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

Functions
PropertiesRef	SDL::GetGlobalProperties ()
	Get the global SDL properties.
Properties	SDL::CreateProperties ()
	Create a group of properties.
PropertiesLock	SDL::PropertiesBase::Lock () &
	Lock 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.

Callbacks for PropertiesBase.SetPointerWithCleanup()
using	SDL::CleanupPropertyCallback = SDL_CleanupPropertyCallback
	A callback used to free resources when a property is deleted.
using	SDL::CleanupPropertyCB = std::function< void(void *)>
	A callback used to free resources when a property is deleted.

Callbacks for PropertiesBase.Enumerate()
using	SDL::EnumeratePropertiesCallback = SDL_EnumeratePropertiesCallback
	A callback used to enumerate all the properties in a group of properties.
using	SDL::EnumeratePropertiesCB = std::function< void(PropertiesRef props, const char *name)>
	A callback used to enumerate all the properties in a group of properties.

Detailed Description

All properties are part of a property group (PropertiesBase). A property group can be created with the CreateProperties() function or by simply instantiating Properties. It can be destroyed with the PropertiesRef.reset(), 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:

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

Properties can be removed from a group by using PropertiesBase.Clear().

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 PropertiesBase.SetPointerWithCleanup 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

PropertiesBase.SetPointerWithCleanup

CleanupPropertyCB

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

See also

CleanupPropertyCallback

PropertiesBase.SetPointerWithCleanup()

result-callback

Category:

Result callback

EnumeratePropertiesCallback

using SDL::EnumeratePropertiesCallback = typedef SDL_EnumeratePropertiesCallback

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

Parameters

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

Thread safety:

PropertiesBase.Enumerate holds a lock on props during this callback.

Since

This datatype is available since SDL 3.2.0.

See also

PropertiesBase.Enumerate

EnumeratePropertiesCB

using SDL::EnumeratePropertiesCB = typedef std::function<void(PropertiesRef props, const char* name)>

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

Parameters

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

Thread safety:

PropertiesBase.Enumerate holds a lock on props during this callback.

Since

This datatype is available since SDL 3.2.0.

Category:

Immediate callback

See also

PropertiesBase.Enumerate

EnumeratePropertiesCallback

PropertyType

using SDL::PropertyType = typedef SDL_PropertyType

Since

This enum is available since SDL 3.2.0.

Function Documentation

CreateProperties()

Properties SDL::CreateProperties ( )

inline

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

Returns

a valid Properties for a new group of properties, 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

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.

Lock()

PropertiesLock SDL::PropertiesBase::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.

Returns

PropertiesLock 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

PropertiesLock.Unlock

Variable Documentation

PROPERTY_TYPE_BOOLEAN

constexpr PropertyType SDL::PROPERTY_TYPE_BOOLEAN

constexpr

Initial value:

=
  SDL_PROPERTY_TYPE_BOOLEAN

PROPERTY_TYPE_INVALID

constexpr PropertyType SDL::PROPERTY_TYPE_INVALID

constexpr

Initial value:

=
  SDL_PROPERTY_TYPE_INVALID

PROPERTY_TYPE_NUMBER

constexpr PropertyType SDL::PROPERTY_TYPE_NUMBER

constexpr

Initial value:

=
  SDL_PROPERTY_TYPE_NUMBER

PROPERTY_TYPE_POINTER

constexpr PropertyType SDL::PROPERTY_TYPE_POINTER

constexpr

Initial value:

=
  SDL_PROPERTY_TYPE_POINTER

PROPERTY_TYPE_STRING

constexpr PropertyType SDL::PROPERTY_TYPE_STRING

constexpr

Initial value:

=
  SDL_PROPERTY_TYPE_STRING