SDL 3.0
SDL_tray.h File Reference
+ Include dependency graph for SDL_tray.h:
+ This graph shows which files directly or indirectly include this file:

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)
 

Functions

SDL_TraySDL_CreateTray (SDL_Surface *icon, const char *tooltip)
 
void SDL_SetTrayIcon (SDL_Tray *tray, SDL_Surface *icon)
 
void SDL_SetTrayTooltip (SDL_Tray *tray, const char *tooltip)
 
SDL_TrayMenuSDL_CreateTrayMenu (SDL_Tray *tray)
 
SDL_TrayMenuSDL_CreateTraySubmenu (SDL_TrayEntry *entry)
 
SDL_TrayMenuSDL_GetTrayMenu (SDL_Tray *tray)
 
SDL_TrayMenuSDL_GetTraySubmenu (SDL_TrayEntry *entry)
 
const SDL_TrayEntry ** SDL_GetTrayEntries (SDL_TrayMenu *menu, int *count)
 
void SDL_RemoveTrayEntry (SDL_TrayEntry *entry)
 
SDL_TrayEntrySDL_InsertTrayEntryAt (SDL_TrayMenu *menu, int pos, const char *label, SDL_TrayEntryFlags flags)
 
void SDL_SetTrayEntryLabel (SDL_TrayEntry *entry, const char *label)
 
const char * SDL_GetTrayEntryLabel (SDL_TrayEntry *entry)
 
void SDL_SetTrayEntryChecked (SDL_TrayEntry *entry, bool checked)
 
bool SDL_GetTrayEntryChecked (SDL_TrayEntry *entry)
 
void SDL_SetTrayEntryEnabled (SDL_TrayEntry *entry, bool enabled)
 
bool SDL_GetTrayEntryEnabled (SDL_TrayEntry *entry)
 
void SDL_SetTrayEntryCallback (SDL_TrayEntry *entry, SDL_TrayCallback callback, void *userdata)
 
void SDL_ClickTrayEntry (SDL_TrayEntry *entry)
 
void SDL_DestroyTray (SDL_Tray *tray)
 
SDL_TrayMenuSDL_GetTrayEntryParent (SDL_TrayEntry *entry)
 
SDL_TrayEntrySDL_GetTrayMenuParentEntry (SDL_TrayMenu *menu)
 
SDL_TraySDL_GetTrayMenuParentTray (SDL_TrayMenu *menu)
 
void SDL_UpdateTrays (void)
 

Macro Definition Documentation

◆ SDL_TRAYENTRY_BUTTON

#define SDL_TRAYENTRY_BUTTON   0x00000001u

Make the entry a simple button. Required.

Definition at line 80 of file SDL_tray.h.

◆ SDL_TRAYENTRY_CHECKBOX

#define SDL_TRAYENTRY_CHECKBOX   0x00000002u

Make the entry a checkbox. Required.

Definition at line 81 of file SDL_tray.h.

◆ SDL_TRAYENTRY_CHECKED

#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.

◆ SDL_TRAYENTRY_DISABLED

#define SDL_TRAYENTRY_DISABLED   0x80000000u

Make the entry disabled. Optional.

Definition at line 83 of file SDL_tray.h.

◆ SDL_TRAYENTRY_SUBMENU

#define SDL_TRAYENTRY_SUBMENU   0x00000004u

Prepare the entry to have a submenu. Required

Definition at line 82 of file SDL_tray.h.

Typedef Documentation

◆ SDL_Tray

typedef struct SDL_Tray SDL_Tray

CategoryTray

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.

Since
This struct is available since SDL 3.2.0.

Definition at line 51 of file SDL_tray.h.

◆ SDL_TrayCallback

typedef void(* SDL_TrayCallback) (void *userdata, SDL_TrayEntry *entry)

A callback that is invoked when a tray entry is selected.

Parameters
userdataan optional pointer to pass extra data to the callback when it will be invoked.
entrythe tray entry that was selected.
Since
This datatype is available since SDL 3.2.0.
See also
SDL_SetTrayEntryCallback

Definition at line 97 of file SDL_tray.h.

◆ SDL_TrayEntry

typedef struct SDL_TrayEntry SDL_TrayEntry

An opaque handle representing an entry on a system tray object.

Since
This struct is available since SDL 3.2.0.

Definition at line 65 of file SDL_tray.h.

◆ 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.

