136 lines
No EOL
22 KiB
HTML
136 lines
No EOL
22 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Interface for interacting with the Wayland protocol, client-side."><title>cosmic::cctk::sctk::reexports::client - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../../../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../../../static.files/rustdoc-aa0817cf.css"><meta name="rustdoc-vars" data-root-path="../../../../../" data-static-root-path="../../../../../static.files/" data-current-crate="cosmic" data-themes="" data-resource-suffix="" data-rustdoc-version="1.90.0-nightly (3048886e5 2025-07-30)" data-channel="nightly" data-search-js="search-fa3e91e5.js" data-settings-js="settings-5514c975.js" ><script src="../../../../../static.files/storage-68b7e25d.js"></script><script defer src="../../../../../crates.js"></script><script defer src="../../../../../static.files/main-eebb9057.js"></script><noscript><link rel="stylesheet" href="../../../../../static.files/noscript-32bb7600.css"></noscript><link rel="alternate icon" type="image/png" href="../../../../../static.files/favicon-32x32-6580c154.png"><link rel="icon" type="image/svg+xml" href="../../../../../static.files/favicon-044be391.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../../../cosmic/index.html">cosmic</a><span class="version">1.0.0</span></h2></div><div class="sidebar-elems"><ul class="block"><li><a id="all-types" href="all.html">All Items</a></li></ul><section id="rustdoc-toc"><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#general-concepts" title="General concepts">General concepts</a></li><li><a href="#event-dispatching" title="Event dispatching">Event dispatching</a><ul><li><a href="#the-dispatch-trait-and-dispatch-delegation" title="The `Dispatch` trait and dispatch delegation">The <code>Dispatch</code> trait and dispatch delegation</a></li></ul></li><li><a href="#getting-started-example" title="Getting started example">Getting started example</a></li><li><a href="#advanced-use" title="Advanced use">Advanced use</a><ul><li><a href="#bypassing-dispatch" title="Bypassing `Dispatch`">Bypassing <code>Dispatch</code></a></li><li><a href="#interaction-with-ffi" title="Interaction with FFI">Interaction with FFI</a></li></ul></li></ul><h3><a href="#modules">Crate Items</a></h3><ul class="block"><li><a href="#modules" title="Modules">Modules</a></li><li><a href="#macros" title="Macros">Macros</a></li><li><a href="#structs" title="Structs">Structs</a></li><li><a href="#enums" title="Enums">Enums</a></li><li><a href="#traits" title="Traits">Traits</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="../index.html">In cosmic::<wbr>cctk::<wbr>sctk::<wbr>reexports</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../../../index.html">cosmic</a>::<wbr><a href="../../../index.html">cctk</a>::<wbr><a href="../../index.html">sctk</a>::<wbr><a href="../index.html">reexports</a></div><h1>Crate <span>client</span><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"></span></div><span class="item-info"><div class="stab portability">Available on <strong>crate feature <code>wayland</code> and Linux</strong> only.</div></span><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Interface for interacting with the Wayland protocol, client-side.</p>
|
||
<h3 id="general-concepts"><a class="doc-anchor" href="#general-concepts">§</a>General concepts</h3>
|
||
<p>This crate is structured around four main objects: the <a href="struct.Connection.html" title="struct cosmic::cctk::sctk::reexports::client::Connection"><code>Connection</code></a> and <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a> structs,
|
||
proxies (objects implementing the <a href="trait.Proxy.html" title="trait cosmic::cctk::sctk::reexports::client::Proxy"><code>Proxy</code></a> trait), and the <a href="trait.Dispatch.html" title="trait cosmic::cctk::sctk::reexports::client::Dispatch"><code>Dispatch</code></a> trait.</p>
|
||
<p>The <a href="struct.Connection.html" title="struct cosmic::cctk::sctk::reexports::client::Connection"><code>Connection</code></a> is the heart of this crate. It represents your connection to the Wayland server, and
|
||
you’ll generally initialize it using the <a href="struct.Connection.html#method.connect_to_env" title="associated function cosmic::cctk::sctk::reexports::client::Connection::connect_to_env"><code>Connection::connect_to_env()</code></a> method, which will
|
||
attempt to open a Wayland connection following the configuration specified by the ! environment.</p>
|
||
<p>Once you have a <a href="struct.Connection.html" title="struct cosmic::cctk::sctk::reexports::client::Connection"><code>Connection</code></a>, you can create an <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a> from it. This <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a> will take
|
||
care of processing events from the Wayland server and delivering them to your processing logic, in the form
|
||
of a state struct with several <a href="trait.Dispatch.html" title="trait cosmic::cctk::sctk::reexports::client::Dispatch"><code>Dispatch</code></a> implementations (see below).</p>
|
||
<p>Each of the Wayland objects you can manipulate is represented by a struct implementing the <a href="trait.Proxy.html" title="trait cosmic::cctk::sctk::reexports::client::Proxy"><code>Proxy</code></a>
|
||
trait. Those structs are automatically generated from the wayland XML protocol specification. This crate
|
||
provides the types generated from the core protocol in the <a href="protocol/index.html" title="mod cosmic::cctk::sctk::reexports::client::protocol"><code>protocol</code></a> module. For other standard
|
||
protocols, see the <code>wayland-protocols</code> crate.</p>
|
||
<h3 id="event-dispatching"><a class="doc-anchor" href="#event-dispatching">§</a>Event dispatching</h3>
|
||
<p>The core event dispatching logic provided by this crate is built around the <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a> struct. In
|
||
this paradigm, receiving and processing events is a two-step process:</p>
|
||
<ul>
|
||
<li>First, events are read from the Wayland socket. For each event, the backend figures out which <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a>
|
||
manages it, and enqueues the event in an internal buffer of that queue.</li>
|
||
<li>Then, the <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a> empties its internal buffer by sequentially invoking the appropriate
|
||
<a href="trait.Dispatch.html#tymethod.event" title="associated function cosmic::cctk::sctk::reexports::client::Dispatch::event"><code>Dispatch::event()</code></a> method on the <code>State</code> value that was provided to it.</li>
|
||
</ul>
|
||
<p>The main goal of this structure is to make your <code>State</code> accessible without synchronization to most of
|
||
your event-processing logic, to reduce the plumbing costs. See <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a>’s documentation for
|
||
explanations of how to use it to drive your event loop, and when and how to use multiple
|
||
event queues in your app.</p>
|
||
<h4 id="the-dispatch-trait-and-dispatch-delegation"><a class="doc-anchor" href="#the-dispatch-trait-and-dispatch-delegation">§</a>The <a href="trait.Dispatch.html" title="trait cosmic::cctk::sctk::reexports::client::Dispatch"><code>Dispatch</code></a> trait and dispatch delegation</h4>
|
||
<p>In this paradigm, your <code>State</code> needs to implement <code>Dispatch<O, _></code> for every Wayland object <code>O</code> it needs to
|
||
process events for. This is ensured by the fact that, whenever creating an object using the methods on
|
||
an other object, you need to pass a <a href="struct.QueueHandle.html" title="struct cosmic::cctk::sctk::reexports::client::QueueHandle"><code>QueueHandle<State></code></a> from the <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a> that will be
|
||
managing the newly created object.</p>
|
||
<p>However, implementing all those traits on your own is a lot of (often uninteresting) work. To make this
|
||
easier a composition mechanism is provided using the <a href="macro.delegate_dispatch.html" title="macro cosmic::cctk::sctk::reexports::client::delegate_dispatch"><code>delegate_dispatch!</code></a> macro. This way, another
|
||
library (such as Smithay’s Client Toolkit) can provide generic <a href="trait.Dispatch.html" title="trait cosmic::cctk::sctk::reexports::client::Dispatch"><code>Dispatch</code></a> implementations that you
|
||
can reuse in your own app by delegating those objects to that provided implementation. See the
|
||
documentation of those traits and macro for details.</p>
|
||
<h3 id="getting-started-example"><a class="doc-anchor" href="#getting-started-example">§</a>Getting started example</h3>
|
||
<p>As an overview of how this crate is used, here is a commented example of a program that connects to the
|
||
Wayland server and lists the globals this server advertised through the <code>wl_registry</code>:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>wayland_client::{protocol::wl_registry, Connection, Dispatch, QueueHandle};
|
||
<span class="comment">// This struct represents the state of our app. This simple app does not
|
||
// need any state, but this type still supports the `Dispatch` implementations.
|
||
</span><span class="kw">struct </span>AppData;
|
||
|
||
<span class="comment">// Implement `Dispatch<WlRegistry, ()> for our state. This provides the logic
|
||
// to be able to process events for the wl_registry interface.
|
||
//
|
||
// The second type parameter is the user-data of our implementation. It is a
|
||
// mechanism that allows you to associate a value to each particular Wayland
|
||
// object, and allow different dispatching logic depending on the type of the
|
||
// associated value.
|
||
//
|
||
// In this example, we just use () as we don't have any value to associate. See
|
||
// the `Dispatch` documentation for more details about this.
|
||
</span><span class="kw">impl </span>Dispatch<wl_registry::WlRegistry, ()> <span class="kw">for </span>AppData {
|
||
<span class="kw">fn </span>event(
|
||
_state: <span class="kw-2">&mut </span><span class="self">Self</span>,
|
||
<span class="kw">_</span>: <span class="kw-2">&</span>wl_registry::WlRegistry,
|
||
event: wl_registry::Event,
|
||
<span class="kw">_</span>: <span class="kw-2">&</span>(),
|
||
<span class="kw">_</span>: <span class="kw-2">&</span>Connection,
|
||
<span class="kw">_</span>: <span class="kw-2">&</span>QueueHandle<AppData>,
|
||
) {
|
||
<span class="comment">// When receiving events from the wl_registry, we are only interested in the
|
||
// `global` event, which signals a new available global.
|
||
// When receiving this event, we just print its characteristics in this example.
|
||
</span><span class="kw">if let </span>wl_registry::Event::Global { name, interface, version } = event {
|
||
<span class="macro">println!</span>(<span class="string">"[{}] {} (v{})"</span>, name, interface, version);
|
||
}
|
||
}
|
||
}
|
||
|
||
<span class="comment">// The main function of our program
|
||
</span><span class="kw">fn </span>main() {
|
||
<span class="comment">// Create a Wayland connection by connecting to the server through the
|
||
// environment-provided configuration.
|
||
</span><span class="kw">let </span>conn = Connection::connect_to_env().unwrap();
|
||
|
||
<span class="comment">// Retrieve the WlDisplay Wayland object from the connection. This object is
|
||
// the starting point of any Wayland program, from which all other objects will
|
||
// be created.
|
||
</span><span class="kw">let </span>display = conn.display();
|
||
|
||
<span class="comment">// Create an event queue for our event processing
|
||
</span><span class="kw">let </span><span class="kw-2">mut </span>event_queue = conn.new_event_queue();
|
||
<span class="comment">// And get its handle to associate new objects to it
|
||
</span><span class="kw">let </span>qh = event_queue.handle();
|
||
|
||
<span class="comment">// Create a wl_registry object by sending the wl_display.get_registry request.
|
||
// This method takes two arguments: a handle to the queue that the newly created
|
||
// wl_registry will be assigned to, and the user-data that should be associated
|
||
// with this registry (here it is () as we don't need user-data).
|
||
</span><span class="kw">let </span>_registry = display.get_registry(<span class="kw-2">&</span>qh, ());
|
||
|
||
<span class="comment">// At this point everything is ready, and we just need to wait to receive the events
|
||
// from the wl_registry. Our callback will print the advertised globals.
|
||
</span><span class="macro">println!</span>(<span class="string">"Advertised globals:"</span>);
|
||
|
||
<span class="comment">// To actually receive the events, we invoke the `roundtrip` method. This method
|
||
// is special and you will generally only invoke it during the setup of your program:
|
||
// it will block until the server has received and processed all the messages you've
|
||
// sent up to now.
|
||
//
|
||
// In our case, that means it'll block until the server has received our
|
||
// wl_display.get_registry request, and as a reaction has sent us a batch of
|
||
// wl_registry.global events.
|
||
//
|
||
// `roundtrip` will then empty the internal buffer of the queue it has been invoked
|
||
// on, and thus invoke our `Dispatch` implementation that prints the list of advertised
|
||
// globals.
|
||
</span>event_queue.roundtrip(<span class="kw-2">&mut </span>AppData).unwrap();
|
||
}</code></pre></div>
|
||
<h3 id="advanced-use"><a class="doc-anchor" href="#advanced-use">§</a>Advanced use</h3><h4 id="bypassing-dispatch"><a class="doc-anchor" href="#bypassing-dispatch">§</a>Bypassing <a href="trait.Dispatch.html" title="trait cosmic::cctk::sctk::reexports::client::Dispatch"><code>Dispatch</code></a></h4>
|
||
<p>It may be that for some of your objects, handling them via the <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a> is impractical. For example,
|
||
if processing the events from those objects doesn’t require accessing some global state, and/or you need to
|
||
handle them in a context where cranking an event loop is impractical.</p>
|
||
<p>In those contexts, this crate also provides some escape hatches to directly interface with the low-level
|
||
APIs from <code>wayland-backend</code>, allowing you to register callbacks for those objects that will be invoked
|
||
whenever they receive an event and <em>any</em> event queue from the program is being dispatched. Those
|
||
callbacks are more constrained: they don’t get a <code>&mut State</code> reference, and must be threadsafe. See
|
||
<a href="trait.Proxy.html#tymethod.send_constructor" title="method cosmic::cctk::sctk::reexports::client::Proxy::send_constructor"><code>Proxy::send_constructor()</code></a> and <a href="backend/trait.ObjectData.html" title="trait cosmic::cctk::sctk::reexports::client::backend::ObjectData"><code>ObjectData</code></a> for details about how to
|
||
assign such callbacks to objects.</p>
|
||
<h4 id="interaction-with-ffi"><a class="doc-anchor" href="#interaction-with-ffi">§</a>Interaction with FFI</h4>
|
||
<p>It can happen that you’ll need to interact with Wayland states accross FFI. A typical example would be if
|
||
you need to use the <a href="https://docs.rs/raw-window-handle/"><code>raw-window-handle</code></a> crate.</p>
|
||
<p>In this case, you’ll need enable the <code>system</code> feature to use the <code>libwayland</code> backend of
|
||
<code>wayland-backend</code>.</p>
|
||
<ul>
|
||
<li>If you need to send pointers to FFI, you can retrive the <code>*mut wl_proxy</code> pointers from the proxies by
|
||
first getting the <a href="backend/struct.ObjectId.html" title="struct cosmic::cctk::sctk::reexports::client::backend::ObjectId"><code>ObjectId</code></a> using the <a href="trait.Proxy.html#tymethod.id" title="method cosmic::cctk::sctk::reexports::client::Proxy::id"><code>Proxy::id()</code></a> method, and then
|
||
using the <a href="backend/struct.ObjectId.html#method.as_ptr" title="method cosmic::cctk::sctk::reexports::client::backend::ObjectId::as_ptr"><code>ObjectId::as_ptr()</code></a> method.</li>
|
||
</ul>
|
||
</div></details><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><dl class="item-table"><dt><a class="mod" href="backend/index.html" title="mod cosmic::cctk::sctk::reexports::client::backend">backend</a></dt><dd>Backend reexports</dd><dt><a class="mod" href="globals/index.html" title="mod cosmic::cctk::sctk::reexports::client::globals">globals</a></dt><dd>Helpers for handling the initialization of an app</dd><dt><a class="mod" href="protocol/index.html" title="mod cosmic::cctk::sctk::reexports::client::protocol">protocol</a></dt><dd>Generated protocol definitions</dd></dl><h2 id="macros" class="section-header">Macros<a href="#macros" class="anchor">§</a></h2><dl class="item-table"><dt><a class="macro" href="macro.delegate_dispatch.html" title="macro cosmic::cctk::sctk::reexports::client::delegate_dispatch">delegate_<wbr>dispatch</a></dt><dd>A helper macro which delegates a set of <a href="trait.Dispatch.html" title="trait cosmic::cctk::sctk::reexports::client::Dispatch"><code>Dispatch</code></a> implementations for proxies to some other type which
|
||
provides a generic <a href="trait.Dispatch.html" title="trait cosmic::cctk::sctk::reexports::client::Dispatch"><code>Dispatch</code></a> implementation.</dd><dt><a class="macro" href="macro.delegate_noop.html" title="macro cosmic::cctk::sctk::reexports::client::delegate_noop">delegate_<wbr>noop</a></dt><dd>A helper macro which delegates a set of <a href="trait.Dispatch.html" title="trait cosmic::cctk::sctk::reexports::client::Dispatch"><code>Dispatch</code></a> implementations for proxies to a static handler.</dd><dt><a class="macro" href="macro.event_created_child.html" title="macro cosmic::cctk::sctk::reexports::client::event_created_child">event_<wbr>created_<wbr>child</a></dt><dd>Macro used to override <a href="trait.Dispatch.html#method.event_created_child" title="associated function cosmic::cctk::sctk::reexports::client::Dispatch::event_created_child"><code>Dispatch::event_created_child()</code></a></dd></dl><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><dl class="item-table"><dt><a class="struct" href="struct.Connection.html" title="struct cosmic::cctk::sctk::reexports::client::Connection">Connection</a></dt><dd>The Wayland connection</dd><dt><a class="struct" href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue">Event<wbr>Queue</a></dt><dd>An event queue</dd><dt><a class="struct" href="struct.QueueFreezeGuard.html" title="struct cosmic::cctk::sctk::reexports::client::QueueFreezeGuard">Queue<wbr>Freeze<wbr>Guard</a></dt><dd>A handle that temporarily pauses event processing on an <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a>.</dd><dt><a class="struct" href="struct.QueueHandle.html" title="struct cosmic::cctk::sctk::reexports::client::QueueHandle">Queue<wbr>Handle</a></dt><dd>A handle representing an <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a>, used to assign objects upon creation.</dd><dt><a class="struct" href="struct.QueueProxyData.html" title="struct cosmic::cctk::sctk::reexports::client::QueueProxyData">Queue<wbr>Proxy<wbr>Data</a></dt><dd>The <a href="backend/trait.ObjectData.html" title="trait cosmic::cctk::sctk::reexports::client::backend::ObjectData"><code>ObjectData</code></a> implementation used by Wayland proxies, integrating with <a href="trait.Dispatch.html" title="trait cosmic::cctk::sctk::reexports::client::Dispatch"><code>Dispatch</code></a></dd><dt><a class="struct" href="struct.Weak.html" title="struct cosmic::cctk::sctk::reexports::client::Weak">Weak</a></dt><dd>A weak handle to a Wayland object</dd></dl><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><dl class="item-table"><dt><a class="enum" href="enum.ConnectError.html" title="enum cosmic::cctk::sctk::reexports::client::ConnectError">Connect<wbr>Error</a></dt><dd>An error when trying to establish a Wayland connection.</dd><dt><a class="enum" href="enum.DispatchError.html" title="enum cosmic::cctk::sctk::reexports::client::DispatchError">Dispatch<wbr>Error</a></dt><dd>Wayland dispatching error</dd><dt><a class="enum" href="enum.WEnum.html" title="enum cosmic::cctk::sctk::reexports::client::WEnum">WEnum</a></dt><dd>An enum value in the protocol.</dd></dl><h2 id="traits" class="section-header">Traits<a href="#traits" class="anchor">§</a></h2><dl class="item-table"><dt><a class="trait" href="trait.Dispatch.html" title="trait cosmic::cctk::sctk::reexports::client::Dispatch">Dispatch</a></dt><dd>A trait for handlers of proxies’ events delivered to an <a href="struct.EventQueue.html" title="struct cosmic::cctk::sctk::reexports::client::EventQueue"><code>EventQueue</code></a>.</dd><dt><a class="trait" href="trait.Proxy.html" title="trait cosmic::cctk::sctk::reexports::client::Proxy">Proxy</a></dt><dd>Trait representing a Wayland interface</dd></dl></section></div></main></body></html> |