Module ggez::input::keyboard

Keyboard utility functions; allow querying state of keyboard keys and modifiers.

On Keycodes and Scancodes

You can see functions for keys and functions for scancodes listed here.

Keycodes are the “meaning” of a key once keyboard layout translation has been applied. For example, when the user presses “Q” in their layout, the enum value for Q is provided to this function.

Scancodes are hardware dependent names for keys that refer to the key’s location rather than the character it prints when pressed. They are not necessarily cross platform (e.g. between Windows and Linux).

For example, on a US QWERTY keyboard layout, the WASD keys are located in an inverted T shape on the left of the keyboard. This is not the case for AZERTY keyboards, which have those keys in a different location. Using scan codes over key codes in this case would map those characters to their physical location on the keyboard.

In general, keycodes should be used when the meaning of the typed character is important (e.g. “I” to open the inventory), and scancodes for when the location is important (e.g. the WASD key block). The text_input_event handler should be used to collect raw text.

The keycode is optional because not all inputs can be matched to a specific key code. This will happen on non-English keyboards, for example.

---

Example:

use ggez::event::{self, EventHandler};
use ggez::input::keyboard::{KeyCode, KeyMods, KeyInput};
use ggez::{graphics::{self, Color}, timer};
use ggez::{Context, GameResult};

struct MainState {
    position_x: f32,
}

impl EventHandler for MainState {
    fn update(&mut self, ctx: &mut Context) -> GameResult {
        let k_ctx = &ctx.keyboard;
        // Increase or decrease `position_x` by 0.5, or by 5.0 if Shift is held.
        if k_ctx.is_key_pressed(KeyCode::Right) {
            if k_ctx.is_mod_active(KeyMods::SHIFT) {
                self.position_x += 4.5;
            }
            self.position_x += 0.5;
        } else if k_ctx.is_key_pressed(KeyCode::Left) {
            if k_ctx.is_mod_active(KeyMods::SHIFT) {
                self.position_x -= 4.5;
            }
            self.position_x -= 0.5;
        }
        Ok(())
    }

    fn draw(&mut self, ctx: &mut Context) -> GameResult {
        let mut canvas = graphics::Canvas::from_frame(
            ctx,
            Color::from([0.1, 0.2, 0.3, 1.0]),
        );
        // Create a circle at `position_x` and draw
        let circle = graphics::Mesh::new_circle(
            ctx,
            graphics::DrawMode::fill(),
            glam::vec2(self.position_x, 380.0),
            100.0,
            2.0,
            graphics::Color::WHITE,
        )?;
        canvas.draw(&circle, graphics::DrawParam::default());
        canvas.finish(ctx)?;
        timer::yield_now();
        Ok(())
    }

    fn key_down_event(&mut self, ctx: &mut Context, input: KeyInput, _repeat: bool) -> GameResult {
        match input.keycode {
            // Quit if Shift+Ctrl+Q is pressed.
            Some(KeyCode::Q) => {
                if input.mods.contains(KeyMods::SHIFT) && input.mods.contains(KeyMods::CTRL) {
                    println!("Terminating!");
                    ctx.request_quit();
                } else if input.mods.contains(KeyMods::SHIFT) || input.mods.contains(KeyMods::CTRL) {
                    println!("You need to hold both Shift and Control to quit.");
                } else {
                    println!("Now you're not even trying!");
                }
            }
            _ => (),
        }
        Ok(())
    }
}

pub fn main() -> GameResult {
    let cb = ggez::ContextBuilder::new("keyboard", "ggez");
    let (mut ctx, event_loop) = cb.build()?;

    let state = MainState { position_x: 0.0 };
    event::run(ctx, event_loop, state)
}

Structs

• KeyInput
  A simple wrapper bundling the four properties of a keyboard stroke.
• KeyMods
  Bitflags describing the state of keyboard modifiers, such as Control or Shift.
• KeyboardContext
  Tracks held down keyboard keys, active keyboard modifiers, and figures out if the system is sending repeat keystrokes.

Enums

• KeyCode
  A key code. Symbolic name for a keyboard key.

Functions

• active_modsDeprecated
  Returns currently active keyboard modifiers.
• is_key_just_pressedDeprecated
  Checks if a key has been pressed down this frame.
• is_key_just_releasedDeprecated
  Checks if a key has been released this frame.
• is_key_pressedDeprecated
  Checks if a key is currently pressed down.
• is_key_repeatedDeprecated
  Checks if the last keystroke sent by the system is repeated, like when a key is held down for a period of time.
• is_mod_activeDeprecated
  Checks if keyboard modifier (or several) is active.
• pressed_keysDeprecated
  Returns a reference to the set of currently pressed keys.

Type Definitions

• ScanCode
  Hardware-dependent keyboard scan code.