SDL offers a way to add items to the "system tray" (more correctly called the "notification area" on Windows). More...

Classes
class	SDL::Tray
	An opaque handle representing a toplevel system tray object. More...
struct	SDL::TrayRef
	Reference for Tray. More...
class	SDL::TrayMenu
	An opaque handle representing a menu/submenu on a system tray object. More...
class	SDL::TrayEntry
	An opaque handle representing an entry on a system tray object. More...
struct	SDL::TrayEntryScoped
	RAII owning version TrayEntry. More...

Typedefs
using	SDL::TrayRaw = SDL_Tray*
	Alias to raw representation for Tray.
using	SDL::TrayMenuRaw = SDL_TrayMenu*
	Alias to raw representation for TrayMenu.
using	SDL::TrayEntryRaw = SDL_TrayEntry*
	Alias to raw representation for TrayEntry.
using	SDL::TrayEntryRef = TrayEntry
	Alias to TrayEntry for non owning parameters.
using	SDL::TrayEntryFlags = Uint32
	Flags that control the creation of system tray entries.
using	SDL::TrayCallback = void(SDLCALL)(void userdata, TrayEntryRaw entry)
	A callback that is invoked when a tray entry is selected.
using	SDL::TrayCB = MakeFrontCallback<void(TrayEntryRaw entry)>
	A callback that is invoked when a tray entry is selected.

Functions
Tray	SDL::CreateTray (SurfaceRef icon, StringParam tooltip)
	Create an icon to be placed in the operating system's tray, or equivalent.
void	SDL::SetTrayIcon (TrayRef tray, SurfaceRef icon)
	Updates the system tray icon's icon.
void	SDL::SetTrayTooltip (TrayRef tray, StringParam tooltip)
	Updates the system tray icon's tooltip.
TrayMenu	SDL::CreateTrayMenu (TrayRef tray)
	Create a menu for a system tray.
TrayMenu	SDL::CreateTraySubmenu (TrayEntryRef entry)
	Create a submenu for a system tray entry.
TrayMenu	SDL::GetTrayMenu (TrayRef tray)
	Gets a previously created tray menu.
TrayMenu	SDL::GetTraySubmenu (TrayEntryRef entry)
	Gets a previously created tray entry submenu.
std::span< TrayEntry >	SDL::GetTrayEntries (TrayMenu menu)
	Returns a list of entries in the menu, in order.
void	SDL::RemoveTrayEntry (TrayEntryRaw entry)
	Removes a tray entry.
TrayEntry	SDL::InsertTrayEntryAt (TrayMenu menu, int pos, StringParam label, TrayEntryFlags flags)
	Insert a tray entry at a given position.
void	SDL::SetTrayEntryLabel (TrayEntryRef entry, StringParam label)
	Sets the label of an entry.
const char *	SDL::GetTrayEntryLabel (TrayEntryRef entry)
	Gets the label of an entry.
void	SDL::SetTrayEntryChecked (TrayEntryRef entry, bool checked)
	Sets whether or not an entry is checked.
bool	SDL::GetTrayEntryChecked (TrayEntryRef entry)
	Gets whether or not an entry is checked.
void	SDL::SetTrayEntryEnabled (TrayEntryRef entry, bool enabled)
	Sets whether or not an entry is enabled.
bool	SDL::GetTrayEntryEnabled (TrayEntryRef entry)
	Gets whether or not an entry is enabled.
void	SDL::SetTrayEntryCallback (TrayEntryRef entry, TrayCallback callback, void *userdata)
	Sets a callback to be invoked when the entry is selected.
void	SDL::ClickTrayEntry (TrayEntryRef entry)
	Simulate a click on a tray entry.
void	SDL::DestroyTray (TrayRaw tray)
	Destroys a tray object.
TrayMenu	SDL::GetTrayEntryParent (TrayEntryRef entry)
	Gets the menu containing a certain tray entry.
TrayEntryRef	SDL::GetTrayMenuParentEntry (TrayMenuRaw menu)
	Gets the entry for which the menu is a submenu, if the current menu is a submenu.
TrayRef	SDL::GetTrayMenuParentTray (TrayMenuRaw menu)
	Gets the tray for which this menu is the first-level menu, if the current menu isn't a submenu.
