mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-09-05 19:08:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

tray: document thread-safety

Browse Source
This commit is contained in:
Sam Lantinga
2025-01-19 10:42:49 -08:00
parent d4cda51057
commit dfdc120268
4 changed files with 60 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
include/SDL3/SDL_tray.h
View File

@@ -108,6 +108,8 @@ typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry);
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should only be called on the main thread.
*
* \sa SDL_CreateTrayMenu
* \sa SDL_GetTrayMenu
* \sa SDL_DestroyTray
@@ -122,6 +124,8 @@ extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_CreateTray(SDL_Surface *icon, const ch
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_CreateTray
*/
extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *icon);
@@ -134,6 +138,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *ic
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_CreateTray
*/
extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *tooltip);
@@ -153,6 +159,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_CreateTray
* \sa SDL_GetTrayMenu
* \sa SDL_GetTrayMenuParentTray
@@ -174,6 +182,8 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray);
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_InsertTrayEntryAt
* \sa SDL_GetTraySubmenu
* \sa SDL_GetTrayMenuParentEntry
@@ -196,6 +206,8 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *e
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_CreateTray
* \sa SDL_CreateTrayMenu
*/
@@ -217,6 +229,8 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayMenu(SDL_Tray *tray);
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_InsertTrayEntryAt
* \sa SDL_CreateTraySubmenu
*/
@@ -234,6 +248,8 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entr
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_RemoveTrayEntry
* \sa SDL_InsertTrayEntryAt
*/
@@ -246,6 +262,8 @@ extern SDL_DECLSPEC const SDL_TrayEntry **SDLCALL SDL_GetTrayEntries(SDL_TrayMen
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
*/
@@ -269,6 +287,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry);
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_TrayEntryFlags
* \sa SDL_GetTrayEntries
* \sa SDL_RemoveTrayEntry
@@ -289,6 +309,8 @@ extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *m
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
* \sa SDL_GetTrayEntryLabel
@@ -305,6 +327,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, con
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
* \sa SDL_SetTrayEntryLabel
@@ -321,6 +345,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *ent
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
* \sa SDL_GetTrayEntryChecked
@@ -337,6 +363,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, b
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
* \sa SDL_SetTrayEntryChecked
@@ -351,6 +379,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry);
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
* \sa SDL_GetTrayEntryEnabled
@@ -365,6 +395,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, b
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
* \sa SDL_SetTrayEntryEnabled
@@ -381,6 +413,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry);
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
*/
@@ -392,6 +426,8 @@ 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.
*/
extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry);
@@ -404,18 +440,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry);
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_CreateTray
*/
extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray);
/**
* Gets the menu contianing a certain tray entry.
* Gets the menu containing a certain tray entry.
*
* \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.
*
* \sa SDL_InsertTrayEntryAt
*/
extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *entry);
@@ -432,6 +472,8 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_CreateTraySubmenu
* \sa SDL_GetTrayMenuParentTray
*/
@@ -449,6 +491,8 @@ extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMe
*
* \since This function is available since SDL 3.1.8.
*
* \threadsafety This function should be called on the thread that created the tray.
*
* \sa SDL_CreateTrayMenu
* \sa SDL_GetTrayMenuParentEntry
*/

5
src/tray/cocoa/SDL_tray.m
View File

@@ -80,6 +80,11 @@ static void DestroySDLMenu(SDL_TrayMenu *menu)
SDL_Tray *SDL_CreateTray(SDL_Surface *icon, const char *tooltip)
{
if (!SDL_IsMainThread()) {
SDL_SetError("This function should be called on the main thread");
return NULL;
}
if (icon) {
icon = SDL_ConvertSurface(icon, SDL_PIXELFORMAT_RGBA32);
if (!icon) {

5
src/tray/unix/SDL_tray.c
View File

@@ -398,6 +398,11 @@ static void DestroySDLMenu(SDL_TrayMenu *menu)
SDL_Tray *SDL_CreateTray(SDL_Surface *icon, const char *tooltip)
{
if (!SDL_IsMainThread()) {
SDL_SetError("This function should be called on the main thread");
return NULL;
}
if (init_gtk() != true) {
return NULL;
}

5
src/tray/windows/SDL_tray.c
View File

@@ -211,6 +211,11 @@ static HICON load_default_icon()
SDL_Tray *SDL_CreateTray(SDL_Surface *icon, const char *tooltip)
{
if (!SDL_IsMainThread()) {
SDL_SetError("This function should be called on the main thread");
return NULL;
}
SDL_Tray *tray = (SDL_Tray *)SDL_calloc(1, sizeof(*tray));
if (!tray) {