Struct wayland_client::Display

pub struct Display { /* fields omitted */ }

A connection to a wayland server

This object both represent the connection to the server and contains the primary WlDisplay wayland object. As such, it must be kept alive as long as you are connected. You can access the contained WlDisplay via Deref to create all the objects you need.

Implementations

impl Display

pub fn connect_to_env() -> Result<(Display, EventQueue), ConnectError>

Attempt to connect to a wayland server using the contents of the environment variables

First of all, if the WAYLAND_SOCKET environment variable is set, it'll try to interpret it as a FD number to use

Otherwise, it will try to connect to the socket name defined in the WAYLAND_DISPLAY environment variable, and error if it is not set.

On success, you are given the Display object as well as the main EventQueue hosting the WlDisplay wayland object.

This requires the XDG_RUNTIME_DIR variable to be properly set.

pub fn connect_to_name<S: Into<OsString>>(
    name: S
) -> Result<(Display, EventQueue), ConnectError>

Attempt to connect to a wayland server socket with given name

On success, you are given the Display object as well as the main EventQueue hosting the WlDisplay wayland object.

This requires the XDG_RUNTIME_DIR variable to be properly set.

pub unsafe fn from_fd(fd: RawFd) -> Result<(Display, EventQueue), ConnectError>

Attempt to use an already connected unix socket on given FD to start a wayland connection

On success, you are given the Display object as well as the main EventQueue hosting the WlDisplay wayland object.

Will take ownership of the FD.

pub fn flush(&self) -> Result<()>

Non-blocking write to the server

Outgoing messages to the server are buffered by the library for efficiency. This method flushes the internal buffer to the server socket.

Will write as many pending requests as possible to the server socket. Never blocks: if not all requests could be written, will return an io error WouldBlock.

On success returns the number of written requests.

pub fn create_event_queue(&self) -> EventQueue

Create a new event queue associated with this wayland connection

pub fn protocol_error(&self) -> Option<ProtocolError>

Retrieve the last protocol error if any occured

If your client does not respect some part of a protocol it is using, the server will send a special "protocol error" event and kill your connection. This method allows you to retrieve the contents of this event if it occured.

If the dispatch methods of the EventQueue return an error, this is an indication that a protocol error may have occured. Such errors are not recoverable, but this method allows you to gracefully display them to the user, along with indications for submitting a bug-report for example.

pub unsafe fn from_external_display(
    display_ptr: *mut wl_display
) -> (Display, EventQueue)

Create a Display and Event Queue from an external display

This allows you to interface with an already-existing wayland connection, for example provided by a GUI toolkit.

To avoid interferences with the owner of the connection, wayland-client will create a new event queue and register a wrapper of the wl_display to this queue, then provide them to you. You can then use them as if they came from a direct wayland connection.

Note that if you need to retrieve the actual wl_display pointer back (rather than its wrapper), you must use the get_display_ptr() method.

pub fn get_display_ptr(&self) -> *mut wl_display

Retrieve the wl_display pointer

If this Display was created from an external wl_display, its c_ptr() method will return a wrapper to the actual display. While this is perfectly good as a wl_proxy pointer, to send requests, this is not the actual wl_display and cannot be used as such.

This method will give you the wl_display.

Methods from Deref<Target = WlDisplay>

pub fn sync<F>(&self, implementor: F) -> Result<WlCallback, ()> where
    F: FnOnce(NewProxy<WlCallback>) -> WlCallback, 

asynchronous roundtrip

The sync request asks the server to emit the 'done' event on the returned wl_callback object. Since requests are handled in-order and events are delivered in-order, this can be used as a barrier to ensure all previous requests and the resulting events have been handled.

The object returned by this request will be destroyed by the compositor after the callback is fired and as such the client must not attempt to use it after that point.

The callback_data passed in the callback is the event serial.

pub fn get_registry<F>(&self, implementor: F) -> Result<WlRegistry, ()> where
    F: FnOnce(NewProxy<WlRegistry>) -> WlRegistry, 

get global registry object

This request creates a registry object that allows the client to list and bind the global objects available from the compositor.

It should be noted that the server side resources consumed in response to a get_registry request can only be released when the client disconnects, not when the client side proxy is destroyed. Therefore, clients should invoke get_registry as infrequently as possible to avoid wasting memory.

Trait Implementations

impl Clone for Display

fn clone(&self) -> Display

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Deref for Display

type Target = WlDisplay

The resulting type after dereferencing.

fn deref(&self) -> &WlDisplay

Dereferences the value.