SDL_tray.h File Reference
`#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>`
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_Tray * | SDL_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_TrayMenu * | SDL_CreateTrayMenu (SDL_Tray *tray)
SDL_TrayMenu * | SDL_CreateTraySubmenu (SDL_TrayEntry *entry)
SDL_TrayMenu * | SDL_GetTrayMenu (SDL_Tray *tray)
SDL_TrayMenu * | SDL_GetTraySubmenu (SDL_TrayEntry *entry)
const SDL_TrayEntry ** | SDL_GetTrayEntries (SDL_TrayMenu *menu, int *count)
void | SDL_RemoveTrayEntry (SDL_TrayEntry *entry)
SDL_TrayEntry * | SDL_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_TrayMenu * | SDL_GetTrayEntryParent (SDL_TrayEntry *entry)
SDL_TrayEntry * | SDL_GetTrayMenuParentEntry (SDL_TrayMenu *menu)
SDL_Tray * | SDL_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

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

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.

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 | ) |

extern

Simulate a click on a tray entry.

Parameters

  entry | The 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
| ) |  |

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.

Parameters

  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.

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 | ) |

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.

Parameters

  tray | the 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 | ) |

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.

Parameters

  entry | the 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 | ) |

extern

Destroys a tray object.

This also destroys all associated menus and entries.

Parameters

  tray | the 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
| ) |  |

extern

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

Parameters

  menu | The menu to get entries from.
  count | An 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 | ) |

extern

Gets whether or not an entry is checked.

The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.

Parameters

  entry | the 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 | ) |

extern

Gets whether or not an entry is enabled.

Parameters

  entry | the 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 | ) |

extern

Gets the label of an entry.

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

Parameters

  entry | the 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 | ) |

extern

Gets the menu containing a certain tray entry.

Parameters

  entry | the 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 | ) |

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.

Parameters

  tray | the 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 | ) |

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.

Parameters

  menu | the 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 | ) |

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.

Parameters

  menu | the 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 | ) |

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.

Parameters

  entry | the 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
| ) |  |

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.

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 NULL for a separator.
  flags | a 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 | ) |

extern

Removes a tray entry.

Parameters

  entry | The 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
| ) |  |

extern

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.

\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
| ) |  |

extern

Sets whether or not an entry is checked.

The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.

Parameters

  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.

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
| ) |  |

extern

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.

\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
| ) |  |

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.

Parameters

  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.

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
| ) |  |

extern

Updates the system tray icon's icon.

Parameters

  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.

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
| ) |  |

extern

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 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 |  | ) |

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.

Since
  This function is available since SDL 3.2.0.