From 53a53502921d7c46258babb99ed51fdca00c2aad Mon Sep 17 00:00:00 2001 From: SDL Wiki Bot Date: Mon, 20 Jan 2025 02:54:44 +0000 Subject: [PATCH] Sync SDL3 wiki -> header [ci skip] --- include/SDL3/SDL_tray.h | 116 ++++++++++++++++++++++++---------------- 1 file changed, 69 insertions(+), 47 deletions(-) diff --git a/include/SDL3/SDL_tray.h b/include/SDL3/SDL_tray.h index f1fbc01cb5..ba96c3f6f2 100644 --- a/include/SDL3/SDL_tray.h +++ b/include/SDL3/SDL_tray.h @@ -106,10 +106,10 @@ typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry); * UTF-8 encoding. Not supported on all platforms. May be NULL. * \returns The newly created system tray icon. * - * \since This function is available since SDL 3.1.8. - * * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.1.8. + * * \sa SDL_CreateTrayMenu * \sa SDL_GetTrayMenu * \sa SDL_DestroyTray @@ -122,9 +122,10 @@ extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_CreateTray(SDL_Surface *icon, const ch * \param tray the tray icon to be updated. * \param icon the new icon. May be NULL. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTray */ @@ -136,9 +137,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *ic * \param tray the tray icon to be updated. * \param tooltip the new tooltip in UTF-8 encoding. May be NULL. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTray */ @@ -157,9 +159,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char * * \param tray the tray to bind the menu to. * \returns the newly created menu. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTray * \sa SDL_GetTrayMenu @@ -180,9 +183,10 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray); * \param entry the tray entry to bind the menu to. * \returns the newly created menu. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_InsertTrayEntryAt * \sa SDL_GetTraySubmenu @@ -204,9 +208,10 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *e * \param tray the tray entry to bind the menu to. * \returns the newly created menu. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTray * \sa SDL_CreateTrayMenu @@ -227,9 +232,10 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayMenu(SDL_Tray *tray); * \param entry the tray entry to bind the menu to. * \returns the newly created menu. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_InsertTrayEntryAt * \sa SDL_CreateTraySubmenu @@ -246,9 +252,10 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entr * pointer becomes invalid when any function that inserts or deletes * entries in the menu is called. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_RemoveTrayEntry * \sa SDL_InsertTrayEntryAt @@ -260,9 +267,10 @@ extern SDL_DECLSPEC const SDL_TrayEntry **SDLCALL SDL_GetTrayEntries(SDL_TrayMen * * \param entry The entry to be deleted. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries * \sa SDL_InsertTrayEntryAt @@ -285,9 +293,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry); * \param flags a combination of flags, some of which are mandatory. * \returns the newly created entry, or NULL if pos is out of bounds. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_TrayEntryFlags * \sa SDL_GetTrayEntries @@ -307,9 +316,10 @@ extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *m * \param entry the entry to be updated. * \param label the new label for the entry in UTF-8 encoding. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries * \sa SDL_InsertTrayEntryAt @@ -325,9 +335,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, con * \param entry the entry to be read. * \returns the label of the entry in UTF-8 encoding. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries * \sa SDL_InsertTrayEntryAt @@ -343,9 +354,10 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *ent * \param entry the entry to be updated. * \param checked true if the entry should be checked; false otherwise. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries * \sa SDL_InsertTrayEntryAt @@ -361,9 +373,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, b * \param entry the entry to be read. * \returns true if the entry is checked; false otherwise. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries * \sa SDL_InsertTrayEntryAt @@ -377,9 +390,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry); * \param entry the entry to be updated. * \param enabled true if the entry should be enabled; false otherwise. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries * \sa SDL_InsertTrayEntryAt @@ -393,9 +407,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, b * \param entry the entry to be read. * \returns true if the entry is enabled; false otherwise. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries * \sa SDL_InsertTrayEntryAt @@ -411,9 +426,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry); * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_GetTrayEntries * \sa SDL_InsertTrayEntryAt @@ -425,9 +441,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, * * \param entry The entry to activate. * - * \since This function is available since SDL 3.1.10. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.10. */ extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); @@ -438,9 +455,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); * * \param tray the tray icon to be destroyed. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTray */ @@ -452,9 +470,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray); * \param entry the entry for which to get the parent menu. * \returns the parent menu. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_InsertTrayEntryAt */ @@ -470,9 +489,10 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry * * \param menu the menu for which to get the parent entry. * \returns the parent entry, or NULL if this menu is not a submenu. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTraySubmenu * \sa SDL_GetTrayMenuParentTray @@ -489,9 +509,10 @@ extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMe * \param menu the menu for which to get the parent enttrayry. * \returns the parent tray, or NULL if this menu is a submenu. * - * \since This function is available since SDL 3.1.8. + * \threadsafety This function should be called on the thread that created the + * tray. * - * \threadsafety This function should be called on the thread that created the tray. + * \since This function is available since SDL 3.1.8. * * \sa SDL_CreateTrayMenu * \sa SDL_GetTrayMenuParentEntry @@ -501,11 +522,12 @@ extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_GetTrayMenuParentTray(SDL_TrayMenu *me /** * Update the trays. * - * This is called automatically by the event loop and is only needed if you're using trays but aren't handling SDL events. - * - * \since This function is available since SDL 3.2.0. + * This is called automatically by the event loop and is only needed if you're + * using trays but aren't handling SDL events. * * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateTrays(void);