void	SDL::UpdateTrays ()
	Update the trays.
	SDL::Tray::Tray (SurfaceRef icon, StringParam tooltip)
	Create an icon to be placed in the operating system's tray, or equivalent.
void	SDL::Tray::SetIcon (SurfaceRef icon)
	Updates the system tray icon's icon.
void	SDL::Tray::SetTooltip (StringParam tooltip)
	Updates the system tray icon's tooltip.
TrayMenu	SDL::Tray::CreateMenu ()
	Create a menu for a system tray.
TrayMenu	SDL::TrayEntry::CreateSubmenu ()
	Create a submenu for a system tray entry.
TrayMenu	SDL::Tray::GetMenu () const
	Gets a previously created tray menu.
TrayMenu	SDL::TrayEntry::GetSubmenu ()
	Gets a previously created tray entry submenu.
std::span< TrayEntry >	SDL::TrayMenu::GetEntries ()
	Returns a list of entries in the menu, in order.
void	SDL::TrayEntry::Remove ()
	Removes a tray entry.
TrayEntry	SDL::TrayMenu::InsertEntry (int pos, StringParam label, TrayEntryFlags flags)
	Insert a tray entry at a given position.
void	SDL::TrayEntry::SetLabel (StringParam label)
	Sets the label of an entry.
const char *	SDL::TrayEntry::GetLabel () const
	Gets the label of an entry.
void	SDL::TrayEntry::SetChecked (bool checked)
	Sets whether or not an entry is checked.
bool	SDL::TrayEntry::GetChecked () const
	Gets whether or not an entry is checked.
void	SDL::TrayEntry::SetEnabled (bool enabled)
	Sets whether or not an entry is enabled.
bool	SDL::TrayEntry::GetEnabled () const
	Gets whether or not an entry is enabled.
void	SDL::TrayEntry::SetCallback (TrayCallback callback, void *userdata)
	Sets a callback to be invoked when the entry is selected.
void	SDL::TrayEntry::Click ()
	Simulate a click on a tray entry.
void	SDL::Tray::Destroy ()
	Destroys a tray object.
TrayMenu	SDL::TrayEntry::GetParent ()
	Gets the menu containing a certain tray entry.
TrayEntryRef	SDL::TrayMenu::GetParentEntry () const
	Gets the entry for which the menu is a submenu, if the current menu is a submenu.
TrayRef	SDL::TrayMenu::GetParentTray () const
	Gets the tray for which this menu is the first-level menu, if the current menu isn't a submenu.

Variables
constexpr TrayEntryFlags	SDL::TRAYENTRY_BUTTON
	Make the entry a simple button. Required.
constexpr TrayEntryFlags	SDL::TRAYENTRY_CHECKBOX
	Make the entry a checkbox. Required.
constexpr TrayEntryFlags	SDL::TRAYENTRY_SUBMENU
	Prepare the entry to have a submenu. Required.
constexpr TrayEntryFlags	SDL::TRAYENTRY_DISABLED
	Make the entry disabled. Optional.
constexpr TrayEntryFlags	SDL::TRAYENTRY_CHECKED = SDL_TRAYENTRY_CHECKED
	Make the entry checked. This is valid only for checkboxes. Optional.

Detailed Description

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.

Typedef Documentation

◆ TrayCallback

using SDL::TrayCallback = void(SDLCALL*)(void* userdata, TrayEntryRaw entry)

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

Parameters

userdata	an optional pointer to pass extra data to the callback when it will be invoked.
entry	the tray entry that was selected.

Since: This datatype is available since SDL 3.2.0.

See also: TrayEntry.SetCallback

◆ TrayCB

using SDL::TrayCB = MakeFrontCallback<void(TrayEntryRaw entry)>

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

Parameters

entry the tray entry that was selected.

Since: This datatype is available since SDL 3.2.0.

See also: TrayEntry.SetCallback; TrayCallback

◆ TrayEntryFlags

using SDL::TrayEntryFlags = Uint32

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: TrayMenu.InsertEntry

Function Documentation

◆ Click()

void SDL::TrayEntry::Click ( )

inline

Simulate a click on a tray entry.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

◆ ClickTrayEntry()

void SDL::ClickTrayEntry ( TrayEntryRef entry )

inline

Simulate a click on a tray entry.

Parameters

entry The entry to activate.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

◆ CreateMenu()

