Struct pixel_game_lib::window::Input

pub struct Input { /* private fields */ }

Re-export winit_input_helper type. The main struct of the API.

Create with WinitInputHelper::new. Call WinitInputHelper::update for every winit::event::Event you receive from winit. WinitInputHelper::update returning true indicates a step has occured. You should now run your application logic, calling any of the accessor methods you need.

An alternative API is provided via WinitInputHelper::step_with_window_events, call this method instead of WinitInputHelper::update if you need to manually control when a new step begins. A step occurs every time this method is called.

Do not mix usages of WinitInputHelper::update and WinitInputHelper::step_with_window_events. You should stick to one or the other.

Implementations

impl WinitInputHelper

pub fn new() -> WinitInputHelper

pub fn update<T>(&mut self, event: &Event<T>) -> bool

Pass every winit event to this function and run your application logic when it returns true.

The following winit events are handled:

• Event::NewEvents clears all internal state.
• Event::MainEventsCleared causes this function to return true, signifying a “step” has completed.
• Event::WindowEvent updates internal state, this will affect the result of accessor methods immediately.
• Event::DeviceEvent updates value of mouse_diff()

pub fn step_with_window_events(&mut self, events: &[WindowEvent])

Pass a slice containing every winit event that occured within the step to this function. Ensure this method is only called once per application main loop. Ensure every event since the last WinitInputHelper::step_with_window_events call is included in the events argument.

WinitInputHelper::Update is easier to use. But this method is useful when your application logic steps dont line up with winit’s event loop. e.g. you have a seperate thread for application logic using WinitInputHelper that constantly runs regardless of winit’s event loop and you need to send events to it directly.

pub fn key_pressed(&self, keycode: KeyCode) -> bool

Returns true when the key with the specified keycode goes from “not pressed” to “pressed”. Otherwise returns false.

Uses physical keys in the US layout, so for example the W key will be in the same physical key on both US and french keyboards.

This is suitable for game controls.

Examples found in repository

examples/window.rs (line 26)

    fn update(&mut self, input: &Input, _mouse_pos: Option<Vec2<usize>>, _dt: f32) -> bool {
        // Increment when mouse is clicked
        if input.mouse_held(MouseButton::Left) {
            self.pixels_to_draw += 1;
        }

        // Exit when escape is pressed
        input.key_pressed(KeyCode::Escape)
    }

examples/font.rs (line 36)

fn main() {
    // Window configuration with default pixel size and scaling
    let window_config = WindowConfig {
        ..Default::default()
    };

    // Load a font for the widgets
    let font = font();

    // Open the window and start the game-loop
    pixel_game_lib::window(
        // We don't use any state so we pass a zero-sized type
        (),
        window_config.clone(),
        // Update loop exposing input events we can handle, this is where you would handle the game logic
        |_state, input, _mouse, _dt| {
            // Exit when escape is pressed
            input.key_pressed(KeyCode::Escape)
        },
        // Render loop exposing the pixel buffer we can mutate
        move |_state, canvas, _dt| {
            // Draw the text at the center of the screen
            font.render_centered(
                "pixel-game-lib font example",
                Vec2::new(
                    window_config.buffer_size.w / 2,
                    window_config.buffer_size.h / 2,
                )
                .as_(),
                canvas,
            );
        },
    )
    .expect("Error opening window");
}

examples/draw.rs (line 29)

fn main() {
    // Window configuration with huge pixels
    let window_config = WindowConfig {
        buffer_size: Extent2::new(64, 64),
        scaling: 8,
        ..Default::default()
    };

    // Open the window and start the game-loop
    pixel_game_lib::window(
        // Keep track of the mouse as our "game state"
        Vec2::zero(),
        window_config.clone(),
        // Update loop exposing input events we can handle, this is where you would handle the game logic
        |state, input, mouse, _dt| {
            // Set the mouse position as the game state
            if let Some(mouse) = mouse {
                *state = mouse;
            }

            // Exit when escape is pressed
            input.key_pressed(KeyCode::Escape)
        },
        // Render loop exposing the pixel buffer we can mutate
        move |mouse, canvas, _dt| {
            // Reset the canvas with a white color
            canvas.fill(0xFFFFFFFF);

            // Draw a gray circle with the radius being the distance of the center to the mouse
            let circle_center = Vec2::new(50.0, 50.0);
            let dist_from_mouse = mouse.as_().distance(circle_center);
            canvas.draw_circle(Disk::new(circle_center, dist_from_mouse), 0xFF999999);
            // Draw a darker gray circle outline on top of the circle
            canvas.draw_circle_outline(Disk::new(circle_center, dist_from_mouse), 0xFF333333);

            // Draw a light green blue triangle with one corner being snapped to the mouse
            canvas.draw_triangle(
                [Vec2::new(45.0, 5.0), Vec2::new(60.0, 8.0), mouse.as_()],
                0xFF99FF99,
            );

            // Draw a light blue quadrilateral with one corner being snapped to the mouse
            canvas.draw_quad(
                [
                    Vec2::new(5.0, 5.0),
                    Vec2::new(20.0, 8.0),
                    Vec2::new(8.0, 30.0),
                    mouse.as_(),
                ],
                0xFF9999FF,
            );

            // Draw a black line from the center of the canvas to our mouse
            canvas.draw_line(
                (window_config.buffer_size.as_() / 2.0).into(),
                mouse.as_(),
                0xFF000000,
            );

            // Draw a red pixel under the mouse
            canvas.set_pixel(mouse.as_(), 0xFFFF0000);
        },
    )
    .expect("Error opening window");
}

