sdl3_sys/generated/
tray.rs

1//! SDL offers a way to add items to the "system tray" (more correctly called
2//! the "notification area" on Windows). On platforms that offer this concept,
3//! an SDL app can add a tray icon, submenus, checkboxes, and clickable
4//! entries, and register a callback that is fired when the user clicks on
5//! these pieces.
6
7use super::stdinc::*;
8
9use super::error::*;
10
11use super::surface::*;
12
13use super::video::*;
14
15/// Flags that control the creation of system tray entries.
16///
17/// Some of these flags are required; exactly one of them must be specified at
18/// the time a tray entry is created. Other flags are optional; zero or more of
19/// those can be OR'ed together with the required flag.
20///
21/// ## Availability
22/// This datatype is available since SDL 3.2.0.
23///
24/// ## See also
25/// - [`SDL_InsertTrayEntryAt`]
26///
27/// ## Known values (`sdl3-sys`)
28/// | Associated constant | Global constant | Description |
29/// | ------------------- | --------------- | ----------- |
30/// | [`BUTTON`](SDL_TrayEntryFlags::BUTTON) | [`SDL_TRAYENTRY_BUTTON`] | Make the entry a simple button. Required. |
31/// | [`CHECKBOX`](SDL_TrayEntryFlags::CHECKBOX) | [`SDL_TRAYENTRY_CHECKBOX`] | Make the entry a checkbox. Required. |
32/// | [`SUBMENU`](SDL_TrayEntryFlags::SUBMENU) | [`SDL_TRAYENTRY_SUBMENU`] | Prepare the entry to have a submenu. Required |
33/// | [`DISABLED`](SDL_TrayEntryFlags::DISABLED) | [`SDL_TRAYENTRY_DISABLED`] | Make the entry disabled. Optional. |
34/// | [`CHECKED`](SDL_TrayEntryFlags::CHECKED) | [`SDL_TRAYENTRY_CHECKED`] | Make the entry checked. This is valid only for checkboxes. Optional. |
35#[repr(transparent)]
36#[derive(Clone, Copy, Default, PartialEq, Eq, Hash)]
37pub struct SDL_TrayEntryFlags(pub Uint32);
38
39impl ::core::cmp::PartialEq<Uint32> for SDL_TrayEntryFlags {
40    #[inline(always)]
41    fn eq(&self, other: &Uint32) -> bool {
42        &self.0 == other
43    }
44}
45
46impl ::core::cmp::PartialEq<SDL_TrayEntryFlags> for Uint32 {
47    #[inline(always)]
48    fn eq(&self, other: &SDL_TrayEntryFlags) -> bool {
49        self == &other.0
50    }
51}
52
53impl From<SDL_TrayEntryFlags> for Uint32 {
54    #[inline(always)]
55    fn from(value: SDL_TrayEntryFlags) -> Self {
56        value.0
57    }
58}
59
60#[cfg(feature = "debug-impls")]
61impl ::core::fmt::Debug for SDL_TrayEntryFlags {
62    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
63        let mut first = true;
64        let all_bits = 0;
65        write!(f, "SDL_TrayEntryFlags(")?;
66        let all_bits = all_bits | Self::BUTTON.0;
67        if (Self::BUTTON != 0 || self.0 == 0) && *self & Self::BUTTON == Self::BUTTON {
68            if !first {
69                write!(f, " | ")?;
70            }
71            first = false;
72            write!(f, "BUTTON")?;
73        }
74        let all_bits = all_bits | Self::CHECKBOX.0;
75        if (Self::CHECKBOX != 0 || self.0 == 0) && *self & Self::CHECKBOX == Self::CHECKBOX {
76            if !first {
77                write!(f, " | ")?;
78            }
79            first = false;
80            write!(f, "CHECKBOX")?;
81        }
82        let all_bits = all_bits | Self::SUBMENU.0;
83        if (Self::SUBMENU != 0 || self.0 == 0) && *self & Self::SUBMENU == Self::SUBMENU {
84            if !first {
85                write!(f, " | ")?;
86            }
87            first = false;
88            write!(f, "SUBMENU")?;
89        }
90        let all_bits = all_bits | Self::DISABLED.0;
91        if (Self::DISABLED != 0 || self.0 == 0) && *self & Self::DISABLED == Self::DISABLED {
92            if !first {
93                write!(f, " | ")?;
94            }
95            first = false;
96            write!(f, "DISABLED")?;
97        }
98        let all_bits = all_bits | Self::CHECKED.0;
99        if (Self::CHECKED != 0 || self.0 == 0) && *self & Self::CHECKED == Self::CHECKED {
100            if !first {
101                write!(f, " | ")?;
102            }
103            first = false;
104            write!(f, "CHECKED")?;
105        }
106
107        if self.0 & !all_bits != 0 {
108            if !first {
109                write!(f, " | ")?;
110            }
111            write!(f, "{:#x}", self.0)?;
112        } else if first {
113            write!(f, "0")?;
114        }
115        write!(f, ")")
116    }
117}
118
119impl ::core::ops::BitAnd for SDL_TrayEntryFlags {
120    type Output = Self;
121
122    #[inline(always)]
123    fn bitand(self, rhs: Self) -> Self::Output {
124        Self(self.0 & rhs.0)
125    }
126}
127
128impl ::core::ops::BitAndAssign for SDL_TrayEntryFlags {
129    #[inline(always)]
130    fn bitand_assign(&mut self, rhs: Self) {
131        self.0 &= rhs.0;
132    }
133}
134
135impl ::core::ops::BitOr for SDL_TrayEntryFlags {
136    type Output = Self;
137
138    #[inline(always)]
139    fn bitor(self, rhs: Self) -> Self::Output {
140        Self(self.0 | rhs.0)
141    }
142}
143
144impl ::core::ops::BitOrAssign for SDL_TrayEntryFlags {
145    #[inline(always)]
146    fn bitor_assign(&mut self, rhs: Self) {
147        self.0 |= rhs.0;
148    }
149}
150
151impl ::core::ops::BitXor for SDL_TrayEntryFlags {
152    type Output = Self;
153
154    #[inline(always)]
155    fn bitxor(self, rhs: Self) -> Self::Output {
156        Self(self.0 ^ rhs.0)
157    }
158}
159
160impl ::core::ops::BitXorAssign for SDL_TrayEntryFlags {
161    #[inline(always)]
162    fn bitxor_assign(&mut self, rhs: Self) {
163        self.0 ^= rhs.0;
164    }
165}
166
167impl ::core::ops::Not for SDL_TrayEntryFlags {
168    type Output = Self;
169
170    #[inline(always)]
171    fn not(self) -> Self::Output {
172        Self(!self.0)
173    }
174}
175
176impl SDL_TrayEntryFlags {
177    /// Make the entry a simple button. Required.
178    pub const BUTTON: Self = Self((0x00000001 as Uint32));
179    /// Make the entry a checkbox. Required.
180    pub const CHECKBOX: Self = Self((0x00000002 as Uint32));
181    /// Prepare the entry to have a submenu. Required
182    pub const SUBMENU: Self = Self((0x00000004 as Uint32));
183    /// Make the entry disabled. Optional.
184    pub const DISABLED: Self = Self((0x80000000 as Uint32));
185    /// Make the entry checked. This is valid only for checkboxes. Optional.
186    pub const CHECKED: Self = Self((0x40000000 as Uint32));
187}
188
189/// Make the entry a simple button. Required.
190pub const SDL_TRAYENTRY_BUTTON: SDL_TrayEntryFlags = SDL_TrayEntryFlags::BUTTON;
191/// Make the entry a checkbox. Required.
192pub const SDL_TRAYENTRY_CHECKBOX: SDL_TrayEntryFlags = SDL_TrayEntryFlags::CHECKBOX;
193/// Prepare the entry to have a submenu. Required
194pub const SDL_TRAYENTRY_SUBMENU: SDL_TrayEntryFlags = SDL_TrayEntryFlags::SUBMENU;
195/// Make the entry disabled. Optional.
196pub const SDL_TRAYENTRY_DISABLED: SDL_TrayEntryFlags = SDL_TrayEntryFlags::DISABLED;
197/// Make the entry checked. This is valid only for checkboxes. Optional.
198pub const SDL_TRAYENTRY_CHECKED: SDL_TrayEntryFlags = SDL_TrayEntryFlags::CHECKED;
199
200#[cfg(feature = "metadata")]
201impl sdl3_sys::metadata::GroupMetadata for SDL_TrayEntryFlags {
202    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
203        &crate::metadata::tray::METADATA_SDL_TrayEntryFlags;
204}
205
206/// A callback that is invoked when a tray entry is selected.
207///
208/// ## Parameters
209/// - `userdata`: an optional pointer to pass extra data to the callback when
210///   it will be invoked.
211/// - `entry`: the tray entry that was selected.
212///
213/// ## Availability
214/// This datatype is available since SDL 3.2.0.
215///
216/// ## See also
217/// - [`SDL_SetTrayEntryCallback`]
218pub type SDL_TrayCallback = ::core::option::Option<
219    unsafe extern "C" fn(userdata: *mut ::core::ffi::c_void, entry: *mut SDL_TrayEntry),
220>;
221
222unsafe extern "C" {
223    /// Create an icon to be placed in the operating system's tray, or equivalent.
224    ///
225    /// Many platforms advise not using a system tray unless persistence is a
226    /// necessary feature. Avoid needlessly creating a tray icon, as the user may
227    /// feel like it clutters their interface.
228    ///
229    /// Using tray icons require the video subsystem.
230    ///
231    /// ## Parameters
232    /// - `icon`: a surface to be used as icon. May be NULL.
233    /// - `tooltip`: a tooltip to be displayed when the mouse hovers the icon in
234    ///   UTF-8 encoding. Not supported on all platforms. May be NULL.
235    ///
236    /// ## Return value
237    /// Returns The newly created system tray icon.
238    ///
239    /// ## Thread safety
240    /// This function should only be called on the main thread.
241    ///
242    /// ## Availability
243    /// This function is available since SDL 3.2.0.
244    ///
245    /// ## See also
246    /// - [`SDL_CreateTrayMenu`]
247    /// - [`SDL_GetTrayMenu`]
248    /// - [`SDL_DestroyTray`]
249    pub fn SDL_CreateTray(
250        icon: *mut SDL_Surface,
251        tooltip: *const ::core::ffi::c_char,
252    ) -> *mut SDL_Tray;
253}
254
255unsafe extern "C" {
256    /// Updates the system tray icon's icon.
257    ///
258    /// ## Parameters
259    /// - `tray`: the tray icon to be updated.
260    /// - `icon`: the new icon. May be NULL.
261    ///
262    /// ## Thread safety
263    /// This function should be called on the thread that created the
264    ///   tray.
265    ///
266    /// ## Availability
267    /// This function is available since SDL 3.2.0.
268    ///
269    /// ## See also
270    /// - [`SDL_CreateTray`]
271    pub fn SDL_SetTrayIcon(tray: *mut SDL_Tray, icon: *mut SDL_Surface);
272}
273
274unsafe extern "C" {
275    /// Updates the system tray icon's tooltip.
276    ///
277    /// ## Parameters
278    /// - `tray`: the tray icon to be updated.
279    /// - `tooltip`: the new tooltip in UTF-8 encoding. May be NULL.
280    ///
281    /// ## Thread safety
282    /// This function should be called on the thread that created the
283    ///   tray.
284    ///
285    /// ## Availability
286    /// This function is available since SDL 3.2.0.
287    ///
288    /// ## See also
289    /// - [`SDL_CreateTray`]
290    pub fn SDL_SetTrayTooltip(tray: *mut SDL_Tray, tooltip: *const ::core::ffi::c_char);
291}
292
293unsafe extern "C" {
294    /// Create a menu for a system tray.
295    ///
296    /// This should be called at most once per tray icon.
297    ///
298    /// This function does the same thing as [`SDL_CreateTraySubmenu()`], except that
299    /// it takes a [`SDL_Tray`] instead of a [`SDL_TrayEntry`].
300    ///
301    /// A menu does not need to be destroyed; it will be destroyed with the tray.
302    ///
303    /// ## Parameters
304    /// - `tray`: the tray to bind the menu to.
305    ///
306    /// ## Return value
307    /// Returns the newly created menu.
308    ///
309    /// ## Thread safety
310    /// This function should be called on the thread that created the
311    ///   tray.
312    ///
313    /// ## Availability
314    /// This function is available since SDL 3.2.0.
315    ///
316    /// ## See also
317    /// - [`SDL_CreateTray`]
318    /// - [`SDL_GetTrayMenu`]
319    /// - [`SDL_GetTrayMenuParentTray`]
320    pub fn SDL_CreateTrayMenu(tray: *mut SDL_Tray) -> *mut SDL_TrayMenu;
321}
322
323unsafe extern "C" {
324    /// Create a submenu for a system tray entry.
325    ///
326    /// This should be called at most once per tray entry.
327    ///
328    /// This function does the same thing as [`SDL_CreateTrayMenu`], except that it
329    /// takes a [`SDL_TrayEntry`] instead of a [`SDL_Tray`].
330    ///
331    /// A menu does not need to be destroyed; it will be destroyed with the tray.
332    ///
333    /// ## Parameters
334    /// - `entry`: the tray entry to bind the menu to.
335    ///
336    /// ## Return value
337    /// Returns the newly created menu.
338    ///
339    /// ## Thread safety
340    /// This function should be called on the thread that created the
341    ///   tray.
342    ///
343    /// ## Availability
344    /// This function is available since SDL 3.2.0.
345    ///
346    /// ## See also
347    /// - [`SDL_InsertTrayEntryAt`]
348    /// - [`SDL_GetTraySubmenu`]
349    /// - [`SDL_GetTrayMenuParentEntry`]
350    pub fn SDL_CreateTraySubmenu(entry: *mut SDL_TrayEntry) -> *mut SDL_TrayMenu;
351}
352
353unsafe extern "C" {
354    /// Gets a previously created tray menu.
355    ///
356    /// You should have called [`SDL_CreateTrayMenu()`] on the tray object. This
357    /// function allows you to fetch it again later.
358    ///
359    /// This function does the same thing as [`SDL_GetTraySubmenu()`], except that it
360    /// takes a [`SDL_Tray`] instead of a [`SDL_TrayEntry`].
361    ///
362    /// A menu does not need to be destroyed; it will be destroyed with the tray.
363    ///
364    /// ## Parameters
365    /// - `tray`: the tray entry to bind the menu to.
366    ///
367    /// ## Return value
368    /// Returns the newly created menu.
369    ///
370    /// ## Thread safety
371    /// This function should be called on the thread that created the
372    ///   tray.
373    ///
374    /// ## Availability
375    /// This function is available since SDL 3.2.0.
376    ///
377    /// ## See also
378    /// - [`SDL_CreateTray`]
379    /// - [`SDL_CreateTrayMenu`]
380    pub fn SDL_GetTrayMenu(tray: *mut SDL_Tray) -> *mut SDL_TrayMenu;
381}
382
383unsafe extern "C" {
384    /// Gets a previously created tray entry submenu.
385    ///
386    /// You should have called [`SDL_CreateTraySubmenu()`] on the entry object. This
387    /// function allows you to fetch it again later.
388    ///
389    /// This function does the same thing as [`SDL_GetTrayMenu()`], except that it
390    /// takes a [`SDL_TrayEntry`] instead of a [`SDL_Tray`].
391    ///
392    /// A menu does not need to be destroyed; it will be destroyed with the tray.
393    ///
394    /// ## Parameters
395    /// - `entry`: the tray entry to bind the menu to.
396    ///
397    /// ## Return value
398    /// Returns the newly created menu.
399    ///
400    /// ## Thread safety
401    /// This function should be called on the thread that created the
402    ///   tray.
403    ///
404    /// ## Availability
405    /// This function is available since SDL 3.2.0.
406    ///
407    /// ## See also
408    /// - [`SDL_InsertTrayEntryAt`]
409    /// - [`SDL_CreateTraySubmenu`]
410    pub fn SDL_GetTraySubmenu(entry: *mut SDL_TrayEntry) -> *mut SDL_TrayMenu;
411}
412
413unsafe extern "C" {
414    /// Returns a list of entries in the menu, in order.
415    ///
416    /// ## Parameters
417    /// - `menu`: The menu to get entries from.
418    /// - `count`: An optional pointer to obtain the number of entries in the
419    ///   menu.
420    ///
421    /// ## Return value
422    /// Returns a NULL-terminated list of entries within the given menu. The
423    ///   pointer becomes invalid when any function that inserts or deletes
424    ///   entries in the menu is called.
425    ///
426    /// ## Thread safety
427    /// This function should be called on the thread that created the
428    ///   tray.
429    ///
430    /// ## Availability
431    /// This function is available since SDL 3.2.0.
432    ///
433    /// ## See also
434    /// - [`SDL_RemoveTrayEntry`]
435    /// - [`SDL_InsertTrayEntryAt`]
436    pub fn SDL_GetTrayEntries(
437        menu: *mut SDL_TrayMenu,
438        count: *mut ::core::ffi::c_int,
439    ) -> *mut *const SDL_TrayEntry;
440}
441
442unsafe extern "C" {
443    /// Removes a tray entry.
444    ///
445    /// ## Parameters
446    /// - `entry`: The entry to be deleted.
447    ///
448    /// ## Thread safety
449    /// This function should be called on the thread that created the
450    ///   tray.
451    ///
452    /// ## Availability
453    /// This function is available since SDL 3.2.0.
454    ///
455    /// ## See also
456    /// - [`SDL_GetTrayEntries`]
457    /// - [`SDL_InsertTrayEntryAt`]
458    pub fn SDL_RemoveTrayEntry(entry: *mut SDL_TrayEntry);
459}
460
461unsafe extern "C" {
462    /// Insert a tray entry at a given position.
463    ///
464    /// If label is NULL, the entry will be a separator. Many functions won't work
465    /// for an entry that is a separator.
466    ///
467    /// An entry does not need to be destroyed; it will be destroyed with the tray.
468    ///
469    /// ## Parameters
470    /// - `menu`: the menu to append the entry to.
471    /// - `pos`: the desired position for the new entry. Entries at or following
472    ///   this place will be moved. If pos is -1, the entry is appended.
473    /// - `label`: the text to be displayed on the entry, in UTF-8 encoding, or
474    ///   NULL for a separator.
475    /// - `flags`: a combination of flags, some of which are mandatory.
476    ///
477    /// ## Return value
478    /// Returns the newly created entry, or NULL if pos is out of bounds.
479    ///
480    /// ## Thread safety
481    /// This function should be called on the thread that created the
482    ///   tray.
483    ///
484    /// ## Availability
485    /// This function is available since SDL 3.2.0.
486    ///
487    /// ## See also
488    /// - [`SDL_TrayEntryFlags`]
489    /// - [`SDL_GetTrayEntries`]
490    /// - [`SDL_RemoveTrayEntry`]
491    /// - [`SDL_GetTrayEntryParent`]
492    pub fn SDL_InsertTrayEntryAt(
493        menu: *mut SDL_TrayMenu,
494        pos: ::core::ffi::c_int,
495        label: *const ::core::ffi::c_char,
496        flags: SDL_TrayEntryFlags,
497    ) -> *mut SDL_TrayEntry;
498}
499
500unsafe extern "C" {
501    /// Sets the label of an entry.
502    ///
503    /// An entry cannot change between a separator and an ordinary entry; that is,
504    /// it is not possible to set a non-NULL label on an entry that has a NULL
505    /// label (separators), or to set a NULL label to an entry that has a non-NULL
506    /// label. The function will silently fail if that happens.
507    ///
508    /// ## Parameters
509    /// - `entry`: the entry to be updated.
510    /// - `label`: the new label for the entry in UTF-8 encoding.
511    ///
512    /// ## Thread safety
513    /// This function should be called on the thread that created the
514    ///   tray.
515    ///
516    /// ## Availability
517    /// This function is available since SDL 3.2.0.
518    ///
519    /// ## See also
520    /// - [`SDL_GetTrayEntries`]
521    /// - [`SDL_InsertTrayEntryAt`]
522    /// - [`SDL_GetTrayEntryLabel`]
523    pub fn SDL_SetTrayEntryLabel(entry: *mut SDL_TrayEntry, label: *const ::core::ffi::c_char);
524}
525
526unsafe extern "C" {
527    /// Gets the label of an entry.
528    ///
529    /// If the returned value is NULL, the entry is a separator.
530    ///
531    /// ## Parameters
532    /// - `entry`: the entry to be read.
533    ///
534    /// ## Return value
535    /// Returns the label of the entry in UTF-8 encoding.
536    ///
537    /// ## Thread safety
538    /// This function should be called on the thread that created the
539    ///   tray.
540    ///
541    /// ## Availability
542    /// This function is available since SDL 3.2.0.
543    ///
544    /// ## See also
545    /// - [`SDL_GetTrayEntries`]
546    /// - [`SDL_InsertTrayEntryAt`]
547    /// - [`SDL_SetTrayEntryLabel`]
548    pub fn SDL_GetTrayEntryLabel(entry: *mut SDL_TrayEntry) -> *const ::core::ffi::c_char;
549}
550
551unsafe extern "C" {
552    /// Sets whether or not an entry is checked.
553    ///
554    /// The entry must have been created with the [`SDL_TRAYENTRY_CHECKBOX`] flag.
555    ///
556    /// ## Parameters
557    /// - `entry`: the entry to be updated.
558    /// - `checked`: true if the entry should be checked; false otherwise.
559    ///
560    /// ## Thread safety
561    /// This function should be called on the thread that created the
562    ///   tray.
563    ///
564    /// ## Availability
565    /// This function is available since SDL 3.2.0.
566    ///
567    /// ## See also
568    /// - [`SDL_GetTrayEntries`]
569    /// - [`SDL_InsertTrayEntryAt`]
570    /// - [`SDL_GetTrayEntryChecked`]
571    pub fn SDL_SetTrayEntryChecked(entry: *mut SDL_TrayEntry, checked: ::core::primitive::bool);
572}
573
574unsafe extern "C" {
575    /// Gets whether or not an entry is checked.
576    ///
577    /// The entry must have been created with the [`SDL_TRAYENTRY_CHECKBOX`] flag.
578    ///
579    /// ## Parameters
580    /// - `entry`: the entry to be read.
581    ///
582    /// ## Return value
583    /// Returns true if the entry is checked; false otherwise.
584    ///
585    /// ## Thread safety
586    /// This function should be called on the thread that created the
587    ///   tray.
588    ///
589    /// ## Availability
590    /// This function is available since SDL 3.2.0.
591    ///
592    /// ## See also
593    /// - [`SDL_GetTrayEntries`]
594    /// - [`SDL_InsertTrayEntryAt`]
595    /// - [`SDL_SetTrayEntryChecked`]
596    pub fn SDL_GetTrayEntryChecked(entry: *mut SDL_TrayEntry) -> ::core::primitive::bool;
597}
598
599unsafe extern "C" {
600    /// Sets whether or not an entry is enabled.
601    ///
602    /// ## Parameters
603    /// - `entry`: the entry to be updated.
604    /// - `enabled`: true if the entry should be enabled; false otherwise.
605    ///
606    /// ## Thread safety
607    /// This function should be called on the thread that created the
608    ///   tray.
609    ///
610    /// ## Availability
611    /// This function is available since SDL 3.2.0.
612    ///
613    /// ## See also
614    /// - [`SDL_GetTrayEntries`]
615    /// - [`SDL_InsertTrayEntryAt`]
616    /// - [`SDL_GetTrayEntryEnabled`]
617    pub fn SDL_SetTrayEntryEnabled(entry: *mut SDL_TrayEntry, enabled: ::core::primitive::bool);
618}
619
620unsafe extern "C" {
621    /// Gets whether or not an entry is enabled.
622    ///
623    /// ## Parameters
624    /// - `entry`: the entry to be read.
625    ///
626    /// ## Return value
627    /// Returns true if the entry is enabled; false otherwise.
628    ///
629    /// ## Thread safety
630    /// This function should be called on the thread that created the
631    ///   tray.
632    ///
633    /// ## Availability
634    /// This function is available since SDL 3.2.0.
635    ///
636    /// ## See also
637    /// - [`SDL_GetTrayEntries`]
638    /// - [`SDL_InsertTrayEntryAt`]
639    /// - [`SDL_SetTrayEntryEnabled`]
640    pub fn SDL_GetTrayEntryEnabled(entry: *mut SDL_TrayEntry) -> ::core::primitive::bool;
641}
642
643unsafe extern "C" {
644    /// Sets a callback to be invoked when the entry is selected.
645    ///
646    /// ## Parameters
647    /// - `entry`: the entry to be updated.
648    /// - `callback`: a callback to be invoked when the entry is selected.
649    /// - `userdata`: an optional pointer to pass extra data to the callback when
650    ///   it will be invoked.
651    ///
652    /// ## Thread safety
653    /// This function should be called on the thread that created the
654    ///   tray.
655    ///
656    /// ## Availability
657    /// This function is available since SDL 3.2.0.
658    ///
659    /// ## See also
660    /// - [`SDL_GetTrayEntries`]
661    /// - [`SDL_InsertTrayEntryAt`]
662    pub fn SDL_SetTrayEntryCallback(
663        entry: *mut SDL_TrayEntry,
664        callback: SDL_TrayCallback,
665        userdata: *mut ::core::ffi::c_void,
666    );
667}
668
669unsafe extern "C" {
670    /// Simulate a click on a tray entry.
671    ///
672    /// ## Parameters
673    /// - `entry`: The entry to activate.
674    ///
675    /// ## Thread safety
676    /// This function should be called on the thread that created the
677    ///   tray.
678    ///
679    /// ## Availability
680    /// This function is available since SDL 3.2.0.
681    pub fn SDL_ClickTrayEntry(entry: *mut SDL_TrayEntry);
682}
683
684unsafe extern "C" {
685    /// Destroys a tray object.
686    ///
687    /// This also destroys all associated menus and entries.
688    ///
689    /// ## Parameters
690    /// - `tray`: the tray icon to be destroyed.
691    ///
692    /// ## Thread safety
693    /// This function should be called on the thread that created the
694    ///   tray.
695    ///
696    /// ## Availability
697    /// This function is available since SDL 3.2.0.
698    ///
699    /// ## See also
700    /// - [`SDL_CreateTray`]
701    pub fn SDL_DestroyTray(tray: *mut SDL_Tray);
702}
703
704unsafe extern "C" {
705    /// Gets the menu containing a certain tray entry.
706    ///
707    /// ## Parameters
708    /// - `entry`: the entry for which to get the parent menu.
709    ///
710    /// ## Return value
711    /// Returns the parent menu.
712    ///
713    /// ## Thread safety
714    /// This function should be called on the thread that created the
715    ///   tray.
716    ///
717    /// ## Availability
718    /// This function is available since SDL 3.2.0.
719    ///
720    /// ## See also
721    /// - [`SDL_InsertTrayEntryAt`]
722    pub fn SDL_GetTrayEntryParent(entry: *mut SDL_TrayEntry) -> *mut SDL_TrayMenu;
723}
724
725unsafe extern "C" {
726    /// Gets the entry for which the menu is a submenu, if the current menu is a
727    /// submenu.
728    ///
729    /// Either this function or [`SDL_GetTrayMenuParentTray()`] will return non-NULL
730    /// for any given menu.
731    ///
732    /// ## Parameters
733    /// - `menu`: the menu for which to get the parent entry.
734    ///
735    /// ## Return value
736    /// Returns the parent entry, or NULL if this menu is not a submenu.
737    ///
738    /// ## Thread safety
739    /// This function should be called on the thread that created the
740    ///   tray.
741    ///
742    /// ## Availability
743    /// This function is available since SDL 3.2.0.
744    ///
745    /// ## See also
746    /// - [`SDL_CreateTraySubmenu`]
747    /// - [`SDL_GetTrayMenuParentTray`]
748    pub fn SDL_GetTrayMenuParentEntry(menu: *mut SDL_TrayMenu) -> *mut SDL_TrayEntry;
749}
750
751unsafe extern "C" {
752    /// Gets the tray for which this menu is the first-level menu, if the current
753    /// menu isn't a submenu.
754    ///
755    /// Either this function or [`SDL_GetTrayMenuParentEntry()`] will return non-NULL
756    /// for any given menu.
757    ///
758    /// ## Parameters
759    /// - `menu`: the menu for which to get the parent enttrayry.
760    ///
761    /// ## Return value
762    /// Returns the parent tray, or NULL if this menu is a submenu.
763    ///
764    /// ## Thread safety
765    /// This function should be called on the thread that created the
766    ///   tray.
767    ///
768    /// ## Availability
769    /// This function is available since SDL 3.2.0.
770    ///
771    /// ## See also
772    /// - [`SDL_CreateTrayMenu`]
773    /// - [`SDL_GetTrayMenuParentEntry`]
774    pub fn SDL_GetTrayMenuParentTray(menu: *mut SDL_TrayMenu) -> *mut SDL_Tray;
775}
776
777unsafe extern "C" {
778    /// Update the trays.
779    ///
780    /// This is called automatically by the event loop and is only needed if you're
781    /// using trays but aren't handling SDL events.
782    ///
783    /// ## Thread safety
784    /// This function should only be called on the main thread.
785    ///
786    /// ## Availability
787    /// This function is available since SDL 3.2.0.
788    pub fn SDL_UpdateTrays();
789}
790
791/// An opaque handle representing a toplevel system tray object.
792///
793/// ## Availability
794/// This struct is available since SDL 3.2.0.
795#[repr(C)]
796pub struct SDL_Tray {
797    _opaque: [::core::primitive::u8; 0],
798}
799
800/// An opaque handle representing an entry on a system tray object.
801///
802/// ## Availability
803/// This struct is available since SDL 3.2.0.
804#[repr(C)]
805pub struct SDL_TrayEntry {
806    _opaque: [::core::primitive::u8; 0],
807}
808
809/// An opaque handle representing a menu/submenu on a system tray object.
810///
811/// ## Availability
812/// This struct is available since SDL 3.2.0.
813#[repr(C)]
814pub struct SDL_TrayMenu {
815    _opaque: [::core::primitive::u8; 0],
816}
817
818#[cfg(doc)]
819use crate::everything::*;
sdl3_sys/generated/tray.rs

sdl3_sys/generated/
tray.rs
