SDL 3.0
SDL_properties.h File Reference
+ Include dependency graph for SDL_properties.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef Uint32 SDL_PropertiesID
 
typedef void(* SDL_EnumeratePropertiesCallback) (void *userdata, SDL_PropertiesID props, const char *name)
 

Enumerations

enum  SDL_PropertyType {
  SDL_PROPERTY_TYPE_INVALID ,
  SDL_PROPERTY_TYPE_POINTER ,
  SDL_PROPERTY_TYPE_STRING ,
  SDL_PROPERTY_TYPE_NUMBER ,
  SDL_PROPERTY_TYPE_FLOAT ,
  SDL_PROPERTY_TYPE_BOOLEAN
}
 

Functions

SDL_PropertiesID SDL_GetGlobalProperties (void)
 
SDL_PropertiesID SDL_CreateProperties (void)
 
int SDL_LockProperties (SDL_PropertiesID props)
 
void SDL_UnlockProperties (SDL_PropertiesID props)
 
int SDL_SetPropertyWithCleanup (SDL_PropertiesID props, const char *name, void *value, void(*cleanup)(void *userdata, void *value), void *userdata)
 
int SDL_SetProperty (SDL_PropertiesID props, const char *name, void *value)
 
int SDL_SetStringProperty (SDL_PropertiesID props, const char *name, const char *value)
 
int SDL_SetNumberProperty (SDL_PropertiesID props, const char *name, Sint64 value)
 
int SDL_SetFloatProperty (SDL_PropertiesID props, const char *name, float value)
 
int SDL_SetBooleanProperty (SDL_PropertiesID props, const char *name, SDL_bool value)
 
SDL_PropertyType SDL_GetPropertyType (SDL_PropertiesID props, const char *name)
 
void * SDL_GetProperty (SDL_PropertiesID props, const char *name, void *default_value)
 
const char * SDL_GetStringProperty (SDL_PropertiesID props, const char *name, const char *default_value)
 
Sint64 SDL_GetNumberProperty (SDL_PropertiesID props, const char *name, Sint64 default_value)
 
float SDL_GetFloatProperty (SDL_PropertiesID props, const char *name, float default_value)
 
SDL_bool SDL_GetBooleanProperty (SDL_PropertiesID props, const char *name, SDL_bool default_value)
 
int SDL_ClearProperty (SDL_PropertiesID props, const char *name)
 
int SDL_EnumerateProperties (SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata)
 
void SDL_DestroyProperties (SDL_PropertiesID props)
 

Detailed Description

Header file for SDL properties.

Definition in file SDL_properties.h.

Typedef Documentation

◆ SDL_EnumeratePropertiesCallback

typedef void(* SDL_EnumeratePropertiesCallback) (void *userdata, SDL_PropertiesID props, const char *name)

Definition at line 367 of file SDL_properties.h.

◆ SDL_PropertiesID

SDL properties ID

Definition at line 40 of file SDL_properties.h.

Enumeration Type Documentation

◆ SDL_PropertyType

SDL property type

Enumerator
SDL_PROPERTY_TYPE_INVALID 
SDL_PROPERTY_TYPE_POINTER 
SDL_PROPERTY_TYPE_STRING 
SDL_PROPERTY_TYPE_NUMBER 
SDL_PROPERTY_TYPE_FLOAT 
SDL_PROPERTY_TYPE_BOOLEAN 

Definition at line 45 of file SDL_properties.h.

Function Documentation

◆ SDL_ClearProperty()

int SDL_ClearProperty ( SDL_PropertiesID  props,
const char *  name 
)
extern

Clear a property on a set of properties

Parameters
propsthe properties to modify
namethe name of the property to clear
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetProperty

◆ SDL_CreateProperties()

SDL_PropertiesID SDL_CreateProperties ( void  )
extern

Create a set of properties

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

Returns
an ID for a new set of properties, or 0 on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_DestroyProperties

◆ SDL_DestroyProperties()

void SDL_DestroyProperties ( SDL_PropertiesID  props)
extern

Destroy a set of properties

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

Parameters
propsthe properties to destroy

\threadsafety 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.0.0.
See also
SDL_CreateProperties

◆ SDL_EnumerateProperties()

int SDL_EnumerateProperties ( SDL_PropertiesID  props,
SDL_EnumeratePropertiesCallback  callback,
void *  userdata 
)
extern

Enumerate the properties on a set of properties

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

Parameters
propsthe properties to query
callbackthe function to call for each property
userdataa pointer that is passed to callback
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.

◆ SDL_GetBooleanProperty()

SDL_bool SDL_GetBooleanProperty ( SDL_PropertiesID  props,
const char *  name,
SDL_bool  default_value 
)
extern

Get a boolean property on a set of properties

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

Parameters
propsthe properties to query
namethe name of the property to query
default_valuethe default value of the property
Returns
the value of the property, or default_value if it is not set or not a float property.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetPropertyType
SDL_SetBooleanProperty