TrayMenu SDL::Tray::CreateMenu ( )

inline

Create a menu for a system tray.

This should be called at most once per tray icon.

This function does the same thing as TrayEntry.CreateSubmenu(), except that it takes a Tray instead of a TrayEntry.

A menu does not need to be destroyed; it will be destroyed with the tray.

Returns: the newly created menu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: CreateTray; Tray.GetMenu; TrayMenu.GetParentTray

◆ CreateSubmenu()

TrayMenu SDL::TrayEntry::CreateSubmenu ( )

inline

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 Tray.CreateMenu, except that it takes a TrayEntry instead of a Tray.

A menu does not need to be destroyed; it will be destroyed with the tray.

Returns: the newly created menu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.InsertEntry; TrayEntry.GetSubmenu; TrayMenu.GetParentEntry

◆ CreateTray()

Tray SDL::CreateTray	(	SurfaceRef	icon,
		StringParam	tooltip )

inline

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

icon	a surface to be used as icon. May be nullptr.
tooltip	a tooltip to be displayed when the mouse hovers the icon in UTF-8 encoding. Not supported on all platforms. May be nullptr.

Returns: The newly created system tray icon.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: Tray.CreateMenu; Tray.GetMenu; Tray.Destroy

◆ CreateTrayMenu()

TrayMenu SDL::CreateTrayMenu ( TrayRef tray )

inline

Create a menu for a system tray.

This should be called at most once per tray icon.

This function does the same thing as TrayEntry.CreateSubmenu(), except that it takes a Tray instead of a TrayEntry.

A menu does not need to be destroyed; it will be destroyed with the tray.

Parameters

tray	the tray to bind the menu to.

Returns: the newly created menu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: CreateTray; Tray.GetMenu; TrayMenu.GetParentTray

◆ CreateTraySubmenu()

TrayMenu SDL::CreateTraySubmenu ( TrayEntryRef entry )

inline

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 Tray.CreateMenu, except that it takes a TrayEntry instead of a Tray.

A menu does not need to be destroyed; it will be destroyed with the tray.

Parameters

entry the tray entry to bind the menu to.

Returns: the newly created menu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.InsertEntry; TrayEntry.GetSubmenu; TrayMenu.GetParentEntry

◆ Destroy()

void SDL::Tray::Destroy ( )

inline

Destroys a tray object.

This also destroys all associated menus and entries.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: CreateTray

◆ DestroyTray()

void SDL::DestroyTray ( TrayRaw tray )

inline

Destroys a tray object.

This also destroys all associated menus and entries.

Parameters

tray	the tray icon to be destroyed.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: CreateTray

◆ GetChecked()

bool SDL::TrayEntry::GetChecked ( ) const

inline

Gets whether or not an entry is checked.

The entry must have been created with the TRAYENTRY_CHECKBOX flag.

Returns: true if the entry is checked; false otherwise.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.SetChecked

◆ GetEnabled()

bool SDL::TrayEntry::GetEnabled ( ) const

inline

Gets whether or not an entry is enabled.

Returns: true if the entry is enabled; false otherwise.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.SetEnabled

◆ GetEntries()

std::span< TrayEntry > SDL::TrayMenu::GetEntries ( )

inline

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

Returns: a nullptr-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.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayEntry.Remove; TrayMenu.InsertEntry

◆ GetLabel()

const char * SDL::TrayEntry::GetLabel ( ) const

inline

Gets the label of an entry.

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

Returns: the label of the entry in UTF-8 encoding.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.SetLabel

◆ GetMenu()

TrayMenu SDL::Tray::GetMenu ( ) const

inline

Gets a previously created tray menu.

You should have called Tray.CreateMenu() on the tray object. This function allows you to fetch it again later.

This function does the same thing as TrayEntry.GetSubmenu(), except that it takes a Tray instead of a TrayEntry.

A menu does not need to be destroyed; it will be destroyed with the tray.

Returns: the newly created menu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: CreateTray; Tray.CreateMenu

◆ GetParent()

TrayMenu SDL::TrayEntry::GetParent ( )

inline

Gets the menu containing a certain tray entry.

Returns: the parent menu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.InsertEntry

◆ GetParentEntry()

TrayEntryRef SDL::TrayMenu::GetParentEntry ( ) const

inline

