SDL 3.0
SDL_tray.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * # CategoryTray
24 *
25 * System tray menu support.
26 */
27
28#ifndef SDL_tray_h_
29#define SDL_tray_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_error.h>
33#include <SDL3/SDL_surface.h>
34#include <SDL3/SDL_video.h>
35
36#include <SDL3/SDL_begin_code.h>
37/* Set up for C function definitions, even when using C++ */
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42/**
43 * An opaque handle representing a toplevel system tray object.
44 *
45 * \since This struct is available since SDL 3.2.0.
46 */
47typedef struct SDL_Tray SDL_Tray;
48
49/**
50 * An opaque handle representing a menu/submenu on a system tray object.
51 *
52 * \since This struct is available since SDL 3.2.0.
53 */
55
56/**
57 * An opaque handle representing an entry on a system tray object.
58 *
59 * \since This struct is available since SDL 3.2.0.
60 */
62
63/**
64 * Flags that control the creation of system tray entries.
65 *
66 * Some of these flags are required; exactly one of them must be specified at
67 * the time a tray entry is created. Other flags are optional; zero or more of
68 * those can be OR'ed together with the required flag.
69 *
70 * \since This datatype is available since SDL 3.2.0.
71 *
72 * \sa SDL_InsertTrayEntryAt
73 */
75
76#define SDL_TRAYENTRY_BUTTON 0x00000001u /**< Make the entry a simple button. Required. */
77#define SDL_TRAYENTRY_CHECKBOX 0x00000002u /**< Make the entry a checkbox. Required. */
78#define SDL_TRAYENTRY_SUBMENU 0x00000004u /**< Prepare the entry to have a submenu. Required */
79#define SDL_TRAYENTRY_DISABLED 0x80000000u /**< Make the entry disabled. Optional. */
80#define SDL_TRAYENTRY_CHECKED 0x40000000u /**< Make the entry checked. This is valid only for checkboxes. Optional. */
81
82/**
83 * A callback that is invoked when a tray entry is selected.
84 *
85 * \param userdata an optional pointer to pass extra data to the callback when
86 * it will be invoked.
87 * \param entry the tray entry that was selected.
88 *
89 * \since This datatype is available since SDL 3.2.0.
90 *
91 * \sa SDL_SetTrayEntryCallback
92 */
93typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry);
94
95/**
96 * Create an icon to be placed in the operating system's tray, or equivalent.
97 *
98 * Many platforms advise not using a system tray unless persistence is a
99 * necessary feature. Avoid needlessly creating a tray icon, as the user may
100 * feel like it clutters their interface.
101 *
102 * Using tray icons require the video subsystem.
103 *
104 * \param icon a surface to be used as icon. May be NULL.
105 * \param tooltip a tooltip to be displayed when the mouse hovers the icon in
106 * UTF-8 encoding. Not supported on all platforms. May be NULL.
107 * \returns The newly created system tray icon.
108 *
109 * \since This function is available since SDL 3.2.0.
110 *
111 * \sa SDL_CreateTrayMenu
112 * \sa SDL_GetTrayMenu
113 * \sa SDL_DestroyTray
114 */
115extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_CreateTray(SDL_Surface *icon, const char *tooltip);
116
117/**
118 * Updates the system tray icon's icon.
119 *
120 * \param tray the tray icon to be updated.
121 * \param icon the new icon. May be NULL.
122 *
123 * \since This function is available since SDL 3.2.0.
124 *
125 * \sa SDL_CreateTray
126 */
127extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *icon);
128
129/**
130 * Updates the system tray icon's tooltip.
131 *
132 * \param tray the tray icon to be updated.
133 * \param tooltip the new tooltip in UTF-8 encoding. May be NULL.
134 *
135 * \since This function is available since SDL 3.2.0.
136 *
137 * \sa SDL_CreateTray
138 */
139extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *tooltip);
140
141/**
142 * Create a menu for a system tray.
143 *
144 * This should be called at most once per tray icon.
145 *
146 * This function does the same thing as SDL_CreateTraySubmenu(), except that
147 * it takes a SDL_Tray instead of a SDL_TrayEntry.
148 *
149 * A menu does not need to be destroyed; it will be destroyed with the tray.
150 *
151 * \param tray the tray to bind the menu to.
152 * \returns the newly created menu.
153 *
154 * \since This function is available since SDL 3.2.0.
155 *
156 * \sa SDL_CreateTray
157 * \sa SDL_GetTrayMenu
158 * \sa SDL_GetTrayMenuParentTray
159 */
160extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray);
161
162/**
163 * Create a submenu for a system tray entry.
164 *
165 * This should be called at most once per tray entry.
166 *
167 * This function does the same thing as SDL_CreateTrayMenu, except that it
168 * takes a SDL_TrayEntry instead of a SDL_Tray.
169 *
170 * A menu does not need to be destroyed; it will be destroyed with the tray.
171 *
172 * \param entry the tray entry to bind the menu to.
173 * \returns the newly created menu.
174 *
175 * \since This function is available since SDL 3.2.0.
176 *
177 * \sa SDL_InsertTrayEntryAt
178 * \sa SDL_GetTraySubmenu
179 * \sa SDL_GetTrayMenuParentEntry
180 */
181extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *entry);
182
183/**
184 * Gets a previously created tray menu.
185 *
186 * You should have called SDL_CreateTrayMenu() on the tray object. This
187 * function allows you to fetch it again later.
188 *
189 * This function does the same thing as SDL_GetTraySubmenu(), except that it
190 * takes a SDL_Tray instead of a SDL_TrayEntry.
191 *
192 * A menu does not need to be destroyed; it will be destroyed with the tray.
193 *
194 * \param tray the tray entry to bind the menu to.
195 * \returns the newly created menu.
196 *
197 * \since This function is available since SDL 3.2.0.
198 *
199 * \sa SDL_CreateTray
200 * \sa SDL_CreateTrayMenu
201 */
202extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayMenu(SDL_Tray *tray);
203
204/**
205 * Gets a previously created tray entry submenu.
206 *
207 * You should have called SDL_CreateTraySubenu() on the entry object. This
208 * function allows you to fetch it again later.
209 *
210 * This function does the same thing as SDL_GetTrayMenu(), except that it
211 * takes a SDL_TrayEntry instead of a SDL_Tray.
212 *
213 * A menu does not need to be destroyed; it will be destroyed with the tray.
214 *
215 * \param entry the tray entry to bind the menu to.
216 * \returns the newly created menu.
217 *
218 * \since This function is available since SDL 3.2.0.
219 *
220 * \sa SDL_InsertTrayEntryAt
221 * \sa SDL_CreateTraySubmenu
222 */
223extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entry);
224
225/**
226 * Returns a list of entries in the menu, in order.
227 *
228 * \param menu The menu to get entries from.
229 * \param size An optional pointer to obtain the number of entries in the
230 * menu.
231 * \returns a NULL-terminated list of entries within the given menu. The
232 * pointer becomes invalid when any function that inserts or deletes
233 * entries in the menu is called.
234 *
235 * \since This function is available since SDL 3.2.0.
236 *
237 * \sa SDL_RemoveTrayEntry
238 * \sa SDL_InsertTrayEntryAt
239 */
240extern SDL_DECLSPEC const SDL_TrayEntry **SDLCALL SDL_GetTrayEntries(SDL_TrayMenu *menu, int *size);
241
242/**
243 * Removes a tray entry.
244 *
245 * \param entry The entry to be deleted.
246 *
247 * \since This function is available since SDL 3.2.0.
248 *
249 * \sa SDL_GetTrayEntries
250 * \sa SDL_InsertTrayEntryAt
251 */
252extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry);
253
254/**
255 * Insert a tray entry at a given position.
256 *
257 * If label is NULL, the entry will be a separator. Many functions won't work
258 * for an entry that is a separator.
259 *
260 * An entry does not need to be destroyed; it will be destroyed with the tray.
261 *
262 * \param menu the menu to append the entry to.
263 * \param pos the desired position for the new entry. Entries at or following
264 * this place will be moved. If pos is -1, the entry is appended.
265 * \param label the text to be displayed on the entry, in UTF-8 encoding, or
266 * NULL for a separator.
267 * \param flags a combination of flags, some of which are mandatory.
268 * \returns the newly created entry, or NULL if pos is out of bounds.
269 *
270 * \since This function is available since SDL 3.2.0.
271 *
272 * \sa SDL_TrayEntryFlags
273 * \sa SDL_GetTrayEntries
274 * \sa SDL_RemoveTrayEntry
275 * \sa SDL_GetTrayEntryParent
276 */
277extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *menu, int pos, const char *label, SDL_TrayEntryFlags flags);
278
279/**
280 * Sets the label of an entry.
281 *
282 * An entry cannot change between a separator and an ordinary entry; that is,
283 * it is not possible to set a non-NULL label on an entry that has a NULL
284 * label (separators), or to set a NULL label to an entry that has a non-NULL
285 * label. The function will silently fail if that happens.
286 *
287 * \param entry the entry to be updated.
288 * \param label the new label for the entry in UTF-8 encoding.
289 *
290 * \since This function is available since SDL 3.2.0.
291 *
292 * \sa SDL_GetTrayEntries
293 * \sa SDL_InsertTrayEntryAt
294 * \sa SDL_GetTrayEntryLabel
295 */
296extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, const char *label);
297
298/**
299 * Gets the label of an entry.
300 *
301 * If the returned value is NULL, the entry is a separator.
302 *
303 * \param entry the entry to be read.
304 * \returns the label of the entry in UTF-8 encoding.
305 *
306 * \since This function is available since SDL 3.2.0.
307 *
308 * \sa SDL_GetTrayEntries
309 * \sa SDL_InsertTrayEntryAt
310 * \sa SDL_SetTrayEntryLabel
311 */
312extern SDL_DECLSPEC const char *SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *entry);
313
314/**
315 * Sets whether or not an entry is checked.
316 *
317 * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.
318 *
319 * \param entry the entry to be updated.
320 * \param checked SDL_TRUE if the entry should be checked; SDL_FALSE
321 * otherwise.
322 *
323 * \since This function is available since SDL 3.2.0.
324 *
325 * \sa SDL_GetTrayEntries
326 * \sa SDL_InsertTrayEntryAt
327 * \sa SDL_GetTrayEntryChecked
328 */
329extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, bool checked);
330
331/**
332 * Gets whether or not an entry is checked.
333 *
334 * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.
335 *
336 * \param entry the entry to be read.
337 * \returns SDL_TRUE if the entry is checked; SDL_FALSE otherwise.
338 *
339 * \since This function is available since SDL 3.2.0.
340 *
341 * \sa SDL_GetTrayEntries
342 * \sa SDL_InsertTrayEntryAt
343 * \sa SDL_SetTrayEntryChecked
344 */
345extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry);
346
347/**
348 * Sets whether or not an entry is enabled.
349 *
350 * \param entry the entry to be updated.
351 * \param enabled SDL_TRUE if the entry should be enabled; SDL_FALSE
352 * otherwise.
353 *
354 * \since This function is available since SDL 3.2.0.
355 *
356 * \sa SDL_GetTrayEntries
357 * \sa SDL_InsertTrayEntryAt
358 * \sa SDL_GetTrayEntryEnabled
359 */
360extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, bool enabled);
361
362/**
363 * Gets whether or not an entry is enabled.
364 *
365 * \param entry the entry to be read.
366 * \returns SDL_TRUE if the entry is enabled; SDL_FALSE otherwise.
367 *
368 * \since This function is available since SDL 3.2.0.
369 *
370 * \sa SDL_GetTrayEntries
371 * \sa SDL_InsertTrayEntryAt
372 * \sa SDL_SetTrayEntryEnabled
373 */
374extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry);
375
376/**
377 * Sets a callback to be invoked when the entry is selected.
378 *
379 * \param entry the entry to be updated.
380 * \param callback a callback to be invoked when the entry is selected.
381 * \param userdata an optional pointer to pass extra data to the callback when
382 * it will be invoked.
383 *
384 * \since This function is available since SDL 3.2.0.
385 *
386 * \sa SDL_GetTrayEntries
387 * \sa SDL_InsertTrayEntryAt
388 */
389extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, SDL_TrayCallback callback, void *userdata);
390
391/**
392 * Destroys a tray object.
393 *
394 * This also destroys all associated menus and entries.
395 *
396 * \param tray the tray icon to be destroyed.
397 *
398 * \since This function is available since SDL 3.2.0.
399 *
400 * \sa SDL_CreateTray
401 */
402extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray);
403
404/**
405 * Gets the menu contianing a certain tray entry.
406 *
407 * \param entry the entry for which to get the parent menu.
408 * \returns the parent menu.
409 *
410 * \since This function is available since SDL 3.2.0.
411 *
412 * \sa SDL_InsertTrayEntryAt
413 */
414extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *entry);
415
416/**
417 * Gets the entry for which the menu is a submenu, if the current menu is a
418 * submenu.
419 *
420 * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL
421 * for any given menu.
422 *
423 * \param menu the menu for which to get the parent entry.
424 * \returns the parent entry, or NULL if this menu is not a submenu.
425 *
426 * \since This function is available since SDL 3.2.0.
427 *
428 * \sa SDL_CreateTraySubmenu
429 * \sa SDL_GetTrayMenuParentTray
430 */
431extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMenu *menu);
432
433/**
434 * Gets the tray for which this menu is the first-level menu, if the current
435 * menu isn't a submenu.
436 *
437 * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL
438 * for any given menu.
439 *
440 * \param menu the menu for which to get the parent enttrayry.
441 * \returns the parent tray, or NULL if this menu is a submenu.
442 *
443 * \since This function is available since SDL 3.2.0.
444 *
445 * \sa SDL_CreateTrayMenu
446 * \sa SDL_GetTrayMenuParentEntry
447 */
448extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_GetTrayMenuParentTray(SDL_TrayMenu *menu);
449
450/* Ends C function definitions when using C++ */
451#ifdef __cplusplus
452}
453#endif
454#include <SDL3/SDL_close_code.h>
455
456#endif /* SDL_tray_h_ */
SDL_MALLOC size_t size
uint32_t Uint32
Definition SDL_stdinc.h:435
SDL_TrayMenu * SDL_GetTrayMenu(SDL_Tray *tray)
SDL_Tray * SDL_CreateTray(SDL_Surface *icon, const char *tooltip)
bool SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry)
void SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *icon)
void SDL_SetTrayTooltip(SDL_Tray *tray, const char *tooltip)
SDL_TrayMenu * SDL_CreateTraySubmenu(SDL_TrayEntry *entry)
void(* SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry)
Definition SDL_tray.h:93
struct SDL_TrayMenu SDL_TrayMenu
Definition SDL_tray.h:54
void SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, bool enabled)
SDL_TrayEntry * SDL_GetTrayMenuParentEntry(SDL_TrayMenu *menu)
void SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, SDL_TrayCallback callback, void *userdata)
SDL_TrayEntry * SDL_InsertTrayEntryAt(SDL_TrayMenu *menu, int pos, const char *label, SDL_TrayEntryFlags flags)
const char * SDL_GetTrayEntryLabel(SDL_TrayEntry *entry)
SDL_TrayMenu * SDL_GetTrayEntryParent(SDL_TrayEntry *entry)
const SDL_TrayEntry ** SDL_GetTrayEntries(SDL_TrayMenu *menu, int *size)
bool SDL_GetTrayEntryChecked(SDL_TrayEntry *entry)
SDL_TrayMenu * SDL_GetTraySubmenu(SDL_TrayEntry *entry)
SDL_Tray * SDL_GetTrayMenuParentTray(SDL_TrayMenu *menu)
void SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, bool checked)
Uint32 SDL_TrayEntryFlags
Definition SDL_tray.h:74
void SDL_DestroyTray(SDL_Tray *tray)
struct SDL_TrayEntry SDL_TrayEntry
Definition SDL_tray.h:61
SDL_TrayMenu * SDL_CreateTrayMenu(SDL_Tray *tray)
void SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, const char *label)
void SDL_RemoveTrayEntry(SDL_TrayEntry *entry)
struct SDL_Tray SDL_Tray
Definition SDL_tray.h:47