◆ SDL_GetFloatProperty()

float SDL_GetFloatProperty ( SDL_PropertiesID  props,
const char *  name,
float  default_value 
)
extern

Get a floating point property on a set of properties

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

Parameters
propsthe properties to query
namethe name of the property to query
default_valuethe default value of the property
Returns
the value of the property, or default_value if it is not set or not a float property.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetPropertyType
SDL_SetFloatProperty

◆ SDL_GetGlobalProperties()

SDL_PropertiesID SDL_GetGlobalProperties ( void  )
extern

Get the global SDL properties

Returns
a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetProperty
SDL_SetProperty

◆ SDL_GetNumberProperty()

Sint64 SDL_GetNumberProperty ( SDL_PropertiesID  props,
const char *  name,
Sint64  default_value 
)
extern

Get a number property on a set of properties

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

Parameters
propsthe properties to query
namethe name of the property to query
default_valuethe default value of the property
Returns
the value of the property, or default_value if it is not set or not a number property.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetPropertyType
SDL_SetNumberProperty

◆ SDL_GetProperty()

void * SDL_GetProperty ( SDL_PropertiesID  props,
const char *  name,
void *  default_value 
)
extern

Get a property on a set 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
propsthe properties to query
namethe name of the property to query
default_valuethe default value of the property
Returns
the value of the property, or default_value if it is not set or not a pointer property.

\threadsafety 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 SDL_SetProperty() or SDL_ClearProperty() on these properties from another thread. If you need to avoid this, use SDL_LockProperties() and SDL_UnlockProperties().

Since
This function is available since SDL 3.0.0.
See also
SDL_GetPropertyType
SDL_SetProperty

◆ SDL_GetPropertyType()

SDL_PropertyType SDL_GetPropertyType ( SDL_PropertiesID  props,
const char *  name 
)
extern

Get the type of a property on a set of properties

Parameters
propsthe properties to query
namethe name of the property to query
Returns
the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is not set.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.

◆ SDL_GetStringProperty()

const char * SDL_GetStringProperty ( SDL_PropertiesID  props,
const char *  name,
const char *  default_value 
)
extern

Get a string property on a set of properties

Parameters
propsthe properties to query
namethe name of the property to query
default_valuethe default value of the property
Returns
the value of the property, or default_value if it is not set or not a string property.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetPropertyType
SDL_SetStringProperty

◆ SDL_LockProperties()

int SDL_LockProperties ( SDL_PropertiesID  props)
extern

Lock a set 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
propsthe properties to lock
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_UnlockProperties

◆ SDL_SetBooleanProperty()

int SDL_SetBooleanProperty ( SDL_PropertiesID  props,
const char *  name,
SDL_bool  value 
)
extern

Set a boolean property on a set of properties

Parameters
propsthe properties to modify
namethe name of the property to modify
valuethe new value of the property
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetBooleanProperty

◆ SDL_SetFloatProperty()

int SDL_SetFloatProperty ( SDL_PropertiesID  props,
const char *  name,
float  value 
)
extern

Set a floating point property on a set of properties

Parameters
propsthe properties to modify
namethe name of the property to modify
valuethe new value of the property
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetFloatProperty

◆ SDL_SetNumberProperty()

int SDL_SetNumberProperty ( SDL_PropertiesID  props,
const char *  name,
Sint64  value 
)
extern

Set an integer property on a set of properties

Parameters
propsthe properties to modify
namethe name of the property to modify
valuethe new value of the property
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetNumberProperty

◆ SDL_SetProperty()

int SDL_SetProperty ( SDL_PropertiesID  props,
const char *  name,
void *  value 
)
extern

Set a property on a set of properties

Parameters
propsthe properties to modify
namethe name of the property to modify
valuethe new value of the property, or NULL to delete the property
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetProperty
SDL_SetPropertyWithCleanup

◆ SDL_SetPropertyWithCleanup()

int SDL_SetPropertyWithCleanup ( SDL_PropertiesID  props,
const char *  name,
void *  value,
void(*)(void *userdata, void *value)  cleanup,
void *  userdata 
)
extern

Set a property on a set of properties with a cleanup function that is called when the property is deleted

Parameters
propsthe properties to modify
namethe name of the property to modify
valuethe new value of the property, or NULL to delete the property
cleanupthe function to call when this property is deleted, or NULL if no cleanup is necessary
userdataa pointer that is passed to the cleanup function
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetProperty
SDL_SetProperty

◆ SDL_SetStringProperty()

int SDL_SetStringProperty ( SDL_PropertiesID  props,
const char *  name,
const char *  value 
)
extern

Set a string property on a set of properties

Parameters
propsthe properties to modify
namethe name of the property to modify
valuethe new value of the property, or NULL to delete the property
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetStringProperty

◆ SDL_UnlockProperties()

void SDL_UnlockProperties ( SDL_PropertiesID  props)
extern

Unlock a set of properties

Parameters
propsthe properties to unlock

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_LockProperties