diff --git a/crates/bevy_input/src/keyboard.rs b/crates/bevy_input/src/keyboard.rs index e829b90e47..40eec4b35a 100644 --- a/crates/bevy_input/src/keyboard.rs +++ b/crates/bevy_input/src/keyboard.rs @@ -1,16 +1,31 @@ use crate::{ButtonState, Input}; -use bevy_ecs::event::EventReader; -use bevy_ecs::system::ResMut; +use bevy_ecs::{event::EventReader, system::ResMut}; -/// A key input event from a keyboard device +/// A keyboard input event. +/// +/// This event is the translated version of the `WindowEvent::KeyboardInput` from the `winit` crate. +/// It is available to the end user and can be used for game logic. +/// +/// ## Usage +/// +/// The event is consumed inside of the [`keyboard_input_system`](crate::keyboard::keyboard_input_system) +/// to update the [`Input`](crate::Input) resource. #[derive(Debug, Clone)] pub struct KeyboardInput { + /// The scan code of the key. pub scan_code: u32, + /// The key code of the key. pub key_code: Option, + /// The press state of the key. pub state: ButtonState, } -/// Updates the `Input` resource with the latest `KeyboardInput` events +/// Updates the [`Input`] resource with the latest [`KeyboardInput`] events. +/// +/// ## Differences +/// +/// The main difference between the [`KeyboardInput`] event and the [`Input`] resource is that +/// the latter has convenient functions like [`Input::pressed`], [`Input::just_pressed`] and [`Input::just_released`]. pub fn keyboard_input_system( mut keyboard_input: ResMut>, mut keyboard_input_events: EventReader, @@ -31,206 +46,364 @@ pub fn keyboard_input_system( } } -/// The key code of a keyboard input. +/// The key code of a [`KeyboardInput`](crate::keyboard::KeyboardInput). +/// +/// ## Usage +/// +/// It is used as the generic `T` value of an [`Input`](crate::Input) to create a `Res>`. +/// The resource stores the data of the buttons of a keyboard and can be accessed inside of a system. +/// +/// ## Updating +/// +/// The resource is updated inside of the [`keyboard_input_system`](crate::keyboard::keyboard_input_system). #[derive(Debug, Hash, Ord, PartialOrd, PartialEq, Eq, Clone, Copy)] #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))] #[repr(u32)] pub enum KeyCode { - /// The '1' key over the letters. + /// The `1` key over the letters. Key1, - /// The '2' key over the letters. + /// The `2` key over the letters. Key2, - /// The '3' key over the letters. + /// The `3` key over the letters. Key3, - /// The '4' key over the letters. + /// The `4` key over the letters. Key4, - /// The '5' key over the letters. + /// The `5` key over the letters. Key5, - /// The '6' key over the letters. + /// The `6` key over the letters. Key6, - /// The '7' key over the letters. + /// The `7` key over the letters. Key7, - /// The '8' key over the letters. + /// The `8` key over the letters. Key8, - /// The '9' key over the letters. + /// The `9` key over the letters. Key9, - /// The '0' key over the 'O' and 'P' keys. + /// The `0` key over the letters. Key0, + /// The `A` key. A, + /// The `B` key. B, + /// The `C` key. C, + /// The `D` key. D, + /// The `E` key. E, + /// The `F` key. F, + /// The `G` key. G, + /// The `H` key. H, + /// The `I` key. I, + /// The `J` key. J, + /// The `K` key. K, + /// The `L` key. L, + /// The `M` key. M, + /// The `N` key. N, + /// The `O` key. O, + /// The `P` key. P, + /// The `Q` key. Q, + /// The `R` key. R, + /// The `S` key. S, + /// The `T` key. T, + /// The `U` key. U, + /// The `V` key. V, + /// The `W` key. W, + /// The `X` key. X, + /// The `Y` key. Y, + /// The `Z` key. Z, - /// The Escape key, next to F1. + /// The `Escape` / `ESC` key, next to the `F1` key. Escape, + /// The `F1` key. F1, + /// The `F2` key. F2, + /// The `F3` key. F3, + /// The `F4` key. F4, + /// The `F5` key. F5, + /// The `F6` key. F6, + /// The `F7` key. F7, + /// The `F8` key. F8, + /// The `F9` key. F9, + /// The `F10` key. F10, + /// The `F11` key. F11, + /// The `F12` key. F12, + /// The `F13` key. F13, + /// The `F14` key. F14, + /// The `F15` key. F15, + /// The `F16` key. F16, + /// The `F17` key. F17, + /// The `F18` key. F18, + /// The `F19` key. F19, + /// The `F20` key. F20, + /// The `F21` key. F21, + /// The `F22` key. F22, + /// The `F23` key. F23, + /// The `F24` key. F24, - /// Print Screen/SysRq. + /// The `Snapshot` / `Print Screen` key. Snapshot, - /// Scroll Lock. + /// The `Scroll` / `Scroll Lock` key. Scroll, - /// Pause/Break key, next to Scroll lock. + /// The `Pause` / `Break` key, next to the `Scroll` key. Pause, - /// `Insert`, next to Backspace. + /// The `Insert` key, next to the `Backspace` key. Insert, + /// The `Home` key. Home, + /// The `Delete` key. Delete, + /// The `End` key. End, + /// The `PageDown` key. PageDown, + /// The `PageUp` key. PageUp, + /// The `Left` / `Left Arrow` key. Left, + /// The `Up` / `Up Arrow` key. Up, + /// The `Right` / `Right Arrow` key. Right, + /// The `Down` / `Down Arrow` key. Down, - /// The Backspace key, right over Enter. + /// The `Back` / `Backspace` key. Back, - /// The Enter key. + /// The `Return` / `Enter` key. Return, - /// The space bar. + /// The `Space` / `Spacebar` / ` ` key. Space, - /// The "Compose" key on Linux. + /// The `Compose` key on Linux. Compose, - + /// The `Caret` / `^` key. Caret, + /// The `Numlock` key. Numlock, + /// The `Numpad0` / `0` key. Numpad0, + /// The `Numpad1` / `1` key. Numpad1, + /// The `Numpad2` / `2` key. Numpad2, + /// The `Numpad3` / `3` key. Numpad3, + /// The `Numpad4` / `4` key. Numpad4, + /// The `Numpad5` / `5` key. Numpad5, + /// The `Numpad6` / `6` key. Numpad6, + /// The `Numpad7` / `7` key. Numpad7, + /// The `Numpad8` / `8` key. Numpad8, + /// The `Numpad9` / `9` key. Numpad9, + /// The `AbntC1` key. AbntC1, + /// The `AbntC2` key. AbntC2, + + /// The `NumpadAdd` / `+` key. NumpadAdd, + /// The `Apostrophe` / `'` key. Apostrophe, + /// The `Apps` key. Apps, + /// The `Asterik` / `*` key. Asterisk, + /// The `Plus` / `+` key. Plus, + /// The `At` / `@` key. At, + /// The `Ax` key. Ax, + /// The `Backslash` / `\` key. Backslash, + /// The `Calculator` key. Calculator, + /// The `Capital` key. Capital, + /// The `Colon` / `:` key. Colon, + /// The `Comma` / `,` key. Comma, + /// The `Convert` key. Convert, + /// The `NumpadDecimal` / `.` key. NumpadDecimal, + /// The `NumpadDivide` / `/` key. NumpadDivide, + /// The `Equals` / `=` key. Equals, + /// The `Grave` / `Backtick` / `` ` `` key. Grave, + /// The `Kana` key. Kana, + /// The `Kanji` key. Kanji, - /// The left alt key. Maps to left option on Mac. + + /// The `LAlt` / `Left Alt` key. Maps to `Left Option` on Mac. LAlt, + /// The `LBracket` / `Left Bracket` key. LBracket, + /// The `LControl` / `Left Control` key. LControl, + /// The `LShift` / `Left Shift` key. LShift, - /// The left Windows key. Maps to left Command on Mac. + /// The `LWin` / `Left Windows` key. Maps to `Left Command` on Mac. LWin, + + /// The `Mail` key. Mail, + /// The `MediaSelect` key. MediaSelect, + /// The `MediaStop` key. MediaStop, + /// The `Minus` / `-` key. Minus, + /// The `NumpadMultiply` / `*` key. NumpadMultiply, + /// The `Mute` key. Mute, + /// The `MyComputer` key. MyComputer, - NavigateForward, // also called "Prior" - NavigateBackward, // also called "Next" + /// The `NavigateForward` / `Prior` key. + NavigateForward, + /// The `NavigateBackward` / `Next` key. + NavigateBackward, + /// The `NextTrack` key. NextTrack, + /// The `NoConvert` key. NoConvert, + /// The `NumpadComma` / `,` key. NumpadComma, + /// The `NumpadEnter` key. NumpadEnter, + /// The `NumpadEquals` / `=` key. NumpadEquals, + /// The `Oem102` key. Oem102, + /// The `Period` / `.` key. Period, + /// The `PlayPause` key. PlayPause, + /// The `Power` key. Power, + /// The `PrevTrack` key. PrevTrack, - /// The right alt key. Maps to right option on Mac. + + /// The `RAlt` / `Right Alt` key. Maps to `Right Option` on Mac. RAlt, + /// The `RBracket` / `Right Bracket` key. RBracket, + /// The `RControl` / `Right Control` key. RControl, + /// The `RShift` / `Right Shift` key. RShift, - /// The right Windows key. Maps to right Command on Mac. + /// The `RWin` / `Right Windows` key. Maps to `Right Command` on Mac. RWin, + + /// The `Semicolon` / `;` key. Semicolon, + /// The `Slash` / `/` key. Slash, + /// The `Sleep` key. Sleep, + /// The `Stop` key. Stop, + /// The `NumpadSubtract` / `-` key. NumpadSubtract, + /// The `Sysrq` key. Sysrq, + /// The `Tab` / ` ` key. Tab, + /// The `Underline` / `_` key. Underline, + /// The `Unlabeled` key. Unlabeled, + + /// The `VolumeDown` key. VolumeDown, + /// The `VolumeUp` key. VolumeUp, + + /// The `Wake` key. Wake, + + /// The `WebBack` key. WebBack, + /// The `WebFavorites` key. WebFavorites, + /// The `WebForward` key. WebForward, + /// The `WebHome` key. WebHome, + /// The `WebRefresh` key. WebRefresh, + /// The `WebSearch` key. WebSearch, + /// The `WebStop` key. WebStop, + + /// The `Yen` key. Yen, + + /// The `Copy` key. Copy, + /// The `Paste` key. Paste, + /// The `Cut` key. Cut, }