Struct wayland_client::Display
source · pub struct Display {
pub(crate) inner: Arc<DisplayInner>,
}Expand description
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.
Safety note: If you activate the use_system_lib cargo feature and provide pointers
to wayland objects to other libraries, you must ensure that these libraries clean up
their state before the last clone of this Display is dropped, otherwise these libraries
will access freed memory when doing their cleanup.
Fields§
§inner: Arc<DisplayInner>Implementations§
source§impl Display
impl Display
sourcepub fn connect_to_env() -> Result<Display, ConnectError>
pub fn connect_to_env() -> Result<Display, 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.
This requires the XDG_RUNTIME_DIR variable to be properly set.
sourcepub fn connect_to_name<S: Into<OsString>>(
name: S
) -> Result<Display, ConnectError>
pub fn connect_to_name<S: Into<OsString>>( name: S ) -> Result<Display, 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.
sourcepub unsafe fn from_fd(fd: RawFd) -> Result<Display, ConnectError>
pub unsafe fn from_fd(fd: RawFd) -> Result<Display, 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.
Will take ownership of the FD.
Safety
The file descriptor must be associated to a connected unix socket.
sourcepub fn flush(&self) -> Result<()>
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.
sourcepub fn create_event_queue(&self) -> EventQueue
pub fn create_event_queue(&self) -> EventQueue
Create a new event queue associated with this wayland connection
sourcepub fn protocol_error(&self) -> Option<ProtocolError>
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.
sourcepub fn get_connection_fd(&self) -> RawFd
pub fn get_connection_fd(&self) -> RawFd
Retrieve the file descriptor associated with the wayland socket
This FD should only be used to integrate into a polling mechanism, and should never be directly read from or written to.
sourcepub unsafe fn from_external_display(display_ptr: *mut wl_display) -> Display
pub unsafe fn from_external_display(display_ptr: *mut wl_display) -> Display
Create a Display and from an external display
This allows you to interface with an already-existing wayland connection, for example provided by a GUI toolkit.
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.
Safety
The provided pointer must point to a valid wl_display from libwayland-client
sourcepub fn get_display_ptr(&self) -> *mut wl_display
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>>§
sourcepub fn send<J>(&self, msg: I::Request, version: Option<u32>) -> Option<Main<J>>where
J: Interface + AsRef<Proxy<J>> + From<Proxy<J>>,
pub fn send<J>(&self, msg: I::Request, version: Option<u32>) -> Option<Main<J>>where J: Interface + AsRef<Proxy<J>> + From<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 methods on the Rust object.
This is the generic method to send requests.
sourcepub fn is_alive(&self) -> bool
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 (if it was created from a raw
pointer from some other library your program interfaces with), this will always
returns true.
sourcepub fn version(&self) -> u32
pub fn version(&self) -> u32
Retrieve the interface version of this wayland object instance
Returns 0 on dead objects
sourcepub fn user_data(&self) -> &UserData
pub fn user_data(&self) -> &UserData
Access the UserData associated to this object
Each wayland object has an associated UserData, that can store a payload of arbitrary type and is shared by all proxies of this object.
See UserData documentation for more details.
sourcepub fn equals(&self, other: &Proxy<I>) -> bool
pub fn equals(&self, other: &Proxy<I>) -> bool
Check if the other proxy refers to the same underlying wayland object
You can also use the PartialEq implementation.
sourcepub fn attach(&self, token: QueueToken) -> Attached<I>
pub fn attach(&self, token: QueueToken) -> Attached<I>
Attach this proxy to the event queue represented by this token
Once a proxy is attached, you can use it to send requests that create new objects. These new objects will be handled by the event queue represented by the provided token.
This does not impact the events received by this object, which are still handled by their original event queue.
sourcepub fn is_external(&self) -> bool
pub fn is_external(&self) -> bool
Check whether this proxy is managed by the library or not
See from_c_ptr for details.
NOTE: This method will panic if called while the use_system_lib feature is
not activated.
sourcepub fn c_ptr(&self) -> *mut wl_proxy
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).
NOTE: This method will panic if called while the use_system_lib feature is
not activated.