Struct wayland_client::Proxy
source · pub struct Proxy<I: Interface> { /* private fields */ }
Expand description
An handle to a wayland proxy
This represents a wayland object instantiated in your client session. Several handles to the same object can exist at a given time, and cloning them won’t create a new protocol object, only clone the handle. The lifetime of the protocol object is not tied to the lifetime of these handles, but rather to sending or receiving destroying messages.
These handles are notably used to send requests to the server. To do this
you need to convert them to the corresponding Rust object (using .into()
)
and use methods on the Rust object.
This handle is the most conservative one: it can be sent between threads, but you cannot send any message that would create a new object using it. You must attach it to a event queue, that will host the newly created objects.
Implementations§
source§impl<I> Proxy<I>
impl<I> Proxy<I>
sourcepub fn send<J>(&self, msg: I::Request, version: Option<u32>) -> Option<Main<J>>
pub fn send<J>(&self, msg: I::Request, version: Option<u32>) -> Option<Main<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 anonymize(self) -> Proxy<AnonymousObject>
pub fn anonymize(self) -> Proxy<AnonymousObject>
Erase the actual type of this proxy
source§impl Proxy<AnonymousObject>
impl Proxy<AnonymousObject>
sourcepub fn deanonymize<I: Interface>(self) -> Result<Proxy<I>, Self>
pub fn deanonymize<I: Interface>(self) -> Result<Proxy<I>, Self>
Attempt to recover the typed variant of an anonymous proxy
source§impl<I: Interface + AsRef<Proxy<I>> + From<Proxy<I>>> Proxy<I>
impl<I: Interface + AsRef<Proxy<I>> + From<Proxy<I>>> Proxy<I>
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.
sourcepub unsafe fn from_c_ptr(_ptr: *mut wl_proxy) -> Proxy<I>
pub unsafe fn from_c_ptr(_ptr: *mut wl_proxy) -> Proxy<I>
Create a Proxy
instance from a C pointer
Create a Proxy
from a raw pointer to a wayland object from the
C library.
If the pointer was previously obtained by the c_ptr()
method, this
constructs a new proxy for the same object just like the clone()
method would have.
If the object was created by some other C library you are interfacing
with, it will be created in an “unmanaged” state: wayland-client will
treat it as foreign, and as such most of the safeties will be absent.
Notably the lifetime of the object can’t be tracked, so the alive()
method will always return true
and you are responsible of not using
an object past its destruction (as this would cause a protocol error).
You will also be unable to associate any user data value to this object.
In order to handle protocol races, invoking it with a NULL pointer will create an already-dead object.
NOTE: This method will panic if called while the use_system_lib
feature is
not activated.
Safety
The provided pointer must point to a valid wayland object from libwayland-client
with the correct interface.