Gets the entry for which the menu is a submenu, if the current menu is a submenu.

Either this function or TrayMenu.GetParentTray() will return non-nullptr for any given menu.

Returns: the parent entry, or nullptr if this menu is not a submenu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayEntry.CreateSubmenu; TrayMenu.GetParentTray

◆ GetParentTray()

TrayRef SDL::TrayMenu::GetParentTray ( ) const

inline

Gets the tray for which this menu is the first-level menu, if the current menu isn't a submenu.

Either this function or TrayMenu.GetParentEntry() will return non-nullptr for any given menu.

Returns: the parent tray, or nullptr if this menu is a submenu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: Tray.CreateMenu; TrayMenu.GetParentEntry

◆ GetSubmenu()

TrayMenu SDL::TrayEntry::GetSubmenu ( )

inline

Gets a previously created tray entry submenu.

You should have called TrayEntry.CreateSubmenu() on the entry object. This function allows you to fetch it again later.

This function does the same thing as Tray.GetMenu(), except that it takes a TrayEntry instead of a Tray.

A menu does not need to be destroyed; it will be destroyed with the tray.

Returns: the newly created menu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.InsertEntry; TrayEntry.CreateSubmenu

◆ GetTrayEntries()

std::span< TrayEntry > SDL::GetTrayEntries ( TrayMenu menu )

inline

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

Parameters

menu	The menu to get entries from.

Returns: a nullptr-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.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayEntry.Remove; TrayMenu.InsertEntry

◆ GetTrayEntryChecked()

bool SDL::GetTrayEntryChecked ( TrayEntryRef entry )

inline

Gets whether or not an entry is checked.

The entry must have been created with the TRAYENTRY_CHECKBOX flag.

Parameters

entry the entry to be read.

Returns: true if the entry is checked; false otherwise.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.SetChecked

◆ GetTrayEntryEnabled()

bool SDL::GetTrayEntryEnabled ( TrayEntryRef entry )

inline

Gets whether or not an entry is enabled.

Parameters

entry the entry to be read.

Returns: true if the entry is enabled; false otherwise.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.SetEnabled

◆ GetTrayEntryLabel()

const char * SDL::GetTrayEntryLabel ( TrayEntryRef entry )

inline

Gets the label of an entry.

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

Parameters

entry the entry to be read.

Returns: the label of the entry in UTF-8 encoding.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.SetLabel

◆ GetTrayEntryParent()

TrayMenu SDL::GetTrayEntryParent ( TrayEntryRef entry )

inline

Gets the menu containing a certain tray entry.

Parameters

entry the entry for which to get the parent menu.

Returns: the parent menu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.InsertEntry

◆ GetTrayMenu()

TrayMenu SDL::GetTrayMenu ( TrayRef tray )

inline

Gets a previously created tray menu.

You should have called Tray.CreateMenu() on the tray object. This function allows you to fetch it again later.

This function does the same thing as TrayEntry.GetSubmenu(), except that it takes a Tray instead of a TrayEntry.

A menu does not need to be destroyed; it will be destroyed with the tray.

Parameters

tray	the tray entry to bind the menu to.

Returns: the newly created menu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: CreateTray; Tray.CreateMenu

◆ GetTrayMenuParentEntry()

TrayEntryRef SDL::GetTrayMenuParentEntry ( TrayMenuRaw menu )

inline

Gets the entry for which the menu is a submenu, if the current menu is a submenu.

Either this function or TrayMenu.GetParentTray() will return non-nullptr for any given menu.

Parameters

menu	the menu for which to get the parent entry.

Returns: the parent entry, or nullptr if this menu is not a submenu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayEntry.CreateSubmenu; TrayMenu.GetParentTray

◆ GetTrayMenuParentTray()

TrayRef SDL::GetTrayMenuParentTray ( TrayMenuRaw menu )

inline

Gets the tray for which this menu is the first-level menu, if the current menu isn't a submenu.

Either this function or TrayMenu.GetParentEntry() will return non-nullptr for any given menu.

Parameters

menu	the menu for which to get the parent enttrayry.

Returns: the parent tray, or nullptr if this menu is a submenu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: Tray.CreateMenu; TrayMenu.GetParentEntry

◆ GetTraySubmenu()

TrayMenu SDL::GetTraySubmenu ( TrayEntryRef entry )

