Struct gilrs::Gilrs

pub struct Gilrs { /* fields omitted */ }

Main object responsible of managing gamepads.

Event loop

All interesting actions like button was pressed or new controller was connected are represented by struct Event. Use next_event() function to retrieve event from queue.

use gilrs::{Gilrs, Event, EventType, Button};

let mut gilrs = Gilrs::new();

// Event loop
loop {
    while let Some(event) = gilrs.next_event() {
        match event {
            Event { id, event: EventType::ButtonPressed(Button::South, _), .. } => {
                println!("Player {}: jump!", id + 1)
            }
            Event { id, event: EventType::Disconnected, .. } => {
                println!("We lost player {}", id + 1)
            }
            _ => (),
        };
    }
}

Cached gamepad state

Gilrs also menage cached gamepad state. To update it, use update(Event) method. Updating is not done automatically, because you probably want the state after filtered events (see ev::filter module), not these from event_next().

To access state you can use Gamepad::state() function. Gamepad also implement some state related functions directly, see Gamepad for more.

Counter

Gilrs has additional functionality, referred here as counter. The idea behind it is simple, each time you end iteration of update loop, you call Gilrs::inc() which will increase internal counter by one. When state of one if elements changes, value of counter is saved. When checking state of one of elements you can tell exactly when this event happened. Timestamps are not good solution here because they can tell you when system observed event, not when you processed it. On the other hand, they are good when you want to implement key repeat or software debouncing.

use gilrs::{Gilrs, Button};

let mut gilrs = Gilrs::new();

loop {
    while let Some(ev) = gilrs.next_event() {
        gilrs.update(&ev);
        // Do other things with event
    }

    if gilrs.gamepad(0).is_pressed(Button::DPadLeft) {
        // go left
    }

    match gilrs.gamepad(0).button_data(Button::South) {
        Some(d) if d.is_pressed() && d.counter() == gilrs.counter() => {
            // jump
        }
        _ => ()
    }

    gilrs.inc();
}

Methods

impl Gilrs

fn new() -> Self

Creates new Gilrs with default settings. See GilrsBuilder for more details.

fn next_event(&mut self) -> Option<Event>

Returns next pending event.

fn update(&mut self, event: &Event)

Updates internal state according to event.

fn inc(&mut self)

Increases internal counter by one. Counter data is stored with state and can be used to determine when last event happened. You probably want to use this function in your update loop after processing events.

fn counter(&self) -> u64

Returns counter. Counter data is stored with state and can be used to determine when last event happened.

fn reset_counter(&mut self)

Sets counter to 0.

fn gamepad(&self, id: usize) -> &Gamepad

Borrow gamepad with given id. This method always return reference to some gamepad, even if it was disconnected or never observed. If gamepad's status is not equal to Status::Connected all actions preformed on it are no-op and all values in cached gamepad state are 0 (false for buttons and 0.0 for axes).

fn gamepad_mut(&mut self, id: usize) -> &mut Gamepad

See gamepad()

fn gamepads(&self) -> ConnectedGamepadsIterator

Returns iterator over all connected gamepads and their ids.

for (id, gamepad) in gilrs.gamepads() {
    assert!(gamepad.is_connected());
    println!("Gamepad with id {} and name {} is connected",
             id, gamepad.name());
}

fn gamepads_mut(&mut self) -> ConnectedGamepadsMutIterator

Returns iterator over all connected gamepads and their ids.

for (id, gamepad) in gilrs.gamepads_mut() {
    assert!(gamepad.is_connected());
    println!("Gamepad with id {} and name {} is connected",
             id, gamepad.name());
}

fn connected_gamepad(&self, id: usize) -> Option<&Gamepad>

Returns a reference to connected gamepad or None.

fn connected_gamepad_mut(&mut self, id: usize) -> Option<&mut Gamepad>

Returns a mutable reference to connected gamepad or None.

Trait Implementations

impl Debug for Gilrs

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Index<usize> for Gilrs

type Output = Gamepad

The returned type after indexing.

fn index(&self, idx: usize) -> &Gamepad

Performs the indexing (container[index]) operation.

impl IndexMut<usize> for Gilrs

fn index_mut(&mut self, idx: usize) -> &mut Gamepad

Performs the mutable indexing (container[index]) operation.