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

Classes
struct	SDL::TrayRef
	An opaque handle representing a toplevel system tray object. More...

struct	SDL::Tray
	Handle to an owned tray. More...

struct	SDL::TrayUnsafe
	Unsafe Handle to tray. More...

class	SDL::TrayMenu
	An opaque handle representing a menu/submenu on a system tray object. More...

struct	SDL::TrayEntryRef
	An opaque handle representing an entry on a system tray object. More...

struct	SDL::TrayEntry
	Handle to an owned trayEntry. More...

struct	SDL::TrayEntryUnsafe
	Unsafe Handle to trayEntry. More...

Typedefs
using	SDL::TrayShared = ResourceShared< Tray >
	Handle to a shared tray.

using	SDL::TrayWeak = ResourceWeak< Tray >
	Weak handle to a shared tray.

using	SDL::TrayEntryShared = ResourceShared< TrayEntry >
	Handle to a shared trayEntry.

using	SDL::TrayEntryWeak = ResourceWeak< TrayEntry >
	Weak handle to a shared trayEntry.

using	SDL::DetachedTrayEntry = DetachedResource< TrayEntryRef, TrayEntry >
	A trayEntry result that will be owned only if assigned to a TrayEntry.

using	SDL::TrayEntryFlags = Uint32
	Flags that control the creation of system tray entries.

using	SDL::TrayCallback = SDL_TrayCallback
	A callback that is invoked when a tray entry is selected.

using	SDL::TrayCB = std::function< void(TrayEntryRef)>
	A callback that is invoked when a tray entry is selected.

Functions
void	SDL::UpdateTrays ()
	Update the trays.

TrayShared	SDL::Tray::share ()
	Move this tray into a TrayShared.

TrayEntryShared	SDL::TrayEntry::share ()
	Move this trayEntry into a TrayEntryShared.

TrayMenu	SDL::TrayRef::CreateMenu ()
	Create a menu for a system tray.

TrayMenu	SDL::TrayRef::GetMenu () const
	Gets a previously created tray menu.

std::span< TrayEntry >	SDL::TrayMenu::GetEntries ()
	Returns a list of entries in the menu, in order.

DetachedTrayEntry	SDL::TrayMenu::InsertEntry (int pos, StringParam label, TrayEntryFlags flags)
	Insert a tray entry at a given position.

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.

Detailed Description

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

◆ DetachedTrayEntry

using SDL::DetachedTrayEntry = typedef DetachedResource<TrayEntryRef, TrayEntry>

This is designed as resource types to cases where ownership might not be required.

◆ TrayCallback

using SDL::TrayCallback = typedef SDL_TrayCallback

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: TrayEntryRef.SetCallback

◆ TrayCB

using SDL::TrayCB = typedef std::function<void(TrayEntryRef)>

Parameters

entry the tray entry that was selected.

Since: This datatype is available since SDL 3.2.0.

See also: TrayEntryRef.SetCallback; TrayCallback

◆ TrayEntryFlags

using SDL::TrayEntryFlags = typedef Uint32

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

◆ TrayEntryShared

using SDL::TrayEntryShared = typedef ResourceShared<TrayEntry>

Category:: Resource

See also: TrayEntryRef; TrayEntry

◆ TrayEntryWeak

using SDL::TrayEntryWeak = typedef ResourceWeak<TrayEntry>

Category:: Resource

See also: TrayEntryShared; TrayEntryRef

◆ TrayShared

using SDL::TrayShared = typedef ResourceShared<Tray>

Category:: Resource

See also: TrayRef; Tray

◆ TrayWeak

using SDL::TrayWeak = typedef ResourceWeak<Tray>

Category:: Resource

See also: TrayShared; TrayRef

Function Documentation

◆ CreateMenu()

TrayMenu SDL::TrayRef::CreateMenu ( )

inline

This should be called at most once per tray icon.

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

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: Tray.Create; TrayRef.GetMenu; TrayMenu.GetParentTray

◆ GetEntries()

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

inline

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

◆ GetMenu()

TrayMenu SDL::TrayRef::GetMenu ( ) const

inline

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

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

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: Tray.Create; TrayRef.CreateMenu

◆ GetParentEntry()

TrayEntryRef SDL::TrayMenu::GetParentEntry ( ) const

inline

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: TrayEntryRef.CreateSubmenu; TrayMenu.GetParentTray

◆ GetParentTray()

TrayRef SDL::TrayMenu::GetParentTray ( ) const

inline

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: TrayRef.CreateMenu; TrayMenu.GetParentEntry

◆ InsertEntry()

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

inline

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: TrayMenu.AppendEntry; TrayEntryFlags; TrayMenu.GetEntries; TrayEntry.Remove; TrayEntryRef.GetParent

◆ UpdateTrays()

void SDL::UpdateTrays ( )

inline

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

constexpr TrayEntryFlags SDL::TRAYENTRY_BUTTON

constexpr

Initial value:

=

SDL_TRAYENTRY_BUTTON

◆ TRAYENTRY_CHECKBOX

constexpr TrayEntryFlags SDL::TRAYENTRY_CHECKBOX

constexpr

Initial value:

=

SDL_TRAYENTRY_CHECKBOX

◆ TRAYENTRY_CHECKED

constexpr TrayEntryFlags SDL::TRAYENTRY_CHECKED = SDL_TRAYENTRY_CHECKED

constexpr

This is valid only for checkboxes. Optional.

◆ TRAYENTRY_DISABLED

constexpr TrayEntryFlags SDL::TRAYENTRY_DISABLED

constexpr

Initial value:

=

SDL_TRAYENTRY_DISABLED

◆ TRAYENTRY_SUBMENU

constexpr TrayEntryFlags SDL::TRAYENTRY_SUBMENU

constexpr

Initial value:

=

SDL_TRAYENTRY_SUBMENU

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ DetachedTrayEntry

◆ TrayCallback

◆ TrayCB

◆ TrayEntryFlags

◆ TrayEntryShared

◆ TrayEntryWeak

◆ TrayShared

◆ TrayWeak

Function Documentation

◆ CreateMenu()

◆ GetEntries()

◆ GetMenu()

◆ GetParentEntry()

◆ GetParentTray()

◆ InsertEntry()

◆ UpdateTrays()

Variable Documentation

◆ TRAYENTRY_BUTTON

◆ TRAYENTRY_CHECKBOX

◆ TRAYENTRY_CHECKED

◆ TRAYENTRY_DISABLED

◆ TRAYENTRY_SUBMENU