From 4c70aa33ae9159335dc7989a0848eb7612462138 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Tue, 24 Dec 2024 18:50:21 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
[ci skip]
---
include/SDL3/SDL_tray.h | 81 ++++++++++++++++++++++-------------------
1 file changed, 43 insertions(+), 38 deletions(-)
diff --git a/include/SDL3/SDL_tray.h b/include/SDL3/SDL_tray.h
index b7c50207062b7..abb16949f5c19 100644
--- a/include/SDL3/SDL_tray.h
+++ b/include/SDL3/SDL_tray.h
@@ -82,11 +82,11 @@ typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry);
* Using tray icons require the video subsystem.
*
* \param icon a surface to be used as icon. May be NULL.
- * \param tooltip a tooltip to be displayed when the mouse hovers the icon. Not
- * supported on all platforms. May be NULL.
+ * \param tooltip a tooltip to be displayed when the mouse hovers the icon.
+ * Not supported on all platforms. May be NULL.
* \returns The newly created system tray icon.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_CreateTrayMenu
* \sa SDL_GetTrayMenu
@@ -100,7 +100,7 @@ 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.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_CreateTray
*/
@@ -112,7 +112,7 @@ 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. May be NULL.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_CreateTray
*/
@@ -123,15 +123,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *
*
* This should be called at most once per tray icon.
*
- * This function does the same thing as SDL_CreateTraySubmenu(), except that it
- * takes a SDL_Tray instead of a SDL_TrayEntry.
+ * This function does the same thing as SDL_CreateTraySubmenu(), except that
+ * it takes a SDL_Tray instead of a SDL_TrayEntry.
*
* A menu does not need to be destroyed; it will be destroyed with the tray.
*
* \param tray the tray to bind the menu to.
* \returns the newly created menu.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_CreateTray
* \sa SDL_GetTrayMenu
@@ -152,7 +152,7 @@ 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.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_InsertTrayEntryAt
* \sa SDL_GetTraySubmenu
@@ -174,7 +174,7 @@ 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.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_CreateTray
* \sa SDL_CreateTrayMenu
@@ -195,7 +195,7 @@ 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.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_InsertTrayEntryAt
* \sa SDL_CreateTraySubmenu
@@ -206,11 +206,13 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entr
* Returns a list of entries in the menu, in order.
*
* \param menu The menu to get entries from.
- * \param size An optional pointer to obtain the number of entries in the menu.
- * \returns the entries within the given menu. The pointer becomes invalid when
- * any function that inserts or deletes entries in the menu is called.
+ * \param size An optional pointer to obtain the number of entries in the
+ * menu.
+ * \returns the entries within the given menu. The pointer becomes invalid
+ * when any function that inserts or deletes entries in the menu is
+ * called.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_RemoveTrayEntry
* \sa SDL_InsertTrayEntryAt
@@ -222,7 +224,7 @@ 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.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
@@ -240,11 +242,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry);
* \param menu the menu to append the entry to.
* \param pos the desired position for the new entry. Entries at or following
* this place will be moved. If pos is -1, the entry is appended.
- * \param label the text to be displayed on the entry, or NULL for a separator.
+ * \param label the text to be displayed on the entry, or NULL for a
+ * separator.
* \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.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_TrayEntryFlags
* \sa SDL_GetTrayEntries
@@ -257,14 +260,14 @@ extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *m
* Sets the label of an entry.
*
* An entry cannot change between a separator and an ordinary entry; that is,
- * it is not possible to set a non-NULL label on an entry that has a NULL label
- * (separators), or to set a NULL label to an entry that has a non-NULL label.
- * The function will silently fail if that happens.
+ * it is not possible to set a non-NULL label on an entry that has a NULL
+ * label (separators), or to set a NULL label to an entry that has a non-NULL
+ * label. The function will silently fail if that happens.
*
* \param entry the entry to be updated.
* \param label the new label for the entry.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
@@ -280,7 +283,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, con
* \param entry the entry to be read.
* \returns the label of the entry.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
@@ -294,9 +297,10 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *ent
* The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.
*
* \param entry the entry to be updated.
- * \param checked SDL_TRUE if the entry should be checked; SDL_FALSE otherwise.
+ * \param checked SDL_TRUE if the entry should be checked; SDL_FALSE
+ * otherwise.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
@@ -312,7 +316,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, b
* \param entry the entry to be read.
* \returns SDL_TRUE if the entry is checked; SDL_FALSE otherwise.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
@@ -324,9 +328,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry);
* Sets whether or not an entry is enabled.
*
* \param entry the entry to be updated.
- * \param enabled SDL_TRUE if the entry should be enabled; SDL_FALSE otherwise.
+ * \param enabled SDL_TRUE if the entry should be enabled; SDL_FALSE
+ * otherwise.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
@@ -340,7 +345,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, b
* \param entry the entry to be read.
* \returns SDL_TRUE if the entry is enabled; SDL_FALSE otherwise.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
@@ -356,7 +361,7 @@ 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.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_GetTrayEntries
* \sa SDL_InsertTrayEntryAt
@@ -370,7 +375,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry,
*
* \param tray the tray icon to be destroyed.
*
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_CreateTray
*/
@@ -382,7 +387,7 @@ 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.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_InsertTrayEntryAt
*/
@@ -392,13 +397,13 @@ extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *
* Gets the entry for which the menu is a submenu, if the current menu is a
* submenu.
*
- * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL for
- * any given menu.
+ * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL
+ * for any given menu.
*
* \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.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_CreateTraySubmenu
* \sa SDL_GetTrayMenuParentTray
@@ -409,13 +414,13 @@ extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMe
* Gets the tray for which this menu is the first-level menu, if the current
* menu isn't a submenu.
*
- * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL for
- * any given menu.
+ * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL
+ * for any given menu.
*
* \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.0.0.
+ * \since This function is available since SDL 3.2.0.
*
* \sa SDL_CreateTrayMenu
* \sa SDL_GetTrayMenuParentEntry