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_CopyProperties (SDL_PropertiesID src, SDL_PropertiesID dst)
 
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_bool SDL_HasProperty (SDL_PropertiesID props, const char *name)
 
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 428 of file SDL_properties.h.

◆ SDL_PropertiesID

SDL properties ID

Since
This datatype is available since SDL 3.0.0.

Definition at line 45 of file SDL_properties.h.

Enumeration Type Documentation

◆ SDL_PropertyType

SDL property type

Since
This enum is available since SDL 3.0.0.
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 52 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.

◆ SDL_CopyProperties()

int SDL_CopyProperties ( SDL_PropertiesID  src,
SDL_PropertiesID  dst 
)
extern

Copy a set of properties.

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

Parameters
srcthe properties to copy
dstthe destination properties
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_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_HasProperty
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_HasProperty
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_HasProperty
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_GetBooleanProperty
SDL_GetFloatProperty
SDL_GetNumberProperty
SDL_GetPropertyType
SDL_GetStringProperty
SDL_HasProperty
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.
See also
SDL_HasProperty

◆ 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_HasProperty
SDL_SetStringProperty

◆ SDL_HasProperty()

SDL_bool SDL_HasProperty ( SDL_PropertiesID  props,
const char *  name 
)
extern

Return whether a property exists in a set of properties.

Parameters
propsthe properties to query
namethe name of the property to query
Returns
SDL_TRUE if the property exists, or SDL_FALSE if it doesn't.

\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_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_HasProperty
SDL_SetBooleanProperty
SDL_SetFloatProperty
SDL_SetNumberProperty
SDL_SetPropertyWithCleanup
SDL_SetStringProperty

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

The cleanup function is also called if setting the property fails for any reason.

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.

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

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