Object Properties

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

Classes
struct	SDL::PropertiesRef
	SDL properties ID. More...
struct	SDL::Properties
	Handle to an owned properties. More...
struct	SDL::PropertiesUnsafe
	Unsafe Handle to properties. More...
struct	SDL::PropertiesLock
	Wrap the lock state for Properties. More...

Typedefs
using	SDL::PropertyType = SDL_PropertyType
	SDL property type.
using	SDL::PropertiesShared = ResourceShared< Properties >
	Handle to a shared properties.
using	SDL::PropertiesWeak = ResourceWeak< Properties >
	Weak handle to a shared properties.

Functions
PropertiesRef	SDL::GetGlobalProperties ()
	Get the global SDL properties.
PropertiesShared	SDL::Properties::share ()
	Move this properties into a PropertiesShared.
PropertiesLock	SDL::PropertiesRef::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 PropertiesRef.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 PropertiesRef.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 (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:

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

Properties can be removed from a group by using PropertiesRef.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 PropertiesRef.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

PropertiesRef.SetPointerWithCleanup

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

PropertiesRef.SetPointerWithCleanup

CleanupPropertyCallback

result-callback

Category:

Result callback

EnumeratePropertiesCallback

using SDL::EnumeratePropertiesCallback = typedef SDL_EnumeratePropertiesCallback

This callback is called from PropertiesRef.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:

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

Since

This datatype is available since SDL 3.2.0.

See also

PropertiesRef.Enumerate

EnumeratePropertiesCB

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

This callback is called from PropertiesRef.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:

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

Since

This datatype is available since SDL 3.2.0.

Category:

Immediate callback

See also

PropertiesRef.Enumerate

EnumeratePropertiesCallback

PropertiesShared

using SDL::PropertiesShared = typedef ResourceShared<Properties>

Category:

Resource

See also

PropertiesRef

Properties

PropertiesWeak

using SDL::PropertiesWeak = typedef ResourceWeak<Properties>

Category:

Resource

See also

PropertiesShared

PropertiesRef

PropertyType

using SDL::PropertyType = typedef SDL_PropertyType

Since

This enum is available since SDL 3.2.0.

Function Documentation

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::PropertiesRef::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