Struct gilrs::Gilrs

pub struct Gilrs { /* fields omitted */ }

Main object responsible of managing gamepads.

Gilrs owns all gamepads and you can use one of two methods to get reference to specific one. First, you can use Index operator. It will always return some gamepad, even if it was disconnected or never observed. All actions on such gamepads are no-op, and state of all elements should be 0. This makes it ideal when you don't care whether gamepad is connected.

The second method is to use get() function. Because it return Option, it will return None if gamepad is not connected.

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().unwrap();

// 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. Updating state is done automatically, unless it's disabled by GilrsBuilder::set_update_state(false). However, if you are using custom filters, you still have to update state manually – to do this call update() method.

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().unwrap();

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

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

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

    gilrs.inc();
}

Methods

impl Gilrs

pub fn new() -> Result<Self, Error>

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

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

Returns next pending event.

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

Updates internal state according to event.

pub 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.

pub fn counter(&self) -> u64

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

pub fn reset_counter(&mut self)

Sets counter to 0.

Important traits for ConnectedGamepadsIterator<'a>

impl<'a> Iterator for ConnectedGamepadsIterator<'a> type Item = (usize, &'a Gamepad);

pub 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());
}

Important traits for ConnectedGamepadsMutIterator<'a>

impl<'a> Iterator for ConnectedGamepadsMutIterator<'a> type Item = (usize, &'a mut Gamepad);

pub 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());
}

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

Returns a reference to connected gamepad or None.

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

Returns a mutable reference to connected gamepad or None.

pub fn insert_event(&mut self, ev: Event)

Adds ev at the end of internal event queue. It can later be retrieved with next_event().

Trait Implementations

impl Debug for Gilrs

fn fmt(&self, f: &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.