imgui/input/
keyboard.rs

1use crate::sys;
2use crate::Ui;
3
4/// A key identifier
5#[repr(u32)]
6#[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
7#[allow(missing_docs)] // Self-describing
8#[non_exhaustive]
9pub enum Key {
10    Tab = sys::ImGuiKey_Tab,
11    LeftArrow = sys::ImGuiKey_LeftArrow,
12    RightArrow = sys::ImGuiKey_RightArrow,
13    UpArrow = sys::ImGuiKey_UpArrow,
14    DownArrow = sys::ImGuiKey_DownArrow,
15    PageUp = sys::ImGuiKey_PageUp,
16    PageDown = sys::ImGuiKey_PageDown,
17    Home = sys::ImGuiKey_Home,
18    End = sys::ImGuiKey_End,
19    Insert = sys::ImGuiKey_Insert,
20    Delete = sys::ImGuiKey_Delete,
21    Backspace = sys::ImGuiKey_Backspace,
22    Space = sys::ImGuiKey_Space,
23    Enter = sys::ImGuiKey_Enter,
24    Escape = sys::ImGuiKey_Escape,
25    LeftCtrl = sys::ImGuiKey_LeftCtrl,
26    LeftShift = sys::ImGuiKey_LeftShift,
27    LeftAlt = sys::ImGuiKey_LeftAlt,
28    LeftSuper = sys::ImGuiKey_LeftSuper,
29    RightCtrl = sys::ImGuiKey_RightCtrl,
30    RightShift = sys::ImGuiKey_RightShift,
31    RightAlt = sys::ImGuiKey_RightAlt,
32    RightSuper = sys::ImGuiKey_RightSuper,
33    Menu = sys::ImGuiKey_Menu,
34    Alpha0 = sys::ImGuiKey_0,
35    Alpha1 = sys::ImGuiKey_1,
36    Alpha2 = sys::ImGuiKey_2,
37    Alpha3 = sys::ImGuiKey_3,
38    Alpha4 = sys::ImGuiKey_4,
39    Alpha5 = sys::ImGuiKey_5,
40    Alpha6 = sys::ImGuiKey_6,
41    Alpha7 = sys::ImGuiKey_7,
42    Alpha8 = sys::ImGuiKey_8,
43    Alpha9 = sys::ImGuiKey_9,
44    A = sys::ImGuiKey_A,
45    B = sys::ImGuiKey_B,
46    C = sys::ImGuiKey_C,
47    D = sys::ImGuiKey_D,
48    E = sys::ImGuiKey_E,
49    F = sys::ImGuiKey_F,
50    G = sys::ImGuiKey_G,
51    H = sys::ImGuiKey_H,
52    I = sys::ImGuiKey_I,
53    J = sys::ImGuiKey_J,
54    K = sys::ImGuiKey_K,
55    L = sys::ImGuiKey_L,
56    M = sys::ImGuiKey_M,
57    N = sys::ImGuiKey_N,
58    O = sys::ImGuiKey_O,
59    P = sys::ImGuiKey_P,
60    Q = sys::ImGuiKey_Q,
61    R = sys::ImGuiKey_R,
62    S = sys::ImGuiKey_S,
63    T = sys::ImGuiKey_T,
64    U = sys::ImGuiKey_U,
65    V = sys::ImGuiKey_V,
66    W = sys::ImGuiKey_W,
67    X = sys::ImGuiKey_X,
68    Y = sys::ImGuiKey_Y,
69    Z = sys::ImGuiKey_Z,
70    F1 = sys::ImGuiKey_F1,
71    F2 = sys::ImGuiKey_F2,
72    F3 = sys::ImGuiKey_F3,
73    F4 = sys::ImGuiKey_F4,
74    F5 = sys::ImGuiKey_F5,
75    F6 = sys::ImGuiKey_F6,
76    F7 = sys::ImGuiKey_F7,
77    F8 = sys::ImGuiKey_F8,
78    F9 = sys::ImGuiKey_F9,
79    F10 = sys::ImGuiKey_F10,
80    F11 = sys::ImGuiKey_F11,
81    F12 = sys::ImGuiKey_F12,
82    Apostrophe = sys::ImGuiKey_Apostrophe,
83    Comma = sys::ImGuiKey_Comma,
84    Minus = sys::ImGuiKey_Minus,
85    Period = sys::ImGuiKey_Period,
86    Slash = sys::ImGuiKey_Slash,
87    Semicolon = sys::ImGuiKey_Semicolon,
88    Equal = sys::ImGuiKey_Equal,
89    LeftBracket = sys::ImGuiKey_LeftBracket,
90    Backslash = sys::ImGuiKey_Backslash,
91    RightBracket = sys::ImGuiKey_RightBracket,
92    GraveAccent = sys::ImGuiKey_GraveAccent,
93    CapsLock = sys::ImGuiKey_CapsLock,
94    ScrollLock = sys::ImGuiKey_ScrollLock,
95    NumLock = sys::ImGuiKey_NumLock,
96    PrintScreen = sys::ImGuiKey_PrintScreen,
97    Pause = sys::ImGuiKey_Pause,
98    Keypad0 = sys::ImGuiKey_Keypad0,
99    Keypad1 = sys::ImGuiKey_Keypad1,
100    Keypad2 = sys::ImGuiKey_Keypad2,
101    Keypad3 = sys::ImGuiKey_Keypad3,
102    Keypad4 = sys::ImGuiKey_Keypad4,
103    Keypad5 = sys::ImGuiKey_Keypad5,
104    Keypad6 = sys::ImGuiKey_Keypad6,
105    Keypad7 = sys::ImGuiKey_Keypad7,
106    Keypad8 = sys::ImGuiKey_Keypad8,
107    Keypad9 = sys::ImGuiKey_Keypad9,
108    KeypadDecimal = sys::ImGuiKey_KeypadDecimal,
109    KeypadDivide = sys::ImGuiKey_KeypadDivide,
110    KeypadMultiply = sys::ImGuiKey_KeypadMultiply,
111    KeypadSubtract = sys::ImGuiKey_KeypadSubtract,
112    KeypadAdd = sys::ImGuiKey_KeypadAdd,
113    KeypadEnter = sys::ImGuiKey_KeypadEnter,
114    KeypadEqual = sys::ImGuiKey_KeypadEqual,
115    GamepadStart = sys::ImGuiKey_GamepadStart,
116    GamepadBack = sys::ImGuiKey_GamepadBack,
117    GamepadFaceLeft = sys::ImGuiKey_GamepadFaceLeft,
118    GamepadFaceRight = sys::ImGuiKey_GamepadFaceRight,
119    GamepadFaceUp = sys::ImGuiKey_GamepadFaceUp,
120    GamepadFaceDown = sys::ImGuiKey_GamepadFaceDown,
121    GamepadDpadLeft = sys::ImGuiKey_GamepadDpadLeft,
122    GamepadDpadRight = sys::ImGuiKey_GamepadDpadRight,
123    GamepadDpadUp = sys::ImGuiKey_GamepadDpadUp,
124    GamepadDpadDown = sys::ImGuiKey_GamepadDpadDown,
125    GamepadL1 = sys::ImGuiKey_GamepadL1,
126    GamepadR1 = sys::ImGuiKey_GamepadR1,
127    GamepadL2 = sys::ImGuiKey_GamepadL2,
128    GamepadR2 = sys::ImGuiKey_GamepadR2,
129    GamepadL3 = sys::ImGuiKey_GamepadL3,
130    GamepadR3 = sys::ImGuiKey_GamepadR3,
131    GamepadLStickLeft = sys::ImGuiKey_GamepadLStickLeft,
132    GamepadLStickRight = sys::ImGuiKey_GamepadLStickRight,
133    GamepadLStickUp = sys::ImGuiKey_GamepadLStickUp,
134    GamepadLStickDown = sys::ImGuiKey_GamepadLStickDown,
135    GamepadRStickLeft = sys::ImGuiKey_GamepadRStickLeft,
136    GamepadRStickRight = sys::ImGuiKey_GamepadRStickRight,
137    GamepadRStickUp = sys::ImGuiKey_GamepadRStickUp,
138    GamepadRStickDown = sys::ImGuiKey_GamepadRStickDown,
139    MouseLeft = sys::ImGuiKey_MouseLeft,
140    MouseRight = sys::ImGuiKey_MouseRight,
141    MouseMiddle = sys::ImGuiKey_MouseMiddle,
142    MouseX1 = sys::ImGuiKey_MouseX1,
143    MouseX2 = sys::ImGuiKey_MouseX2,
144    MouseWheelX = sys::ImGuiKey_MouseWheelX,
145    MouseWheelY = sys::ImGuiKey_MouseWheelY,
146    ReservedForModCtrl = sys::ImGuiKey_ReservedForModCtrl,
147    ReservedForModShift = sys::ImGuiKey_ReservedForModShift,
148    ReservedForModAlt = sys::ImGuiKey_ReservedForModAlt,
149    ReservedForModSuper = sys::ImGuiKey_ReservedForModSuper,
150    ModCtrl = sys::ImGuiMod_Ctrl,
151    ModShift = sys::ImGuiMod_Shift,
152    ModAlt = sys::ImGuiMod_Alt,
153    ModSuper = sys::ImGuiMod_Super,
154    ModShortcut = sys::ImGuiMod_Shortcut,
155}
156
157impl Key {
158    /// All possible `Key` variants
159    pub const VARIANTS: [Key; Key::COUNT] = [
160        Key::Tab,
161        Key::LeftArrow,
162        Key::RightArrow,
163        Key::UpArrow,
164        Key::DownArrow,
165        Key::PageUp,
166        Key::PageDown,
167        Key::Home,
168        Key::End,
169        Key::Insert,
170        Key::Delete,
171        Key::Backspace,
172        Key::Space,
173        Key::Enter,
174        Key::Escape,
175        Key::LeftCtrl,
176        Key::LeftShift,
177        Key::LeftAlt,
178        Key::LeftSuper,
179        Key::RightCtrl,
180        Key::RightShift,
181        Key::RightAlt,
182        Key::RightSuper,
183        Key::Menu,
184        Key::Alpha0,
185        Key::Alpha1,
186        Key::Alpha2,
187        Key::Alpha3,
188        Key::Alpha4,
189        Key::Alpha5,
190        Key::Alpha6,
191        Key::Alpha7,
192        Key::Alpha8,
193        Key::Alpha9,
194        Key::A,
195        Key::B,
196        Key::C,
197        Key::D,
198        Key::E,
199        Key::F,
200        Key::G,
201        Key::H,
202        Key::I,
203        Key::J,
204        Key::K,
205        Key::L,
206        Key::M,
207        Key::N,
208        Key::O,
209        Key::P,
210        Key::Q,
211        Key::R,
212        Key::S,
213        Key::T,
214        Key::U,
215        Key::V,
216        Key::W,
217        Key::X,
218        Key::Y,
219        Key::Z,
220        Key::F1,
221        Key::F2,
222        Key::F3,
223        Key::F4,
224        Key::F5,
225        Key::F6,
226        Key::F7,
227        Key::F8,
228        Key::F9,
229        Key::F10,
230        Key::F11,
231        Key::F12,
232        Key::Apostrophe,
233        Key::Comma,
234        Key::Minus,
235        Key::Period,
236        Key::Slash,
237        Key::Semicolon,
238        Key::Equal,
239        Key::LeftBracket,
240        Key::Backslash,
241        Key::RightBracket,
242        Key::GraveAccent,
243        Key::CapsLock,
244        Key::ScrollLock,
245        Key::NumLock,
246        Key::PrintScreen,
247        Key::Pause,
248        Key::Keypad0,
249        Key::Keypad1,
250        Key::Keypad2,
251        Key::Keypad3,
252        Key::Keypad4,
253        Key::Keypad5,
254        Key::Keypad6,
255        Key::Keypad7,
256        Key::Keypad8,
257        Key::Keypad9,
258        Key::KeypadDecimal,
259        Key::KeypadDivide,
260        Key::KeypadMultiply,
261        Key::KeypadSubtract,
262        Key::KeypadAdd,
263        Key::KeypadEnter,
264        Key::KeypadEqual,
265        Key::GamepadStart,
266        Key::GamepadBack,
267        Key::GamepadFaceLeft,
268        Key::GamepadFaceRight,
269        Key::GamepadFaceUp,
270        Key::GamepadFaceDown,
271        Key::GamepadDpadLeft,
272        Key::GamepadDpadRight,
273        Key::GamepadDpadUp,
274        Key::GamepadDpadDown,
275        Key::GamepadL1,
276        Key::GamepadR1,
277        Key::GamepadL2,
278        Key::GamepadR2,
279        Key::GamepadL3,
280        Key::GamepadR3,
281        Key::GamepadLStickLeft,
282        Key::GamepadLStickRight,
283        Key::GamepadLStickUp,
284        Key::GamepadLStickDown,
285        Key::GamepadRStickLeft,
286        Key::GamepadRStickRight,
287        Key::GamepadRStickUp,
288        Key::GamepadRStickDown,
289        Key::MouseLeft,
290        Key::MouseRight,
291        Key::MouseMiddle,
292        Key::MouseX1,
293        Key::MouseX2,
294        Key::MouseWheelX,
295        Key::MouseWheelY,
296        Key::ReservedForModCtrl,
297        Key::ReservedForModShift,
298        Key::ReservedForModAlt,
299        Key::ReservedForModSuper,
300    ];
301    /// Total count of `Key` variants
302    pub const COUNT: usize = sys::ImGuiKey_NamedKey_COUNT as usize;
303}
304
305/// Target widget selection for keyboard focus
306#[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
307pub enum FocusedWidget {
308    /// Previous widget
309    Previous,
310    /// Next widget
311    Next,
312    /// Widget using a relative positive offset (0 is the next widget).
313    ///
314    /// Use this to access sub components of a multiple component widget.
315    Offset(u32),
316}
317
318impl FocusedWidget {
319    #[inline]
320    fn as_offset(self) -> i32 {
321        match self {
322            FocusedWidget::Previous => -1,
323            FocusedWidget::Next => 0,
324            FocusedWidget::Offset(offset) => offset as i32,
325        }
326    }
327}
328
329/// # Input: Keyboard
330impl Ui {
331    /// Returns the key index of the given key identifier.
332    ///
333    /// Equivalent to indexing the Io struct `key_map` field: `ui.io().key_map[key]`
334    #[inline]
335    #[doc(alias = "GetKeyIndex")]
336    fn key_index(&self, key: Key) -> u32 {
337        unsafe { sys::igGetKeyIndex(key as u32) }
338    }
339    /// Returns true if the key is being held.
340    ///
341    /// Equivalent to indexing the Io struct `keys_down` field: `ui.io().keys_down[key_index]`
342    #[inline]
343    #[doc(alias = "IsKeyDown")]
344    pub fn is_key_down(&self, key: Key) -> bool {
345        let key_index = self.key_index(key);
346        self.is_key_index_down(key_index)
347    }
348
349    /// Same as [`is_key_down`](Self::is_key_down) but takes a key index. The meaning of
350    /// index is defined by your backend implementation.
351    #[inline]
352    #[doc(alias = "IsKeyDown")]
353    pub fn is_key_index_down(&self, key_index: u32) -> bool {
354        cfg_if::cfg_if! {
355            if #[cfg(feature = "docking")] {
356                unsafe { sys::igIsKeyDown_Nil(key_index) }
357            } else {
358                unsafe { sys::igIsKeyDown(key_index) }
359            }
360        }
361    }
362
363    /// Returns true if the key was pressed (went from !down to down).
364    ///
365    /// Affected by key repeat settings (`io.key_repeat_delay`, `io.key_repeat_rate`)
366    #[inline]
367    #[doc(alias = "IsKeyPressed")]
368    pub fn is_key_pressed(&self, key: Key) -> bool {
369        let key_index = self.key_index(key);
370        self.is_key_index_pressed(key_index)
371    }
372
373    /// Same as [`is_key_pressed`](Self::is_key_pressed) but takes a key index.
374    ///
375    /// The meaning of index is defined by your backend
376    /// implementation.
377    #[inline]
378    #[doc(alias = "IsKeyPressed")]
379    pub fn is_key_index_pressed(&self, key_index: u32) -> bool {
380        cfg_if::cfg_if! {
381            if #[cfg(feature = "docking")] {
382                unsafe { sys::igIsKeyPressed_Bool(key_index, true) }
383            } else {
384                unsafe { sys::igIsKeyPressed(key_index, true) }
385            }
386        }
387    }
388
389    /// Returns true if the key was pressed (went from !down to down).
390    ///
391    /// Is **not** affected by key repeat settings (`io.key_repeat_delay`, `io.key_repeat_rate`)
392    #[inline]
393    #[doc(alias = "IsKeyPressed")]
394    pub fn is_key_pressed_no_repeat(&self, key: Key) -> bool {
395        let key_index = self.key_index(key);
396        self.is_key_index_pressed_no_repeat(key_index)
397    }
398
399    /// Same as [`is_key_pressed_no_repeat`](Self::is_key_pressed_no_repeat)
400    /// but takes a key index.
401    ///
402    /// The meaning of index is defined by your backend
403    /// implementation.
404    #[inline]
405    #[doc(alias = "IsKeyPressed")]
406    pub fn is_key_index_pressed_no_repeat(&self, key_index: u32) -> bool {
407        cfg_if::cfg_if! {
408            if #[cfg(feature = "docking")] {
409                unsafe { sys::igIsKeyPressed_Bool(key_index, false) }
410            } else {
411                unsafe { sys::igIsKeyPressed(key_index, false) }
412            }
413        }
414    }
415
416    /// Returns true if the key was released (went from down to !down)
417    #[inline]
418    #[doc(alias = "IsKeyReleased")]
419    pub fn is_key_released(&self, key: Key) -> bool {
420        let key_index = self.key_index(key);
421        self.is_key_index_released(key_index)
422    }
423
424    /// Same as [`is_key_released`](Self::is_key_released) but takes a key index.
425    ///
426    /// The meaning of index is defined by your backend
427    /// implementation.
428    #[inline]
429    #[doc(alias = "IsKeyReleased")]
430    pub fn is_key_index_released(&self, key_index: u32) -> bool {
431        cfg_if::cfg_if! {
432            if #[cfg(feature = "docking")] {
433                unsafe { sys::igIsKeyReleased_Nil(key_index) }
434            } else {
435                unsafe { sys::igIsKeyReleased(key_index) }
436            }
437        }
438    }
439
440    /// Returns a count of key presses using the given repeat rate/delay settings.
441    ///
442    /// Usually returns 0 or 1, but might be >1 if `rate` is small enough that `io.delta_time` >
443    /// `rate`.
444    #[inline]
445    #[doc(alias = "GetKeyPressedAmount")]
446    pub fn key_pressed_amount(&self, key: Key, repeat_delay: f32, rate: f32) -> u32 {
447        let key_index = self.key_index(key);
448        self.key_index_pressed_amount(key_index, repeat_delay, rate)
449    }
450
451    /// Same as [`crate::Ui::key_pressed_amount`] but takes a key index.
452    #[inline]
453    #[doc(alias = "GetKeyPressedAmount")]
454    pub fn key_index_pressed_amount(&self, key_index: u32, repeat_delay: f32, rate: f32) -> u32 {
455        unsafe { sys::igGetKeyPressedAmount(key_index, repeat_delay, rate) as u32 }
456    }
457
458    /// Focuses keyboard on the next widget.
459    ///
460    /// This is the equivalent to [set_keyboard_focus_here_with_offset](Self::set_keyboard_focus_here_with_offset)
461    /// with `target_widget` set to `FocusedWidget::Next`.
462    #[inline]
463    #[doc(alias = "SetKeyboardFocusHere")]
464    pub fn set_keyboard_focus_here(&self) {
465        self.set_keyboard_focus_here_with_offset(FocusedWidget::Next);
466    }
467
468    /// Focuses keyboard on a widget relative to current position.
469    #[inline]
470    #[doc(alias = "SetKeyboardFocusHere")]
471    pub fn set_keyboard_focus_here_with_offset(&self, target_widget: FocusedWidget) {
472        unsafe {
473            sys::igSetKeyboardFocusHere(target_widget.as_offset());
474        }
475    }
476}
imgui/input/keyboard.rs

imgui/input/
keyboard.rs
