      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    273
    274
    275
    276
    277
    278
    279
    280
    281
    282
    283
    284
    285
    286
    287
    288
    289
    290
    291
    292
    293
    294
    295
    296
    297
    298
    299
    300
    301
    302
    303
    304
    305
    306
    307
    308
    309
    310
    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326
    327
    328
    329
    330
    331
    332
    333
    334
    335
    336
    337
    338
    339
    340
    341
    342
    343
    344
    345
    346
    347
    348
    349
    350
    351
    352
    353
    354
    355
    356
    357
    358
    359
    360
    361

    use wayland_commons::utils::UserData;
    use wayland_commons::{AnonymousObject, Interface};

    #[cfg(feature = "native_lib")]
    use wayland_sys::client::*;

    use event_queue::QueueToken;

    use imp::{NewProxyInner, ProxyInner};

    use wayland_commons::MessageGroup;
    use ProxyMap;

    /// 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
    /// you need to import the associated `RequestsTrait` trait from the module
    /// of this interface.
    pub struct Proxy<I: Interface> {
        _i: ::std::marker::PhantomData<&'static I>,
        pub(crate) inner: ProxyInner,
    }

    impl<I: Interface> Clone for Proxy<I> {
        fn clone(&self) -> Proxy<I> {
            Proxy {
                _i: ::std::marker::PhantomData,
                inner: self.inner.clone(),
            }
        }
    }

    impl<I: Interface> PartialEq for Proxy<I> {
        fn eq(&self, other: &Proxy<I>) -> bool {
            self.equals(other)
        }
    }

    impl<I: Interface> Eq for Proxy<I> {}

    impl<I: Interface> Proxy<I> {
        pub(crate) fn wrap(inner: ProxyInner) -> Proxy<I> {
            Proxy {
                _i: ::std::marker::PhantomData,
                inner,
            }
        }

        /// 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(&self, msg: I::Request) {
            self.inner.send::<I>(msg)
        }

        /// 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 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>,
        {
            self.inner
                .send_constructor::<I, J>(msg, version)
                .map(NewProxy::wrap)
                .map(implementor)
        }

        /// 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 is_alive(&self) -> bool {
            self.inner.is_alive()
        }

        /// Retrieve the interface version of this wayland object instance
        ///
        /// Returns 0 on dead objects
        pub fn version(&self) -> u32 {
            self.inner.version()
        }

        /// Retrieve the object id of this wayland object
        pub fn id(&self) -> u32 {
            self.inner.id()
        }

        /// 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 user_data<UD: 'static>(&self) -> Option<&UD> {
            self.inner.get_user_data()
        }

        /// Check if the other proxy refers to the same underlying wayland object
        pub fn equals(&self, other: &Proxy<I>) -> bool {
            self.inner.equals(&other.inner)
        }

        /// 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 child<C: Interface>(&self) -> NewProxy<C> {
            NewProxy {
                _i: ::std::marker::PhantomData,
                inner: self.inner.child::<C>(),
            }
        }

        /// Creates a handle of this proxy with its actual type erased
        pub fn anonymize(&self) -> Proxy<AnonymousObject> {
            Proxy {
                _i: ::std::marker::PhantomData,
                inner: self.inner.clone(),
            }
        }

        /// 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 make_wrapper(&self, queue: &QueueToken) -> Result<Proxy<I>, ()> {
            let inner = self.inner.make_wrapper(&queue.inner)?;

            Ok(Proxy {
                _i: ::std::marker::PhantomData,
                inner,
            })
        }

        /// 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 child_placeholder<J: Interface>(&self) -> Proxy<J> {
            Proxy::wrap(self.inner.child_placeholder())
        }
    }

    #[cfg(feature = "native_lib")]
    impl<I: Interface> Proxy<I> {
        /// Check whether this proxy is managed by the library or not
        ///
        /// See `from_c_ptr` for details.
        pub fn is_external(&self) -> bool {
            self.inner.is_external()
        }

        /// 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).
        pub fn c_ptr(&self) -> *mut wl_proxy {
            self.inner.c_ptr()
        }

        /// 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 `false` 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 pointer to this object.
        ///
        /// In order to handle protocol races, invoking it with a NULL pointer will
        /// create an already-dead object.
        pub unsafe fn from_c_ptr(ptr: *mut wl_proxy) -> Proxy<I> {
            Proxy {
                _i: ::std::marker::PhantomData,
                inner: ProxyInner::from_c_ptr::<I>(ptr),
            }
        }
    }

    #[cfg(feature = "native_lib")]
    impl Proxy<::protocol::wl_display::WlDisplay> {
        pub(crate) unsafe fn from_c_display_wrapper(
            ptr: *mut wl_proxy,
        ) -> Proxy<::protocol::wl_display::WlDisplay> {
            Proxy {
                _i: ::std::marker::PhantomData,
                inner: ProxyInner::from_c_display_wrapper(ptr),
            }
        }
    }

    /// A newly-created proxy that needs implementation
    ///
    /// Whenever a new wayland object is created, you will
    /// receive it as a `NewProxy`. You then have to provide an
    /// implementation for it, in order to process the incoming
    /// events it may receive. Once this done you will be able
    /// to use it as a regular `Proxy`.
    ///
    /// Implementations are structs implementing the appropriate
    /// variant of the `Implementation` trait. They can also be
    /// closures.
    pub struct NewProxy<I: Interface> {
        _i: ::std::marker::PhantomData<*const I>,
        pub(crate) inner: NewProxyInner,
    }

    impl<I: Interface + 'static> NewProxy<I> {
        #[allow(dead_code)]
        pub(crate) fn wrap(inner: NewProxyInner) -> NewProxy<I> {
            NewProxy {
                _i: ::std::marker::PhantomData,
                inner,
            }
        }

        /// Implement this proxy using given function and implementation data.
        pub fn implement<F, UD>(self, implementation: F, user_data: UD) -> Proxy<I>
        where
            F: FnMut(I::Event, Proxy<I>) + Send + 'static,
            UD: Send + Sync + 'static,
            I::Event: MessageGroup<Map = ProxyMap>,
        {
            let inner = unsafe {
                self.inner
                    .implement::<I, _>(implementation, UserData::new_threadsafe(user_data))
            };
            Proxy {
                _i: ::std::marker::PhantomData,
                inner: inner,
            }
        }

        /// Implement this proxy using given function and implementation data.
        ///
        /// This method allows the implementation to not be `Send`, but requires for
        /// safety that you provide a token to the event queue this proxy will be implemented
        /// on. This method will then ensure that this proxy is registered on this event queue,
        /// so that it cannot be dispatched from an other thread.
        ///
        /// **Unsafety:**
        ///
        /// This call can be racy if the proxy is not already registered on this event queue and its
        /// old queue is being dispatched from an other thread.
        ///
        /// To ensure safety, see `Proxy::make_wrapper`.
        pub unsafe fn implement_nonsend<Impl, UD>(
            self,
            implementation: Impl,
            user_data: UD,
            queue: &QueueToken,
        ) -> Proxy<I>
        where
            Impl: FnMut(I::Event, Proxy<I>) + 'static,
            UD: 'static,
            I::Event: MessageGroup<Map = ProxyMap>,
        {
            #[cfg(feature = "native_lib")]
            {
                queue.inner.assign_proxy(self.inner.c_ptr());
            }
            #[cfg(not(feature = "native_lib"))]
            {
                self.inner.assign_queue(&queue.inner);
            }
            let inner = self
                .inner
                .implement::<I, _>(implementation, UserData::new(user_data));
            Proxy {
                _i: ::std::marker::PhantomData,
                inner: inner,
            }
        }
    }

    #[cfg(feature = "native_lib")]
    impl<I: Interface + 'static> NewProxy<I> {
        /// 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).
        ///
        /// Use this if you need to pass an unimplemented object to the C library
        /// you are interfacing with.
        pub fn c_ptr(&self) -> *mut wl_proxy {
            self.inner.c_ptr()
        }

        /// Create a `NewProxy` instance from a C pointer.
        ///
        /// By doing so, you assert that this wayland object was newly created and
        /// can be safely implemented. As implementing it will overwrite any previously
        /// associated data or implementation, this can cause weird errors akin to
        /// memory corruption if it was not the case.
        pub unsafe fn from_c_ptr(ptr: *mut wl_proxy) -> Self {
            NewProxy {
                _i: ::std::marker::PhantomData,
                inner: NewProxyInner::from_c_ptr(ptr),
            }
        }
    }

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)