SDL_SetAppMetadataProperty(3)

💖 SDL_SetAppMetadataProperty 💖

okay bestie, welcome to the SDL3 FUNCTIONS manual, this one's about SDL_SetAppMetadataProperty(3) and it's genuinely so cute, it's the "tell SDL who u are" function 🎀

---

✨ NAME ✨

SDL_SetAppMetadataProperty — spill the tea about ur app through a set of properties 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_init.h>

bool SDL_SetAppMetadataProperty(const char *name, const char *value);

---

🦋 DESCRIPTION 🦋

so like, u can optionally hand SDL some metadata about ur app. it's not required, but bestie, it is strongly encouraged. do it. be iconic. 👑

there's a bunch of places where SDL can actually use this metadata — think an "About" box chilling in the macOS menu bar, or ur app's name showing up in some audio mixers, etc etc. and ngl any single piece of metadata can just be left out if that specific detail doesn't make sense for ur app. no pressure, no cap. 🫶

call this function as early as possible, like before SDL_Init. multiple calls to this function are allowed, but heads up — various state might not change once it's been set up by a previous call to this function. so like, order matters, iykyk. 💀

once u set it, this metadata can be read back using SDL_GetAppMetadataProperty(). 💖

and these are the supported properties, queen:

• SDL_PROP_APP_METADATA_NAME_STRING — the human-readable name of the application, like "My Game 2: Bad Guy's Revenge!". this shows up anywhere the OS shows the app's name separately from window titles, like volume control applets, etc. if the app doesn't provide it, SDL will attempt to pick a reasonable default (the app's binary's name if the platform can provide it, or "SDL Application" if all else fails). 🎀
• 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, go wild. 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. if u plan on packaging ur application in a container such as Flatpak, the app ID should match the name of ur Flatpak container as well. 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, do NOT paste a copy of a whole software license in here bestie i'm begging 😭. 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". 💜

---

💅 FUNCTION PARAMETERS 💅

• name — the name of the metadata property to set.
• value — the value of the property, or NULL to remove that property.

---

👑 RETURN VALUE 👑

returns true on success or false on failure; call SDL_GetError() for more information. and yes, if it's false, go read the error, don't just sit there. 🙈

---

🧚 THREAD SAFETY 🧚

it is safe to call this function from any thread. slay, no locks needed, she's thread-safe periodt. ✨

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0. (yes it's new, yes she's thriving)

---

🌸 SEE ALSO 🌸

• SDL_GetAppMetadataProperty(3)
• SDL_SetAppMetadata(3)

---

ok that's the whole page bestie, go set ur metadata, make ur app's About box cute, and remember: reverse-domain format or it doesn't count 💖🦋

this has been a page from Simple Directmedia Layer, SDL 3.4.18 — mwah, take care of urself, drink some water, and call SDL_Init after ur metadata, not before 😌💅🎀