mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2026-02-17 17:08:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Added SDL_SetAppMetadata() (#10404)

Browse Source 
Removed duplicate hints SDL_HINT_APP_NAME, SDL_HINT_APP_ID, and
SDL_HINT_AUDIO_DEVICE_APP_NAME.

Wired up a few things to use the metadata; more to come!

Fixes https://github.com/libsdl-org/SDL/issues/4703
This commit is contained in:
Sam Lantinga
2024-07-28 07:22:46 -07:00
committed by GitHub
parent 35e42d0a25
commit a36fe632fd
13 changed files with 214 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
include/SDL3/SDL_hints.h
View File

@@ -125,79 +125,6 @@ extern "C" {
*/
#define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON"
/**
* A variable setting the app ID string.
*
* This string is used by desktop compositors to identify and group windows
* together, as well as match applications with associated desktop settings
* and icons.
*
* On Wayland this corresponds to the "app ID" window property and on X11 this
* corresponds to the WM_CLASS property. Windows inherit the value of this
* hint at creation time. Changing this hint after a window has been created
* will not change the app ID or class of existing windows.
*
* For *nix platforms, this string should be formatted in reverse-DNS notation
* and follow some basic rules to be valid:
*
* - The application ID must be composed of two or more elements separated by
* a period (.) character.
* - Each element must contain one or more of the alphanumeric characters
* (A-Z, a-z, 0-9) plus underscore (_) and hyphen (-) and must not start
* with a digit. Note that hyphens, while technically allowed, should not be
* used if possible, as they are not supported by all components that use
* the ID, such as D-Bus. For maximum compatibility, replace hyphens with an
* underscore.
* - The empty string is not a valid element (ie: your application ID may not
* start or end with a period and it is not valid to have two periods in a
* row).
* - The entire ID must be less than 255 characters in length.
*
* Examples of valid app ID strings:
*
* - org.MyOrg.MyApp
* - com.your_company.your_app
*
* Desktops such as GNOME and KDE require that the app ID string matches your
* application's .desktop file name (e.g. if the app ID string is
* 'org.MyOrg.MyApp', your application's .desktop file should be named
* 'org.MyOrg.MyApp.desktop').
*
* If you plan to package your application in a container such as Flatpak, the
* app ID should match the name of your Flatpak container as well.
*
* If not set, SDL will attempt to use the application executable name. If the
* executable name cannot be retrieved, the generic string "SDL_App" will be
* used.
*
* This hint should be set before SDL is initialized.
*
* \since This hint is available since SDL 3.0.0.
*/
#define SDL_HINT_APP_ID "SDL_APP_ID"
/**
* Specify an application name.
*
* This hint lets you specify the application name sent to the OS when
* required. For example, this will often appear in volume control applets for
* audio streams, and in lists of applications which are inhibiting the
* screensaver. You should use a string that describes your program ("My Game
* 2: The Revenge")
*
* Setting this to "" or leaving it unset will have SDL use a reasonable
* default: probably the application's name or "SDL Application" if SDL
* doesn't have any better information.
*
* Note that, for audio streams, this can be overridden with
* SDL_HINT_AUDIO_DEVICE_APP_NAME.
*
* This hint should be set before SDL is initialized.
*
* \since This hint is available since SDL 3.0.0.
*/
#define SDL_HINT_APP_NAME "SDL_APP_NAME"
/**
* A variable controlling whether controllers used with the Apple TV generate
* UI events.
@@ -254,29 +181,6 @@ extern "C" {
*/
#define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY"
/**
* Specify an application name for an audio device.
*
* Some audio backends (such as PulseAudio) allow you to describe your audio
* stream. Among other things, this description might show up in a system
* control panel that lets the user adjust the volume on specific audio
* streams instead of using one giant master volume slider.
*
* This hints lets you transmit that information to the OS. The contents of
* this hint are used while opening an audio device. You should use a string
* that describes your program ("My Game 2: The Revenge")
*
* Setting this to "" or leaving it unset will have SDL use a reasonable
* default: this will be the name set with SDL_HINT_APP_NAME, if that hint is
* set. Otherwise, it'll probably the application's name or "SDL Application"
* if SDL doesn't have any better information.
*
* This hint should be set before an audio device is opened.
*
* \since This hint is available since SDL 3.0.0.
*/
#define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME"
/**
* Specify an application icon name for an audio device.
*

124
include/SDL3/SDL_init.h
View File

@@ -105,12 +105,18 @@ typedef Uint32 SDL_InitFlags;
* call SDL_Quit() to force shutdown). If a subsystem is already loaded then
* this call will increase the ref-count and return.
*
* Consider reporting some basic metadata about your application before
* calling SDL_Init, using either SDL_SetAppMetadata() or
* SDL_SetAppMetadataProperty().
*
* \param flags subsystem initialization flags.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_SetAppMetadata
* \sa SDL_SetAppMetadataProperty
* \sa SDL_InitSubSystem
* \sa SDL_Quit
* \sa SDL_SetMainReady
@@ -182,6 +188,124 @@ extern SDL_DECLSPEC SDL_InitFlags SDLCALL SDL_WasInit(SDL_InitFlags flags);
*/
extern SDL_DECLSPEC void SDLCALL SDL_Quit(void);
/**
* Specify basic metadata about your app.
*
* You can optionally provide metadata about your app to SDL. This is not
* required, but strongly encouraged.
*
* There are several locations where SDL can make use of metadata (an "About"
* box in the macOS menu bar, the name of the app can be shown on some audio
* mixers, etc). Any piece of metadata can be left as NULL, if a specific detail
* doesn't make sense for the app.
*
* This function should be called as early as possible, before SDL_Init.
* Multiple calls to this function are allowed, but various state might not
* change once it has been set up with a previous call to this function.
*
* Passing a NULL removes any previous metadata.
*
* This is a simplified interface for the most important information. You can
* supply significantly more detailed metadata with SDL_SetAppMetadataProperty().
*
* \param appname The name of the application ("My Game 2: Bad Guy's Revenge!").
* \param appversion The version of the application ("1.0.0beta5" or a git hash, or whatever makes sense).
* \param appidentifier A unique string in reverse-domain format that identifies this app ("com.example.mygame2").
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \threadsafety It is safe to call this function from any thread.
*
* \sa SDL_SetAppMetadataProperty
*/
extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier);
/**
* Specify metadata about your app through a set of properties.
*
* You can optionally provide metadata about your app to SDL. This is not
* required, but strongly encouraged.
*
* There are several locations where SDL can make use of metadata (an "About"
* box in the macOS menu bar, the name of the app can be shown on some audio
* mixers, etc). Any piece of metadata can be left out, if a specific detail
* doesn't make sense for the app.
*
* This function should be called as early as possible, before SDL_Init.
* Multiple calls to this function are allowed, but various state might not
* change once it has been set up with a previous call to this function.
*
* Once set, this metadata can be read using SDL_GetMetadataProperty().
*
* These are the supported properties:
*
* - `SDL_PROP_APP_METADATA_NAME_STRING`: The human-readable name of
* the application, like "My Game 2: Bad Guy's Revenge!". This defaults to "SDL Application".
* - SDL_PROP_APP_METADATA_VERSION_STRING`: The version of the app that
* is running; there are no rules on format, so "1.0.3beta2" and
* "April 22nd, 2024" and a git hash are all valid options. This has no default.
* - `SDL_PROP_APP_METADATA_IDENTIFIER_STRING`: A unique string that
* identifies this app. This must be in reverse-domain format, like
* "com.example.mygame2". This string is used by desktop compositors to
* identify and group windows together, as well as match applications
* with associated desktop settings and icons. This has no default.
* - SDL_PROP_APP_METADATA_CREATOR_STRING`: The human-readable name
* of the creator/developer/maker of this app, like "MojoWorkshop, LLC"
* - SDL_PROP_APP_METADATA_COPYRIGHT_STRING`: The human-readable copyright
* notice, like "Copyright (c) 2024 MojoWorkshop, LLC" or whatnot. Keep
* this to one line, don't paste a copy of a whole software license in
* here. This has no default.
* - SDL_PROP_APP_METADATA_URL_STRING`: A URL to the app on the web. Maybe
* a product page, or a storefront, or even a GitHub repository, for
* user's further information This has no default.
* - SDL_PROP_APP_METADATA_TYPE_STRING`: The type of application this is.
* Currently this string can be "game" for a video game, "mediaplayer" for
* a media player, or generically "application" if nothing else applies.
* Future versions of SDL might add new types. This defaults to "application".
*
* \param name the name of the metadata property to set.
* \param value the value of the property, or NULL to remove that property.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \threadsafety It is safe to call this function from any thread.
*
* \sa SDL_GetAppMetadataProperty
* \sa SDL_SetAppMetadata
*/
extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value);
#define SDL_PROP_APP_METADATA_NAME_STRING "SDL.app.metadata.name"
#define SDL_PROP_APP_METADATA_VERSION_STRING "SDL.app.metadata.version"
#define SDL_PROP_APP_METADATA_IDENTIFIER_STRING "SDL.app.metadata.identifier"
#define SDL_PROP_APP_METADATA_CREATOR_STRING "SDL.app.metadata.creator"
#define SDL_PROP_APP_METADATA_COPYRIGHT_STRING "SDL.app.metadata.copyright"
#define SDL_PROP_APP_METADATA_URL_STRING "SDL.app.metadata.url"
#define SDL_PROP_APP_METADATA_TYPE_STRING "SDL.app.metadata.type"
/**
* Get metadata about your app.
*
* This returns metadata previously set using SDL_SetAppMetadata() or SDL_SetAppMetadataProperty(). See SDL_SetAppMetadataProperty() for the list of available properties and their meanings.
*
* \param name the name of the metadata property to get.
* \returns the current value of the metadata property, or the default if it is not set, NULL for properties with no default.
*
* \since This function is available since SDL 3.0.0.
*
* \threadsafety It is safe to call this function from any thread, although
* the string returned is not protected and could potentially be
* freed if you call SDL_SetAppMetadataProperty() to set that property from another thread.
*
* \sa SDL_SetAppMetadata
* \sa SDL_SetAppMetadataProperty
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetAppMetadataProperty(const char *name);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}