pub fn key_pressed_os(&self, keycode: KeyCode) -> bool

Returns true when the key with the specified keycode goes from “not pressed” to “pressed”. Otherwise returns false.

Uses physical keys in the US layout, so for example the W key will be in the same physical key on both US and french keyboards.

Will repeat key presses while held down according to the OS’s key repeat configuration This is suitable for UI.

pub fn key_released(&self, keycode: KeyCode) -> bool

Returns true when the key with the specified KeyCode goes from “pressed” to “not pressed”. Otherwise returns false.

Uses physical keys in the US layout, so for example the W key will be in the same physical key on both US and french keyboards.

pub fn key_held(&self, keycode: KeyCode) -> bool

Returns true when the key with the specified keycode remains “pressed”. Otherwise returns false.

Uses physical keys in the US layout, so for example the W key will be in the same physical key on both US and french keyboards.

pub fn held_shift(&self) -> bool

Returns true while any shift key is held on the keyboard. Otherwise returns false.

Uses physical keys.

pub fn held_control(&self) -> bool

Returns true while any control key is held on the keyboard. Otherwise returns false.

Uses physical keys.

pub fn held_alt(&self) -> bool

Returns true while any alt key is held on the keyboard. Otherwise returns false.

Uses physical keys.

pub fn key_pressed_logical(&self, check_key: Key<&str>) -> bool

Returns true when the specified keyboard key goes from “not pressed” to “pressed”. Otherwise returns false.

Uses logical keypresses, so for example W is changed between a US and french keyboard. Will never repeat keypresses while held.

pub fn key_pressed_os_logical(&self, check_key: Key<&str>) -> bool

Returns true when the specified keyboard key goes from “not pressed” to “pressed”. Otherwise returns false.

Uses logical keypresses, so for example W is changed between a US and french keyboard.

Will repeat key presses while held down according to the OS’s key repeat configuration This is suitable for UI.

pub fn key_released_logical(&self, check_key: Key<&str>) -> bool

Returns true when the specified keyboard key goes from “pressed” to “not pressed”. Otherwise returns false.

Uses logical keypresses, so for example W is changed between a US and french keyboard.

pub fn key_held_logical(&self, check_key: Key<&str>) -> bool

Returns true while the specified keyboard key remains “pressed”. Otherwise returns false.

Uses logical keypresses, so for example W is changed between a US and french keyboard.

pub fn mouse_pressed(&self, mouse_button: MouseButton) -> bool

Returns true when the specified mouse button goes from “not pressed” to “pressed”. Otherwise returns false.

pub fn mouse_released(&self, mouse_button: MouseButton) -> bool

Returns true when the specified mouse button goes from “pressed” to “not pressed”. Otherwise returns false.

pub fn mouse_held(&self, mouse_button: MouseButton) -> bool

Returns true while the specified mouse button remains “pressed”. Otherwise returns false.

Examples found in repository

examples/window.rs (line 21)

    fn update(&mut self, input: &Input, _mouse_pos: Option<Vec2<usize>>, _dt: f32) -> bool {
        // Increment when mouse is clicked
        if input.mouse_held(MouseButton::Left) {
            self.pixels_to_draw += 1;
        }

        // Exit when escape is pressed
        input.key_pressed(KeyCode::Escape)
    }

pub fn scroll_diff(&self) -> (f32, f32)

Returns (0.0, 0.0) when the window is not focused. Otherwise returns the amount scrolled by the mouse during the last step. Returns (horizontally, vertically)

pub fn cursor(&self) -> Option<(f32, f32)>

Returns the cursor coordinates in pixels, when window is focused AND (cursor is on window OR any mouse button remains held while cursor moved off window) Otherwise returns None

pub fn cursor_diff(&self) -> (f32, f32)

Returns the change in cursor coordinates that occured during the last step, when window is focused AND (cursor is on window OR any mouse button remains held while cursor moved off window) Otherwise returns (0.0, 0.0).

pub fn mouse_diff(&self) -> (f32, f32)

Returns the change in mouse coordinates that occured during the last step.

This is useful when implementing first person controls with a captured mouse.

Because this uses DeviceEvents, the step_with_windows_events function won’t update this as it is not a WindowEvent.

pub fn text(&self) -> &[Key]

Returns the characters pressed during the last step. The characters are in the order they were pressed.

pub fn dropped_file(&self) -> Option<PathBuf>

Returns the path to a file that has been drag-and-dropped onto the window.

pub fn window_resized(&self) -> Option<PhysicalSize<u32>>

Returns the current window size if it was resized during the last step. Otherwise returns None.

pub fn resolution(&self) -> Option<(u32, u32)>

Returns None when no WindowEvent::Resized have been received yet. After one has been received it returns the current resolution of the window.

pub fn scale_factor_changed(&self) -> Option<f64>

Returns the current scale factor if it was changed during the last step. Otherwise returns None.

pub fn scale_factor(&self) -> Option<f64>

Returns None when no WindowEvent::ScaleFactorChanged have been received yet. After one has been received it returns the current scale_factor of the window.

pub fn destroyed(&self) -> bool

Returns true if the window has been destroyed Otherwise returns false. Once this method has returned true once all following calls to this method will also return true.

pub fn close_requested(&self) -> bool

Returns true if the OS has requested the application to close during this step. Otherwise returns false.

pub fn delta_time(&self) -> Option<Duration>

Returns the std::time::Duration elapsed since the last step. Returns None if the step is still in progress.

Trait Implementations

impl Clone for WinitInputHelper

fn clone(&self) -> WinitInputHelper

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for WinitInputHelper

fn default() -> WinitInputHelper

Returns the “default value” for a type.