Since
This datatype is available since SDL 3.2.0.
See also
SDL_InsertTrayEntryAt

Definition at line 78 of file SDL_tray.h.

◆ SDL_TrayMenu

typedef struct SDL_TrayMenu SDL_TrayMenu

An opaque handle representing a menu/submenu on a system tray object.

Since
This struct is available since SDL 3.2.0.

Definition at line 58 of file SDL_tray.h.

Function Documentation

◆ SDL_ClickTrayEntry()

void SDL_ClickTrayEntry ( SDL_TrayEntry entry)

Simulate a click on a tray entry.

Parameters
entryThe entry to activate.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.

◆ SDL_CreateTray()

SDL_Tray * SDL_CreateTray ( SDL_Surface icon,
const char *  tooltip 
)

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.

Parameters
icona surface to be used as icon. May be NULL.
tooltipa tooltip to be displayed when the mouse hovers the icon in UTF-8 encoding. Not supported on all platforms. May be NULL.
Returns
The newly created system tray icon.

\threadsafety This function should only be called on the main thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_CreateTrayMenu
SDL_GetTrayMenu
SDL_DestroyTray

◆ SDL_CreateTrayMenu()

SDL_TrayMenu * SDL_CreateTrayMenu ( SDL_Tray tray)

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.

Parameters
traythe tray to bind the menu to.
Returns
the newly created menu.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_CreateTray
SDL_GetTrayMenu
SDL_GetTrayMenuParentTray

◆ SDL_CreateTraySubmenu()

SDL_TrayMenu * SDL_CreateTraySubmenu ( SDL_TrayEntry entry)

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.

Parameters
entrythe tray entry to bind the menu to.
Returns
the newly created menu.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_InsertTrayEntryAt
SDL_GetTraySubmenu
SDL_GetTrayMenuParentEntry

◆ SDL_DestroyTray()

void SDL_DestroyTray ( SDL_Tray tray)

Destroys a tray object.

This also destroys all associated menus and entries.

Parameters
traythe tray icon to be destroyed.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_CreateTray

◆ SDL_GetTrayEntries()

const SDL_TrayEntry ** SDL_GetTrayEntries ( SDL_TrayMenu menu,
int *  count 
)

Returns a list of entries in the menu, in order.

Parameters
menuThe menu to get entries from.
countAn optional pointer to obtain the number of entries in the menu.
Returns
a NULL-terminated list of entries within the given menu. The pointer becomes invalid when any function that inserts or deletes entries in the menu is called.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_RemoveTrayEntry
SDL_InsertTrayEntryAt

◆ SDL_GetTrayEntryChecked()

bool SDL_GetTrayEntryChecked ( SDL_TrayEntry entry)

Gets whether or not an entry is checked.

The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.

Parameters
entrythe entry to be read.
Returns
true if the entry is checked; false otherwise.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetTrayEntries
SDL_InsertTrayEntryAt
SDL_SetTrayEntryChecked

◆ SDL_GetTrayEntryEnabled()

bool SDL_GetTrayEntryEnabled ( SDL_TrayEntry entry)

Gets whether or not an entry is enabled.

Parameters
entrythe entry to be read.
Returns
true if the entry is enabled; false otherwise.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetTrayEntries
SDL_InsertTrayEntryAt
SDL_SetTrayEntryEnabled

◆ SDL_GetTrayEntryLabel()

const char * SDL_GetTrayEntryLabel ( SDL_TrayEntry entry)

Gets the label of an entry.

If the returned value is NULL, the entry is a separator.

Parameters
entrythe entry to be read.
Returns
the label of the entry in UTF-8 encoding.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetTrayEntries
SDL_InsertTrayEntryAt
SDL_SetTrayEntryLabel

◆ SDL_GetTrayEntryParent()

SDL_TrayMenu * SDL_GetTrayEntryParent ( SDL_TrayEntry entry)

Gets the menu containing a certain tray entry.

Parameters
entrythe entry for which to get the parent menu.
Returns
the parent menu.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_InsertTrayEntryAt

◆ SDL_GetTrayMenu()

SDL_TrayMenu * SDL_GetTrayMenu ( SDL_Tray tray)

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.

Parameters
traythe tray entry to bind the menu to.
Returns
the newly created menu.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_CreateTray
SDL_CreateTrayMenu

◆ SDL_GetTrayMenuParentEntry()

