SDL 3.0
|
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_surface.h>
#include <SDL3/SDL_video.h>
#include <SDL3/SDL_begin_code.h>
#include <SDL3/SDL_close_code.h>
Go to the source code of this file.
Macros | |
#define | SDL_TRAYENTRY_BUTTON 0x00000001u |
#define | SDL_TRAYENTRY_CHECKBOX 0x00000002u |
#define | SDL_TRAYENTRY_SUBMENU 0x00000004u |
#define | SDL_TRAYENTRY_DISABLED 0x80000000u |
#define | SDL_TRAYENTRY_CHECKED 0x40000000u |
Typedefs | |
typedef struct SDL_Tray | SDL_Tray |
typedef struct SDL_TrayMenu | SDL_TrayMenu |
typedef struct SDL_TrayEntry | SDL_TrayEntry |
typedef Uint32 | SDL_TrayEntryFlags |
typedef void(* | SDL_TrayCallback) (void *userdata, SDL_TrayEntry *entry) |
#define SDL_TRAYENTRY_BUTTON 0x00000001u |
Make the entry a simple button. Required.
Definition at line 80 of file SDL_tray.h.
#define SDL_TRAYENTRY_CHECKBOX 0x00000002u |
Make the entry a checkbox. Required.
Definition at line 81 of file SDL_tray.h.
#define SDL_TRAYENTRY_CHECKED 0x40000000u |
Make the entry checked. This is valid only for checkboxes. Optional.
Definition at line 84 of file SDL_tray.h.
#define SDL_TRAYENTRY_DISABLED 0x80000000u |
Make the entry disabled. Optional.
Definition at line 83 of file SDL_tray.h.
#define SDL_TRAYENTRY_SUBMENU 0x00000004u |
Prepare the entry to have a submenu. Required
Definition at line 82 of file SDL_tray.h.
SDL offers a way to add items to the "system tray" (more correctly called the "notification area" on Windows). On platforms that offer this concept, an SDL app can add a tray icon, submenus, checkboxes, and clickable entries, and register a callback that is fired when the user clicks on these pieces. An opaque handle representing a toplevel system tray object.
Definition at line 51 of file SDL_tray.h.
typedef void(* SDL_TrayCallback) (void *userdata, SDL_TrayEntry *entry) |
A callback that is invoked when a tray entry is selected.
userdata | an optional pointer to pass extra data to the callback when it will be invoked. |
entry | the tray entry that was selected. |
Definition at line 97 of file SDL_tray.h.
typedef struct SDL_TrayEntry SDL_TrayEntry |
An opaque handle representing an entry on a system tray object.
Definition at line 65 of file SDL_tray.h.
typedef Uint32 SDL_TrayEntryFlags |
Flags that control the creation of system tray entries.
Some of these flags are required; exactly one of them must be specified at the time a tray entry is created. Other flags are optional; zero or more of those can be OR'ed together with the required flag.
Definition at line 78 of file SDL_tray.h.
typedef struct SDL_TrayMenu SDL_TrayMenu |
An opaque handle representing a menu/submenu on a system tray object.
Definition at line 58 of file SDL_tray.h.
|
extern |
Simulate a click on a tray entry.
entry | The entry to activate. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Create an icon to be placed in the operating system's tray, or equivalent.
Many platforms advise not using a system tray unless persistence is a necessary feature. Avoid needlessly creating a tray icon, as the user may feel like it clutters their interface.
Using tray icons require the video subsystem.
icon | a surface to be used as icon. May be NULL. |
tooltip | a tooltip to be displayed when the mouse hovers the icon in UTF-8 encoding. Not supported on all platforms. May be NULL. |
\threadsafety This function should only be called on the main thread.
|
extern |
Create a menu for a system tray.
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.
A menu does not need to be destroyed; it will be destroyed with the tray.
tray | the tray to bind the menu to. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Create a submenu for a system tray entry.
This should be called at most once per tray entry.
This function does the same thing as SDL_CreateTrayMenu, except that it takes a SDL_TrayEntry instead of a SDL_Tray.
A menu does not need to be destroyed; it will be destroyed with the tray.
entry | the tray entry to bind the menu to. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Destroys a tray object.
This also destroys all associated menus and entries.
tray | the tray icon to be destroyed. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Returns a list of entries in the menu, in order.
menu | The menu to get entries from. |
count | An optional pointer to obtain the number of entries in the menu. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Gets whether or not an entry is checked.
The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.
entry | the entry to be read. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Gets whether or not an entry is enabled.
entry | the entry to be read. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Gets the label of an entry.
If the returned value is NULL, the entry is a separator.
entry | the entry to be read. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Gets the menu containing a certain tray entry.
entry | the entry for which to get the parent menu. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Gets a previously created tray menu.
You should have called SDL_CreateTrayMenu() on the tray object. This function allows you to fetch it again later.
This function does the same thing as SDL_GetTraySubmenu(), 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.
tray | the tray entry to bind the menu to. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
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.
menu | the menu for which to get the parent entry. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
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.
menu | the menu for which to get the parent enttrayry. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Gets a previously created tray entry submenu.
You should have called SDL_CreateTraySubmenu() on the entry object. This function allows you to fetch it again later.
This function does the same thing as SDL_GetTrayMenu(), except that it takes a SDL_TrayEntry instead of a SDL_Tray.
A menu does not need to be destroyed; it will be destroyed with the tray.
entry | the tray entry to bind the menu to. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Insert a tray entry at a given position.
If label is NULL, the entry will be a separator. Many functions won't work for an entry that is a separator.
An entry does not need to be destroyed; it will be destroyed with the tray.
menu | the menu to append the entry to. |
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. |
label | the text to be displayed on the entry, in UTF-8 encoding, or NULL for a separator. |
flags | a combination of flags, some of which are mandatory. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Removes a tray entry.
entry | The entry to be deleted. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Sets a callback to be invoked when the entry is selected.
entry | the entry to be updated. |
callback | a callback to be invoked when the entry is selected. |
userdata | an optional pointer to pass extra data to the callback when it will be invoked. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Sets whether or not an entry is checked.
The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.
entry | the entry to be updated. |
checked | true if the entry should be checked; false otherwise. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Sets whether or not an entry is enabled.
entry | the entry to be updated. |
enabled | true if the entry should be enabled; false otherwise. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
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.
entry | the entry to be updated. |
label | the new label for the entry in UTF-8 encoding. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Updates the system tray icon's icon.
tray | the tray icon to be updated. |
icon | the new icon. May be NULL. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
Updates the system tray icon's tooltip.
tray | the tray icon to be updated. |
tooltip | the new tooltip in UTF-8 encoding. May be NULL. |
\threadsafety This function should be called on the thread that created the tray.
|
extern |
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.
\threadsafety This function should only be called on the main thread.