mirrors/SDL
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clarify property group documentation

Browse Source 
Fixes https://github.com/libsdl-org/SDL/issues/10241
This commit is contained in:
Sam Lantinga 2024-07-12 10:45:32 -07:00
parent be15d4ae1f
commit 0e56f6a3ca
1 changed files with 29 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
include/SDL3/SDL_properties.h
View File

@ -25,11 +25,11 @@
* A property is a variable that can be created and retrieved by name at
* runtime.
*
* All properties are part of a property set (SDL_PropertiesID). A property
* set can be created with the SDL_CreateProperties function and destroyed
* All properties are part of a property group (SDL_PropertiesID). A property
* group can be created with the SDL_CreateProperties function and destroyed
* with the SDL_DestroyProperties function.
*
* Properties can be added to and retrieved from a property set through the
* Properties can be added to and retrieved from a property group through the
* following functions:
*
* - SDL_SetPointerProperty and SDL_GetPointerProperty operate on `void*`
@ -42,7 +42,7 @@
* - SDL_SetBooleanProperty and SDL_GetBooleanProperty operate on boolean
* types.
*
* Properties can be removed from a set by using SDL_ClearProperty.
* Properties can be removed from a group by using SDL_ClearProperty.
*/
@ -91,11 +91,11 @@ typedef enum SDL_PropertyType
extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);
/**
* Create a set of properties.
* Create a group 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
* \returns an ID for a new group of properties, or 0 on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
@ -107,9 +107,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);
extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
/**
* Copy a set of properties.
* Copy a group of properties.
*
* Copy all the properties from one set of properties to another, with the
* Copy all the properties from one group of properties to another, with the
* exception of properties requiring cleanup (set using
* SDL_SetPointerPropertyWithCleanup()), which will not be copied. Any
* property that already exists on `dst` will be overwritten.
@ -126,7 +126,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
extern SDL_DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst);
/**
* Lock a set of properties.
* Lock a group 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
@ -150,7 +150,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_Pro
extern SDL_DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);
/**
* Unlock a set of properties.
* Unlock a group of properties.
*
* \param props the properties to unlock.
*
@ -168,7 +168,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
* This should release any resources associated with `value` that are no
* longer needed.
*
* This callback is set per-property. Different properties in the same set can
* This callback is set per-property. Different properties in the same group can
* have different cleanup callbacks.
*
* This callback will be called _during_ SDL_SetPointerPropertyWithCleanup if
@ -187,7 +187,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value);
/**
* Set a property on a set of properties with a cleanup function that is
* Set a property on a group 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
@ -218,7 +218,7 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value)
extern SDL_DECLSPEC int SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata);
/**
* Set a property on a set of properties.
* Set a property on a group of properties.
*
* \param props the properties to modify.
* \param name the name of the property to modify.
@ -241,7 +241,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Properties
extern SDL_DECLSPEC int SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value);
/**
* Set a string property on a set of properties.
* Set a string property on a group of properties.
*
* This function makes a copy of the string; the caller does not have to
* preserve the data after this call completes.
@ -261,7 +261,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, c
extern SDL_DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value);
/**
* Set an integer property on a set of properties.
* Set an integer property on a group of properties.
*
* \param props the properties to modify.
* \param name the name of the property to modify.
@ -278,7 +278,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, co
extern SDL_DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value);
/**
* Set a floating point property on a set of properties.
* Set a floating point property on a group of properties.
*
* \param props the properties to modify.
* \param name the name of the property to modify.
@ -295,7 +295,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, co
extern SDL_DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value);
/**
* Set a boolean property on a set of properties.
* Set a boolean property on a group of properties.
*
* \param props the properties to modify.
* \param name the name of the property to modify.
@ -312,7 +312,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, con
extern SDL_DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value);
/**
* Return whether a property exists in a set of properties.
* Return whether a property exists in a group of properties.
*
* \param props the properties to query.
* \param name the name of the property to query.
@ -327,7 +327,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, c
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name);
/**
* Get the type of a property on a set of properties.
* Get the type of a property on a group of properties.
*
* \param props the properties to query.
* \param name the name of the property to query.
@ -343,7 +343,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, con
extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name);
/**
* Get a property on a set of properties.
* Get a property on a group 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
@ -376,7 +376,7 @@ extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesI
extern SDL_DECLSPEC void *SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props, const char *name, void *default_value);
/**
* Get a string property on a set of properties.
* Get a string property on a group of properties.
*
* The returned string follows the SDL_GetStringRule.
*
@ -397,7 +397,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props,
extern SDL_DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);
/**
* Get a number property on a set of properties.
* Get a number property on a group of properties.
*
* You can use SDL_GetPropertyType() to query whether the property exists and
* is a number property.
@ -419,7 +419,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID p
extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value);
/**
* Get a floating point property on a set of properties.
* Get a floating point property on a group of properties.
*
* You can use SDL_GetPropertyType() to query whether the property exists and
* is a floating point property.
@ -441,7 +441,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props,
extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value);
/**
* Get a boolean property on a set of properties.
* Get a boolean property on a group of properties.
*
* You can use SDL_GetPropertyType() to query whether the property exists and
* is a boolean property.
@ -463,7 +463,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c
extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value);
/**
* Clear a property on a set of properties.
* Clear a property on a group of properties.
*
* \param props the properties to modify.
* \param name the name of the property to clear.
@ -477,7 +477,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID pro
extern SDL_DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name);
/**
* A callback used to enumerate all properties set in an SDL_PropertiesID.
* A callback used to enumerate all the properties in a group of properties.
*
* This callback is called from SDL_EnumerateProperties(), and is called once
* per property in the set.
@ -496,9 +496,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const
typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name);
/**
* Enumerate the properties contained in a property set.
* Enumerate the properties contained in a group of properties.
*
* The callback function is called for each property on the set of properties.
* The callback function is called for each property in the group of properties.
* The properties are locked during enumeration.
*
* \param props the properties to query.
@ -514,7 +514,7 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop
extern SDL_DECLSPEC int SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata);
/**
* Destroy a set of properties.
* Destroy a group of properties.
*
* All properties are deleted and their cleanup functions will be called, if
* any.