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 as such must be kept alive as long as you are connected, and contains the primary WlDisplay wayland object, from which you can create all your need objects. The inner Proxy<WlDisplay> can be accessed via Deref.

Methods

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

If the WAYLAND_DISPLAY variable is set, it will try to connect to the socket it points to. Otherwise, it will default to wayland-0.

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 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 = Proxy<WlDisplay>>

pub fn send(&self, msg: I::Request)

Send a request through this object

Warning: This method is mostly intended to be used by code generated by wayland-scanner, and you should probably never need to use it directly, but rather use the appropriate RequestsTrait for your proxy.

This is the generic method to send requests.

If your request needs to create an object, use send_constructor.

pub fn send_constructor<J, F>(
    &self,
    msg: I::Request,
    implementor: F,
    version: Option<u32>
) -> Result<Proxy<J>, ()> where
    J: Interface,
    F: FnOnce(NewProxy<J>) -> Proxy<J>, 

Send a request creating an object through this object

Warning: This method is mostly intended to be used by code generated by wayland-scanner, and you should probably never need to use it directly, but rather use the appropriate RequestsTrait for your proxy.

This is the generic method to send requests that create objects

The slot in the message corresponding with the newly created object must have been filled by a placeholder object (see child_placeholder).

pub fn is_alive(&self) -> bool

Check if the object associated with this proxy is still alive

Will return false if the object has been destroyed.

If the object is not managed by this library, this will always returns true.

pub fn version(&self) -> u32

Retrieve the interface version of this wayland object instance

Returns 0 on dead objects

pub fn id(&self) -> u32

Retrieve the object id of this wayland object

pub fn user_data<UD: 'static>(&self) -> Option<&UD>

Access the arbitrary payload associated to this object

You need to specify the expected type of this payload, and this function will return None if either the types don't match or you are attempting to access a non Send + Sync user data from the wrong thread.

This value is associated to the Proxy when you implement it, and you cannot access it mutably afterwards. If you need interior mutability, you are responsible for using a Mutex or similar type to achieve it.

pub fn equals(&self, other: &Proxy<I>) -> bool

Check if the other proxy refers to the same underlying wayland object

pub fn child<C: Interface>(&self) -> NewProxy<C>

Create a new child object

Warning: This method is mostly intended to be used by code generated by wayland-scanner, and you should probably never need to use it directly, but rather use the appropriate RequestsTrait for your proxy.

This creates a new wayland object, considered as a child of this object. It will notably inherit its interface version.

The created object should immediately be implemented and sent in a request to the server, to keep the object list properly synchronized. Failure to do so will likely cause a protocol error.

pub fn anonymize(&self) -> Proxy<AnonymousObject>

Creates a handle of this proxy with its actual type erased

pub fn make_wrapper(&self, queue: &QueueToken) -> Result<Proxy<I>, ()>

Create a wrapper for this object for queue management

As assigning a proxy to an event queue can be a racy operation in contexts involving multiple thread, this provides a facility to do this safely.

The wrapper object created behaves like a regular Proxy, except that all objects created as the result of its requests will be assigned to the queue associated to the provided token, rather than the queue of their parent. This does not change the queue of the proxy itself.

pub fn child_placeholder<J: Interface>(&self) -> Proxy<J>

Create a placeholder object, to be used with send_constructor

Warning: This method is mostly intended to be used by code generated by wayland-scanner, and you should probably never need to use it directly, but rather use the appropriate RequestsTrait for your proxy.

pub fn is_external(&self) -> bool

Check whether this proxy is managed by the library or not

See from_c_ptr for details.

pub fn c_ptr(&self) -> *mut wl_proxy

Get a raw pointer to the underlying wayland object

Retrieve a pointer to the object from the libwayland-client.so library. You will mostly need it to interface with C libraries needing access to wayland objects (to initialize an opengl context for example).

Trait Implementations

impl Deref for Display

type Target = Proxy<WlDisplay>

The resulting type after dereferencing.

fn deref(&self) -> &Proxy<WlDisplay>

Dereferences the value.