inline

Gets a previously created tray entry submenu.

You should have called TrayEntry.CreateSubmenu() on the entry object. This function allows you to fetch it again later.

This function does the same thing as Tray.GetMenu(), except that it takes a TrayEntry instead of a Tray.

A menu does not need to be destroyed; it will be destroyed with the tray.

Parameters

entry the tray entry to bind the menu to.

Returns: the newly created menu.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.InsertEntry; TrayEntry.CreateSubmenu

◆ InsertEntry()

TrayEntry SDL::TrayMenu::InsertEntry	(	int	pos,
		StringParam	label,
		TrayEntryFlags	flags )

inline

Insert a tray entry at a given position.

If label is nullptr, 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

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 nullptr for a separator.
flags	a combination of flags, some of which are mandatory.

Returns: the newly created entry, or nullptr if pos is out of bounds.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayEntryFlags; TrayMenu.GetEntries; TrayEntry.Remove; TrayEntry.GetParent

◆ InsertTrayEntryAt()

TrayEntry SDL::InsertTrayEntryAt	(	TrayMenu	menu,
		int	pos,
		StringParam	label,
		TrayEntryFlags	flags )

inline

Insert a tray entry at a given position.

If label is nullptr, 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

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 nullptr for a separator.
flags	a combination of flags, some of which are mandatory.

Returns: the newly created entry, or nullptr if pos is out of bounds.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayEntryFlags; TrayMenu.GetEntries; TrayEntry.Remove; TrayEntry.GetParent

◆ Remove()

void SDL::TrayEntry::Remove ( )

inline

Removes a tray entry.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry

◆ RemoveTrayEntry()

void SDL::RemoveTrayEntry ( TrayEntryRaw entry )

inline

Removes a tray entry.

Parameters

entry The entry to be deleted.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry

◆ SetCallback()

void SDL::TrayEntry::SetCallback	(	TrayCallback	callback,
		void *	userdata )

inline

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

Parameters

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.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry

◆ SetChecked()

void SDL::TrayEntry::SetChecked ( bool checked )

inline

Sets whether or not an entry is checked.

The entry must have been created with the TRAYENTRY_CHECKBOX flag.

Parameters

checked true if the entry should be checked; false otherwise.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.GetChecked

◆ SetEnabled()

void SDL::TrayEntry::SetEnabled ( bool enabled )

inline

Sets whether or not an entry is enabled.

Parameters

enabled true if the entry should be enabled; false otherwise.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.GetEnabled

◆ SetIcon()

void SDL::Tray::SetIcon ( SurfaceRef icon )

inline

Updates the system tray icon's icon.

Parameters

icon	the new icon. May be nullptr.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: CreateTray

◆ SetLabel()

void SDL::TrayEntry::SetLabel ( StringParam label )

inline

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-nullptr label on an entry that has a nullptr label (separators), or to set a nullptr label to an entry that has a non-nullptr label. The function will silently fail if that happens.

Parameters

label the new label for the entry in UTF-8 encoding.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.GetLabel

◆ SetTooltip()

void SDL::Tray::SetTooltip ( StringParam tooltip )

inline

Updates the system tray icon's tooltip.

Parameters

tooltip the new tooltip in UTF-8 encoding. May be nullptr.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: CreateTray

◆ SetTrayEntryCallback()

void SDL::SetTrayEntryCallback	(	TrayEntryRef	entry,
		TrayCallback	callback,
		void *	userdata )

inline

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

Parameters

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.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry

◆ SetTrayEntryChecked()

void SDL::SetTrayEntryChecked	(	TrayEntryRef	entry,
		bool	checked )

inline

Sets whether or not an entry is checked.

The entry must have been created with the TRAYENTRY_CHECKBOX flag.

Parameters

entry	the entry to be updated.
checked	true if the entry should be checked; false otherwise.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.GetChecked

◆ SetTrayEntryEnabled()

void SDL::SetTrayEntryEnabled	(	TrayEntryRef	entry,
		bool	enabled )

inline

Sets whether or not an entry is enabled.

Parameters

entry	the entry to be updated.
enabled	true if the entry should be enabled; false otherwise.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.GetEnabled

◆ SetTrayEntryLabel()

