Struct wayland_client::EventQueue

pub struct EventQueue { /* fields omitted */ }

An event queue managing wayland events

Each wayland object can receive events from the server. To handle these events you must use a handler object: a struct (or enum) which you have implemented the appropriate Handler traits on it (each wayland interface defines a Handler trait in its module), and declared it using the declare_handler!(..) macro.

This handler contains the state all your handler methods will be able to access via the &mut self argument. You can then instantiate your type, and give ownership of the handler object to the event queue, via the add_handler(..) method. Then, each wayland object must be registered to a handler via the register(..) method (or its events will all be ignored).

The event queues also provides you control on the flow of the program, via the dispatch() and dispatch_pending() methods.

example of use

struct MyHandler { /* ... */ }

impl wl_surface::Handler for MyHandler {
    // implementation of the handler methods
}

declare_handler!(MyHandler, wl_surface::Handler, wl_surface::WlSurface);

fn main() {
    /* ... setup of your environment ... */
    let surface = compositor.create_surface().expect("Compositor cannot be destroyed.");
    let my_id = eventqueue.add_handler(MyHandler::new());
    eventqueue.register::<_, MyHandler>(&surface, my_id);

    // main event loop
    loop {
        // flush requests to the server
        display.flush().unwrap();
        // dispatch events from the server, blocking if needed
        eventqueue.dispatch().unwrap();
    }
}

Methods

impl EventQueue

fn dispatch(&mut self) -> IoResult<u32>

Dispatches events from the internal buffer.

Dispatches all events to their appropriate handlers. If not events were in the internal buffer, will block until some events are read and dispatch them. This process can insert events in the internal buffers of other event queues.

If an error is returned, your connection with the wayland compositor is probably lost.

fn dispatch_pending(&mut self) -> IoResult<u32>

Dispatches pending events from the internal buffer.

Dispatches all events to their appropriate handlers. Never blocks, if not events were pending, simply returns Ok(0).

If an error is returned, your connection with the wayland compositor is probably lost.

fn sync_roundtrip(&mut self) -> IoResult<i32>

Synchronous roundtrip

This call will cause a synchonous roundtrip with the wayland server. It will block until all pending requests of this queue are send to the server and it has processed all of them and send the appropriate events.

Handlers are called as a consequence.

On success returns the number of dispatched events.

fn state(&mut self) -> StateGuard

Get a handle to the internal state

The returned guard object allows you to get references to the handler objects you previously inserted in this event queue.

fn prepare_read(&self) -> Option<ReadEventsGuard>

Prepare an conccurent read

Will declare your intention to read events from the server socket.

Will return None if there are still some events awaiting dispatch on this EventIterator. In this case, you need to call dispatch_pending() before calling this method again.

As long as the returned guard is in scope, no events can be dispatched to any event iterator.

The guard can then be destroyed by two means:

• Calling its cancel() method (or letting it go out of scope): the read intention will be cancelled
• Calling its read_events() method: will block until all existing guards are destroyed by one of these methods, then events will be read and all blocked read_events() calls will return.

This call will otherwise not block on the server socket if it is empty, and return an io error WouldBlock in such cases.

Methods from Deref<Target = EventQueueHandle>

fn register<P, H>(&mut self, proxy: &P, handler_id: usize) -> RegisterStatus where
    P: Proxy,
    H: Handler<P> + Any + Send + 'static, 

Register a proxy to a handler of this event queue.

The H type must be provided and match the type of the targetted Handler, or it will panic.

This overwrites any precedently set Handler for this proxy.

Returns appropriately and does nothing if this proxy is dead or already managed by something else than this library.

fn add_handler<H: Any + Send + 'static>(&mut self, handler: H) -> usize

Insert a new handler to this event queue

Returns the index of this handler in the internal array, which is needed to register proxies to it.

fn add_handler_with_init<H: Init + Any + Send + 'static>(
    &mut self,
    handler: H
) -> usize

Insert a new handler with init

Allows you to insert handlers that require some interaction with the event loop in their initialization, like registering some objects to it.

The handler must implement the Init trait, and its init method will be called after its insertion.

Trait Implementations

impl Send for EventQueue

impl Deref for EventQueue

type Target = EventQueueHandle

The resulting type after dereferencing

fn deref(&self) -> &EventQueueHandle

The method called to dereference a value

impl DerefMut for EventQueue

fn deref_mut(&mut self) -> &mut EventQueueHandle

The method called to mutably dereference a value