Atlas - SDL_tray.h
Home / ext / SDL / include / SDL3
Lines: 1 | Size: 20706 bytes
[Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)] 
[FILE BEGIN]
1/*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2026 Sam Lantinga <[email protected]>
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 * SDL offers a way to add items to the "system tray" (more correctly called
26 * the "notification area" on Windows). On platforms that offer this concept,
27 * an SDL app can add a tray icon, submenus, checkboxes, and clickable
28 * entries, and register a callback that is fired when the user clicks on
29 * these pieces.
30 */
31
32#ifndef SDL_tray_h_
33#define SDL_tray_h_
34
35#include <SDL3/SDL_stdinc.h>
36#include <SDL3/SDL_error.h>
37#include <SDL3/SDL_properties.h>
38#include <SDL3/SDL_surface.h>
39#include <SDL3/SDL_video.h>
40
41#include <SDL3/SDL_begin_code.h>
42/* Set up for C function definitions, even when using C++ */
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47/**
48 * An opaque handle representing a toplevel system tray object.
49 *
50 * \since This struct is available since SDL 3.2.0.
51 */
52typedef struct SDL_Tray SDL_Tray;
53
54/**
55 * An opaque handle representing a menu/submenu on a system tray object.
56 *
57 * \since This struct is available since SDL 3.2.0.
58 */
59typedef struct SDL_TrayMenu SDL_TrayMenu;
60
61/**
62 * An opaque handle representing an entry on a system tray object.
63 *
64 * \since This struct is available since SDL 3.2.0.
65 */
66typedef struct SDL_TrayEntry SDL_TrayEntry;
67
68/**
69 * Flags that control the creation of system tray entries.
70 *
71 * Some of these flags are required; exactly one of them must be specified at
72 * the time a tray entry is created. Other flags are optional; zero or more of
73 * those can be OR'ed together with the required flag.
74 *
75 * \since This datatype is available since SDL 3.2.0.
76 *
77 * \sa SDL_InsertTrayEntryAt
78 */
79typedef Uint32 SDL_TrayEntryFlags;
80
81#define SDL_TRAYENTRY_BUTTON      0x00000001u /**< Make the entry a simple button. Required. */
82#define SDL_TRAYENTRY_CHECKBOX    0x00000002u /**< Make the entry a checkbox. Required. */
83#define SDL_TRAYENTRY_SUBMENU     0x00000004u /**< Prepare the entry to have a submenu. Required */
84#define SDL_TRAYENTRY_DISABLED    0x80000000u /**< Make the entry disabled. Optional. */
85#define SDL_TRAYENTRY_CHECKED     0x40000000u /**< Make the entry checked. This is valid only for checkboxes. Optional. */
86
87/**
88 * A callback that is invoked when a tray entry is selected.
89 *
90 * \param userdata an optional pointer to pass extra data to the callback when
91 *                 it will be invoked.
92 * \param entry the tray entry that was selected.
93 *
94 * \since This datatype is available since SDL 3.2.0.
95 *
96 * \sa SDL_SetTrayEntryCallback
97 */
98typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry);
99
100/**
101 * A callback that is invoked when the tray icon is clicked.
102 *
103 * \param userdata an optional pointer to pass extra data to the callback when
104 *                 it will be invoked. May be NULL.
105 * \param tray the tray that was clicked.
106 * \returns true to show the tray menu after the callback returns, false to
107 *          skip showing the menu. This return value is only used for left and
108 *          right click callbacks; other mouse events ignore the return value.
109 *
110 * \since This datatype is available since SDL 3.6.0.
111 *
112 * \sa SDL_CreateTrayWithProperties
113 */
114typedef bool (SDLCALL *SDL_TrayClickCallback)(void *userdata, SDL_Tray *tray);
115
116/**
117 * Create an icon to be placed in the operating system's tray, or equivalent.
118 *
119 * Many platforms advise not using a system tray unless persistence is a
120 * necessary feature. Avoid needlessly creating a tray icon, as the user may
121 * feel like it clutters their interface.
122 *
123 * Using tray icons require the video subsystem.
124 *
125 * \param icon a surface to be used as icon. May be NULL.
126 * \param tooltip a tooltip to be displayed when the mouse hovers the icon in
127 *                UTF-8 encoding. Not supported on all platforms. May be NULL.
128 * \returns The newly created system tray icon.
129 *
130 * \threadsafety This function should only be called on the main thread.
131 *
132 * \since This function is available since SDL 3.2.0.
133 *
134 * \sa SDL_CreateTrayWithProperties
135 * \sa SDL_CreateTrayMenu
136 * \sa SDL_GetTrayMenu
137 * \sa SDL_DestroyTray
138 */
139extern SDL_DECLSPEC SDL_Tray * SDLCALL SDL_CreateTray(SDL_Surface *icon, const char *tooltip);
140
141/**
142 * Create an icon to be placed in the operating system's tray, or equivalent.
143 *
144 * Many platforms advise not using a system tray unless persistence is a
145 * necessary feature. Avoid needlessly creating a tray icon, as the user may
146 * feel like it clutters their interface.
147 *
148 * Using tray icons require the video subsystem.
149 *
150 * These are the supported properties:
151 *
152 * - `SDL_PROP_TRAY_CREATE_ICON_POINTER`: an SDL_Surface to be used as the
153 *   tray icon. May be NULL.
154 * - `SDL_PROP_TRAY_CREATE_TOOLTIP_STRING`: a tooltip to be displayed when the
155 *   mouse hovers the icon in UTF-8 encoding. Not supported on all platforms.
156 *   May be NULL.
157 * - `SDL_PROP_TRAY_CREATE_USERDATA_POINTER`: an optional pointer to associate
158 *   with the tray, which will be passed to click callbacks. May be NULL.
159 * - `SDL_PROP_TRAY_CREATE_LEFTCLICK_CALLBACK_POINTER`: an
160 *   SDL_TrayClickCallback to be invoked when the tray icon is left-clicked.
161 *   Not supported on all platforms. The callback should return true to show
162 *   the default menu, or false to skip showing it. May be NULL.
163 * - `SDL_PROP_TRAY_CREATE_RIGHTCLICK_CALLBACK_POINTER`: an
164 *   SDL_TrayClickCallback to be invoked when the tray icon is right-clicked.
165 *   Not supported on all platforms. The callback should return true to show
166 *   the default menu, or false to skip showing it. May be NULL.
167 * - `SDL_PROP_TRAY_CREATE_MIDDLECLICK_CALLBACK_POINTER`: an
168 *   SDL_TrayClickCallback to be invoked when the tray icon is middle-clicked.
169 *   Not supported on all platforms. May be NULL.
170 *
171 * \param props the properties to use.
172 * \returns The newly created system tray icon.
173 *
174 * \threadsafety This function should only be called on the main thread.
175 *
176 * \since This function is available since SDL 3.6.0.
177 *
178 * \sa SDL_CreateTray
179 * \sa SDL_CreateTrayMenu
180 * \sa SDL_GetTrayMenu
181 * \sa SDL_DestroyTray
182 */
183extern SDL_DECLSPEC SDL_Tray * SDLCALL SDL_CreateTrayWithProperties(SDL_PropertiesID props);
184
185#define SDL_PROP_TRAY_CREATE_ICON_POINTER                 "SDL.tray.create.icon"
186#define SDL_PROP_TRAY_CREATE_TOOLTIP_STRING               "SDL.tray.create.tooltip"
187#define SDL_PROP_TRAY_CREATE_USERDATA_POINTER             "SDL.tray.create.userdata"
188#define SDL_PROP_TRAY_CREATE_LEFTCLICK_CALLBACK_POINTER   "SDL.tray.create.leftclick_callback"
189#define SDL_PROP_TRAY_CREATE_RIGHTCLICK_CALLBACK_POINTER  "SDL.tray.create.rightclick_callback"
190#define SDL_PROP_TRAY_CREATE_MIDDLECLICK_CALLBACK_POINTER "SDL.tray.create.middleclick_callback"
191
192/**
193 * Updates the system tray icon's icon.
194 *
195 * \param tray the tray icon to be updated.
196 * \param icon the new icon. May be NULL.
197 *
198 * \threadsafety This function should be called on the thread that created the
199 *               tray.
200 *
201 * \since This function is available since SDL 3.2.0.
202 *
203 * \sa SDL_CreateTray
204 */
205extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *icon);
206
207/**
208 * Updates the system tray icon's tooltip.
209 *
210 * \param tray the tray icon to be updated.
211 * \param tooltip the new tooltip in UTF-8 encoding. May be NULL.
212 *
213 * \threadsafety This function should be called on the thread that created the
214 *               tray.
215 *
216 * \since This function is available since SDL 3.2.0.
217 *
218 * \sa SDL_CreateTray
219 */
220extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *tooltip);
221
222/**
223 * Create a menu for a system tray.
224 *
225 * This should be called at most once per tray icon.
226 *
227 * This function does the same thing as SDL_CreateTraySubmenu(), except that
228 * it takes a SDL_Tray instead of a SDL_TrayEntry.
229 *
230 * A menu does not need to be destroyed; it will be destroyed with the tray.
231 *
232 * \param tray the tray to bind the menu to.
233 * \returns the newly created menu.
234 *
235 * \threadsafety This function should be called on the thread that created the
236 *               tray.
237 *
238 * \since This function is available since SDL 3.2.0.
239 *
240 * \sa SDL_CreateTray
241 * \sa SDL_GetTrayMenu
242 * \sa SDL_GetTrayMenuParentTray
243 */
244extern SDL_DECLSPEC SDL_TrayMenu * SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray);
245
246/**
247 * Create a submenu for a system tray entry.
248 *
249 * This should be called at most once per tray entry.
250 *
251 * This function does the same thing as SDL_CreateTrayMenu, except that it
252 * takes a SDL_TrayEntry instead of a SDL_Tray.
253 *
254 * A menu does not need to be destroyed; it will be destroyed with the tray.
255 *
256 * \param entry the tray entry to bind the menu to.
257 * \returns the newly created menu.
258 *
259 * \threadsafety This function should be called on the thread that created the
260 *               tray.
261 *
262 * \since This function is available since SDL 3.2.0.
263 *
264 * \sa SDL_InsertTrayEntryAt
265 * \sa SDL_GetTraySubmenu
266 * \sa SDL_GetTrayMenuParentEntry
267 */
268extern SDL_DECLSPEC SDL_TrayMenu * SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *entry);
269
270/**
271 * Gets a previously created tray menu.
272 *
273 * You should have called SDL_CreateTrayMenu() on the tray object. This
274 * function allows you to fetch it again later.
275 *
276 * This function does the same thing as SDL_GetTraySubmenu(), except that it
277 * takes a SDL_Tray instead of a SDL_TrayEntry.
278 *
279 * A menu does not need to be destroyed; it will be destroyed with the tray.
280 *
281 * \param tray the tray entry to bind the menu to.
282 * \returns the newly created menu.
283 *
284 * \threadsafety This function should be called on the thread that created the
285 *               tray.
286 *
287 * \since This function is available since SDL 3.2.0.
288 *
289 * \sa SDL_CreateTray
290 * \sa SDL_CreateTrayMenu
291 */
292extern SDL_DECLSPEC SDL_TrayMenu * SDLCALL SDL_GetTrayMenu(SDL_Tray *tray);
293
294/**
295 * Gets a previously created tray entry submenu.
296 *
297 * You should have called SDL_CreateTraySubmenu() on the entry object. This
298 * function allows you to fetch it again later.
299 *
300 * This function does the same thing as SDL_GetTrayMenu(), except that it
301 * takes a SDL_TrayEntry instead of a SDL_Tray.
302 *
303 * A menu does not need to be destroyed; it will be destroyed with the tray.
304 *
305 * \param entry the tray entry to bind the menu to.
306 * \returns the newly created menu.
307 *
308 * \threadsafety This function should be called on the thread that created the
309 *               tray.
310 *
311 * \since This function is available since SDL 3.2.0.
312 *
313 * \sa SDL_InsertTrayEntryAt
314 * \sa SDL_CreateTraySubmenu
315 */
316extern SDL_DECLSPEC SDL_TrayMenu * SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entry);
317
318/**
319 * Returns a list of entries in the menu, in order.
320 *
321 * \param menu The menu to get entries from.
322 * \param count An optional pointer to obtain the number of entries in the
323 *              menu.
324 * \returns a NULL-terminated list of entries within the given menu. The
325 *          pointer becomes invalid when any function that inserts or deletes
326 *          entries in the menu is called.
327 *
328 * \threadsafety This function should be called on the thread that created the
329 *               tray.
330 *
331 * \since This function is available since SDL 3.2.0.
332 *
333 * \sa SDL_RemoveTrayEntry
334 * \sa SDL_InsertTrayEntryAt
335 */
336extern SDL_DECLSPEC const SDL_TrayEntry ** SDLCALL SDL_GetTrayEntries(SDL_TrayMenu *menu, int *count);
337
338/**
339 * Removes a tray entry.
340 *
341 * \param entry The entry to be deleted.
342 *
343 * \threadsafety This function should be called on the thread that created the
344 *               tray.
345 *
346 * \since This function is available since SDL 3.2.0.
347 *
348 * \sa SDL_GetTrayEntries
349 * \sa SDL_InsertTrayEntryAt
350 */
351extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry);
352
353/**
354 * Insert a tray entry at a given position.
355 *
356 * If label is NULL, the entry will be a separator. Many functions won't work
357 * for an entry that is a separator.
358 *
359 * An entry does not need to be destroyed; it will be destroyed with the tray.
360 *
361 * \param menu the menu to append the entry to.
362 * \param pos the desired position for the new entry. Entries at or following
363 *            this place will be moved. If pos is -1, the entry is appended.
364 * \param label the text to be displayed on the entry, in UTF-8 encoding, or
365 *              NULL for a separator.
366 * \param flags a combination of flags, some of which are mandatory.
367 * \returns the newly created entry, or NULL if pos is out of bounds.
368 *
369 * \threadsafety This function should be called on the thread that created the
370 *               tray.
371 *
372 * \since This function is available since SDL 3.2.0.
373 *
374 * \sa SDL_TrayEntryFlags
375 * \sa SDL_GetTrayEntries
376 * \sa SDL_RemoveTrayEntry
377 * \sa SDL_GetTrayEntryParent
378 */
379extern SDL_DECLSPEC SDL_TrayEntry * SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *menu, int pos, const char *label, SDL_TrayEntryFlags flags);
380
381/**
382 * Sets the label of an entry.
383 *
384 * An entry cannot change between a separator and an ordinary entry; that is,
385 * it is not possible to set a non-NULL label on an entry that has a NULL
386 * label (separators), or to set a NULL label to an entry that has a non-NULL
387 * label. The function will silently fail if that happens.
388 *
389 * \param entry the entry to be updated.
390 * \param label the new label for the entry in UTF-8 encoding.
391 *
392 * \threadsafety This function should be called on the thread that created the
393 *               tray.
394 *
395 * \since This function is available since SDL 3.2.0.
396 *
397 * \sa SDL_GetTrayEntries
398 * \sa SDL_InsertTrayEntryAt
399 * \sa SDL_GetTrayEntryLabel
400 */
401extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, const char *label);
402
403/**
404 * Gets the label of an entry.
405 *
406 * If the returned value is NULL, the entry is a separator.
407 *
408 * \param entry the entry to be read.
409 * \returns the label of the entry in UTF-8 encoding.
410 *
411 * \threadsafety This function should be called on the thread that created the
412 *               tray.
413 *
414 * \since This function is available since SDL 3.2.0.
415 *
416 * \sa SDL_GetTrayEntries
417 * \sa SDL_InsertTrayEntryAt
418 * \sa SDL_SetTrayEntryLabel
419 */
420extern SDL_DECLSPEC const char * SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *entry);
421
422/**
423 * Sets whether or not an entry is checked.
424 *
425 * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.
426 *
427 * \param entry the entry to be updated.
428 * \param checked true if the entry should be checked; false otherwise.
429 *
430 * \threadsafety This function should be called on the thread that created the
431 *               tray.
432 *
433 * \since This function is available since SDL 3.2.0.
434 *
435 * \sa SDL_GetTrayEntries
436 * \sa SDL_InsertTrayEntryAt
437 * \sa SDL_GetTrayEntryChecked
438 */
439extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, bool checked);
440
441/**
442 * Gets whether or not an entry is checked.
443 *
444 * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag.
445 *
446 * \param entry the entry to be read.
447 * \returns true if the entry is checked; false otherwise.
448 *
449 * \threadsafety This function should be called on the thread that created the
450 *               tray.
451 *
452 * \since This function is available since SDL 3.2.0.
453 *
454 * \sa SDL_GetTrayEntries
455 * \sa SDL_InsertTrayEntryAt
456 * \sa SDL_SetTrayEntryChecked
457 */
458extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry);
459
460/**
461 * Sets whether or not an entry is enabled.
462 *
463 * \param entry the entry to be updated.
464 * \param enabled true if the entry should be enabled; false otherwise.
465 *
466 * \threadsafety This function should be called on the thread that created the
467 *               tray.
468 *
469 * \since This function is available since SDL 3.2.0.
470 *
471 * \sa SDL_GetTrayEntries
472 * \sa SDL_InsertTrayEntryAt
473 * \sa SDL_GetTrayEntryEnabled
474 */
475extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, bool enabled);
476
477/**
478 * Gets whether or not an entry is enabled.
479 *
480 * \param entry the entry to be read.
481 * \returns true if the entry is enabled; false otherwise.
482 *
483 * \threadsafety This function should be called on the thread that created the
484 *               tray.
485 *
486 * \since This function is available since SDL 3.2.0.
487 *
488 * \sa SDL_GetTrayEntries
489 * \sa SDL_InsertTrayEntryAt
490 * \sa SDL_SetTrayEntryEnabled
491 */
492extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry);
493
494/**
495 * Sets a callback to be invoked when the entry is selected.
496 *
497 * \param entry the entry to be updated.
498 * \param callback a callback to be invoked when the entry is selected.
499 * \param userdata an optional pointer to pass extra data to the callback when
500 *                 it will be invoked.
501 *
502 * \threadsafety This function should be called on the thread that created the
503 *               tray.
504 *
505 * \since This function is available since SDL 3.2.0.
506 *
507 * \sa SDL_GetTrayEntries
508 * \sa SDL_InsertTrayEntryAt
509 */
510extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, SDL_TrayCallback callback, void *userdata);
511
512/**
513 * Simulate a click on a tray entry.
514 *
515 * \param entry The entry to activate.
516 *
517 * \threadsafety This function should be called on the thread that created the
518 *               tray.
519 *
520 * \since This function is available since SDL 3.2.0.
521 */
522extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry);
523
524/**
525 * Destroys a tray object.
526 *
527 * This also destroys all associated menus and entries.
528 *
529 * \param tray the tray icon to be destroyed.
530 *
531 * \threadsafety This function should be called on the thread that created the
532 *               tray.
533 *
534 * \since This function is available since SDL 3.2.0.
535 *
536 * \sa SDL_CreateTray
537 */
538extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray);
539
540/**
541 * Gets the menu containing a certain tray entry.
542 *
543 * \param entry the entry for which to get the parent menu.
544 * \returns the parent menu.
545 *
546 * \threadsafety This function should be called on the thread that created the
547 *               tray.
548 *
549 * \since This function is available since SDL 3.2.0.
550 *
551 * \sa SDL_InsertTrayEntryAt
552 */
553extern SDL_DECLSPEC SDL_TrayMenu * SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *entry);
554
555/**
556 * Gets the entry for which the menu is a submenu, if the current menu is a
557 * submenu.
558 *
559 * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL
560 * for any given menu.
561 *
562 * \param menu the menu for which to get the parent entry.
563 * \returns the parent entry, or NULL if this menu is not a submenu.
564 *
565 * \threadsafety This function should be called on the thread that created the
566 *               tray.
567 *
568 * \since This function is available since SDL 3.2.0.
569 *
570 * \sa SDL_CreateTraySubmenu
571 * \sa SDL_GetTrayMenuParentTray
572 */
573extern SDL_DECLSPEC SDL_TrayEntry * SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMenu *menu);
574
575/**
576 * Gets the tray for which this menu is the first-level menu, if the current
577 * menu isn't a submenu.
578 *
579 * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL
580 * for any given menu.
581 *
582 * \param menu the menu for which to get the parent enttrayry.
583 * \returns the parent tray, or NULL if this menu is a submenu.
584 *
585 * \threadsafety This function should be called on the thread that created the
586 *               tray.
587 *
588 * \since This function is available since SDL 3.2.0.
589 *
590 * \sa SDL_CreateTrayMenu
591 * \sa SDL_GetTrayMenuParentEntry
592 */
593extern SDL_DECLSPEC SDL_Tray * SDLCALL SDL_GetTrayMenuParentTray(SDL_TrayMenu *menu);
594
595/**
596 * Update the trays.
597 *
598 * This is called automatically by the event loop and is only needed if you're
599 * using trays but aren't handling SDL events.
600 *
601 * \threadsafety This function should only be called on the main thread.
602 *
603 * \since This function is available since SDL 3.2.0.
604 */
605extern SDL_DECLSPEC void SDLCALL SDL_UpdateTrays(void);
606
607/* Ends C function definitions when using C++ */
608#ifdef __cplusplus
609}
610#endif
611#include <SDL3/SDL_close_code.h>
612
613#endif /* SDL_tray_h_ */
614
[FILE END]
(C) 2025 0x4248
(C) 2025 4248 Media and 4248 Systems, All part of 0x4248
See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.