void SDL::SetTrayEntryLabel	(	TrayEntryRef	entry,
		StringParam	label )

inline

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-nullptr label on an entry that has a nullptr label (separators), or to set a nullptr label to an entry that has a non-nullptr label. The function will silently fail if that happens.

Parameters

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

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: TrayMenu.GetEntries; TrayMenu.InsertEntry; TrayEntry.GetLabel

◆ SetTrayIcon()

void SDL::SetTrayIcon	(	TrayRef	tray,
		SurfaceRef	icon )

inline

Updates the system tray icon's icon.

Parameters

tray	the tray icon to be updated.
icon	the new icon. May be nullptr.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: CreateTray

◆ SetTrayTooltip()

void SDL::SetTrayTooltip	(	TrayRef	tray,
		StringParam	tooltip )

inline

Updates the system tray icon's tooltip.

Parameters

tray	the tray icon to be updated.
tooltip	the new tooltip in UTF-8 encoding. May be nullptr.

Thread safety:: This function should be called on the thread that created the tray.

Since: This function is available since SDL 3.2.0.

See also: CreateTray

◆ Tray()

SDL::Tray::Tray	(	SurfaceRef	icon,
		StringParam	tooltip )

inline

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

icon	a surface to be used as icon. May be nullptr.
tooltip	a tooltip to be displayed when the mouse hovers the icon in UTF-8 encoding. Not supported on all platforms. May be nullptr.

Postcondition: The newly created system tray icon.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: Tray.CreateMenu; Tray.GetMenu; Tray.Destroy

◆ UpdateTrays()

void SDL::UpdateTrays ( )

inline

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.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

Variable Documentation

◆ TRAYENTRY_BUTTON

TrayEntryFlags SDL::TRAYENTRY_BUTTON

constexpr

Initial value:

=

SDL_TRAYENTRY_BUTTON

Make the entry a simple button. Required.

◆ TRAYENTRY_CHECKBOX

TrayEntryFlags SDL::TRAYENTRY_CHECKBOX

constexpr

Initial value:

=

SDL_TRAYENTRY_CHECKBOX

Make the entry a checkbox. Required.

◆ TRAYENTRY_DISABLED

TrayEntryFlags SDL::TRAYENTRY_DISABLED

constexpr

Initial value:

=

SDL_TRAYENTRY_DISABLED

Make the entry disabled. Optional.

◆ TRAYENTRY_SUBMENU

TrayEntryFlags SDL::TRAYENTRY_SUBMENU

constexpr

Initial value:

=

SDL_TRAYENTRY_SUBMENU

Prepare the entry to have a submenu. Required.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ TrayCallback

◆ TrayCB

◆ TrayEntryFlags

Function Documentation

◆ Click()

◆ ClickTrayEntry()

◆ CreateMenu()

◆ CreateSubmenu()

◆ CreateTray()

◆ CreateTrayMenu()

◆ CreateTraySubmenu()

◆ Destroy()

◆ DestroyTray()

◆ GetChecked()

◆ GetEnabled()

◆ GetEntries()

◆ GetLabel()

◆ GetMenu()

◆ GetParent()

◆ GetParentEntry()

◆ GetParentTray()

◆ GetSubmenu()

◆ GetTrayEntries()

◆ GetTrayEntryChecked()

◆ GetTrayEntryEnabled()

◆ GetTrayEntryLabel()

◆ GetTrayEntryParent()

◆ GetTrayMenu()

◆ GetTrayMenuParentEntry()

◆ GetTrayMenuParentTray()

◆ GetTraySubmenu()

◆ InsertEntry()

◆ InsertTrayEntryAt()

◆ Remove()

◆ RemoveTrayEntry()

◆ SetCallback()

◆ SetChecked()

◆ SetEnabled()

◆ SetIcon()

◆ SetLabel()

◆ SetTooltip()

◆ SetTrayEntryCallback()

◆ SetTrayEntryChecked()

◆ SetTrayEntryEnabled()

◆ SetTrayEntryLabel()

◆ SetTrayIcon()

◆ SetTrayTooltip()

◆ Tray()

◆ UpdateTrays()

Variable Documentation

◆ TRAYENTRY_BUTTON

◆ TRAYENTRY_CHECKBOX

◆ TRAYENTRY_DISABLED

◆ TRAYENTRY_SUBMENU