Crate wayland_client [] [src]

Client-side Wayland connector

Overview

Connection to the Wayland compositor is achieved by the default_connect() function, which provides you with a WlDisplay and an EventQueue.

From the display, you'll retrieve the registry, from which you can instantiate the globals you need. This step being really similar in most cases, this crate contains an utility struct EnvHandler which can do this job for you. See its documentation for details.

You then register your handlers for events to the event queue, and integrate it in your main event loop.

Implementations and event queues

This crate mirrors the callback-oriented design of the Wayland C library by using implementation structs: each wayland type defines an Implementation struct in its module, with one function field for each possible event this object can receive.

When registering an object on an event queue, you need to provide an implementation for this object. You can also provide some "implementation data": a value that will be provided as second argument to all the callback methods of your implementation.

A typical use of implementation data is to store here one or more state tokens to access some part of the shared state from your callback.

Example of implementation

You can register your wayland objects to an event queue:

Be careful when using this code, it's not being tested!
event_queue.register(&my_object, implementation, impl_data);

A given wayland object can only be registered to a event queue at a given time, re-registering it will overwrite the previous configuration.

Objects can be registered to event queues using the &EventQueueHandle argument, available from withing an event callback.

Event loop integration

Once this setup is done, you can integrate the event queue to the main event loop of your program:

Be careful when using this code, it's not being tested!
loop {
    // flush events to the server
    display.flush().unwrap();
    // receive events from the server and dispatch them
    // to handlers (might block)
    event_queue.dispatch().unwrap();
}

For more precise control of the flow of the event queue (and importantly non-blocking options), see EventQueue documentation.

Protocols integration

This crate provides the basic primitives as well as the core wayland protocol (in the protocol module), but other protocols can be integrated from XML descriptions.

The the crate wayland_scanner and its documentation for details about how to do so.

Modules

cursor

Cursor utilities

egl

EGL utilities

protocol

The wayland core protocol

protocol_interfaces

Interfaces for the core protocol

sys

Reexports of types and objects from wayland-sys

Macros

wayland_env

Create an environment handling struct

Structs

EnvHandler

Utility type to handle the registry and global objects

EnvNotify

An implementation to receive globals notifications for the EnvHandler

EventQueue

An event queue managing wayland events

EventQueueHandle

Handle to an event queue

ReadEventsGuard

A guard over a read intention.

State

A token store

StateProxy

A Proxy representing a Store with ongoing borrows

StateToken

A token for accessing the store contents

Enums

ConnectError

Enum representing the possible reasons why connecting to the wayland server failed

FatalError

Enum representing possible errors fatal to a wayland session

Liveness

Represents the state of liveness of a wayland object

RegisterStatus

Status of a registration attempt of a proxy.

RequestResult

Possible outcome of the call of a request on a proxy

Traits

Implementable

Common trait for wayland objects that can be registered to an EventQueue

Proxy

Common routines for wayland proxy objects.

Functions

connect_to

Connect to the compositor socket

default_connect

Connect to the compositor socket