SDL_TrayEntry * SDL_GetTrayMenuParentEntry ( SDL_TrayMenu menu)

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.

Parameters
menuthe menu for which to get the parent entry.
Returns
the parent entry, or NULL if this menu is not a submenu.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_CreateTraySubmenu
SDL_GetTrayMenuParentTray

◆ SDL_GetTrayMenuParentTray()

SDL_Tray * SDL_GetTrayMenuParentTray ( SDL_TrayMenu menu)

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.

Parameters
menuthe menu for which to get the parent enttrayry.
Returns
the parent tray, or NULL if this menu is a submenu.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_CreateTrayMenu
SDL_GetTrayMenuParentEntry

◆ SDL_GetTraySubmenu()

SDL_TrayMenu * SDL_GetTraySubmenu ( SDL_TrayEntry entry)

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.

Parameters
entrythe tray entry to bind the menu to.
Returns
the newly created menu.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_InsertTrayEntryAt
SDL_CreateTraySubmenu

◆ SDL_InsertTrayEntryAt()

SDL_TrayEntry * SDL_InsertTrayEntryAt ( SDL_TrayMenu menu,
int  pos,
const char *  label,
SDL_TrayEntryFlags  flags 
)

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.

Parameters
menuthe menu to append the entry to.
posthe desired position for the new entry. Entries at or following this place will be moved. If pos is -1, the entry is appended.
labelthe text to be displayed on the entry, in UTF-8 encoding, or NULL for a separator.
flagsa combination of flags, some of which are mandatory.
Returns
the newly created entry, or NULL if pos is out of bounds.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_TrayEntryFlags
SDL_GetTrayEntries
SDL_RemoveTrayEntry
SDL_GetTrayEntryParent

◆ SDL_RemoveTrayEntry()

void SDL_RemoveTrayEntry ( SDL_TrayEntry entry)

Removes a tray entry.

Parameters
entryThe entry to be deleted.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetTrayEntries
SDL_InsertTrayEntryAt

◆ SDL_SetTrayEntryCallback()

void SDL_SetTrayEntryCallback ( SDL_TrayEntry entry,
SDL_TrayCallback  callback,
void *  userdata 
)

Sets a callback to be invoked when the entry is selected.

Parameters
entrythe entry to be updated.
callbacka callback to be invoked when the entry is selected.
userdataan 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.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetTrayEntries
SDL_InsertTrayEntryAt

◆ SDL_SetTrayEntryChecked()

void SDL_SetTrayEntryChecked ( SDL_TrayEntry entry,
bool  checked 
)

Sets whether or not an entry is checked.

The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.

Parameters
entrythe entry to be updated.
checkedtrue if the entry should be checked; false otherwise.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetTrayEntries
SDL_InsertTrayEntryAt
SDL_GetTrayEntryChecked

◆ SDL_SetTrayEntryEnabled()

void SDL_SetTrayEntryEnabled ( SDL_TrayEntry entry,
bool  enabled 
)

Sets whether or not an entry is enabled.

Parameters
entrythe entry to be updated.
enabledtrue if the entry should be enabled; false otherwise.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetTrayEntries
SDL_InsertTrayEntryAt
SDL_GetTrayEntryEnabled

◆ SDL_SetTrayEntryLabel()

void SDL_SetTrayEntryLabel ( SDL_TrayEntry entry,
const char *  label 
)

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.

Parameters
entrythe entry to be updated.
labelthe new label for the entry in UTF-8 encoding.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetTrayEntries
SDL_InsertTrayEntryAt
SDL_GetTrayEntryLabel

◆ SDL_SetTrayIcon()

void SDL_SetTrayIcon ( SDL_Tray tray,
SDL_Surface icon 
)

Updates the system tray icon's icon.

Parameters
traythe tray icon to be updated.
iconthe new icon. May be NULL.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_CreateTray

◆ SDL_SetTrayTooltip()

void SDL_SetTrayTooltip ( SDL_Tray tray,
const char *  tooltip 
)

Updates the system tray icon's tooltip.

Parameters
traythe tray icon to be updated.
tooltipthe new tooltip in UTF-8 encoding. May be NULL.

\threadsafety This function should be called on the thread that created the tray.

Since
This function is available since SDL 3.2.0.
See also
SDL_CreateTray

◆ SDL_UpdateTrays()

void SDL_UpdateTrays ( void  )

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.

Since
This function is available since SDL 3.2.0.