Struct EventSubsystem

pub struct EventSubsystem { /* private fields */ }

Available on crate feature dep_sdl3 only.

Implementations

impl EventSubsystem

pub fn flush_event(&self, event_type: EventType)

Removes all events in the event queue that match the specified event type.

pub fn flush_events(&self, min_type: u32, max_type: u32)

Removes all events in the event queue that match the specified type range.

pub fn peek_events<B>(&self, max_amount: u32) -> B

where B: FromIterator<Event>,

Reads the events at the front of the event queue, until the maximum amount of events is read.

The events will not be removed from the queue.

Example

use sdl3::event::Event;

let sdl_context = sdl3::init().unwrap();
let event_subsystem = sdl_context.event().unwrap();

// Read up to 1024 events
let events: Vec<Event> = event_subsystem.peek_events(1024);

// Print each one
for event in events {
    println!("{:?}", event);
}

pub fn push_event(&self, event: Event) -> Result<(), Error>

Pushes an event to the event queue.

pub unsafe fn register_event(&self) -> Result<u32, Error>

Register a custom SDL event.

When pushing a user event, you must make sure that the type_ field is set to a registered SDL event number.

The code, data1, and data2 fields can be used to store user defined data.

See the SDL documentation for more information.

Example

let sdl = sdl3::init().unwrap();
let ev = sdl.event().unwrap();

let custom_event_type_id = unsafe { ev.register_event().unwrap() };
let event = sdl3::event::Event::User {
   timestamp: 0,
   window_id: 0,
   type_: custom_event_type_id,
   code: 456,
   data1: 0x1234 as *mut libc::c_void,
   data2: 0x5678 as *mut libc::c_void,
};

ev.push_event(event);

pub unsafe fn register_events(&self, nr: u32) -> Result<Vec<u32>, Error>

Registers custom SDL events.

Returns an error, if no more user events can be created.

pub fn register_custom_event<T>(&self) -> Result<(), Error>

where T: Any,

Register a custom event

It returns an error when the same type is registered twice.

Example

See push_custom_event

pub fn push_custom_event<T>(&self, event: T) -> Result<(), Error>

where T: Any,

Push a custom event

If the event type T was not registered using register_custom_event, this method will panic.

Example: pushing and receiving a custom event

struct SomeCustomEvent {
    a: i32
}

let sdl = sdl3::init().unwrap();
let ev = sdl.event().unwrap();
let mut ep = sdl.event_pump().unwrap();

ev.register_custom_event::<SomeCustomEvent>().unwrap();

let event = SomeCustomEvent { a: 42 };

ev.push_custom_event(event);

let received = ep.poll_event().unwrap(); // or within a for event in ep.poll_iter()
if received.is_user_event() {
    let e2 = received.as_user_event_type::<SomeCustomEvent>().unwrap();
    assert_eq!(e2.a, 42);
}

pub fn event_sender(&self) -> EventSender

Create an event sender that can be sent to other threads.

An EventSender will not keep the event subsystem alive. If the event subsystem is shut down calls to push_event and push_custom_event will return errors.

pub fn add_event_watch<'a, CB>(&self, callback: CB) -> EventWatch<'a, CB>

where CB: EventWatchCallback + 'a,

Create an event watcher which is called every time an event is added to event queue.

The watcher is disabled when the return value is dropped. Just calling this function without binding to a variable immediately disables the watcher. In order to make it persistent, you have to bind in a variable and keep it until it’s no longer needed.

Example: dump every event to stderr

let sdl = sdl3::init().unwrap();
let ev = sdl.event().unwrap();

// `let _ = ...` is insufficient, as it is dropped immediately.
let _event_watch = ev.add_event_watch(|event| {
    dbg!(event);
});

Trait Implementations

impl Clone for EventSubsystem

fn clone(&self) -> EventSubsystem

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for EventSubsystem

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Drop for EventSubsystem

fn drop(&mut self)

Executes the destructor for this type.

impl Sync for EventSubsystem