sdl3/
hint.rs

1use crate::sys;
2use libc::c_char;
3use std::ffi::{CStr, CString};
4
5pub mod names;
6
7pub enum Hint {
8    Default,
9    Normal,
10    Override,
11}
12
13/// A hint that specifies whether a fullscreen [Window](../video/Window.t.html) will be
14/// minimized if key focus is lost.
15///
16/// [Official SDL documentation](https://wiki.libsdl.org/SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS)
17///
18/// # Default
19/// This is enabled by default.
20///
21/// # Example
22/// ```rust,no_run
23/// sdl3::hint::set_video_minimize_on_focus_loss(false);
24/// ```
25///
26/// * `value`: `true` to enable minimizing of the Window if it loses key focus when in fullscreen mode,
27///            `false` to disable this feature.
28pub fn set_video_minimize_on_focus_loss(value: bool) -> bool {
29    set(
30        names::VIDEO_MINIMIZE_ON_FOCUS_LOSS,
31        if value { "1" } else { "0" },
32    )
33}
34
35/// A hint that specifies whether a fullscreen [Window](../video/Window.t.html) will be
36/// minimized if key focus is lost.
37///
38/// [Official SDL documentation](https://wiki.libsdl.org/SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS)
39///
40/// # Example
41/// ```rust,no_run
42/// sdl3::hint::set_video_minimize_on_focus_loss_with_priority(false, &sdl3::hint::Hint::Override);
43/// ```
44///
45/// * `value`: `true` to enable minimizing of the Window if it loses key focus when in fullscreen mode,
46///            `false` to disable this feature.
47/// * `priority`: The priority controls the behavior when setting a hint that already has a value.
48///               Hints will replace existing hints of their priority and lower.
49///               Environment variables are considered to have override priority.
50pub fn set_video_minimize_on_focus_loss_with_priority(value: bool, priority: &Hint) -> bool {
51    set_with_priority(
52        names::VIDEO_MINIMIZE_ON_FOCUS_LOSS,
53        if value { "1" } else { "0" },
54        priority,
55    )
56}
57
58/// A hint that specifies whether a fullscreen [Window](../video/Window.t.html) will be
59/// minimized if key focus is lost.
60///
61/// [Official SDL documentation](https://wiki.libsdl.org/SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS)
62///
63/// # Default
64/// By default this will return `true`.
65///
66/// # Example
67/// ```rust,no_run
68/// assert_eq!(sdl3::hint::get_video_minimize_on_focus_loss(), true);
69///
70/// sdl3::hint::set_video_minimize_on_focus_loss(false);
71/// assert_eq!(sdl3::hint::get_video_minimize_on_focus_loss(), false);
72/// ```
73pub fn get_video_minimize_on_focus_loss() -> bool {
74    let Some(value) = get(names::VIDEO_MINIMIZE_ON_FOCUS_LOSS) else {
75        return true;
76    };
77    &*value == "1"
78}
79
80#[doc(alias = "SDL_SetHint")]
81pub fn set(name: &str, value: &str) -> bool {
82    let name = CString::new(name).unwrap();
83    let value = CString::new(value).unwrap();
84    unsafe {
85        sys::hints::SDL_SetHint(
86            name.as_ptr() as *const c_char,
87            value.as_ptr() as *const c_char,
88        )
89    }
90}
91
92#[doc(alias = "SDL_GetHint")]
93pub fn get(name: &str) -> Option<String> {
94    use std::str;
95
96    let name = CString::new(name).unwrap();
97
98    unsafe {
99        let res = sys::hints::SDL_GetHint(name.as_ptr() as *const c_char);
100
101        if res.is_null() {
102            None
103        } else {
104            Some(
105                str::from_utf8(CStr::from_ptr(res as *const _).to_bytes())
106                    .unwrap()
107                    .to_owned(),
108            )
109        }
110    }
111}
112
113#[doc(alias = "SDL_SetHintWithPriority")]
114pub fn set_with_priority(name: &str, value: &str, priority: &Hint) -> bool {
115    let name = CString::new(name).unwrap();
116    let value = CString::new(value).unwrap();
117
118    let priority_val = match *priority {
119        Hint::Normal => sys::hints::SDL_HINT_NORMAL,
120        Hint::Override => sys::hints::SDL_HINT_OVERRIDE,
121        Hint::Default => sys::hints::SDL_HINT_DEFAULT,
122    };
123
124    unsafe {
125        sys::hints::SDL_SetHintWithPriority(
126            name.as_ptr() as *const c_char,
127            value.as_ptr() as *const c_char,
128            priority_val,
129        )
130    }
131}
sdl3/hint.rs

sdl3/
hint.rs
