mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-10-01 07:28:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

Browse Source 
[ci skip]
This commit is contained in:
SDL Wiki Bot
2024-12-24 18:50:21 +00:00
parent 76920a230f
commit 4c70aa33ae
1 changed files with 43 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
include/SDL3/SDL_tray.h
View File

@@ -82,11 +82,11 @@ typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry);
* Using tray icons require the video subsystem. * Using tray icons require the video subsystem.
* *
* \param icon a surface to be used as icon. May be NULL. * \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 * \param tooltip a tooltip to be displayed when the mouse hovers the icon.
* supported on all platforms. May be NULL. * Not supported on all platforms. May be NULL.
* \returns The newly created system tray icon. * \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_CreateTrayMenu
* \sa SDL_GetTrayMenu * \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 tray the tray icon to be updated.
* \param icon the new icon. May be NULL. * \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 * \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 tray the tray icon to be updated.
* \param tooltip the new tooltip. May be NULL. * \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 * \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 should be called at most once per tray icon.
* *
* This function does the same thing as SDL_CreateTraySubmenu(), except that it * This function does the same thing as SDL_CreateTraySubmenu(), except that
* takes a SDL_Tray instead of a SDL_TrayEntry. * 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. * A menu does not need to be destroyed; it will be destroyed with the tray.
* *
* \param tray the tray to bind the menu to. * \param tray the tray to bind the menu to.
* \returns the newly created menu. * \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_CreateTray
* \sa SDL_GetTrayMenu * \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. * \param entry the tray entry to bind the menu to.
* \returns the newly created menu. * \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_InsertTrayEntryAt
* \sa SDL_GetTraySubmenu * \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. * \param tray the tray entry to bind the menu to.
* \returns the newly created menu. * \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_CreateTray
* \sa SDL_CreateTrayMenu * \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. * \param entry the tray entry to bind the menu to.
* \returns the newly created menu. * \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_InsertTrayEntryAt
* \sa SDL_CreateTraySubmenu * \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. * Returns a list of entries in the menu, in order.
* *
* \param menu The menu to get entries from. * \param menu The menu to get entries from.
* \param size An optional pointer to obtain the number of entries in the menu. * \param size An optional pointer to obtain the number of entries in the
* \returns the entries within the given menu. The pointer becomes invalid when * menu.
* any function that inserts or deletes entries in the menu is called. * \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_RemoveTrayEntry
* \sa SDL_InsertTrayEntryAt * \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. * \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_GetTrayEntries
* \sa SDL_InsertTrayEntryAt * \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 menu the menu to append the entry to.
* \param pos the desired position for the new entry. Entries at or following * \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. * 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. * \param flags a combination of flags, some of which are mandatory.
* \returns the newly created entry, or NULL if pos is out of bounds. * \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_TrayEntryFlags
* \sa SDL_GetTrayEntries * \sa SDL_GetTrayEntries
@@ -257,14 +260,14 @@ extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *m
* Sets the label of an entry. * Sets the label of an entry.
* *
* An entry cannot change between a separator and an ordinary entry; that is, * 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 * it is not possible to set a non-NULL label on an entry that has a NULL
* (separators), or to set a NULL label to an entry that has a non-NULL label. * label (separators), or to set a NULL label to an entry that has a non-NULL
* The function will silently fail if that happens. * label. The function will silently fail if that happens.
* *
* \param entry the entry to be updated. * \param entry the entry to be updated.
* \param label the new label for the entry. * \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_GetTrayEntries
* \sa SDL_InsertTrayEntryAt * \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. * \param entry the entry to be read.
* \returns the label of the entry. * \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_GetTrayEntries
* \sa SDL_InsertTrayEntryAt * \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. * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.
* *
* \param entry the entry to be updated. * \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_GetTrayEntries
* \sa SDL_InsertTrayEntryAt * \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. * \param entry the entry to be read.
* \returns SDL_TRUE if the entry is checked; SDL_FALSE otherwise. * \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_GetTrayEntries
* \sa SDL_InsertTrayEntryAt * \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. * Sets whether or not an entry is enabled.
* *
* \param entry the entry to be updated. * \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_GetTrayEntries
* \sa SDL_InsertTrayEntryAt * \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. * \param entry the entry to be read.
* \returns SDL_TRUE if the entry is enabled; SDL_FALSE otherwise. * \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_GetTrayEntries
* \sa SDL_InsertTrayEntryAt * \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 * \param userdata an optional pointer to pass extra data to the callback when
* it will be invoked. * 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_GetTrayEntries
* \sa SDL_InsertTrayEntryAt * \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. * \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 * \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. * \param entry the entry for which to get the parent menu.
* \returns 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 * \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 * Gets the entry for which the menu is a submenu, if the current menu is a
* submenu. * submenu.
* *
* Either this function or SDL_GetTrayMenuParentTray() will return non-NULL for * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL
* any given menu. * for any given menu.
* *
* \param menu the menu for which to get the parent entry. * \param menu the menu for which to get the parent entry.
* \returns the parent entry, or NULL if this menu is not a submenu. * \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_CreateTraySubmenu
* \sa SDL_GetTrayMenuParentTray * \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 * Gets the tray for which this menu is the first-level menu, if the current
* menu isn't a submenu. * menu isn't a submenu.
* *
* Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL for * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL
* any given menu. * for any given menu.
* *
* \param menu the menu for which to get the parent enttrayry. * \param menu the menu for which to get the parent enttrayry.
* \returns the parent tray, or NULL if this menu is a submenu. * \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_CreateTrayMenu
* \sa SDL_GetTrayMenuParentEntry * \sa SDL_GetTrayMenuParentEntry