Struct ButtonEvents 

pub struct ButtonEvents { /* private fields */ }

A stream of top button press and release events.

Subscribers should generally poll for events frequently as events are stored in a circular buffer and a subscriber can lose events if too many are generated before being polled.

See also the following alternative ways to get the pressed/released state of buttons:

• Buttons::currently_pressed()
• Button::is_pressed()
• Button::wait_for_press()
• Button::wait_for_release()

Implementations

impl ButtonEvents

pub fn subscribe() -> ButtonEvents

Subscribe to all button events that take place after this call to subscribe.

Events before subscribe will not be delivered.

Panics

This function should ordinarily never panic, but may if the library has not been initialized.

Examples

let mut button_events = ButtonEvents::subscribe();

pub async fn next(&mut self) -> ButtonEvent

Returns a Future yielding the next ButtonEvent.

Panics

This function should ordinarily never panic, but will if it is called after the internal broadcast::Receiver is closed.

pub async fn next_or_output<F>( &mut self, future: F, ) -> Result<ButtonEvent, <F as Future>::Output>

where F: Future,

Waits for either a ButtonEvent to be received, or for future to complete, and returns whichever is received first.

Errors

This function will return Err(F::Output) if future completes before a ButtonEvent is received.

Examples

let mut button_events = ButtonEvents::subscribe();
let my_future = async {
    sleep_ms(100).await;
    "there have been no button events for 100ms"
};

match button_events.next_or_output(my_future).await {
    Ok(event) => println!("{event:?}"),
    Err(f_out) => println!("{f_out}"),
}

pub async fn next_or_timeout_after( &mut self, timeout: Duration, ) -> Option<ButtonEvent>

Returns Some if self receives an event before timeout elapses. Otherwise, returns None.

pub async fn next_or_completed<F>(&mut self, future: F) -> Option<ButtonEvent>

where F: Future,

Runs future while waiting for a new ButtonEvent, and returns Some if an event occurs before future completes. Otherwise, this function returns None.

pub async fn peek_next_or_output<F>( &mut self, future: F, ) -> Result<ButtonEvent, <F as Future>::Output>

where F: Future,

The same as ButtonEvents::next_or_output, but does not consume an event if one is received.

Errors

This function will return Err(F::Output) if future completes before a ButtonEvent is received.

Examples

let mut button_events = ButtonEvents::subscribe();
let my_future = async {
    sleep_ms(100).await;
    "there have been no button events for 100ms"
};

match button_events.peek_next_or_output(my_future).await {
    Ok(event) => {
        println!("{event:?}");
        // We know there's an event here; unwrap it.
        let ev = button_events.try_next().unwrap();
        println!("{ev:?}");
        assert_eq!(event == ev);
    },
    Err(f_out) => println!("{f_out}"),
}

pub async fn peek_next_or_timeout_after( &mut self, timeout: Duration, ) -> Option<ButtonEvent>

Like next_or_timeout_after, but peeks the event instead of consuming it.

pub async fn peek_next_or_completed<F>( &mut self, future: F, ) -> Option<ButtonEvent>

where F: Future,

Cancels the future if a button event is generated.

pub async fn peek_next(&mut self) -> ButtonEvent

Waits for the next ButtonEvent and returns it without consuming it. Repeated calls to this function will have the same return value.

See also ButtonEvents::try_peek_next

pub fn try_next(&mut self) -> Option<ButtonEvent>

Returns the next ButtonEvent if one has been received, otherwise returns None.

Panics

This function will panic if the underlying broadcast::Receiver is closed.

pub fn try_peek_next(&mut self) -> Option<ButtonEvent>

Returns Some if an event has been received, without consuming it or waiting. Otherwise returns None.

See also ButtonEvents::peek_next

pub fn clear_pending(&mut self)

Clears all pending button events.

Any ButtonEvent returned from a call to next, peek_next, etc via self are guaranteed to have been received after this function returns.

pub fn only_report_press_events(&mut self)

Only press events will be returned from next.

Released events will still be relected in the state of currently_pressed.

pub fn report_press_and_release_events(&mut self)

Report both press and release events.

pub fn only_report_release_events(&mut self)

Only release events will be returned from next.

pub fn ignore_presses_within(&mut self, duration: Duration)

If one or more press events (not release events) follows a press event within duration, do not report them.

pub fn remove_press_within_filter(&mut self)

Reset to the default behavior of not ignoring press events within a duration specified to ignore_presses_within.

pub fn filter_by_buttons(&mut self, buttons: Buttons)

Filter out events that don’t come from a button in buttons.

pub fn remove_button_filter(&mut self)

Stop filtering by button. This is the same as filter_by_buttons(Buttons::all()).