-Copyright © 2008-2012 Kristian Høgsberg
-Copyright © 2010-2012 Intel Corporation
-Copyright © 2011 Benjamin Franzke
-Copyright © 2012 Collabora, Ltd.
-Copyright © 2015 Samsung Electronics co., Ltd. All Rights Reserved.
+Copyright © 2008-2013 Kristian Høgsberg
+Copyright © 2010-2013 Intel Corporation
+Copyright © 2013 Rafael Antognolli
+Copyright © 2013 Jasper St. Pierre
+Copyright © 2014 Jonas Ådahl
+Copyright © 2014 Jason Ekstrand
+Copyright © 2014-2015 Collabora, Ltd.
+Copyright © 2015 Red Hat Inc.
+Copyright © 2011 Benjamin Franzke
+Copyright © 2015-2017 Samsung Electronics co., Ltd. All Rights Reserved.
-Permission to use, copy, modify, distribute, and sell this software and its
-documentation for any purpose is hereby granted without fee, provided that
-the above copyright notice appear in all copies and that both that copyright
-notice and this permission notice appear in supporting documentation, and
-that the name of the copyright holders not be used in advertising or
-publicity pertaining to distribution of the software without specific,
-written prior permission. The copyright holders make no representations
-about the suitability of this software for any purpose. It is provided "as
-is" without express or implied warranty.
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
-THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
-INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
-EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
-CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
-DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
-TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
-OF THIS SOFTWARE.
+The above copyright notice and this permission notice (including the next
+paragraph) shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+---
+
+The above is the version of the MIT "Expat" License used by X.org:
+
+ http://cgit.freedesktop.org/xorg/xserver/tree/COPYING
-INCLUDES = -I$(top_builddir)/protocol/tizen -I$(top_srcdir)/src
+AM_CPPFLAGS = \
+ -I$(top_builddir)/protocol/tizen \
+ -I$(top_srcdir)/src \
+ $(NULL)
pkgconfigdir = $(libdir)/pkgconfig
protocoldir = $(libdir)
libtizen_surface_client_la_SOURCES = protocol/tizen-surface-protocol.c
libtizen_surface_client_la_CFLAGS = @WAYLAND_CLIENT_CFLAGS@
libtizen_surface_client_la_LIBADD = @WAYLAND_CLIENT_LIBS@
+
+### wayland-protocols
+unstable_protocols = \
+ protocol/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml \
+ protocol/unstable/fullscreen-shell/fullscreen-shell-unstable-v1.xml \
+ protocol/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml \
+ protocol/unstable/text-input/text-input-unstable-v1.xml \
+ protocol/unstable/input-method/input-method-unstable-v1.xml \
+ protocol/unstable/xdg-shell/xdg-shell-unstable-v5.xml \
+ protocol/unstable/xdg-shell/xdg-shell-unstable-v6.xml \
+ protocol/unstable/relative-pointer/relative-pointer-unstable-v1.xml \
+ protocol/unstable/pointer-constraints/pointer-constraints-unstable-v1.xml \
+ protocol/unstable/tablet/tablet-unstable-v1.xml \
+ protocol/unstable/tablet/tablet-unstable-v2.xml \
+ protocol/unstable/xdg-foreign/xdg-foreign-unstable-v1.xml \
+ protocol/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml \
+ protocol/unstable/idle-inhibit/idle-inhibit-unstable-v1.xml \
+ protocol/unstable/xwayland-keyboard-grab/xwayland-keyboard-grab-unstable-v1.xml \
+ protocol/unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml \
+ protocol/unstable/xdg-output/xdg-output-unstable-v1.xml \
+ $(NULL)
+
+stable_protocols = \
+ protocol/stable/presentation-time/presentation-time.xml \
+ protocol/stable/viewporter/viewporter.xml \
+ $(NULL)
+
+nobase_dist_pkgdata_DATA = \
+ $(unstable_protocols) \
+ $(stable_protocols) \
+ $(NULL)
+
+dist_noinst_DATA = \
+ $(sort $(foreach p,$(unstable_protocols),$(dir $p)README)) \
+ $(sort $(foreach p,$(stable_protocols),$(dir $p)README)) \
+ $(NULL)
+
+pkgconfig_DATA += src/wayland-protocols.pc
+
+dist_check_SCRIPTS = tests/scan.sh
+
+TESTS = $(unstable_protocols) $(stable_protocols)
+TEST_EXTENSIONS = .xml
+AM_TESTS_ENVIRONMENT = SCANNER='$(wayland_scanner)'; export SCANNER;
+XML_LOG_COMPILER = $(srcdir)/tests/scan.sh
--- /dev/null
+Wayland protocols
+-----------------
+
+wayland-protocols contains Wayland protocols that add functionality not
+available in the Wayland core protocol. Such protocols either add
+completely new functionality, or extend the functionality of some other
+protocol either in Wayland core, or some other protocol in
+wayland-protocols.
+
+A protocol in wayland-protocols consists of a directory containing a set
+of XML files containing the protocol specification, and a README file
+containing detailed state and a list of maintainers.
+
+Protocol directory tree structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Protocols may be 'stable', 'unstable' or 'deprecated', and the interface
+and protocol names as well as place in the directory tree will reflect
+this.
+
+A stable protocol is a protocol which has been declared stable by
+the maintainers. Changes to such protocols will always be backward
+compatible.
+
+An unstable protocol is a protocol currently under development and this
+will be reflected in the protocol and interface names. See <<Unstable
+naming convention>>.
+
+A deprecated protocol is a protocol that has either been replaced by some
+other protocol, or declared undesirable for some other reason. No more
+changes will be made to a deprecated protocol.
+
+Depending on which of the above states the protocol is in, the protocol
+is placed within the toplevel directory containing the protocols with the
+same state. Stable protocols are placed in the +stable/+ directory,
+unstable protocols are placed in the +unstable/+ directory, and
+deprecated protocols are placed in the +deprecated/+ directory.
+
+Protocol development procedure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To propose a new protocol, create a patch adding the relevant files and
+Makefile.am entry to the wayland-protocols git repository with the
+explanation and motivation in the commit message. Then send the patch to
+the wayland-devel@lists.freedesktop.org mailing list using
+'git send-email' with the subject prefix 'RFC wayland-protocols' or
+'PATCH wayland-protocols' depending on what state the protocol is in.
+
+To propose changes to existing protocols, create a patch with the
+changes and send it to the list mentioned above while also CC:ing the
+maintainers mentioned in the README file. Use the same rule for adding a
+subject prefix as above and method for sending the patch.
+
+If the changes are backward incompatible changes to an unstable protocol,
+see <<Unstable protocol changes>>.
+
+Interface naming convention
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+All protocols should avoid using generic namespaces or no namespaces in
+the protocol interface names in order to minimize risk that the generated
+C API collides with other C API. Interface names that may collide with
+interface names from other protocols should also be avoided.
+
+For generic protocols not limited to certain configurations (such as
+specific desktop environment or operating system) the +wp_+ prefix
+should be used on all interfaces in the protocol.
+
+For operating system specific protocols, the interfaces should be
+prefixed with both +wp_+ and the operating system, for example
++wp_linux_+, or +wp_freebsd_+, etc.
+
+Unstable naming convention
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Unstable protocols have a special naming convention in order to make it
+possible to make discoverable backward incompatible changes.
+
+An unstable protocol has at least two versions: the major version, which
+represents backward incompatible changes, and the minor version, which
+represents backward compatible changes to the interfaces in the protocol.
+
+The major version is part of the XML file name, the protocol name in the
+XML, and interface names in the protocol.
+
+Minor versions are the version attributes of the interfaces in the XML.
+There may be more than one minor version per protocol, if there are more
+than one global.
+
+The XML file and protocol name also has the word 'unstable' in them, and
+all of the interfaces in the protocol are prefixed with +z+ and
+suffixed with the major version number.
+
+For example, an unstable protocol called foo-bar with major version 2
+containing the two interfaces wp_foo and wp_bar both minor version 1 will
+be placed in the directory +unstable/foo-bar/+ consisting of one file
+called +README+ and one called +foo-bar-unstable-v2.xml+. The XML file
+will consist of two interfaces called +zwp_foo_v2+ and +zwp_bar_v2+ with
+the +version+ attribute set to +1+.
+
+Unstable protocol changes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+During the development of a new protocol it is possible that backward
+incompatible changes are needed. Such a change needs to be represented
+in the major and minor versions of the protocol.
+
+Assuming a backward incompatible change is needed, the procedure for how to
+do so is the following:
+
+ . Make a copy of the XML file with the major version increased by +1+.
+ . Increase the major version number in the protocol XML by +1+.
+ . Increase the major version number in all of the interfaces in the
+ XML by +1+.
+ . Reset the minor version number (interface version attribute) of all
+ the interfaces to +1+.
+
+Backward compatible changes within a major unstable version can be done
+in the regular way as done in core Wayland or in stable protocols.
+
+Declaring a protocol stable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Once it is decided that a protocol should be declared stable, meaning no
+more backward incompatible changes will ever be allowed, one last
+breakage is needed.
+
+The procedure of doing this is the following:
+
+ . Create a new directory in the +stable/+ toplevel directory with the
+ same name as the protocol directory in the +unstable/+ directory.
+ . Copy the final version of the XML that is the version that was
+ decided to be declared stable into the new directory. The target name
+ should be the same name as the protocol directory but with the +.xml+
+ suffix.
+ . Rename the name of the protocol in the XML by removing the
+ 'unstable' part and the major version number.
+ . Remove the +z+ prefix and the major version number suffix from all
+ of the interfaces in the protocol.
+ . Reset all of the interface version attributes to +1+.
+ . Update the +README+ file in the unstable directory and create a new
+ +README+ file in the new directory.
+
+Releases
+~~~~~~~~
+Each release of wayland-protocols finalizes the version of the protocols
+to their state they had at that time.
src/template-client.pc
src/tizen-remote-surface-server.pc
src/tizen-remote-surface-client.pc
+ src/wayland-protocols.pc
])
AC_OUTPUT
Name: wayland-extension
Version: 1.1.31
Release: 0
-Summary: Wayland Extension Protocol
+Summary: Wayland extenstion protocols that add functionality not available in the Wayland core protocol
License: MIT
Group: Graphics & UI Framework/Wayland Window System
URL: http://www.tizen.org/
BuildRequires: pkgconfig(wayland-client)
%description
-wayland-extension is a protocol for tizen window system.
+wayland-extension contains Wayland protocols that add functionality not available in the Wayland core protocol.
%package -n libwayland-extension-client
Group: Graphics & UI Framework/Wayland Window System
This package contains all necessary include files and libraries needed
to develop a compositor that require these.
+%package -n wayland-protocols
+Summary: Wayland upstream protocols
+Group: Graphics & UI Framework/Development
+Requires: libwayland-client
+
+%description -n wayland-protocols
+wayland-protocols contains Wayland upstream protocols that add functionality not available in the Wayland core protocol
+
+
%prep
%setup -q
cp %{SOURCE1001} .
%_libdir/*-server.so
%_libdir/pkgconfig/*-server.pc
+%files -n wayland-protocols
+%manifest %{name}.manifest
+%license COPYING
+%defattr(-,root,root)
+%_datadir/wayland-extension/protocol/stable/*
+%_datadir/wayland-extension/protocol/unstable/*
+%_libdir/pkgconfig/wayland-protocols.pc
+
%changelog
--- /dev/null
+Presentation time protocol
+
+Maintainers:
+Pekka Paalanen <pekka.paalanen@collabora.co.uk>
+
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="presentation_time">
+<!-- wrap:70 -->
+
+ <copyright>
+ Copyright © 2013-2014 Collabora, Ltd.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <interface name="wp_presentation" version="1">
+ <description summary="timed presentation related wl_surface requests">
+
+<!-- Introduction -->
+
+ The main feature of this interface is accurate presentation
+ timing feedback to ensure smooth video playback while maintaining
+ audio/video synchronization. Some features use the concept of a
+ presentation clock, which is defined in the
+ presentation.clock_id event.
+
+ A content update for a wl_surface is submitted by a
+ wl_surface.commit request. Request 'feedback' associates with
+ the wl_surface.commit and provides feedback on the content
+ update, particularly the final realized presentation time.
+
+<!-- Completing presentation -->
+
+ When the final realized presentation time is available, e.g.
+ after a framebuffer flip completes, the requested
+ presentation_feedback.presented events are sent. The final
+ presentation time can differ from the compositor's predicted
+ display update time and the update's target time, especially
+ when the compositor misses its target vertical blanking period.
+ </description>
+
+ <enum name="error">
+ <description summary="fatal presentation errors">
+ These fatal protocol errors may be emitted in response to
+ illegal presentation requests.
+ </description>
+ <entry name="invalid_timestamp" value="0"
+ summary="invalid value in tv_nsec"/>
+ <entry name="invalid_flag" value="1"
+ summary="invalid flag"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="unbind from the presentation interface">
+ Informs the server that the client will no longer be using
+ this protocol object. Existing objects created by this object
+ are not affected.
+ </description>
+ </request>
+
+ <request name="feedback">
+ <description summary="request presentation feedback information">
+ Request presentation feedback for the current content submission
+ on the given surface. This creates a new presentation_feedback
+ object, which will deliver the feedback information once. If
+ multiple presentation_feedback objects are created for the same
+ submission, they will all deliver the same information.
+
+ For details on what information is returned, see the
+ presentation_feedback interface.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="target surface"/>
+ <arg name="callback" type="new_id" interface="wp_presentation_feedback"
+ summary="new feedback object"/>
+ </request>
+
+ <event name="clock_id">
+ <description summary="clock ID for timestamps">
+ This event tells the client in which clock domain the
+ compositor interprets the timestamps used by the presentation
+ extension. This clock is called the presentation clock.
+
+ The compositor sends this event when the client binds to the
+ presentation interface. The presentation clock does not change
+ during the lifetime of the client connection.
+
+ The clock identifier is platform dependent. On Linux/glibc,
+ the identifier value is one of the clockid_t values accepted
+ by clock_gettime(). clock_gettime() is defined by
+ POSIX.1-2001.
+
+ Timestamps in this clock domain are expressed as tv_sec_hi,
+ tv_sec_lo, tv_nsec triples, each component being an unsigned
+ 32-bit value. Whole seconds are in tv_sec which is a 64-bit
+ value combined from tv_sec_hi and tv_sec_lo, and the
+ additional fractional part in tv_nsec as nanoseconds. Hence,
+ for valid timestamps tv_nsec must be in [0, 999999999].
+
+ Note that clock_id applies only to the presentation clock,
+ and implies nothing about e.g. the timestamps used in the
+ Wayland core protocol input events.
+
+ Compositors should prefer a clock which does not jump and is
+ not slewed e.g. by NTP. The absolute value of the clock is
+ irrelevant. Precision of one millisecond or better is
+ recommended. Clients must be able to query the current clock
+ value directly, not by asking the compositor.
+ </description>
+ <arg name="clk_id" type="uint" summary="platform clock identifier"/>
+ </event>
+
+ </interface>
+
+ <interface name="wp_presentation_feedback" version="1">
+ <description summary="presentation time feedback event">
+ A presentation_feedback object returns an indication that a
+ wl_surface content update has become visible to the user.
+ One object corresponds to one content update submission
+ (wl_surface.commit). There are two possible outcomes: the
+ content update is presented to the user, and a presentation
+ timestamp delivered; or, the user did not see the content
+ update because it was superseded or its surface destroyed,
+ and the content update is discarded.
+
+ Once a presentation_feedback object has delivered a 'presented'
+ or 'discarded' event it is automatically destroyed.
+ </description>
+
+ <event name="sync_output">
+ <description summary="presentation synchronized to this output">
+ As presentation can be synchronized to only one output at a
+ time, this event tells which output it was. This event is only
+ sent prior to the presented event.
+
+ As clients may bind to the same global wl_output multiple
+ times, this event is sent for each bound instance that matches
+ the synchronized output. If a client has not bound to the
+ right wl_output global at all, this event is not sent.
+ </description>
+ <arg name="output" type="object" interface="wl_output"
+ summary="presentation output"/>
+ </event>
+
+ <enum name="kind">
+ <description summary="bitmask of flags in presented event">
+ These flags provide information about how the presentation of
+ the related content update was done. The intent is to help
+ clients assess the reliability of the feedback and the visual
+ quality with respect to possible tearing and timings. The
+ flags are:
+
+ VSYNC:
+ The presentation was synchronized to the "vertical retrace" by
+ the display hardware such that tearing does not happen.
+ Relying on user space scheduling is not acceptable for this
+ flag. If presentation is done by a copy to the active
+ frontbuffer, then it must guarantee that tearing cannot
+ happen.
+
+ HW_CLOCK:
+ The display hardware provided measurements that the hardware
+ driver converted into a presentation timestamp. Sampling a
+ clock in user space is not acceptable for this flag.
+
+ HW_COMPLETION:
+ The display hardware signalled that it started using the new
+ image content. The opposite of this is e.g. a timer being used
+ to guess when the display hardware has switched to the new
+ image content.
+
+ ZERO_COPY:
+ The presentation of this update was done zero-copy. This means
+ the buffer from the client was given to display hardware as
+ is, without copying it. Compositing with OpenGL counts as
+ copying, even if textured directly from the client buffer.
+ Possible zero-copy cases include direct scanout of a
+ fullscreen surface and a surface on a hardware overlay.
+ </description>
+ <entry name="vsync" value="0x1" summary="presentation was vsync'd"/>
+ <entry name="hw_clock" value="0x2"
+ summary="hardware provided the presentation timestamp"/>
+ <entry name="hw_completion" value="0x4"
+ summary="hardware signalled the start of the presentation"/>
+ <entry name="zero_copy" value="0x8"
+ summary="presentation was done zero-copy"/>
+ </enum>
+
+ <event name="presented">
+ <description summary="the content update was displayed">
+ The associated content update was displayed to the user at the
+ indicated time (tv_sec_hi/lo, tv_nsec). For the interpretation of
+ the timestamp, see presentation.clock_id event.
+
+ The timestamp corresponds to the time when the content update
+ turned into light the first time on the surface's main output.
+ Compositors may approximate this from the framebuffer flip
+ completion events from the system, and the latency of the
+ physical display path if known.
+
+ This event is preceded by all related sync_output events
+ telling which output's refresh cycle the feedback corresponds
+ to, i.e. the main output for the surface. Compositors are
+ recommended to choose the output containing the largest part
+ of the wl_surface, or keeping the output they previously
+ chose. Having a stable presentation output association helps
+ clients predict future output refreshes (vblank).
+
+ The 'refresh' argument gives the compositor's prediction of how
+ many nanoseconds after tv_sec, tv_nsec the very next output
+ refresh may occur. This is to further aid clients in
+ predicting future refreshes, i.e., estimating the timestamps
+ targeting the next few vblanks. If such prediction cannot
+ usefully be done, the argument is zero.
+
+ If the output does not have a constant refresh rate, explicit
+ video mode switches excluded, then the refresh argument must
+ be zero.
+
+ The 64-bit value combined from seq_hi and seq_lo is the value
+ of the output's vertical retrace counter when the content
+ update was first scanned out to the display. This value must
+ be compatible with the definition of MSC in
+ GLX_OML_sync_control specification. Note, that if the display
+ path has a non-zero latency, the time instant specified by
+ this counter may differ from the timestamp's.
+
+ If the output does not have a concept of vertical retrace or a
+ refresh cycle, or the output device is self-refreshing without
+ a way to query the refresh count, then the arguments seq_hi
+ and seq_lo must be zero.
+ </description>
+ <arg name="tv_sec_hi" type="uint"
+ summary="high 32 bits of the seconds part of the presentation timestamp"/>
+ <arg name="tv_sec_lo" type="uint"
+ summary="low 32 bits of the seconds part of the presentation timestamp"/>
+ <arg name="tv_nsec" type="uint"
+ summary="nanoseconds part of the presentation timestamp"/>
+ <arg name="refresh" type="uint" summary="nanoseconds till next refresh"/>
+ <arg name="seq_hi" type="uint"
+ summary="high 32 bits of refresh counter"/>
+ <arg name="seq_lo" type="uint"
+ summary="low 32 bits of refresh counter"/>
+ <arg name="flags" type="uint" summary="combination of 'kind' values"/>
+ </event>
+
+ <event name="discarded">
+ <description summary="the content update was not displayed">
+ The content update was never displayed to the user.
+ </description>
+ </event>
+ </interface>
+
+</protocol>
--- /dev/null
+Viewporter: cropping and scaling extension for surface contents
+
+Previously known as wl_scaler.
+
+Maintainers:
+Pekka Paalanen <pekka.paalanen@collabora.co.uk>
+
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="viewporter">
+
+ <copyright>
+ Copyright © 2013-2016 Collabora, Ltd.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <interface name="wp_viewporter" version="1">
+ <description summary="surface cropping and scaling">
+ The global interface exposing surface cropping and scaling
+ capabilities is used to instantiate an interface extension for a
+ wl_surface object. This extended interface will then allow
+ cropping and scaling the surface contents, effectively
+ disconnecting the direct relationship between the buffer and the
+ surface size.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="unbind from the cropping and scaling interface">
+ Informs the server that the client will not be using this
+ protocol object anymore. This does not affect any other objects,
+ wp_viewport objects included.
+ </description>
+ </request>
+
+ <enum name="error">
+ <entry name="viewport_exists" value="0"
+ summary="the surface already has a viewport object associated"/>
+ </enum>
+
+ <request name="get_viewport">
+ <description summary="extend surface interface for crop and scale">
+ Instantiate an interface extension for the given wl_surface to
+ crop and scale its content. If the given wl_surface already has
+ a wp_viewport object associated, the viewport_exists
+ protocol error is raised.
+ </description>
+ <arg name="id" type="new_id" interface="wp_viewport"
+ summary="the new viewport interface id"/>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="the surface"/>
+ </request>
+ </interface>
+
+ <interface name="wp_viewport" version="1">
+ <description summary="crop and scale interface to a wl_surface">
+ An additional interface to a wl_surface object, which allows the
+ client to specify the cropping and scaling of the surface
+ contents.
+
+ This interface works with two concepts: the source rectangle (src_x,
+ src_y, src_width, src_height), and the destination size (dst_width,
+ dst_height). The contents of the source rectangle are scaled to the
+ destination size, and content outside the source rectangle is ignored.
+ This state is double-buffered, and is applied on the next
+ wl_surface.commit.
+
+ The two parts of crop and scale state are independent: the source
+ rectangle, and the destination size. Initially both are unset, that
+ is, no scaling is applied. The whole of the current wl_buffer is
+ used as the source, and the surface size is as defined in
+ wl_surface.attach.
+
+ If the destination size is set, it causes the surface size to become
+ dst_width, dst_height. The source (rectangle) is scaled to exactly
+ this size. This overrides whatever the attached wl_buffer size is,
+ unless the wl_buffer is NULL. If the wl_buffer is NULL, the surface
+ has no content and therefore no size. Otherwise, the size is always
+ at least 1x1 in surface local coordinates.
+
+ If the source rectangle is set, it defines what area of the wl_buffer is
+ taken as the source. If the source rectangle is set and the destination
+ size is not set, then src_width and src_height must be integers, and the
+ surface size becomes the source rectangle size. This results in cropping
+ without scaling. If src_width or src_height are not integers and
+ destination size is not set, the bad_size protocol error is raised when
+ the surface state is applied.
+
+ The coordinate transformations from buffer pixel coordinates up to
+ the surface-local coordinates happen in the following order:
+ 1. buffer_transform (wl_surface.set_buffer_transform)
+ 2. buffer_scale (wl_surface.set_buffer_scale)
+ 3. crop and scale (wp_viewport.set*)
+ This means, that the source rectangle coordinates of crop and scale
+ are given in the coordinates after the buffer transform and scale,
+ i.e. in the coordinates that would be the surface-local coordinates
+ if the crop and scale was not applied.
+
+ If src_x or src_y are negative, the bad_value protocol error is raised.
+ Otherwise, if the source rectangle is partially or completely outside of
+ the non-NULL wl_buffer, then the out_of_buffer protocol error is raised
+ when the surface state is applied. A NULL wl_buffer does not raise the
+ out_of_buffer error.
+
+ The x, y arguments of wl_surface.attach are applied as normal to
+ the surface. They indicate how many pixels to remove from the
+ surface size from the left and the top. In other words, they are
+ still in the surface-local coordinate system, just like dst_width
+ and dst_height are.
+
+ If the wl_surface associated with the wp_viewport is destroyed,
+ all wp_viewport requests except 'destroy' raise the protocol error
+ no_surface.
+
+ If the wp_viewport object is destroyed, the crop and scale
+ state is removed from the wl_surface. The change will be applied
+ on the next wl_surface.commit.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="remove scaling and cropping from the surface">
+ The associated wl_surface's crop and scale state is removed.
+ The change is applied on the next wl_surface.commit.
+ </description>
+ </request>
+
+ <enum name="error">
+ <entry name="bad_value" value="0"
+ summary="negative or zero values in width or height"/>
+ <entry name="bad_size" value="1"
+ summary="destination size is not integer"/>
+ <entry name="out_of_buffer" value="2"
+ summary="source rectangle extends outside of the content area"/>
+ <entry name="no_surface" value="3"
+ summary="the wl_surface was destroyed"/>
+ </enum>
+
+ <request name="set_source">
+ <description summary="set the source rectangle for cropping">
+ Set the source rectangle of the associated wl_surface. See
+ wp_viewport for the description, and relation to the wl_buffer
+ size.
+
+ If all of x, y, width and height are -1.0, the source rectangle is
+ unset instead. Any other set of values where width or height are zero
+ or negative, or x or y are negative, raise the bad_value protocol
+ error.
+
+ The crop and scale state is double-buffered state, and will be
+ applied on the next wl_surface.commit.
+ </description>
+ <arg name="x" type="fixed" summary="source rectangle x"/>
+ <arg name="y" type="fixed" summary="source rectangle y"/>
+ <arg name="width" type="fixed" summary="source rectangle width"/>
+ <arg name="height" type="fixed" summary="source rectangle height"/>
+ </request>
+
+ <request name="set_destination">
+ <description summary="set the surface size for scaling">
+ Set the destination size of the associated wl_surface. See
+ wp_viewport for the description, and relation to the wl_buffer
+ size.
+
+ If width is -1 and height is -1, the destination size is unset
+ instead. Any other pair of values for width and height that
+ contains zero or negative values raises the bad_value protocol
+ error.
+
+ The crop and scale state is double-buffered state, and will be
+ applied on the next wl_surface.commit.
+ </description>
+ <arg name="width" type="int" summary="surface width"/>
+ <arg name="height" type="int" summary="surface height"/>
+ </request>
+ </interface>
+
+</protocol>
--- /dev/null
+Fullscreen shell protocol
+
+Maintainers:
+Jason Ekstrand <jason@jlekstrand.net>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="fullscreen_shell_unstable_v1">
+
+ <interface name="zwp_fullscreen_shell_v1" version="1">
+ <description summary="displays a single surface per output">
+ Displays a single surface per output.
+
+ This interface provides a mechanism for a single client to display
+ simple full-screen surfaces. While there technically may be multiple
+ clients bound to this interface, only one of those clients should be
+ shown at a time.
+
+ To present a surface, the client uses either the present_surface or
+ present_surface_for_mode requests. Presenting a surface takes effect
+ on the next wl_surface.commit. See the individual requests for
+ details about scaling and mode switches.
+
+ The client can have at most one surface per output at any time.
+ Requesting a surface to be presented on an output that already has a
+ surface replaces the previously presented surface. Presenting a null
+ surface removes its content and effectively disables the output.
+ Exactly what happens when an output is "disabled" is
+ compositor-specific. The same surface may be presented on multiple
+ outputs simultaneously.
+
+ Once a surface is presented on an output, it stays on that output
+ until either the client removes it or the compositor destroys the
+ output. This way, the client can update the output's contents by
+ simply attaching a new buffer.
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible changes
+ may be added together with the corresponding interface version bump.
+ Backward incompatible changes are done by bumping the version number in
+ the protocol and interface names and resetting the interface version.
+ Once the protocol is to be declared stable, the 'z' prefix and the
+ version number in the protocol and interface names are removed and the
+ interface version number is reset.
+ </description>
+
+ <request name="release" type="destructor">
+ <description summary="release the wl_fullscreen_shell interface">
+ Release the binding from the wl_fullscreen_shell interface.
+
+ This destroys the server-side object and frees this binding. If
+ the client binds to wl_fullscreen_shell multiple times, it may wish
+ to free some of those bindings.
+ </description>
+ </request>
+
+ <enum name="capability">
+ <description summary="capabilities advertised by the compositor">
+ Various capabilities that can be advertised by the compositor. They
+ are advertised one-at-a-time when the wl_fullscreen_shell interface is
+ bound. See the wl_fullscreen_shell.capability event for more details.
+
+ ARBITRARY_MODES:
+ This is a hint to the client that indicates that the compositor is
+ capable of setting practically any mode on its outputs. If this
+ capability is provided, wl_fullscreen_shell.present_surface_for_mode
+ will almost never fail and clients should feel free to set whatever
+ mode they like. If the compositor does not advertise this, it may
+ still support some modes that are not advertised through wl_global.mode
+ but it is less likely.
+
+ CURSOR_PLANE:
+ This is a hint to the client that indicates that the compositor can
+ handle a cursor surface from the client without actually compositing.
+ This may be because of a hardware cursor plane or some other mechanism.
+ If the compositor does not advertise this capability then setting
+ wl_pointer.cursor may degrade performance or be ignored entirely. If
+ CURSOR_PLANE is not advertised, it is recommended that the client draw
+ its own cursor and set wl_pointer.cursor(NULL).
+ </description>
+ <entry name="arbitrary_modes" value="1" summary="compositor is capable of almost any output mode"/>
+ <entry name="cursor_plane" value="2" summary="compositor has a separate cursor plane"/>
+ </enum>
+
+ <event name="capability">
+ <description summary="advertises a capability of the compositor">
+ Advertises a single capability of the compositor.
+
+ When the wl_fullscreen_shell interface is bound, this event is emitted
+ once for each capability advertised. Valid capabilities are given by
+ the wl_fullscreen_shell.capability enum. If clients want to take
+ advantage of any of these capabilities, they should use a
+ wl_display.sync request immediately after binding to ensure that they
+ receive all the capability events.
+ </description>
+ <arg name="capability" type="uint"/>
+ </event>
+
+ <enum name="present_method">
+ <description summary="different method to set the surface fullscreen">
+ Hints to indicate to the compositor how to deal with a conflict
+ between the dimensions of the surface and the dimensions of the
+ output. The compositor is free to ignore this parameter.
+ </description>
+ <entry name="default" value="0" summary="no preference, apply default policy"/>
+ <entry name="center" value="1" summary="center the surface on the output"/>
+ <entry name="zoom" value="2" summary="scale the surface, preserving aspect ratio, to the largest size that will fit on the output" />
+ <entry name="zoom_crop" value="3" summary="scale the surface, preserving aspect ratio, to fully fill the output cropping if needed" />
+ <entry name="stretch" value="4" summary="scale the surface to the size of the output ignoring aspect ratio" />
+ </enum>
+
+ <request name="present_surface">
+ <description summary="present surface for display">
+ Present a surface on the given output.
+
+ If the output is null, the compositor will present the surface on
+ whatever display (or displays) it thinks best. In particular, this
+ may replace any or all surfaces currently presented so it should
+ not be used in combination with placing surfaces on specific
+ outputs.
+
+ The method parameter is a hint to the compositor for how the surface
+ is to be presented. In particular, it tells the compositor how to
+ handle a size mismatch between the presented surface and the
+ output. The compositor is free to ignore this parameter.
+
+ The "zoom", "zoom_crop", and "stretch" methods imply a scaling
+ operation on the surface. This will override any kind of output
+ scaling, so the buffer_scale property of the surface is effectively
+ ignored.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
+ <arg name="method" type="uint"/>
+ <arg name="output" type="object" interface="wl_output" allow-null="true"/>
+ </request>
+
+ <request name="present_surface_for_mode">
+ <description summary="present surface for display at a particular mode">
+ Presents a surface on the given output for a particular mode.
+
+ If the current size of the output differs from that of the surface,
+ the compositor will attempt to change the size of the output to
+ match the surface. The result of the mode-switch operation will be
+ returned via the provided wl_fullscreen_shell_mode_feedback object.
+
+ If the current output mode matches the one requested or if the
+ compositor successfully switches the mode to match the surface,
+ then the mode_successful event will be sent and the output will
+ contain the contents of the given surface. If the compositor
+ cannot match the output size to the surface size, the mode_failed
+ will be sent and the output will contain the contents of the
+ previously presented surface (if any). If another surface is
+ presented on the given output before either of these has a chance
+ to happen, the present_cancelled event will be sent.
+
+ Due to race conditions and other issues unknown to the client, no
+ mode-switch operation is guaranteed to succeed. However, if the
+ mode is one advertised by wl_output.mode or if the compositor
+ advertises the ARBITRARY_MODES capability, then the client should
+ expect that the mode-switch operation will usually succeed.
+
+ If the size of the presented surface changes, the resulting output
+ is undefined. The compositor may attempt to change the output mode
+ to compensate. However, there is no guarantee that a suitable mode
+ will be found and the client has no way to be notified of success
+ or failure.
+
+ The framerate parameter specifies the desired framerate for the
+ output in mHz. The compositor is free to ignore this parameter. A
+ value of 0 indicates that the client has no preference.
+
+ If the value of wl_output.scale differs from wl_surface.buffer_scale,
+ then the compositor may choose a mode that matches either the buffer
+ size or the surface size. In either case, the surface will fill the
+ output.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ <arg name="output" type="object" interface="wl_output"/>
+ <arg name="framerate" type="int"/>
+ <arg name="feedback" type="new_id" interface="zwp_fullscreen_shell_mode_feedback_v1"/>
+ </request>
+
+ <enum name="error">
+ <description summary="wl_fullscreen_shell error values">
+ These errors can be emitted in response to wl_fullscreen_shell requests.
+ </description>
+ <entry name="invalid_method" value="0" summary="present_method is not known"/>
+ </enum>
+ </interface>
+
+ <interface name="zwp_fullscreen_shell_mode_feedback_v1" version="1">
+ <event name="mode_successful">
+ <description summary="mode switch succeeded">
+ This event indicates that the attempted mode switch operation was
+ successful. A surface of the size requested in the mode switch
+ will fill the output without scaling.
+
+ Upon receiving this event, the client should destroy the
+ wl_fullscreen_shell_mode_feedback object.
+ </description>
+ </event>
+
+ <event name="mode_failed">
+ <description summary="mode switch failed">
+ This event indicates that the attempted mode switch operation
+ failed. This may be because the requested output mode is not
+ possible or it may mean that the compositor does not want to allow it.
+
+ Upon receiving this event, the client should destroy the
+ wl_fullscreen_shell_mode_feedback object.
+ </description>
+ </event>
+
+ <event name="present_cancelled">
+ <description summary="mode switch cancelled">
+ This event indicates that the attempted mode switch operation was
+ cancelled. Most likely this is because the client requested a
+ second mode switch before the first one completed.
+
+ Upon receiving this event, the client should destroy the
+ wl_fullscreen_shell_mode_feedback object.
+ </description>
+ </event>
+ </interface>
+
+</protocol>
--- /dev/null
+Screensaver inhibition protocol
+
+Maintainers:
+Bryce Harrington <bryce@osg.samsung.com>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="idle_inhibit_unstable_v1">
+
+ <copyright>
+ Copyright © 2015 Samsung Electronics Co., Ltd
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <interface name="zwp_idle_inhibit_manager_v1" version="1">
+ <description summary="control behavior when display idles">
+ This interface permits inhibiting the idle behavior such as screen
+ blanking, locking, and screensaving. The client binds the idle manager
+ globally, then creates idle-inhibitor objects for each surface.
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible changes
+ may be added together with the corresponding interface version bump.
+ Backward incompatible changes are done by bumping the version number in
+ the protocol and interface names and resetting the interface version.
+ Once the protocol is to be declared stable, the 'z' prefix and the
+ version number in the protocol and interface names are removed and the
+ interface version number is reset.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the idle inhibitor object">
+ Destroy the inhibit manager.
+ </description>
+ </request>
+
+ <request name="create_inhibitor">
+ <description summary="create a new inhibitor object">
+ Create a new inhibitor object associated with the given surface.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_idle_inhibitor_v1"/>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="the surface that inhibits the idle behavior"/>
+ </request>
+
+ </interface>
+
+ <interface name="zwp_idle_inhibitor_v1" version="1">
+ <description summary="context object for inhibiting idle behavior">
+ An idle inhibitor prevents the output that the associated surface is
+ visible on from being set to a state where it is not visually usable due
+ to lack of user interaction (e.g. blanked, dimmed, locked, set to power
+ save, etc.) Any screensaver processes are also blocked from displaying.
+
+ If the surface is destroyed, unmapped, becomes occluded, loses
+ visibility, or otherwise becomes not visually relevant for the user, the
+ idle inhibitor will not be honored by the compositor; if the surface
+ subsequently regains visibility the inhibitor takes effect once again.
+ Likewise, the inhibitor isn't honored if the system was already idled at
+ the time the inhibitor was established, although if the system later
+ de-idles and re-idles the inhibitor will take effect.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the idle inhibitor object">
+ Remove the inhibitor effect from the associated wl_surface.
+ </description>
+ </request>
+
+ </interface>
+</protocol>
--- /dev/null
+Input method protocol
+
+Maintainers:
+Jan Arne Petersen <janarne@gmail.com>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="input_method_unstable_v1">
+
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <interface name="zwp_input_method_context_v1" version="1">
+ <description summary="input method context">
+ Corresponds to a text input on the input method side. An input method context
+ is created on text input activation on the input method side. It allows
+ receiving information about the text input from the application via events.
+ Input method contexts do not keep state after deactivation and should be
+ destroyed after deactivation is handled.
+
+ Text is generally UTF-8 encoded, indices and lengths are in bytes.
+
+ Serials are used to synchronize the state between the text input and
+ an input method. New serials are sent by the text input in the
+ commit_state request and are used by the input method to indicate
+ the known text input state in events like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible changes
+ may be added together with the corresponding interface version bump.
+ Backward incompatible changes are done by bumping the version number in
+ the protocol and interface names and resetting the interface version.
+ Once the protocol is to be declared stable, the 'z' prefix and the
+ version number in the protocol and interface names are removed and the
+ interface version number is reset.
+ </description>
+
+ <request name="destroy" type="destructor"/>
+
+ <request name="commit_string">
+ <description summary="commit string">
+ Send the commit string text for insertion to the application.
+
+ The text to commit could be either just a single character after a key
+ press or the result of some composing (pre-edit). It could be also an
+ empty text when some text should be removed (see
+ delete_surrounding_text) or when the input cursor should be moved (see
+ cursor_position).
+
+ Any previously set composing text will be removed.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </request>
+
+ <request name="preedit_string">
+ <description summary="pre-edit string">
+ Send the pre-edit string text to the application text input.
+
+ The commit text can be used to replace the pre-edit text on reset (for
+ example on unfocus).
+
+ Previously sent preedit_style and preedit_cursor requests are also
+ processed by the text_input.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </request>
+
+ <request name="preedit_styling">
+ <description summary="pre-edit styling">
+ Set the styling information on composing text. The style is applied for
+ length in bytes from index relative to the beginning of
+ the composing text (as byte offset). Multiple styles can
+ be applied to a composing text.
+
+ This request should be sent before sending a preedit_string request.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint"/>
+ </request>
+
+ <request name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ Set the cursor position inside the composing text (as byte offset)
+ relative to the start of the composing text.
+
+ When index is negative no cursor should be displayed.
+
+ This request should be sent before sending a preedit_string request.
+ </description>
+ <arg name="index" type="int"/>
+ </request>
+
+ <request name="delete_surrounding_text">
+ <description summary="delete text">
+ Remove the surrounding text.
+
+ This request will be handled on the text_input side directly following
+ a commit_string request.
+ </description>
+ <arg name="index" type="int"/>
+ <arg name="length" type="uint"/>
+ </request>
+
+ <request name="cursor_position">
+ <description summary="set cursor to a new position">
+ Set the cursor and anchor to a new position. Index is the new cursor
+ position in bytes (when >= 0 this is relative to the end of the inserted text,
+ otherwise it is relative to the beginning of the inserted text). Anchor is
+ the new anchor position in bytes (when >= 0 this is relative to the end of the
+ inserted text, otherwise it is relative to the beginning of the inserted
+ text). When there should be no selected text, anchor should be the same
+ as index.
+
+ This request will be handled on the text_input side directly following
+ a commit_string request.
+ </description>
+ <arg name="index" type="int"/>
+ <arg name="anchor" type="int"/>
+ </request>
+
+ <request name="modifiers_map">
+ <arg name="map" type="array"/>
+ </request>
+
+ <request name="keysym">
+ <description summary="keysym">
+ Notify when a key event was sent. Key events should not be used for
+ normal text input operations, which should be done with commit_string,
+ delete_surrounding_text, etc. The key event follows the wl_keyboard key
+ event convention. Sym is an XKB keysym, state is a wl_keyboard key_state.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="time" type="uint"/>
+ <arg name="sym" type="uint"/>
+ <arg name="state" type="uint"/>
+ <arg name="modifiers" type="uint"/>
+ </request>
+
+ <request name="grab_keyboard">
+ <description summary="grab hardware keyboard">
+ Allow an input method to receive hardware keyboard input and process
+ key events to generate text events (with pre-edit) over the wire. This
+ allows input methods which compose multiple key events for inputting
+ text like it is done for CJK languages.
+ </description>
+ <arg name="keyboard" type="new_id" interface="wl_keyboard"/>
+ </request>
+
+ <request name="key">
+ <description summary="forward key event">
+ Forward a wl_keyboard::key event to the client that was not processed
+ by the input method itself. Should be used when filtering key events
+ with grab_keyboard. The arguments should be the ones from the
+ wl_keyboard::key event.
+
+ For generating custom key events use the keysym request instead.
+ </description>
+ <arg name="serial" type="uint" summary="serial from wl_keyboard::key"/>
+ <arg name="time" type="uint" summary="time from wl_keyboard::key"/>
+ <arg name="key" type="uint" summary="key from wl_keyboard::key"/>
+ <arg name="state" type="uint" summary="state from wl_keyboard::key"/>
+ </request>
+
+ <request name="modifiers">
+ <description summary="forward modifiers event">
+ Forward a wl_keyboard::modifiers event to the client that was not
+ processed by the input method itself. Should be used when filtering
+ key events with grab_keyboard. The arguments should be the ones
+ from the wl_keyboard::modifiers event.
+ </description>
+ <arg name="serial" type="uint" summary="serial from wl_keyboard::modifiers"/>
+ <arg name="mods_depressed" type="uint" summary="mods_depressed from wl_keyboard::modifiers"/>
+ <arg name="mods_latched" type="uint" summary="mods_latched from wl_keyboard::modifiers"/>
+ <arg name="mods_locked" type="uint" summary="mods_locked from wl_keyboard::modifiers"/>
+ <arg name="group" type="uint" summary="group from wl_keyboard::modifiers"/>
+ </request>
+
+ <request name="language">
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </request>
+
+ <request name="text_direction">
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint"/>
+ </request>
+
+ <event name="surrounding_text">
+ <description summary="surrounding text event">
+ The plain surrounding text around the input position. Cursor is the
+ position in bytes within the surrounding text relative to the beginning
+ of the text. Anchor is the position in bytes of the selection anchor
+ within the surrounding text relative to the beginning of the text. If
+ there is no selected text then anchor is the same as cursor.
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="uint"/>
+ </event>
+
+ <event name="reset">
+ </event>
+
+ <event name="content_type">
+ <arg name="hint" type="uint"/>
+ <arg name="purpose" type="uint"/>
+ </event>
+
+ <event name="invoke_action">
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </event>
+
+ <event name="commit_state">
+ <arg name="serial" type="uint" summary="serial of text input state"/>
+ </event>
+
+ <event name="preferred_language">
+ <arg name="language" type="string"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_input_method_v1" version="1">
+ <description summary="input method">
+ An input method object is responsible for composing text in response to
+ input from hardware or virtual keyboards. There is one input method
+ object per seat. On activate there is a new input method context object
+ created which allows the input method to communicate with the text input.
+ </description>
+
+ <event name="activate">
+ <description summary="activate event">
+ A text input was activated. Creates an input method context object
+ which allows communication with the text input.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_input_method_context_v1"/>
+ </event>
+
+ <event name="deactivate">
+ <description summary="deactivate event">
+ The text input corresponding to the context argument was deactivated.
+ The input method context should be destroyed after deactivation is
+ handled.
+ </description>
+ <arg name="context" type="object" interface="zwp_input_method_context_v1"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_input_panel_v1" version="1">
+ <description summary="interface for implementing keyboards">
+ Only one client can bind this interface at a time.
+ </description>
+
+ <request name="get_input_panel_surface">
+ <arg name="id" type="new_id" interface="zwp_input_panel_surface_v1"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+ </interface>
+
+ <interface name="zwp_input_panel_surface_v1" version="1">
+ <enum name="position">
+ <entry name="center_bottom" value="0"/>
+ </enum>
+
+ <request name="set_toplevel">
+ <description summary="set the surface type as a keyboard">
+ Set the input_panel_surface type to keyboard.
+
+ A keyboard surface is only shown when a text input is active.
+ </description>
+ <arg name="output" type="object" interface="wl_output"/>
+ <arg name="position" type="uint"/>
+ </request>
+
+ <request name="set_overlay_panel">
+ <description summary="set the surface type as an overlay panel">
+ Set the input_panel_surface to be an overlay panel.
+
+ This is shown near the input cursor above the application window when
+ a text input is active.
+ </description>
+ </request>
+ </interface>
+
+</protocol>
--- /dev/null
+Compositor shortcuts inhibit protocol
+
+Maintainers:
+Olivier Fourdan <ofourdan@redhat.com>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="keyboard_shortcuts_inhibit_unstable_v1">
+
+ <copyright>
+ Copyright © 2017 Red Hat Inc.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <description summary="Protocol for inhibiting the compositor keyboard shortcuts">
+ This protocol specifies a way for a client to request the compositor
+ to ignore its own keyboard shortcuts for a given seat, so that all
+ key events from that seat get forwarded to a surface.
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible
+ changes may be added together with the corresponding interface
+ version bump.
+ Backward incompatible changes are done by bumping the version
+ number in the protocol and interface names and resetting the
+ interface version. Once the protocol is to be declared stable,
+ the 'z' prefix and the version number in the protocol and
+ interface names are removed and the interface version number is
+ reset.
+ </description>
+
+ <interface name="zwp_keyboard_shortcuts_inhibit_manager_v1" version="1">
+ <description summary="context object for keyboard grab_manager">
+ A global interface used for inhibiting the compositor keyboard shortcuts.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the keyboard shortcuts inhibitor object">
+ Destroy the keyboard shortcuts inhibitor manager.
+ </description>
+ </request>
+
+ <request name="inhibit_shortcuts">
+ <description summary="create a new keyboard shortcuts inhibitor object">
+ Create a new keyboard shortcuts inhibitor object associated with
+ the given surface for the given seat.
+
+ If shortcuts are already inhibited for the specified seat and surface,
+ a protocol error "already_inhibited" is raised by the compositor.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_keyboard_shortcuts_inhibitor_v1"/>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="the surface that inhibits the keyboard shortcuts behavior"/>
+ <arg name="seat" type="object" interface="wl_seat"
+ summary="the wl_seat for which keyboard shortcuts should be disabled"/>
+ </request>
+
+ <enum name="error">
+ <entry name="already_inhibited"
+ value="0"
+ summary="the shortcuts are already inhibited for this surface"/>
+ </enum>
+ </interface>
+
+ <interface name="zwp_keyboard_shortcuts_inhibitor_v1" version="1">
+ <description summary="context object for keyboard shortcuts inhibitor">
+ A keyboard shortcuts inhibitor instructs the compositor to ignore
+ its own keyboard shortcuts when the associated surface has keyboard
+ focus. As a result, when the surface has keyboard focus on the given
+ seat, it will receive all key events originating from the specified
+ seat, even those which would normally be caught by the compositor for
+ its own shortcuts.
+
+ The Wayland compositor is however under no obligation to disable
+ all of its shortcuts, and may keep some special key combo for its own
+ use, including but not limited to one allowing the user to forcibly
+ restore normal keyboard events routing in the case of an unwilling
+ client. The compositor may also use the same key combo to reactivate
+ an existing shortcut inhibitor that was previously deactivated on
+ user request.
+
+ When the compositor restores its own keyboard shortcuts, an
+ "inactive" event is emitted to notify the client that the keyboard
+ shortcuts inhibitor is not effectively active for the surface and
+ seat any more, and the client should not expect to receive all
+ keyboard events.
+
+ When the keyboard shortcuts inhibitor is inactive, the client has
+ no way to forcibly reactivate the keyboard shortcuts inhibitor.
+
+ The user can chose to re-enable a previously deactivated keyboard
+ shortcuts inhibitor using any mechanism the compositor may offer,
+ in which case the compositor will send an "active" event to notify
+ the client.
+
+ If the surface is destroyed, unmapped, or loses the seat's keyboard
+ focus, the keyboard shortcuts inhibitor becomes irrelevant and the
+ compositor will restore its own keyboard shortcuts but no "inactive"
+ event is emitted in this case.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the keyboard shortcuts inhibitor object">
+ Remove the keyboard shortcuts inhibitor from the associated wl_surface.
+ </description>
+ </request>
+
+ <event name="active">
+ <description summary="shortcuts are inhibited">
+ This event indicates that the shortcut inhibitor is active.
+
+ The compositor sends this event every time compositor shortcuts
+ are inhibited on behalf of the surface. When active, the client
+ may receive input events normally reserved by the compositor
+ (see zwp_keyboard_shortcuts_inhibitor_v1).
+
+ This occurs typically when the initial request "inhibit_shortcuts"
+ first becomes active or when the user instructs the compositor to
+ re-enable and existing shortcuts inhibitor using any mechanism
+ offered by the compositor.
+ </description>
+ </event>
+
+ <event name="inactive">
+ <description summary="shortcuts are restored">
+ This event indicates that the shortcuts inhibitor is inactive,
+ normal shortcuts processing is restored by the compositor.
+ </description>
+ </event>
+ </interface>
+</protocol>
--- /dev/null
+Linux DMA-BUF protocol
+
+Maintainers:
+Pekka Paalanen <pekka.paalanen@collabora.co.uk>
+Daniel Stone <daniels@collabora.com>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="linux_dmabuf_unstable_v1">
+
+ <copyright>
+ Copyright © 2014, 2015 Collabora, Ltd.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <interface name="zwp_linux_dmabuf_v1" version="3">
+ <description summary="factory for creating dmabuf-based wl_buffers">
+ Following the interfaces from:
+ https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt
+ and the Linux DRM sub-system's AddFb2 ioctl.
+
+ This interface offers ways to create generic dmabuf-based
+ wl_buffers. Immediately after a client binds to this interface,
+ the set of supported formats and format modifiers is sent with
+ 'format' and 'modifier' events.
+
+ The following are required from clients:
+
+ - Clients must ensure that either all data in the dma-buf is
+ coherent for all subsequent read access or that coherency is
+ correctly handled by the underlying kernel-side dma-buf
+ implementation.
+
+ - Don't make any more attachments after sending the buffer to the
+ compositor. Making more attachments later increases the risk of
+ the compositor not being able to use (re-import) an existing
+ dmabuf-based wl_buffer.
+
+ The underlying graphics stack must ensure the following:
+
+ - The dmabuf file descriptors relayed to the server will stay valid
+ for the whole lifetime of the wl_buffer. This means the server may
+ at any time use those fds to import the dmabuf into any kernel
+ sub-system that might accept it.
+
+ To create a wl_buffer from one or more dmabufs, a client creates a
+ zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params
+ request. All planes required by the intended format are added with
+ the 'add' request. Finally, a 'create' or 'create_immed' request is
+ issued, which has the following outcome depending on the import success.
+
+ The 'create' request,
+ - on success, triggers a 'created' event which provides the final
+ wl_buffer to the client.
+ - on failure, triggers a 'failed' event to convey that the server
+ cannot use the dmabufs received from the client.
+
+ For the 'create_immed' request,
+ - on success, the server immediately imports the added dmabufs to
+ create a wl_buffer. No event is sent from the server in this case.
+ - on failure, the server can choose to either:
+ - terminate the client by raising a fatal error.
+ - mark the wl_buffer as failed, and send a 'failed' event to the
+ client. If the client uses a failed wl_buffer as an argument to any
+ request, the behaviour is compositor implementation-defined.
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible changes
+ may be added together with the corresponding interface version bump.
+ Backward incompatible changes are done by bumping the version number in
+ the protocol and interface names and resetting the interface version.
+ Once the protocol is to be declared stable, the 'z' prefix and the
+ version number in the protocol and interface names are removed and the
+ interface version number is reset.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="unbind the factory">
+ Objects created through this interface, especially wl_buffers, will
+ remain valid.
+ </description>
+ </request>
+
+ <request name="create_params">
+ <description summary="create a temporary object for buffer parameters">
+ This temporary object is used to collect multiple dmabuf handles into
+ a single batch to create a wl_buffer. It can only be used once and
+ should be destroyed after a 'created' or 'failed' event has been
+ received.
+ </description>
+ <arg name="params_id" type="new_id" interface="zwp_linux_buffer_params_v1"
+ summary="the new temporary"/>
+ </request>
+
+ <event name="format">
+ <description summary="supported buffer format">
+ This event advertises one buffer format that the server supports.
+ All the supported formats are advertised once when the client
+ binds to this interface. A roundtrip after binding guarantees
+ that the client has received all supported formats.
+
+ For the definition of the format codes, see the
+ zwp_linux_buffer_params_v1::create request.
+
+ Warning: the 'format' event is likely to be deprecated and replaced
+ with the 'modifier' event introduced in zwp_linux_dmabuf_v1
+ version 3, described below. Please refrain from using the information
+ received from this event.
+ </description>
+ <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+ </event>
+
+ <event name="modifier" since="3">
+ <description summary="supported buffer format modifier">
+ This event advertises the formats that the server supports, along with
+ the modifiers supported for each format. All the supported modifiers
+ for all the supported formats are advertised once when the client
+ binds to this interface. A roundtrip after binding guarantees that
+ the client has received all supported format-modifier pairs.
+
+ For the definition of the format and modifier codes, see the
+ zwp_linux_buffer_params_v1::create request.
+ </description>
+ <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+ <arg name="modifier_hi" type="uint"
+ summary="high 32 bits of layout modifier"/>
+ <arg name="modifier_lo" type="uint"
+ summary="low 32 bits of layout modifier"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_linux_buffer_params_v1" version="3">
+ <description summary="parameters for creating a dmabuf-based wl_buffer">
+ This temporary object is a collection of dmabufs and other
+ parameters that together form a single logical buffer. The temporary
+ object may eventually create one wl_buffer unless cancelled by
+ destroying it before requesting 'create'.
+
+ Single-planar formats only require one dmabuf, however
+ multi-planar formats may require more than one dmabuf. For all
+ formats, an 'add' request must be called once per plane (even if the
+ underlying dmabuf fd is identical).
+
+ You must use consecutive plane indices ('plane_idx' argument for 'add')
+ from zero to the number of planes used by the drm_fourcc format code.
+ All planes required by the format must be given exactly once, but can
+ be given in any order. Each plane index can be set only once.
+ </description>
+
+ <enum name="error">
+ <entry name="already_used" value="0"
+ summary="the dmabuf_batch object has already been used to create a wl_buffer"/>
+ <entry name="plane_idx" value="1"
+ summary="plane index out of bounds"/>
+ <entry name="plane_set" value="2"
+ summary="the plane index was already set"/>
+ <entry name="incomplete" value="3"
+ summary="missing or too many planes to create a buffer"/>
+ <entry name="invalid_format" value="4"
+ summary="format not supported"/>
+ <entry name="invalid_dimensions" value="5"
+ summary="invalid width or height"/>
+ <entry name="out_of_bounds" value="6"
+ summary="offset + stride * height goes out of dmabuf bounds"/>
+ <entry name="invalid_wl_buffer" value="7"
+ summary="invalid wl_buffer resulted from importing dmabufs via
+ the create_immed request on given buffer_params"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="delete this object, used or not">
+ Cleans up the temporary data sent to the server for dmabuf-based
+ wl_buffer creation.
+ </description>
+ </request>
+
+ <request name="add">
+ <description summary="add a dmabuf to the temporary set">
+ This request adds one dmabuf to the set in this
+ zwp_linux_buffer_params_v1.
+
+ The 64-bit unsigned value combined from modifier_hi and modifier_lo
+ is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the
+ fb modifier, which is defined in drm_mode.h of Linux UAPI.
+ This is an opaque token. Drivers use this token to express tiling,
+ compression, etc. driver-specific modifications to the base format
+ defined by the DRM fourcc code.
+
+ This request raises the PLANE_IDX error if plane_idx is too large.
+ The error PLANE_SET is raised if attempting to set a plane that
+ was already set.
+ </description>
+ <arg name="fd" type="fd" summary="dmabuf fd"/>
+ <arg name="plane_idx" type="uint" summary="plane index"/>
+ <arg name="offset" type="uint" summary="offset in bytes"/>
+ <arg name="stride" type="uint" summary="stride in bytes"/>
+ <arg name="modifier_hi" type="uint"
+ summary="high 32 bits of layout modifier"/>
+ <arg name="modifier_lo" type="uint"
+ summary="low 32 bits of layout modifier"/>
+ </request>
+
+ <enum name="flags">
+ <entry name="y_invert" value="1" summary="contents are y-inverted"/>
+ <entry name="interlaced" value="2" summary="content is interlaced"/>
+ <entry name="bottom_first" value="4" summary="bottom field first"/>
+ </enum>
+
+ <request name="create">
+ <description summary="create a wl_buffer from the given dmabufs">
+ This asks for creation of a wl_buffer from the added dmabuf
+ buffers. The wl_buffer is not created immediately but returned via
+ the 'created' event if the dmabuf sharing succeeds. The sharing
+ may fail at runtime for reasons a client cannot predict, in
+ which case the 'failed' event is triggered.
+
+ The 'format' argument is a DRM_FORMAT code, as defined by the
+ libdrm's drm_fourcc.h. The Linux kernel's DRM sub-system is the
+ authoritative source on how the format codes should work.
+
+ The 'flags' is a bitfield of the flags defined in enum "flags".
+ 'y_invert' means the that the image needs to be y-flipped.
+
+ Flag 'interlaced' means that the frame in the buffer is not
+ progressive as usual, but interlaced. An interlaced buffer as
+ supported here must always contain both top and bottom fields.
+ The top field always begins on the first pixel row. The temporal
+ ordering between the two fields is top field first, unless
+ 'bottom_first' is specified. It is undefined whether 'bottom_first'
+ is ignored if 'interlaced' is not set.
+
+ This protocol does not convey any information about field rate,
+ duration, or timing, other than the relative ordering between the
+ two fields in one buffer. A compositor may have to estimate the
+ intended field rate from the incoming buffer rate. It is undefined
+ whether the time of receiving wl_surface.commit with a new buffer
+ attached, applying the wl_surface state, wl_surface.frame callback
+ trigger, presentation, or any other point in the compositor cycle
+ is used to measure the frame or field times. There is no support
+ for detecting missed or late frames/fields/buffers either, and
+ there is no support whatsoever for cooperating with interlaced
+ compositor output.
+
+ The composited image quality resulting from the use of interlaced
+ buffers is explicitly undefined. A compositor may use elaborate
+ hardware features or software to deinterlace and create progressive
+ output frames from a sequence of interlaced input buffers, or it
+ may produce substandard image quality. However, compositors that
+ cannot guarantee reasonable image quality in all cases are recommended
+ to just reject all interlaced buffers.
+
+ Any argument errors, including non-positive width or height,
+ mismatch between the number of planes and the format, bad
+ format, bad offset or stride, may be indicated by fatal protocol
+ errors: INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS,
+ OUT_OF_BOUNDS.
+
+ Dmabuf import errors in the server that are not obvious client
+ bugs are returned via the 'failed' event as non-fatal. This
+ allows attempting dmabuf sharing and falling back in the client
+ if it fails.
+
+ This request can be sent only once in the object's lifetime, after
+ which the only legal request is destroy. This object should be
+ destroyed after issuing a 'create' request. Attempting to use this
+ object after issuing 'create' raises ALREADY_USED protocol error.
+
+ It is not mandatory to issue 'create'. If a client wants to
+ cancel the buffer creation, it can just destroy this object.
+ </description>
+ <arg name="width" type="int" summary="base plane width in pixels"/>
+ <arg name="height" type="int" summary="base plane height in pixels"/>
+ <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+ <arg name="flags" type="uint" summary="see enum flags"/>
+ </request>
+
+ <event name="created">
+ <description summary="buffer creation succeeded">
+ This event indicates that the attempted buffer creation was
+ successful. It provides the new wl_buffer referencing the dmabuf(s).
+
+ Upon receiving this event, the client should destroy the
+ zlinux_dmabuf_params object.
+ </description>
+ <arg name="buffer" type="new_id" interface="wl_buffer"
+ summary="the newly created wl_buffer"/>
+ </event>
+
+ <event name="failed">
+ <description summary="buffer creation failed">
+ This event indicates that the attempted buffer creation has
+ failed. It usually means that one of the dmabuf constraints
+ has not been fulfilled.
+
+ Upon receiving this event, the client should destroy the
+ zlinux_buffer_params object.
+ </description>
+ </event>
+
+ <request name="create_immed" since="2">
+ <description summary="immediately create a wl_buffer from the given
+ dmabufs">
+ This asks for immediate creation of a wl_buffer by importing the
+ added dmabufs.
+
+ In case of import success, no event is sent from the server, and the
+ wl_buffer is ready to be used by the client.
+
+ Upon import failure, either of the following may happen, as seen fit
+ by the implementation:
+ - the client is terminated with one of the following fatal protocol
+ errors:
+ - INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS,
+ in case of argument errors such as mismatch between the number
+ of planes and the format, bad format, non-positive width or
+ height, or bad offset or stride.
+ - INVALID_WL_BUFFER, in case the cause for failure is unknown or
+ plaform specific.
+ - the server creates an invalid wl_buffer, marks it as failed and
+ sends a 'failed' event to the client. The result of using this
+ invalid wl_buffer as an argument in any request by the client is
+ defined by the compositor implementation.
+
+ This takes the same arguments as a 'create' request, and obeys the
+ same restrictions.
+ </description>
+ <arg name="buffer_id" type="new_id" interface="wl_buffer"
+ summary="id for the newly created wl_buffer"/>
+ <arg name="width" type="int" summary="base plane width in pixels"/>
+ <arg name="height" type="int" summary="base plane height in pixels"/>
+ <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+ <arg name="flags" type="uint" summary="see enum flags"/>
+ </request>
+
+ </interface>
+
+</protocol>
--- /dev/null
+Pointer constraints protocol
+
+Maintainers:
+Jonas Ådahl <jadahl@gmail.com>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="pointer_constraints_unstable_v1">
+
+ <copyright>
+ Copyright © 2014 Jonas Ådahl
+ Copyright © 2015 Red Hat Inc.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <description summary="protocol for constraining pointer motions">
+ This protocol specifies a set of interfaces used for adding constraints to
+ the motion of a pointer. Possible constraints include confining pointer
+ motions to a given region, or locking it to its current position.
+
+ In order to constrain the pointer, a client must first bind the global
+ interface "wp_pointer_constraints" which, if a compositor supports pointer
+ constraints, is exposed by the registry. Using the bound global object, the
+ client uses the request that corresponds to the type of constraint it wants
+ to make. See wp_pointer_constraints for more details.
+
+ Warning! The protocol described in this file is experimental and backward
+ incompatible changes may be made. Backward compatible changes may be added
+ together with the corresponding interface version bump. Backward
+ incompatible changes are done by bumping the version number in the protocol
+ and interface names and resetting the interface version. Once the protocol
+ is to be declared stable, the 'z' prefix and the version number in the
+ protocol and interface names are removed and the interface version number is
+ reset.
+ </description>
+
+ <interface name="zwp_pointer_constraints_v1" version="1">
+ <description summary="constrain the movement of a pointer">
+ The global interface exposing pointer constraining functionality. It
+ exposes two requests: lock_pointer for locking the pointer to its
+ position, and confine_pointer for locking the pointer to a region.
+
+ The lock_pointer and confine_pointer requests create the objects
+ wp_locked_pointer and wp_confined_pointer respectively, and the client can
+ use these objects to interact with the lock.
+
+ For any surface, only one lock or confinement may be active across all
+ wl_pointer objects of the same seat. If a lock or confinement is requested
+ when another lock or confinement is active or requested on the same surface
+ and with any of the wl_pointer objects of the same seat, an
+ 'already_constrained' error will be raised.
+ </description>
+
+ <enum name="error">
+ <description summary="wp_pointer_constraints error values">
+ These errors can be emitted in response to wp_pointer_constraints
+ requests.
+ </description>
+ <entry name="already_constrained" value="1"
+ summary="pointer constraint already requested on that surface"/>
+ </enum>
+
+ <enum name="lifetime">
+ <description summary="constraint lifetime">
+ These values represent different lifetime semantics. They are passed
+ as arguments to the factory requests to specify how the constraint
+ lifetimes should be managed.
+ </description>
+ <entry name="oneshot" value="1">
+ <description summary="the pointer constraint is defunct once deactivated">
+ A oneshot pointer constraint will never reactivate once it has been
+ deactivated. See the corresponding deactivation event
+ (wp_locked_pointer.unlocked and wp_confined_pointer.unconfined) for
+ details.
+ </description>
+ </entry>
+ <entry name="persistent" value="2">
+ <description summary="the pointer constraint may reactivate">
+ A persistent pointer constraint may again reactivate once it has
+ been deactivated. See the corresponding deactivation event
+ (wp_locked_pointer.unlocked and wp_confined_pointer.unconfined) for
+ details.
+ </description>
+ </entry>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the pointer constraints manager object">
+ Used by the client to notify the server that it will no longer use this
+ pointer constraints object.
+ </description>
+ </request>
+
+ <request name="lock_pointer">
+ <description summary="lock pointer to a position">
+ The lock_pointer request lets the client request to disable movements of
+ the virtual pointer (i.e. the cursor), effectively locking the pointer
+ to a position. This request may not take effect immediately; in the
+ future, when the compositor deems implementation-specific constraints
+ are satisfied, the pointer lock will be activated and the compositor
+ sends a locked event.
+
+ The protocol provides no guarantee that the constraints are ever
+ satisfied, and does not require the compositor to send an error if the
+ constraints cannot ever be satisfied. It is thus possible to request a
+ lock that will never activate.
+
+ There may not be another pointer constraint of any kind requested or
+ active on the surface for any of the wl_pointer objects of the seat of
+ the passed pointer when requesting a lock. If there is, an error will be
+ raised. See general pointer lock documentation for more details.
+
+ The intersection of the region passed with this request and the input
+ region of the surface is used to determine where the pointer must be
+ in order for the lock to activate. It is up to the compositor whether to
+ warp the pointer or require some kind of user interaction for the lock
+ to activate. If the region is null the surface input region is used.
+
+ A surface may receive pointer focus without the lock being activated.
+
+ The request creates a new object wp_locked_pointer which is used to
+ interact with the lock as well as receive updates about its state. See
+ the the description of wp_locked_pointer for further information.
+
+ Note that while a pointer is locked, the wl_pointer objects of the
+ corresponding seat will not emit any wl_pointer.motion events, but
+ relative motion events will still be emitted via wp_relative_pointer
+ objects of the same seat. wl_pointer.axis and wl_pointer.button events
+ are unaffected.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_locked_pointer_v1"/>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="surface to lock pointer to"/>
+ <arg name="pointer" type="object" interface="wl_pointer"
+ summary="the pointer that should be locked"/>
+ <arg name="region" type="object" interface="wl_region" allow-null="true"
+ summary="region of surface"/>
+ <arg name="lifetime" type="uint" summary="lock lifetime"/>
+ </request>
+
+ <request name="confine_pointer">
+ <description summary="confine pointer to a region">
+ The confine_pointer request lets the client request to confine the
+ pointer cursor to a given region. This request may not take effect
+ immediately; in the future, when the compositor deems implementation-
+ specific constraints are satisfied, the pointer confinement will be
+ activated and the compositor sends a confined event.
+
+ The intersection of the region passed with this request and the input
+ region of the surface is used to determine where the pointer must be
+ in order for the confinement to activate. It is up to the compositor
+ whether to warp the pointer or require some kind of user interaction for
+ the confinement to activate. If the region is null the surface input
+ region is used.
+
+ The request will create a new object wp_confined_pointer which is used
+ to interact with the confinement as well as receive updates about its
+ state. See the the description of wp_confined_pointer for further
+ information.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_confined_pointer_v1"/>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="surface to lock pointer to"/>
+ <arg name="pointer" type="object" interface="wl_pointer"
+ summary="the pointer that should be confined"/>
+ <arg name="region" type="object" interface="wl_region" allow-null="true"
+ summary="region of surface"/>
+ <arg name="lifetime" type="uint" summary="confinement lifetime"/>
+ </request>
+ </interface>
+
+ <interface name="zwp_locked_pointer_v1" version="1">
+ <description summary="receive relative pointer motion events">
+ The wp_locked_pointer interface represents a locked pointer state.
+
+ While the lock of this object is active, the wl_pointer objects of the
+ associated seat will not emit any wl_pointer.motion events.
+
+ This object will send the event 'locked' when the lock is activated.
+ Whenever the lock is activated, it is guaranteed that the locked surface
+ will already have received pointer focus and that the pointer will be
+ within the region passed to the request creating this object.
+
+ To unlock the pointer, send the destroy request. This will also destroy
+ the wp_locked_pointer object.
+
+ If the compositor decides to unlock the pointer the unlocked event is
+ sent. See wp_locked_pointer.unlock for details.
+
+ When unlocking, the compositor may warp the cursor position to the set
+ cursor position hint. If it does, it will not result in any relative
+ motion events emitted via wp_relative_pointer.
+
+ If the surface the lock was requested on is destroyed and the lock is not
+ yet activated, the wp_locked_pointer object is now defunct and must be
+ destroyed.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the locked pointer object">
+ Destroy the locked pointer object. If applicable, the compositor will
+ unlock the pointer.
+ </description>
+ </request>
+
+ <request name="set_cursor_position_hint">
+ <description summary="set the pointer cursor position hint">
+ Set the cursor position hint relative to the top left corner of the
+ surface.
+
+ If the client is drawing its own cursor, it should update the position
+ hint to the position of its own cursor. A compositor may use this
+ information to warp the pointer upon unlock in order to avoid pointer
+ jumps.
+
+ The cursor position hint is double buffered. The new hint will only take
+ effect when the associated surface gets it pending state applied. See
+ wl_surface.commit for details.
+ </description>
+ <arg name="surface_x" type="fixed"
+ summary="surface-local x coordinate"/>
+ <arg name="surface_y" type="fixed"
+ summary="surface-local y coordinate"/>
+ </request>
+
+ <request name="set_region">
+ <description summary="set a new lock region">
+ Set a new region used to lock the pointer.
+
+ The new lock region is double-buffered. The new lock region will
+ only take effect when the associated surface gets its pending state
+ applied. See wl_surface.commit for details.
+
+ For details about the lock region, see wp_locked_pointer.
+ </description>
+ <arg name="region" type="object" interface="wl_region" allow-null="true"
+ summary="region of surface"/>
+ </request>
+
+ <event name="locked">
+ <description summary="lock activation event">
+ Notification that the pointer lock of the seat's pointer is activated.
+ </description>
+ </event>
+
+ <event name="unlocked">
+ <description summary="lock deactivation event">
+ Notification that the pointer lock of the seat's pointer is no longer
+ active. If this is a oneshot pointer lock (see
+ wp_pointer_constraints.lifetime) this object is now defunct and should
+ be destroyed. If this is a persistent pointer lock (see
+ wp_pointer_constraints.lifetime) this pointer lock may again
+ reactivate in the future.
+ </description>
+ </event>
+ </interface>
+
+ <interface name="zwp_confined_pointer_v1" version="1">
+ <description summary="confined pointer object">
+ The wp_confined_pointer interface represents a confined pointer state.
+
+ This object will send the event 'confined' when the confinement is
+ activated. Whenever the confinement is activated, it is guaranteed that
+ the surface the pointer is confined to will already have received pointer
+ focus and that the pointer will be within the region passed to the request
+ creating this object. It is up to the compositor to decide whether this
+ requires some user interaction and if the pointer will warp to within the
+ passed region if outside.
+
+ To unconfine the pointer, send the destroy request. This will also destroy
+ the wp_confined_pointer object.
+
+ If the compositor decides to unconfine the pointer the unconfined event is
+ sent. The wp_confined_pointer object is at this point defunct and should
+ be destroyed.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the confined pointer object">
+ Destroy the confined pointer object. If applicable, the compositor will
+ unconfine the pointer.
+ </description>
+ </request>
+
+ <request name="set_region">
+ <description summary="set a new confine region">
+ Set a new region used to confine the pointer.
+
+ The new confine region is double-buffered. The new confine region will
+ only take effect when the associated surface gets its pending state
+ applied. See wl_surface.commit for details.
+
+ If the confinement is active when the new confinement region is applied
+ and the pointer ends up outside of newly applied region, the pointer may
+ warped to a position within the new confinement region. If warped, a
+ wl_pointer.motion event will be emitted, but no
+ wp_relative_pointer.relative_motion event.
+
+ The compositor may also, instead of using the new region, unconfine the
+ pointer.
+
+ For details about the confine region, see wp_confined_pointer.
+ </description>
+ <arg name="region" type="object" interface="wl_region" allow-null="true"
+ summary="region of surface"/>
+ </request>
+
+ <event name="confined">
+ <description summary="pointer confined">
+ Notification that the pointer confinement of the seat's pointer is
+ activated.
+ </description>
+ </event>
+
+ <event name="unconfined">
+ <description summary="pointer unconfined">
+ Notification that the pointer confinement of the seat's pointer is no
+ longer active. If this is a oneshot pointer confinement (see
+ wp_pointer_constraints.lifetime) this object is now defunct and should
+ be destroyed. If this is a persistent pointer confinement (see
+ wp_pointer_constraints.lifetime) this pointer confinement may again
+ reactivate in the future.
+ </description>
+ </event>
+ </interface>
+
+</protocol>
--- /dev/null
+Pointer gestures protocol
+
+Maintainers:
+Carlos Garnacho <carlosg@gnome.org>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="pointer_gestures_unstable_v1">
+
+ <interface name="zwp_pointer_gestures_v1" version="1">
+ <description summary="touchpad gestures">
+ A global interface to provide semantic touchpad gestures for a given
+ pointer.
+
+ Two gestures are currently supported: swipe and zoom/rotate.
+ All gestures follow a three-stage cycle: begin, update, end and
+ are identified by a unique id.
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible changes
+ may be added together with the corresponding interface version bump.
+ Backward incompatible changes are done by bumping the version number in
+ the protocol and interface names and resetting the interface version.
+ Once the protocol is to be declared stable, the 'z' prefix and the
+ version number in the protocol and interface names are removed and the
+ interface version number is reset.
+ </description>
+
+ <request name="get_swipe_gesture">
+ <description summary="get swipe gesture">
+ Create a swipe gesture object. See the
+ wl_pointer_gesture_swipe interface for details.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_pointer_gesture_swipe_v1"/>
+ <arg name="pointer" type="object" interface="wl_pointer"/>
+ </request>
+
+ <request name="get_pinch_gesture">
+ <description summary="get pinch gesture">
+ Create a pinch gesture object. See the
+ wl_pointer_gesture_pinch interface for details.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_pointer_gesture_pinch_v1"/>
+ <arg name="pointer" type="object" interface="wl_pointer"/>
+ </request>
+ </interface>
+
+ <interface name="zwp_pointer_gesture_swipe_v1" version="1">
+ <description summary="a swipe gesture object">
+ A swipe gesture object notifies a client about a multi-finger swipe
+ gesture detected on an indirect input device such as a touchpad.
+ The gesture is usually initiated by multiple fingers moving in the
+ same direction but once initiated the direction may change.
+ The precise conditions of when such a gesture is detected are
+ implementation-dependent.
+
+ A gesture consists of three stages: begin, update (optional) and end.
+ There cannot be multiple simultaneous pinch or swipe gestures on a
+ same pointer/seat, how compositors prevent these situations is
+ implementation-dependent.
+
+ A gesture may be cancelled by the compositor or the hardware.
+ Clients should not consider performing permanent or irreversible
+ actions until the end of a gesture has been received.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the pointer swipe gesture object"/>
+ </request>
+
+ <event name="begin">
+ <description summary="multi-finger swipe begin">
+ This event is sent when a multi-finger swipe gesture is detected
+ on the device.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ <arg name="fingers" type="uint" summary="number of fingers"/>
+ </event>
+
+ <event name="update">
+ <description summary="multi-finger swipe motion">
+ This event is sent when a multi-finger swipe gesture changes the
+ position of the logical center.
+
+ The dx and dy coordinates are relative coordinates of the logical
+ center of the gesture compared to the previous event.
+ </description>
+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+ <arg name="dx" type="fixed" summary="delta x coordinate in surface coordinate space"/>
+ <arg name="dy" type="fixed" summary="delta y coordinate in surface coordinate space"/>
+ </event>
+
+ <event name="end">
+ <description summary="multi-finger swipe end">
+ This event is sent when a multi-finger swipe gesture ceases to
+ be valid. This may happen when one or more fingers are lifted or
+ the gesture is cancelled.
+
+ When a gesture is cancelled, the client should undo state changes
+ caused by this gesture. What causes a gesture to be cancelled is
+ implementation-dependent.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+ <arg name="cancelled" type="int" summary="1 if the gesture was cancelled, 0 otherwise"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_pointer_gesture_pinch_v1" version="1">
+ <description summary="a pinch gesture object">
+ A pinch gesture object notifies a client about a multi-finger pinch
+ gesture detected on an indirect input device such as a touchpad.
+ The gesture is usually initiated by multiple fingers moving towards
+ each other or away from each other, or by two or more fingers rotating
+ around a logical center of gravity. The precise conditions of when
+ such a gesture is detected are implementation-dependent.
+
+ A gesture consists of three stages: begin, update (optional) and end.
+ There cannot be multiple simultaneous pinch or swipe gestures on a
+ same pointer/seat, how compositors prevent these situations is
+ implementation-dependent.
+
+ A gesture may be cancelled by the compositor or the hardware.
+ Clients should not consider performing permanent or irreversible
+ actions until the end of a gesture has been received.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the pinch gesture object"/>
+ </request>
+
+ <event name="begin">
+ <description summary="multi-finger pinch begin">
+ This event is sent when a multi-finger pinch gesture is detected
+ on the device.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ <arg name="fingers" type="uint" summary="number of fingers"/>
+ </event>
+
+ <event name="update">
+ <description summary="multi-finger pinch motion">
+ This event is sent when a multi-finger pinch gesture changes the
+ position of the logical center, the rotation or the relative scale.
+
+ The dx and dy coordinates are relative coordinates in the
+ surface coordinate space of the logical center of the gesture.
+
+ The scale factor is an absolute scale compared to the
+ pointer_gesture_pinch.begin event, e.g. a scale of 2 means the fingers
+ are now twice as far apart as on pointer_gesture_pinch.begin.
+
+ The rotation is the relative angle in degrees clockwise compared to the previous
+ pointer_gesture_pinch.begin or pointer_gesture_pinch.update event.
+ </description>
+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+ <arg name="dx" type="fixed" summary="delta x coordinate in surface coordinate space"/>
+ <arg name="dy" type="fixed" summary="delta y coordinate in surface coordinate space"/>
+ <arg name="scale" type="fixed" summary="scale relative to the initial finger position"/>
+ <arg name="rotation" type="fixed" summary="angle in degrees cw relative to the previous event"/>
+ </event>
+
+ <event name="end">
+ <description summary="multi-finger pinch end">
+ This event is sent when a multi-finger pinch gesture ceases to
+ be valid. This may happen when one or more fingers are lifted or
+ the gesture is cancelled.
+
+ When a gesture is cancelled, the client should undo state changes
+ caused by this gesture. What causes a gesture to be cancelled is
+ implementation-dependent.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+ <arg name="cancelled" type="int" summary="1 if the gesture was cancelled, 0 otherwise"/>
+ </event>
+ </interface>
+
+</protocol>
--- /dev/null
+Relative pointer protocol
+
+Maintainers:
+Jonas Ådahl <jadahl@gmail.com>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="relative_pointer_unstable_v1">
+
+ <copyright>
+ Copyright © 2014 Jonas Ådahl
+ Copyright © 2015 Red Hat Inc.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <description summary="protocol for relative pointer motion events">
+ This protocol specifies a set of interfaces used for making clients able to
+ receive relative pointer events not obstructed by barriers (such as the
+ monitor edge or other pointer barriers).
+
+ To start receiving relative pointer events, a client must first bind the
+ global interface "wp_relative_pointer_manager" which, if a compositor
+ supports relative pointer motion events, is exposed by the registry. After
+ having created the relative pointer manager proxy object, the client uses
+ it to create the actual relative pointer object using the
+ "get_relative_pointer" request given a wl_pointer. The relative pointer
+ motion events will then, when applicable, be transmitted via the proxy of
+ the newly created relative pointer object. See the documentation of the
+ relative pointer interface for more details.
+
+ Warning! The protocol described in this file is experimental and backward
+ incompatible changes may be made. Backward compatible changes may be added
+ together with the corresponding interface version bump. Backward
+ incompatible changes are done by bumping the version number in the protocol
+ and interface names and resetting the interface version. Once the protocol
+ is to be declared stable, the 'z' prefix and the version number in the
+ protocol and interface names are removed and the interface version number is
+ reset.
+ </description>
+
+ <interface name="zwp_relative_pointer_manager_v1" version="1">
+ <description summary="get relative pointer objects">
+ A global interface used for getting the relative pointer object for a
+ given pointer.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the relative pointer manager object">
+ Used by the client to notify the server that it will no longer use this
+ relative pointer manager object.
+ </description>
+ </request>
+
+ <request name="get_relative_pointer">
+ <description summary="get a relative pointer object">
+ Create a relative pointer interface given a wl_pointer object. See the
+ wp_relative_pointer interface for more details.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_relative_pointer_v1"/>
+ <arg name="pointer" type="object" interface="wl_pointer"/>
+ </request>
+ </interface>
+
+ <interface name="zwp_relative_pointer_v1" version="1">
+ <description summary="relative pointer object">
+ A wp_relative_pointer object is an extension to the wl_pointer interface
+ used for emitting relative pointer events. It shares the same focus as
+ wl_pointer objects of the same seat and will only emit events when it has
+ focus.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="release the relative pointer object"/>
+ </request>
+
+ <event name="relative_motion">
+ <description summary="relative pointer motion">
+ Relative x/y pointer motion from the pointer of the seat associated with
+ this object.
+
+ A relative motion is in the same dimension as regular wl_pointer motion
+ events, except they do not represent an absolute position. For example,
+ moving a pointer from (x, y) to (x', y') would have the equivalent
+ relative motion (x' - x, y' - y). If a pointer motion caused the
+ absolute pointer position to be clipped by for example the edge of the
+ monitor, the relative motion is unaffected by the clipping and will
+ represent the unclipped motion.
+
+ This event also contains non-accelerated motion deltas. The
+ non-accelerated delta is, when applicable, the regular pointer motion
+ delta as it was before having applied motion acceleration and other
+ transformations such as normalization.
+
+ Note that the non-accelerated delta does not represent 'raw' events as
+ they were read from some device. Pointer motion acceleration is device-
+ and configuration-specific and non-accelerated deltas and accelerated
+ deltas may have the same value on some devices.
+
+ Relative motions are not coupled to wl_pointer.motion events, and can be
+ sent in combination with such events, but also independently. There may
+ also be scenarios where wl_pointer.motion is sent, but there is no
+ relative motion. The order of an absolute and relative motion event
+ originating from the same physical motion is not guaranteed.
+
+ If the client needs button events or focus state, it can receive them
+ from a wl_pointer object of the same seat that the wp_relative_pointer
+ object is associated with.
+ </description>
+ <arg name="utime_hi" type="uint"
+ summary="high 32 bits of a 64 bit timestamp with microsecond granularity"/>
+ <arg name="utime_lo" type="uint"
+ summary="low 32 bits of a 64 bit timestamp with microsecond granularity"/>
+ <arg name="dx" type="fixed"
+ summary="the x component of the motion vector"/>
+ <arg name="dy" type="fixed"
+ summary="the y component of the motion vector"/>
+ <arg name="dx_unaccel" type="fixed"
+ summary="the x component of the unaccelerated motion vector"/>
+ <arg name="dy_unaccel" type="fixed"
+ summary="the y component of the unaccelerated motion vector"/>
+ </event>
+ </interface>
+
+</protocol>
--- /dev/null
+Tablet protocol
+
+Maintainers:
+Peter Hutterer <peter.hutterer@who-t.net>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="tablet_unstable_v1">
+
+ <copyright>
+ Copyright 2014 © Stephen "Lyude" Chandler Paul
+ Copyright 2015-2016 © Red Hat, Inc.
+
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation files
+ (the "Software"), to deal in the Software without restriction,
+ including without limitation the rights to use, copy, modify, merge,
+ publish, distribute, sublicense, and/or sell copies of the Software,
+ and to permit persons to whom the Software is furnished to do so,
+ subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the
+ next paragraph) shall be included in all copies or substantial
+ portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
+ </copyright>
+
+ <description summary="Wayland protocol for graphics tablets">
+ This description provides a high-level overview of the interplay between
+ the interfaces defined this protocol. For details, see the protocol
+ specification.
+
+ More than one tablet may exist, and device-specifics matter. Tablets are
+ not represented by a single virtual device like wl_pointer. A client
+ binds to the tablet manager object which is just a proxy object. From
+ that, the client requests wp_tablet_manager.get_tablet_seat(wl_seat)
+ and that returns the actual interface that has all the tablets. With
+ this indirection, we can avoid merging wp_tablet into the actual Wayland
+ protocol, a long-term benefit.
+
+ The wp_tablet_seat sends a "tablet added" event for each tablet
+ connected. That event is followed by descriptive events about the
+ hardware; currently that includes events for name, vid/pid and
+ a wp_tablet.path event that describes a local path. This path can be
+ used to uniquely identify a tablet or get more information through
+ libwacom. Emulated or nested tablets can skip any of those, e.g. a
+ virtual tablet may not have a vid/pid. The sequence of descriptive
+ events is terminated by a wp_tablet.done event to signal that a client
+ may now finalize any initialization for that tablet.
+
+ Events from tablets require a tool in proximity. Tools are also managed
+ by the tablet seat; a "tool added" event is sent whenever a tool is new
+ to the compositor. That event is followed by a number of descriptive
+ events about the hardware; currently that includes capabilities,
+ hardware id and serial number, and tool type. Similar to the tablet
+ interface, a wp_tablet_tool.done event is sent to terminate that initial
+ sequence.
+
+ Any event from a tool happens on the wp_tablet_tool interface. When the
+ tool gets into proximity of the tablet, a proximity_in event is sent on
+ the wp_tablet_tool interface, listing the tablet and the surface. That
+ event is followed by a motion event with the coordinates. After that,
+ it's the usual motion, axis, button, etc. events. The protocol's
+ serialisation means events are grouped by wp_tablet_tool.frame events.
+
+ Two special events (that don't exist in X) are down and up. They signal
+ "tip touching the surface". For tablets without real proximity
+ detection, the sequence is: proximity_in, motion, down, frame.
+
+ When the tool leaves proximity, a proximity_out event is sent. If any
+ button is still down, a button release event is sent before this
+ proximity event. These button events are sent in the same frame as the
+ proximity event to signal to the client that the buttons were held when
+ the tool left proximity.
+
+ If the tool moves out of the surface but stays in proximity (i.e.
+ between windows), compositor-specific grab policies apply. This usually
+ means that the proximity-out is delayed until all buttons are released.
+
+ Moving a tool physically from one tablet to the other has no real effect
+ on the protocol, since we already have the tool object from the "tool
+ added" event. All the information is already there and the proximity
+ events on both tablets are all a client needs to reconstruct what
+ happened.
+
+ Some extra axes are normalized, i.e. the client knows the range as
+ specified in the protocol (e.g. [0, 65535]), the granularity however is
+ unknown. The current normalized axes are pressure, distance, and slider.
+
+ Other extra axes are in physical units as specified in the protocol.
+ The current extra axes with physical units are tilt, rotation and
+ wheel rotation.
+
+ Since tablets work independently of the pointer controlled by the mouse,
+ the focus handling is independent too and controlled by proximity.
+ The wp_tablet_tool.set_cursor request sets a tool-specific cursor.
+ This cursor surface may be the same as the mouse cursor, and it may be
+ the same across tools but it is possible to be more fine-grained. For
+ example, a client may set different cursors for the pen and eraser.
+
+ Tools are generally independent of tablets and it is
+ compositor-specific policy when a tool can be removed. Common approaches
+ will likely include some form of removing a tool when all tablets the
+ tool was used on are removed.
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible changes
+ may be added together with the corresponding interface version bump.
+ Backward incompatible changes are done by bumping the version number in
+ the protocol and interface names and resetting the interface version.
+ Once the protocol is to be declared stable, the 'z' prefix and the
+ version number in the protocol and interface names are removed and the
+ interface version number is reset.
+ </description>
+
+ <interface name="zwp_tablet_manager_v1" version="1">
+ <description summary="controller object for graphic tablet devices">
+ An object that provides access to the graphics tablets available on this
+ system. All tablets are associated with a seat, to get access to the
+ actual tablets, use wp_tablet_manager.get_tablet_seat.
+ </description>
+
+ <request name="get_tablet_seat">
+ <description summary="get the tablet seat">
+ Get the wp_tablet_seat object for the given seat. This object
+ provides access to all graphics tablets in this seat.
+ </description>
+ <arg name="tablet_seat" type="new_id" interface="zwp_tablet_seat_v1"/>
+ <arg name="seat" type="object" interface="wl_seat" summary="The wl_seat object to retrieve the tablets for" />
+ </request>
+
+ <request name="destroy" type="destructor">
+ <description summary="release the memory for the tablet manager object">
+ Destroy the wp_tablet_manager object. Objects created from this
+ object are unaffected and should be destroyed separately.
+ </description>
+ </request>
+ </interface>
+
+ <interface name="zwp_tablet_seat_v1" version="1">
+ <description summary="controller object for graphic tablet devices of a seat">
+ An object that provides access to the graphics tablets available on this
+ seat. After binding to this interface, the compositor sends a set of
+ wp_tablet_seat.tablet_added and wp_tablet_seat.tool_added events.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="release the memory for the tablet seat object">
+ Destroy the wp_tablet_seat object. Objects created from this
+ object are unaffected and should be destroyed separately.
+ </description>
+ </request>
+
+ <event name="tablet_added">
+ <description summary="new device notification">
+ This event is sent whenever a new tablet becomes available on this
+ seat. This event only provides the object id of the tablet, any
+ static information about the tablet (device name, vid/pid, etc.) is
+ sent through the wp_tablet interface.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_tablet_v1" summary="the newly added graphics tablet"/>
+ </event>
+
+ <event name="tool_added">
+ <description summary="a new tool has been used with a tablet">
+ This event is sent whenever a tool that has not previously been used
+ with a tablet comes into use. This event only provides the object id
+ of the tool; any static information about the tool (capabilities,
+ type, etc.) is sent through the wp_tablet_tool interface.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_tablet_tool_v1" summary="the newly added tablet tool"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_tablet_tool_v1" version="1">
+ <description summary="a physical tablet tool">
+ An object that represents a physical tool that has been, or is
+ currently in use with a tablet in this seat. Each wp_tablet_tool
+ object stays valid until the client destroys it; the compositor
+ reuses the wp_tablet_tool object to indicate that the object's
+ respective physical tool has come into proximity of a tablet again.
+
+ A wp_tablet_tool object's relation to a physical tool depends on the
+ tablet's ability to report serial numbers. If the tablet supports
+ this capability, then the object represents a specific physical tool
+ and can be identified even when used on multiple tablets.
+
+ A tablet tool has a number of static characteristics, e.g. tool type,
+ hardware_serial and capabilities. These capabilities are sent in an
+ event sequence after the wp_tablet_seat.tool_added event before any
+ actual events from this tool. This initial event sequence is
+ terminated by a wp_tablet_tool.done event.
+
+ Tablet tool events are grouped by wp_tablet_tool.frame events.
+ Any events received before a wp_tablet_tool.frame event should be
+ considered part of the same hardware state change.
+ </description>
+
+ <request name="set_cursor">
+ <description summary="set the tablet tool's surface">
+ Sets the surface of the cursor used for this tool on the given
+ tablet. This request only takes effect if the tool is in proximity
+ of one of the requesting client's surfaces or the surface parameter
+ is the current pointer surface. If there was a previous surface set
+ with this request it is replaced. If surface is NULL, the cursor
+ image is hidden.
+
+ The parameters hotspot_x and hotspot_y define the position of the
+ pointer surface relative to the pointer location. Its top-left corner
+ is always at (x, y) - (hotspot_x, hotspot_y), where (x, y) are the
+ coordinates of the pointer location, in surface-local coordinates.
+
+ On surface.attach requests to the pointer surface, hotspot_x and
+ hotspot_y are decremented by the x and y parameters passed to the
+ request. Attach must be confirmed by wl_surface.commit as usual.
+
+ The hotspot can also be updated by passing the currently set pointer
+ surface to this request with new values for hotspot_x and hotspot_y.
+
+ The current and pending input regions of the wl_surface are cleared,
+ and wl_surface.set_input_region is ignored until the wl_surface is no
+ longer used as the cursor. When the use as a cursor ends, the current
+ and pending input regions become undefined, and the wl_surface is
+ unmapped.
+
+ This request gives the surface the role of a cursor. The role
+ assigned by this request is the same as assigned by
+ wl_pointer.set_cursor meaning the same surface can be
+ used both as a wl_pointer cursor and a wp_tablet cursor. If the
+ surface already has another role, it raises a protocol error.
+ The surface may be used on multiple tablets and across multiple
+ seats.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the enter event"/>
+ <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
+ <arg name="hotspot_x" type="int" summary="surface-local x coordinate"/>
+ <arg name="hotspot_y" type="int" summary="surface-local y coordinate"/>
+ </request>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the tool object">
+ This destroys the client's resource for this tool object.
+ </description>
+ </request>
+
+ <enum name="type">
+ <description summary="a physical tool type">
+ Describes the physical type of a tool. The physical type of a tool
+ generally defines its base usage.
+
+ The mouse tool represents a mouse-shaped tool that is not a relative
+ device but bound to the tablet's surface, providing absolute
+ coordinates.
+
+ The lens tool is a mouse-shaped tool with an attached lens to
+ provide precision focus.
+ </description>
+ <entry name="pen" value="0x140" summary="Pen"/>
+ <entry name="eraser" value="0x141" summary="Eraser"/>
+ <entry name="brush" value="0x142" summary="Brush"/>
+ <entry name="pencil" value="0x143" summary="Pencil"/>
+ <entry name="airbrush" value="0x144" summary="Airbrush"/>
+ <entry name="finger" value="0x145" summary="Finger"/>
+ <entry name="mouse" value="0x146" summary="Mouse"/>
+ <entry name="lens" value="0x147" summary="Lens"/>
+ </enum>
+
+ <event name="type">
+ <description summary="tool type">
+ The tool type is the high-level type of the tool and usually decides
+ the interaction expected from this tool.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_tool.done event.
+ </description>
+ <arg name="tool_type" type="uint" enum="type" summary="the physical tool type"/>
+ </event>
+
+ <event name="hardware_serial">
+ <description summary="unique hardware serial number of the tool">
+ If the physical tool can be identified by a unique 64-bit serial
+ number, this event notifies the client of this serial number.
+
+ If multiple tablets are available in the same seat and the tool is
+ uniquely identifiable by the serial number, that tool may move
+ between tablets.
+
+ Otherwise, if the tool has no serial number and this event is
+ missing, the tool is tied to the tablet it first comes into
+ proximity with. Even if the physical tool is used on multiple
+ tablets, separate wp_tablet_tool objects will be created, one per
+ tablet.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_tool.done event.
+ </description>
+ <arg name="hardware_serial_hi" type="uint" summary="the unique serial number of the tool, most significant bits"/>
+ <arg name="hardware_serial_lo" type="uint" summary="the unique serial number of the tool, least significant bits"/>
+ </event>
+
+ <event name="hardware_id_wacom">
+ <description summary="hardware id notification in Wacom's format">
+ This event notifies the client of a hardware id available on this tool.
+
+ The hardware id is a device-specific 64-bit id that provides extra
+ information about the tool in use, beyond the wl_tool.type
+ enumeration. The format of the id is specific to tablets made by
+ Wacom Inc. For example, the hardware id of a Wacom Grip
+ Pen (a stylus) is 0x802.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_tool.done event.
+ </description>
+ <arg name="hardware_id_hi" type="uint" summary="the hardware id, most significant bits"/>
+ <arg name="hardware_id_lo" type="uint" summary="the hardware id, least significant bits"/>
+ </event>
+
+ <enum name="capability">
+ <description summary="capability flags for a tool">
+ Describes extra capabilities on a tablet.
+
+ Any tool must provide x and y values, extra axes are
+ device-specific.
+ </description>
+ <entry name="tilt" value="1" summary="Tilt axes"/>
+ <entry name="pressure" value="2" summary="Pressure axis"/>
+ <entry name="distance" value="3" summary="Distance axis"/>
+ <entry name="rotation" value="4" summary="Z-rotation axis"/>
+ <entry name="slider" value="5" summary="Slider axis"/>
+ <entry name="wheel" value="6" summary="Wheel axis"/>
+ </enum>
+
+ <event name="capability">
+ <description summary="tool capability notification">
+ This event notifies the client of any capabilities of this tool,
+ beyond the main set of x/y axes and tip up/down detection.
+
+ One event is sent for each extra capability available on this tool.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_tool.done event.
+ </description>
+ <arg name="capability" type="uint" enum="capability" summary="the capability"/>
+ </event>
+
+ <event name="done">
+ <description summary="tool description events sequence complete">
+ This event signals the end of the initial burst of descriptive
+ events. A client may consider the static description of the tool to
+ be complete and finalize initialization of the tool.
+ </description>
+ </event>
+
+ <event name="removed">
+ <description summary="tool removed">
+ This event is sent when the tool is removed from the system and will
+ send no further events. Should the physical tool come back into
+ proximity later, a new wp_tablet_tool object will be created.
+
+ It is compositor-dependent when a tool is removed. A compositor may
+ remove a tool on proximity out, tablet removal or any other reason.
+ A compositor may also keep a tool alive until shutdown.
+
+ If the tool is currently in proximity, a proximity_out event will be
+ sent before the removed event. See wp_tablet_tool.proximity_out for
+ the handling of any buttons logically down.
+
+ When this event is received, the client must wp_tablet_tool.destroy
+ the object.
+ </description>
+ </event>
+
+ <event name="proximity_in">
+ <description summary="proximity in event">
+ Notification that this tool is focused on a certain surface.
+
+ This event can be received when the tool has moved from one surface to
+ another, or when the tool has come back into proximity above the
+ surface.
+
+ If any button is logically down when the tool comes into proximity,
+ the respective button event is sent after the proximity_in event but
+ within the same frame as the proximity_in event.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="tablet" type="object" interface="zwp_tablet_v1" summary="The tablet the tool is in proximity of"/>
+ <arg name="surface" type="object" interface="wl_surface" summary="The current surface the tablet tool is over"/>
+ </event>
+
+ <event name="proximity_out">
+ <description summary="proximity out event">
+ Notification that this tool has either left proximity, or is no
+ longer focused on a certain surface.
+
+ When the tablet tool leaves proximity of the tablet, button release
+ events are sent for each button that was held down at the time of
+ leaving proximity. These events are sent before the proximity_out
+ event but within the same wp_tablet.frame.
+
+ If the tool stays within proximity of the tablet, but the focus
+ changes from one surface to another, a button release event may not
+ be sent until the button is actually released or the tool leaves the
+ proximity of the tablet.
+ </description>
+ </event>
+
+ <event name="down">
+ <description summary="tablet tool is making contact">
+ Sent whenever the tablet tool comes in contact with the surface of the
+ tablet.
+
+ If the tool is already in contact with the tablet when entering the
+ input region, the client owning said region will receive a
+ wp_tablet.proximity_in event, followed by a wp_tablet.down
+ event and a wp_tablet.frame event.
+
+ Note that this event describes logical contact, not physical
+ contact. On some devices, a compositor may not consider a tool in
+ logical contact until a minimum physical pressure threshold is
+ exceeded.
+ </description>
+ <arg name="serial" type="uint"/>
+ </event>
+
+ <event name="up">
+ <description summary="tablet tool is no longer making contact">
+ Sent whenever the tablet tool stops making contact with the surface of
+ the tablet, or when the tablet tool moves out of the input region
+ and the compositor grab (if any) is dismissed.
+
+ If the tablet tool moves out of the input region while in contact
+ with the surface of the tablet and the compositor does not have an
+ ongoing grab on the surface, the client owning said region will
+ receive a wp_tablet.up event, followed by a wp_tablet.proximity_out
+ event and a wp_tablet.frame event. If the compositor has an ongoing
+ grab on this device, this event sequence is sent whenever the grab
+ is dismissed in the future.
+
+ Note that this event describes logical contact, not physical
+ contact. On some devices, a compositor may not consider a tool out
+ of logical contact until physical pressure falls below a specific
+ threshold.
+ </description>
+ </event>
+
+ <event name="motion">
+ <description summary="motion event">
+ Sent whenever a tablet tool moves.
+ </description>
+ <arg name="x" type="fixed" summary="surface-local x coordinate"/>
+ <arg name="y" type="fixed" summary="surface-local y coordinate"/>
+ </event>
+
+ <event name="pressure">
+ <description summary="pressure change event">
+ Sent whenever the pressure axis on a tool changes. The value of this
+ event is normalized to a value between 0 and 65535.
+
+ Note that pressure may be nonzero even when a tool is not in logical
+ contact. See the down and up events for more details.
+ </description>
+ <arg name="pressure" type="uint" summary="The current pressure value"/>
+ </event>
+
+ <event name="distance">
+ <description summary="distance change event">
+ Sent whenever the distance axis on a tool changes. The value of this
+ event is normalized to a value between 0 and 65535.
+
+ Note that distance may be nonzero even when a tool is not in logical
+ contact. See the down and up events for more details.
+ </description>
+ <arg name="distance" type="uint" summary="The current distance value"/>
+ </event>
+
+ <event name="tilt">
+ <description summary="tilt change event">
+ Sent whenever one or both of the tilt axes on a tool change. Each tilt
+ value is in 0.01 of a degree, relative to the z-axis of the tablet.
+ The angle is positive when the top of a tool tilts along the
+ positive x or y axis.
+ </description>
+ <arg name="tilt_x" type="int" summary="The current value of the X tilt axis"/>
+ <arg name="tilt_y" type="int" summary="The current value of the Y tilt axis"/>
+ </event>
+
+ <event name="rotation">
+ <description summary="z-rotation change event">
+ Sent whenever the z-rotation axis on the tool changes. The
+ rotation value is in 0.01 of a degree clockwise from the tool's
+ logical neutral position.
+ </description>
+ <arg name="degrees" type="int" summary="The current rotation of the Z axis"/>
+ </event>
+
+ <event name="slider">
+ <description summary="Slider position change event">
+ Sent whenever the slider position on the tool changes. The
+ value is normalized between -65535 and 65535, with 0 as the logical
+ neutral position of the slider.
+
+ The slider is available on e.g. the Wacom Airbrush tool.
+ </description>
+ <arg name="position" type="int" summary="The current position of slider"/>
+ </event>
+
+ <event name="wheel">
+ <description summary="Wheel delta event">
+ Sent whenever the wheel on the tool emits an event. This event
+ contains two values for the same axis change. The degrees value is
+ in 0.01 of a degree in the same orientation as the
+ wl_pointer.vertical_scroll axis. The clicks value is in discrete
+ logical clicks of the mouse wheel. This value may be zero if the
+ movement of the wheel was less than one logical click.
+
+ Clients should choose either value and avoid mixing degrees and
+ clicks. The compositor may accumulate values smaller than a logical
+ click and emulate click events when a certain threshold is met.
+ Thus, wl_tablet_tool.wheel events with non-zero clicks values may
+ have different degrees values.
+ </description>
+ <arg name="degrees" type="int" summary="The wheel delta in 0.01 of a degree"/>
+ <arg name="clicks" type="int" summary="The wheel delta in discrete clicks"/>
+ </event>
+
+ <enum name="button_state">
+ <description summary="physical button state">
+ Describes the physical state of a button that produced the button event.
+ </description>
+ <entry name="released" value="0" summary="button is not pressed"/>
+ <entry name="pressed" value="1" summary="button is pressed"/>
+ </enum>
+
+ <event name="button">
+ <description summary="button event">
+ Sent whenever a button on the tool is pressed or released.
+
+ If a button is held down when the tool moves in or out of proximity,
+ button events are generated by the compositor. See
+ wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for
+ details.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="button" type="uint" summary="The button whose state has changed"/>
+ <arg name="state" type="uint" enum="button_state" summary="Whether the button was pressed or released"/>
+ </event>
+
+ <event name="frame">
+ <description summary="frame event">
+ Marks the end of a series of axis and/or button updates from the
+ tablet. The Wayland protocol requires axis updates to be sent
+ sequentially, however all events within a frame should be considered
+ one hardware event.
+ </description>
+ <arg name="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ </event>
+
+ <enum name="error">
+ <entry name="role" value="0" summary="given wl_surface has another role"/>
+ </enum>
+ </interface>
+
+ <interface name="zwp_tablet_v1" version="1">
+ <description summary="graphics tablet device">
+ The wp_tablet interface represents one graphics tablet device. The
+ tablet interface itself does not generate events; all events are
+ generated by wp_tablet_tool objects when in proximity above a tablet.
+
+ A tablet has a number of static characteristics, e.g. device name and
+ pid/vid. These capabilities are sent in an event sequence after the
+ wp_tablet_seat.tablet_added event. This initial event sequence is
+ terminated by a wp_tablet.done event.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the tablet object">
+ This destroys the client's resource for this tablet object.
+ </description>
+ </request>
+
+ <event name="name">
+ <description summary="tablet device name">
+ This event is sent in the initial burst of events before the
+ wp_tablet.done event.
+ </description>
+ <arg name="name" type="string" summary="the device name"/>
+ </event>
+
+ <event name="id">
+ <description summary="tablet device USB vendor/product id">
+ This event is sent in the initial burst of events before the
+ wp_tablet.done event.
+ </description>
+ <arg name="vid" type="uint" summary="USB vendor id"/>
+ <arg name="pid" type="uint" summary="USB product id"/>
+ </event>
+
+ <event name="path">
+ <description summary="path to the device">
+ A system-specific device path that indicates which device is behind
+ this wp_tablet. This information may be used to gather additional
+ information about the device, e.g. through libwacom.
+
+ A device may have more than one device path. If so, multiple
+ wp_tablet.path events are sent. A device may be emulated and not
+ have a device path, and in that case this event will not be sent.
+
+ The format of the path is unspecified, it may be a device node, a
+ sysfs path, or some other identifier. It is up to the client to
+ identify the string provided.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet.done event.
+ </description>
+ <arg name="path" type="string" summary="path to local device"/>
+ </event>
+
+ <event name="done">
+ <description summary="tablet description events sequence complete">
+ This event is sent immediately to signal the end of the initial
+ burst of descriptive events. A client may consider the static
+ description of the tablet to be complete and finalize initialization
+ of the tablet.
+ </description>
+ </event>
+
+ <event name="removed">
+ <description summary="tablet removed event">
+ Sent when the tablet has been removed from the system. When a tablet
+ is removed, some tools may be removed.
+
+ When this event is received, the client must wp_tablet.destroy
+ the object.
+ </description>
+ </event>
+ </interface>
+
+</protocol>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="tablet_unstable_v2">
+
+ <copyright>
+ Copyright 2014 © Stephen "Lyude" Chandler Paul
+ Copyright 2015-2016 © Red Hat, Inc.
+
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation files
+ (the "Software"), to deal in the Software without restriction,
+ including without limitation the rights to use, copy, modify, merge,
+ publish, distribute, sublicense, and/or sell copies of the Software,
+ and to permit persons to whom the Software is furnished to do so,
+ subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the
+ next paragraph) shall be included in all copies or substantial
+ portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
+ </copyright>
+
+ <description summary="Wayland protocol for graphics tablets">
+ This description provides a high-level overview of the interplay between
+ the interfaces defined this protocol. For details, see the protocol
+ specification.
+
+ More than one tablet may exist, and device-specifics matter. Tablets are
+ not represented by a single virtual device like wl_pointer. A client
+ binds to the tablet manager object which is just a proxy object. From
+ that, the client requests wp_tablet_manager.get_tablet_seat(wl_seat)
+ and that returns the actual interface that has all the tablets. With
+ this indirection, we can avoid merging wp_tablet into the actual Wayland
+ protocol, a long-term benefit.
+
+ The wp_tablet_seat sends a "tablet added" event for each tablet
+ connected. That event is followed by descriptive events about the
+ hardware; currently that includes events for name, vid/pid and
+ a wp_tablet.path event that describes a local path. This path can be
+ used to uniquely identify a tablet or get more information through
+ libwacom. Emulated or nested tablets can skip any of those, e.g. a
+ virtual tablet may not have a vid/pid. The sequence of descriptive
+ events is terminated by a wp_tablet.done event to signal that a client
+ may now finalize any initialization for that tablet.
+
+ Events from tablets require a tool in proximity. Tools are also managed
+ by the tablet seat; a "tool added" event is sent whenever a tool is new
+ to the compositor. That event is followed by a number of descriptive
+ events about the hardware; currently that includes capabilities,
+ hardware id and serial number, and tool type. Similar to the tablet
+ interface, a wp_tablet_tool.done event is sent to terminate that initial
+ sequence.
+
+ Any event from a tool happens on the wp_tablet_tool interface. When the
+ tool gets into proximity of the tablet, a proximity_in event is sent on
+ the wp_tablet_tool interface, listing the tablet and the surface. That
+ event is followed by a motion event with the coordinates. After that,
+ it's the usual motion, axis, button, etc. events. The protocol's
+ serialisation means events are grouped by wp_tablet_tool.frame events.
+
+ Two special events (that don't exist in X) are down and up. They signal
+ "tip touching the surface". For tablets without real proximity
+ detection, the sequence is: proximity_in, motion, down, frame.
+
+ When the tool leaves proximity, a proximity_out event is sent. If any
+ button is still down, a button release event is sent before this
+ proximity event. These button events are sent in the same frame as the
+ proximity event to signal to the client that the buttons were held when
+ the tool left proximity.
+
+ If the tool moves out of the surface but stays in proximity (i.e.
+ between windows), compositor-specific grab policies apply. This usually
+ means that the proximity-out is delayed until all buttons are released.
+
+ Moving a tool physically from one tablet to the other has no real effect
+ on the protocol, since we already have the tool object from the "tool
+ added" event. All the information is already there and the proximity
+ events on both tablets are all a client needs to reconstruct what
+ happened.
+
+ Some extra axes are normalized, i.e. the client knows the range as
+ specified in the protocol (e.g. [0, 65535]), the granularity however is
+ unknown. The current normalized axes are pressure, distance, and slider.
+
+ Other extra axes are in physical units as specified in the protocol.
+ The current extra axes with physical units are tilt, rotation and
+ wheel rotation.
+
+ Since tablets work independently of the pointer controlled by the mouse,
+ the focus handling is independent too and controlled by proximity.
+ The wp_tablet_tool.set_cursor request sets a tool-specific cursor.
+ This cursor surface may be the same as the mouse cursor, and it may be
+ the same across tools but it is possible to be more fine-grained. For
+ example, a client may set different cursors for the pen and eraser.
+
+ Tools are generally independent of tablets and it is
+ compositor-specific policy when a tool can be removed. Common approaches
+ will likely include some form of removing a tool when all tablets the
+ tool was used on are removed.
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible changes
+ may be added together with the corresponding interface version bump.
+ Backward incompatible changes are done by bumping the version number in
+ the protocol and interface names and resetting the interface version.
+ Once the protocol is to be declared stable, the 'z' prefix and the
+ version number in the protocol and interface names are removed and the
+ interface version number is reset.
+ </description>
+
+ <interface name="zwp_tablet_manager_v2" version="1">
+ <description summary="controller object for graphic tablet devices">
+ An object that provides access to the graphics tablets available on this
+ system. All tablets are associated with a seat, to get access to the
+ actual tablets, use wp_tablet_manager.get_tablet_seat.
+ </description>
+
+ <request name="get_tablet_seat">
+ <description summary="get the tablet seat">
+ Get the wp_tablet_seat object for the given seat. This object
+ provides access to all graphics tablets in this seat.
+ </description>
+ <arg name="tablet_seat" type="new_id" interface="zwp_tablet_seat_v2"/>
+ <arg name="seat" type="object" interface="wl_seat" summary="The wl_seat object to retrieve the tablets for" />
+ </request>
+
+ <request name="destroy" type="destructor">
+ <description summary="release the memory for the tablet manager object">
+ Destroy the wp_tablet_manager object. Objects created from this
+ object are unaffected and should be destroyed separately.
+ </description>
+ </request>
+ </interface>
+
+ <interface name="zwp_tablet_seat_v2" version="1">
+ <description summary="controller object for graphic tablet devices of a seat">
+ An object that provides access to the graphics tablets available on this
+ seat. After binding to this interface, the compositor sends a set of
+ wp_tablet_seat.tablet_added and wp_tablet_seat.tool_added events.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="release the memory for the tablet seat object">
+ Destroy the wp_tablet_seat object. Objects created from this
+ object are unaffected and should be destroyed separately.
+ </description>
+ </request>
+
+ <event name="tablet_added">
+ <description summary="new device notification">
+ This event is sent whenever a new tablet becomes available on this
+ seat. This event only provides the object id of the tablet, any
+ static information about the tablet (device name, vid/pid, etc.) is
+ sent through the wp_tablet interface.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_tablet_v2" summary="the newly added graphics tablet"/>
+ </event>
+
+ <event name="tool_added">
+ <description summary="a new tool has been used with a tablet">
+ This event is sent whenever a tool that has not previously been used
+ with a tablet comes into use. This event only provides the object id
+ of the tool; any static information about the tool (capabilities,
+ type, etc.) is sent through the wp_tablet_tool interface.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_tablet_tool_v2" summary="the newly added tablet tool"/>
+ </event>
+
+ <event name="pad_added">
+ <description summary="new pad notification">
+ This event is sent whenever a new pad is known to the system. Typically,
+ pads are physically attached to tablets and a pad_added event is
+ sent immediately after the wp_tablet_seat.tablet_added.
+ However, some standalone pad devices logically attach to tablets at
+ runtime, and the client must wait for wp_tablet_pad.enter to know
+ the tablet a pad is attached to.
+
+ This event only provides the object id of the pad. All further
+ features (buttons, strips, rings) are sent through the wp_tablet_pad
+ interface.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_tablet_pad_v2" summary="the newly added pad"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_tablet_tool_v2" version="1">
+ <description summary="a physical tablet tool">
+ An object that represents a physical tool that has been, or is
+ currently in use with a tablet in this seat. Each wp_tablet_tool
+ object stays valid until the client destroys it; the compositor
+ reuses the wp_tablet_tool object to indicate that the object's
+ respective physical tool has come into proximity of a tablet again.
+
+ A wp_tablet_tool object's relation to a physical tool depends on the
+ tablet's ability to report serial numbers. If the tablet supports
+ this capability, then the object represents a specific physical tool
+ and can be identified even when used on multiple tablets.
+
+ A tablet tool has a number of static characteristics, e.g. tool type,
+ hardware_serial and capabilities. These capabilities are sent in an
+ event sequence after the wp_tablet_seat.tool_added event before any
+ actual events from this tool. This initial event sequence is
+ terminated by a wp_tablet_tool.done event.
+
+ Tablet tool events are grouped by wp_tablet_tool.frame events.
+ Any events received before a wp_tablet_tool.frame event should be
+ considered part of the same hardware state change.
+ </description>
+
+ <request name="set_cursor">
+ <description summary="set the tablet tool's surface">
+ Sets the surface of the cursor used for this tool on the given
+ tablet. This request only takes effect if the tool is in proximity
+ of one of the requesting client's surfaces or the surface parameter
+ is the current pointer surface. If there was a previous surface set
+ with this request it is replaced. If surface is NULL, the cursor
+ image is hidden.
+
+ The parameters hotspot_x and hotspot_y define the position of the
+ pointer surface relative to the pointer location. Its top-left corner
+ is always at (x, y) - (hotspot_x, hotspot_y), where (x, y) are the
+ coordinates of the pointer location, in surface-local coordinates.
+
+ On surface.attach requests to the pointer surface, hotspot_x and
+ hotspot_y are decremented by the x and y parameters passed to the
+ request. Attach must be confirmed by wl_surface.commit as usual.
+
+ The hotspot can also be updated by passing the currently set pointer
+ surface to this request with new values for hotspot_x and hotspot_y.
+
+ The current and pending input regions of the wl_surface are cleared,
+ and wl_surface.set_input_region is ignored until the wl_surface is no
+ longer used as the cursor. When the use as a cursor ends, the current
+ and pending input regions become undefined, and the wl_surface is
+ unmapped.
+
+ This request gives the surface the role of a wp_tablet_tool cursor. A
+ surface may only ever be used as the cursor surface for one
+ wp_tablet_tool. If the surface already has another role or has
+ previously been used as cursor surface for a different tool, a
+ protocol error is raised.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the enter event"/>
+ <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
+ <arg name="hotspot_x" type="int" summary="surface-local x coordinate"/>
+ <arg name="hotspot_y" type="int" summary="surface-local y coordinate"/>
+ </request>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the tool object">
+ This destroys the client's resource for this tool object.
+ </description>
+ </request>
+
+ <enum name="type">
+ <description summary="a physical tool type">
+ Describes the physical type of a tool. The physical type of a tool
+ generally defines its base usage.
+
+ The mouse tool represents a mouse-shaped tool that is not a relative
+ device but bound to the tablet's surface, providing absolute
+ coordinates.
+
+ The lens tool is a mouse-shaped tool with an attached lens to
+ provide precision focus.
+ </description>
+ <entry name="pen" value="0x140" summary="Pen"/>
+ <entry name="eraser" value="0x141" summary="Eraser"/>
+ <entry name="brush" value="0x142" summary="Brush"/>
+ <entry name="pencil" value="0x143" summary="Pencil"/>
+ <entry name="airbrush" value="0x144" summary="Airbrush"/>
+ <entry name="finger" value="0x145" summary="Finger"/>
+ <entry name="mouse" value="0x146" summary="Mouse"/>
+ <entry name="lens" value="0x147" summary="Lens"/>
+ </enum>
+
+ <event name="type">
+ <description summary="tool type">
+ The tool type is the high-level type of the tool and usually decides
+ the interaction expected from this tool.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_tool.done event.
+ </description>
+ <arg name="tool_type" type="uint" enum="type" summary="the physical tool type"/>
+ </event>
+
+ <event name="hardware_serial">
+ <description summary="unique hardware serial number of the tool">
+ If the physical tool can be identified by a unique 64-bit serial
+ number, this event notifies the client of this serial number.
+
+ If multiple tablets are available in the same seat and the tool is
+ uniquely identifiable by the serial number, that tool may move
+ between tablets.
+
+ Otherwise, if the tool has no serial number and this event is
+ missing, the tool is tied to the tablet it first comes into
+ proximity with. Even if the physical tool is used on multiple
+ tablets, separate wp_tablet_tool objects will be created, one per
+ tablet.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_tool.done event.
+ </description>
+ <arg name="hardware_serial_hi" type="uint" summary="the unique serial number of the tool, most significant bits"/>
+ <arg name="hardware_serial_lo" type="uint" summary="the unique serial number of the tool, least significant bits"/>
+ </event>
+
+ <event name="hardware_id_wacom">
+ <description summary="hardware id notification in Wacom's format">
+ This event notifies the client of a hardware id available on this tool.
+
+ The hardware id is a device-specific 64-bit id that provides extra
+ information about the tool in use, beyond the wl_tool.type
+ enumeration. The format of the id is specific to tablets made by
+ Wacom Inc. For example, the hardware id of a Wacom Grip
+ Pen (a stylus) is 0x802.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_tool.done event.
+ </description>
+ <arg name="hardware_id_hi" type="uint" summary="the hardware id, most significant bits"/>
+ <arg name="hardware_id_lo" type="uint" summary="the hardware id, least significant bits"/>
+ </event>
+
+ <enum name="capability">
+ <description summary="capability flags for a tool">
+ Describes extra capabilities on a tablet.
+
+ Any tool must provide x and y values, extra axes are
+ device-specific.
+ </description>
+ <entry name="tilt" value="1" summary="Tilt axes"/>
+ <entry name="pressure" value="2" summary="Pressure axis"/>
+ <entry name="distance" value="3" summary="Distance axis"/>
+ <entry name="rotation" value="4" summary="Z-rotation axis"/>
+ <entry name="slider" value="5" summary="Slider axis"/>
+ <entry name="wheel" value="6" summary="Wheel axis"/>
+ </enum>
+
+ <event name="capability">
+ <description summary="tool capability notification">
+ This event notifies the client of any capabilities of this tool,
+ beyond the main set of x/y axes and tip up/down detection.
+
+ One event is sent for each extra capability available on this tool.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_tool.done event.
+ </description>
+ <arg name="capability" type="uint" enum="capability" summary="the capability"/>
+ </event>
+
+ <event name="done">
+ <description summary="tool description events sequence complete">
+ This event signals the end of the initial burst of descriptive
+ events. A client may consider the static description of the tool to
+ be complete and finalize initialization of the tool.
+ </description>
+ </event>
+
+ <event name="removed">
+ <description summary="tool removed">
+ This event is sent when the tool is removed from the system and will
+ send no further events. Should the physical tool come back into
+ proximity later, a new wp_tablet_tool object will be created.
+
+ It is compositor-dependent when a tool is removed. A compositor may
+ remove a tool on proximity out, tablet removal or any other reason.
+ A compositor may also keep a tool alive until shutdown.
+
+ If the tool is currently in proximity, a proximity_out event will be
+ sent before the removed event. See wp_tablet_tool.proximity_out for
+ the handling of any buttons logically down.
+
+ When this event is received, the client must wp_tablet_tool.destroy
+ the object.
+ </description>
+ </event>
+
+ <event name="proximity_in">
+ <description summary="proximity in event">
+ Notification that this tool is focused on a certain surface.
+
+ This event can be received when the tool has moved from one surface to
+ another, or when the tool has come back into proximity above the
+ surface.
+
+ If any button is logically down when the tool comes into proximity,
+ the respective button event is sent after the proximity_in event but
+ within the same frame as the proximity_in event.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="tablet" type="object" interface="zwp_tablet_v2" summary="The tablet the tool is in proximity of"/>
+ <arg name="surface" type="object" interface="wl_surface" summary="The current surface the tablet tool is over"/>
+ </event>
+
+ <event name="proximity_out">
+ <description summary="proximity out event">
+ Notification that this tool has either left proximity, or is no
+ longer focused on a certain surface.
+
+ When the tablet tool leaves proximity of the tablet, button release
+ events are sent for each button that was held down at the time of
+ leaving proximity. These events are sent before the proximity_out
+ event but within the same wp_tablet.frame.
+
+ If the tool stays within proximity of the tablet, but the focus
+ changes from one surface to another, a button release event may not
+ be sent until the button is actually released or the tool leaves the
+ proximity of the tablet.
+ </description>
+ </event>
+
+ <event name="down">
+ <description summary="tablet tool is making contact">
+ Sent whenever the tablet tool comes in contact with the surface of the
+ tablet.
+
+ If the tool is already in contact with the tablet when entering the
+ input region, the client owning said region will receive a
+ wp_tablet.proximity_in event, followed by a wp_tablet.down
+ event and a wp_tablet.frame event.
+
+ Note that this event describes logical contact, not physical
+ contact. On some devices, a compositor may not consider a tool in
+ logical contact until a minimum physical pressure threshold is
+ exceeded.
+ </description>
+ <arg name="serial" type="uint"/>
+ </event>
+
+ <event name="up">
+ <description summary="tablet tool is no longer making contact">
+ Sent whenever the tablet tool stops making contact with the surface of
+ the tablet, or when the tablet tool moves out of the input region
+ and the compositor grab (if any) is dismissed.
+
+ If the tablet tool moves out of the input region while in contact
+ with the surface of the tablet and the compositor does not have an
+ ongoing grab on the surface, the client owning said region will
+ receive a wp_tablet.up event, followed by a wp_tablet.proximity_out
+ event and a wp_tablet.frame event. If the compositor has an ongoing
+ grab on this device, this event sequence is sent whenever the grab
+ is dismissed in the future.
+
+ Note that this event describes logical contact, not physical
+ contact. On some devices, a compositor may not consider a tool out
+ of logical contact until physical pressure falls below a specific
+ threshold.
+ </description>
+ </event>
+
+ <event name="motion">
+ <description summary="motion event">
+ Sent whenever a tablet tool moves.
+ </description>
+ <arg name="x" type="fixed" summary="surface-local x coordinate"/>
+ <arg name="y" type="fixed" summary="surface-local y coordinate"/>
+ </event>
+
+ <event name="pressure">
+ <description summary="pressure change event">
+ Sent whenever the pressure axis on a tool changes. The value of this
+ event is normalized to a value between 0 and 65535.
+
+ Note that pressure may be nonzero even when a tool is not in logical
+ contact. See the down and up events for more details.
+ </description>
+ <arg name="pressure" type="uint" summary="The current pressure value"/>
+ </event>
+
+ <event name="distance">
+ <description summary="distance change event">
+ Sent whenever the distance axis on a tool changes. The value of this
+ event is normalized to a value between 0 and 65535.
+
+ Note that distance may be nonzero even when a tool is not in logical
+ contact. See the down and up events for more details.
+ </description>
+ <arg name="distance" type="uint" summary="The current distance value"/>
+ </event>
+
+ <event name="tilt">
+ <description summary="tilt change event">
+ Sent whenever one or both of the tilt axes on a tool change. Each tilt
+ value is in degrees, relative to the z-axis of the tablet.
+ The angle is positive when the top of a tool tilts along the
+ positive x or y axis.
+ </description>
+ <arg name="tilt_x" type="fixed" summary="The current value of the X tilt axis"/>
+ <arg name="tilt_y" type="fixed" summary="The current value of the Y tilt axis"/>
+ </event>
+
+ <event name="rotation">
+ <description summary="z-rotation change event">
+ Sent whenever the z-rotation axis on the tool changes. The
+ rotation value is in degrees clockwise from the tool's
+ logical neutral position.
+ </description>
+ <arg name="degrees" type="fixed" summary="The current rotation of the Z axis"/>
+ </event>
+
+ <event name="slider">
+ <description summary="Slider position change event">
+ Sent whenever the slider position on the tool changes. The
+ value is normalized between -65535 and 65535, with 0 as the logical
+ neutral position of the slider.
+
+ The slider is available on e.g. the Wacom Airbrush tool.
+ </description>
+ <arg name="position" type="int" summary="The current position of slider"/>
+ </event>
+
+ <event name="wheel">
+ <description summary="Wheel delta event">
+ Sent whenever the wheel on the tool emits an event. This event
+ contains two values for the same axis change. The degrees value is
+ in the same orientation as the wl_pointer.vertical_scroll axis. The
+ clicks value is in discrete logical clicks of the mouse wheel. This
+ value may be zero if the movement of the wheel was less
+ than one logical click.
+
+ Clients should choose either value and avoid mixing degrees and
+ clicks. The compositor may accumulate values smaller than a logical
+ click and emulate click events when a certain threshold is met.
+ Thus, wl_tablet_tool.wheel events with non-zero clicks values may
+ have different degrees values.
+ </description>
+ <arg name="degrees" type="fixed" summary="The wheel delta in degrees"/>
+ <arg name="clicks" type="int" summary="The wheel delta in discrete clicks"/>
+ </event>
+
+ <enum name="button_state">
+ <description summary="physical button state">
+ Describes the physical state of a button that produced the button event.
+ </description>
+ <entry name="released" value="0" summary="button is not pressed"/>
+ <entry name="pressed" value="1" summary="button is pressed"/>
+ </enum>
+
+ <event name="button">
+ <description summary="button event">
+ Sent whenever a button on the tool is pressed or released.
+
+ If a button is held down when the tool moves in or out of proximity,
+ button events are generated by the compositor. See
+ wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for
+ details.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="button" type="uint" summary="The button whose state has changed"/>
+ <arg name="state" type="uint" enum="button_state" summary="Whether the button was pressed or released"/>
+ </event>
+
+ <event name="frame">
+ <description summary="frame event">
+ Marks the end of a series of axis and/or button updates from the
+ tablet. The Wayland protocol requires axis updates to be sent
+ sequentially, however all events within a frame should be considered
+ one hardware event.
+ </description>
+ <arg name="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ </event>
+
+ <enum name="error">
+ <entry name="role" value="0" summary="given wl_surface has another role"/>
+ </enum>
+ </interface>
+
+ <interface name="zwp_tablet_v2" version="1">
+ <description summary="graphics tablet device">
+ The wp_tablet interface represents one graphics tablet device. The
+ tablet interface itself does not generate events; all events are
+ generated by wp_tablet_tool objects when in proximity above a tablet.
+
+ A tablet has a number of static characteristics, e.g. device name and
+ pid/vid. These capabilities are sent in an event sequence after the
+ wp_tablet_seat.tablet_added event. This initial event sequence is
+ terminated by a wp_tablet.done event.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the tablet object">
+ This destroys the client's resource for this tablet object.
+ </description>
+ </request>
+
+ <event name="name">
+ <description summary="tablet device name">
+ This event is sent in the initial burst of events before the
+ wp_tablet.done event.
+ </description>
+ <arg name="name" type="string" summary="the device name"/>
+ </event>
+
+ <event name="id">
+ <description summary="tablet device USB vendor/product id">
+ This event is sent in the initial burst of events before the
+ wp_tablet.done event.
+ </description>
+ <arg name="vid" type="uint" summary="USB vendor id"/>
+ <arg name="pid" type="uint" summary="USB product id"/>
+ </event>
+
+ <event name="path">
+ <description summary="path to the device">
+ A system-specific device path that indicates which device is behind
+ this wp_tablet. This information may be used to gather additional
+ information about the device, e.g. through libwacom.
+
+ A device may have more than one device path. If so, multiple
+ wp_tablet.path events are sent. A device may be emulated and not
+ have a device path, and in that case this event will not be sent.
+
+ The format of the path is unspecified, it may be a device node, a
+ sysfs path, or some other identifier. It is up to the client to
+ identify the string provided.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet.done event.
+ </description>
+ <arg name="path" type="string" summary="path to local device"/>
+ </event>
+
+ <event name="done">
+ <description summary="tablet description events sequence complete">
+ This event is sent immediately to signal the end of the initial
+ burst of descriptive events. A client may consider the static
+ description of the tablet to be complete and finalize initialization
+ of the tablet.
+ </description>
+ </event>
+
+ <event name="removed">
+ <description summary="tablet removed event">
+ Sent when the tablet has been removed from the system. When a tablet
+ is removed, some tools may be removed.
+
+ When this event is received, the client must wp_tablet.destroy
+ the object.
+ </description>
+ </event>
+ </interface>
+
+ <interface name="zwp_tablet_pad_ring_v2" version="1">
+ <description summary="pad ring">
+ A circular interaction area, such as the touch ring on the Wacom Intuos
+ Pro series tablets.
+
+ Events on a ring are logically grouped by the wl_tablet_pad_ring.frame
+ event.
+ </description>
+
+ <request name="set_feedback">
+ <description summary="set compositor feedback">
+ Request that the compositor use the provided feedback string
+ associated with this ring. This request should be issued immediately
+ after a wp_tablet_pad_group.mode_switch event from the corresponding
+ group is received, or whenever the ring is mapped to a different
+ action. See wp_tablet_pad_group.mode_switch for more details.
+
+ Clients are encouraged to provide context-aware descriptions for
+ the actions associated with the ring; compositors may use this
+ information to offer visual feedback about the button layout
+ (eg. on-screen displays).
+
+ The provided string 'description' is a UTF-8 encoded string to be
+ associated with this ring, and is considered user-visible; general
+ internationalization rules apply.
+
+ The serial argument will be that of the last
+ wp_tablet_pad_group.mode_switch event received for the group of this
+ ring. Requests providing other serials than the most recent one will be
+ ignored.
+ </description>
+ <arg name="description" type="string" summary="ring description"/>
+ <arg name="serial" type="uint" summary="serial of the mode switch event"/>
+ </request>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the ring object">
+ This destroys the client's resource for this ring object.
+ </description>
+ </request>
+
+ <enum name="source">
+ <description summary="ring axis source">
+ Describes the source types for ring events. This indicates to the
+ client how a ring event was physically generated; a client may
+ adjust the user interface accordingly. For example, events
+ from a "finger" source may trigger kinetic scrolling.
+ </description>
+ <entry name="finger" value="1" summary="finger"/>
+ </enum>
+
+ <event name="source">
+ <description summary="ring event source">
+ Source information for ring events.
+
+ This event does not occur on its own. It is sent before a
+ wp_tablet_pad_ring.frame event and carries the source information
+ for all events within that frame.
+
+ The source specifies how this event was generated. If the source is
+ wp_tablet_pad_ring.source.finger, a wp_tablet_pad_ring.stop event
+ will be sent when the user lifts the finger off the device.
+
+ This event is optional. If the source is unknown for an interaction,
+ no event is sent.
+ </description>
+ <arg name="source" type="uint" enum="source" summary="the event source"/>
+ </event>
+
+ <event name="angle">
+ <description summary="angle changed">
+ Sent whenever the angle on a ring changes.
+
+ The angle is provided in degrees clockwise from the logical
+ north of the ring in the pad's current rotation.
+ </description>
+ <arg name="degrees" type="fixed" summary="the current angle in degrees"/>
+ </event>
+
+ <event name="stop">
+ <description summary="interaction stopped">
+ Stop notification for ring events.
+
+ For some wp_tablet_pad_ring.source types, a wp_tablet_pad_ring.stop
+ event is sent to notify a client that the interaction with the ring
+ has terminated. This enables the client to implement kinetic scrolling.
+ See the wp_tablet_pad_ring.source documentation for information on
+ when this event may be generated.
+
+ Any wp_tablet_pad_ring.angle events with the same source after this
+ event should be considered as the start of a new interaction.
+ </description>
+ </event>
+
+ <event name="frame">
+ <description summary="end of a ring event sequence">
+ Indicates the end of a set of ring events that logically belong
+ together. A client is expected to accumulate the data in all events
+ within the frame before proceeding.
+
+ All wp_tablet_pad_ring events before a wp_tablet_pad_ring.frame event belong
+ logically together. For example, on termination of a finger interaction
+ on a ring the compositor will send a wp_tablet_pad_ring.source event,
+ a wp_tablet_pad_ring.stop event and a wp_tablet_pad_ring.frame event.
+
+ A wp_tablet_pad_ring.frame event is sent for every logical event
+ group, even if the group only contains a single wp_tablet_pad_ring
+ event. Specifically, a client may get a sequence: angle, frame,
+ angle, frame, etc.
+ </description>
+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_tablet_pad_strip_v2" version="1">
+ <description summary="pad strip">
+ A linear interaction area, such as the strips found in Wacom Cintiq
+ models.
+
+ Events on a strip are logically grouped by the wl_tablet_pad_strip.frame
+ event.
+ </description>
+
+ <request name="set_feedback">
+ <description summary="set compositor feedback">
+ Requests the compositor to use the provided feedback string
+ associated with this strip. This request should be issued immediately
+ after a wp_tablet_pad_group.mode_switch event from the corresponding
+ group is received, or whenever the strip is mapped to a different
+ action. See wp_tablet_pad_group.mode_switch for more details.
+
+ Clients are encouraged to provide context-aware descriptions for
+ the actions associated with the strip, and compositors may use this
+ information to offer visual feedback about the button layout
+ (eg. on-screen displays).
+
+ The provided string 'description' is a UTF-8 encoded string to be
+ associated with this ring, and is considered user-visible; general
+ internationalization rules apply.
+
+ The serial argument will be that of the last
+ wp_tablet_pad_group.mode_switch event received for the group of this
+ strip. Requests providing other serials than the most recent one will be
+ ignored.
+ </description>
+ <arg name="description" type="string" summary="strip description"/>
+ <arg name="serial" type="uint" summary="serial of the mode switch event"/>
+ </request>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the strip object">
+ This destroys the client's resource for this strip object.
+ </description>
+ </request>
+
+ <enum name="source">
+ <description summary="strip axis source">
+ Describes the source types for strip events. This indicates to the
+ client how a strip event was physically generated; a client may
+ adjust the user interface accordingly. For example, events
+ from a "finger" source may trigger kinetic scrolling.
+ </description>
+ <entry name="finger" value="1" summary="finger"/>
+ </enum>
+
+ <event name="source">
+ <description summary="strip event source">
+ Source information for strip events.
+
+ This event does not occur on its own. It is sent before a
+ wp_tablet_pad_strip.frame event and carries the source information
+ for all events within that frame.
+
+ The source specifies how this event was generated. If the source is
+ wp_tablet_pad_strip.source.finger, a wp_tablet_pad_strip.stop event
+ will be sent when the user lifts their finger off the device.
+
+ This event is optional. If the source is unknown for an interaction,
+ no event is sent.
+ </description>
+ <arg name="source" type="uint" enum="source" summary="the event source"/>
+ </event>
+
+ <event name="position">
+ <description summary="position changed">
+ Sent whenever the position on a strip changes.
+
+ The position is normalized to a range of [0, 65535], the 0-value
+ represents the top-most and/or left-most position of the strip in
+ the pad's current rotation.
+ </description>
+ <arg name="position" type="uint" summary="the current position"/>
+ </event>
+
+ <event name="stop">
+ <description summary="interaction stopped">
+ Stop notification for strip events.
+
+ For some wp_tablet_pad_strip.source types, a wp_tablet_pad_strip.stop
+ event is sent to notify a client that the interaction with the strip
+ has terminated. This enables the client to implement kinetic
+ scrolling. See the wp_tablet_pad_strip.source documentation for
+ information on when this event may be generated.
+
+ Any wp_tablet_pad_strip.position events with the same source after this
+ event should be considered as the start of a new interaction.
+ </description>
+ </event>
+
+ <event name="frame">
+ <description summary="end of a strip event sequence">
+ Indicates the end of a set of events that represent one logical
+ hardware strip event. A client is expected to accumulate the data
+ in all events within the frame before proceeding.
+
+ All wp_tablet_pad_strip events before a wp_tablet_pad_strip.frame event belong
+ logically together. For example, on termination of a finger interaction
+ on a strip the compositor will send a wp_tablet_pad_strip.source event,
+ a wp_tablet_pad_strip.stop event and a wp_tablet_pad_strip.frame
+ event.
+
+ A wp_tablet_pad_strip.frame event is sent for every logical event
+ group, even if the group only contains a single wp_tablet_pad_strip
+ event. Specifically, a client may get a sequence: position, frame,
+ position, frame, etc.
+ </description>
+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_tablet_pad_group_v2" version="1">
+ <description summary="a set of buttons, rings and strips">
+ A pad group describes a distinct (sub)set of buttons, rings and strips
+ present in the tablet. The criteria of this grouping is usually positional,
+ eg. if a tablet has buttons on the left and right side, 2 groups will be
+ presented. The physical arrangement of groups is undisclosed and may
+ change on the fly.
+
+ Pad groups will announce their features during pad initialization. Between
+ the corresponding wp_tablet_pad.group event and wp_tablet_pad_group.done, the
+ pad group will announce the buttons, rings and strips contained in it,
+ plus the number of supported modes.
+
+ Modes are a mechanism to allow multiple groups of actions for every element
+ in the pad group. The number of groups and available modes in each is
+ persistent across device plugs. The current mode is user-switchable, it
+ will be announced through the wp_tablet_pad_group.mode_switch event both
+ whenever it is switched, and after wp_tablet_pad.enter.
+
+ The current mode logically applies to all elements in the pad group,
+ although it is at clients' discretion whether to actually perform different
+ actions, and/or issue the respective .set_feedback requests to notify the
+ compositor. See the wp_tablet_pad_group.mode_switch event for more details.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the pad object">
+ Destroy the wp_tablet_pad_group object. Objects created from this object
+ are unaffected and should be destroyed separately.
+ </description>
+ </request>
+
+ <event name="buttons">
+ <description summary="buttons announced">
+ Sent on wp_tablet_pad_group initialization to announce the available
+ buttons in the group. Button indices start at 0, a button may only be
+ in one group at a time.
+
+ This event is first sent in the initial burst of events before the
+ wp_tablet_pad_group.done event.
+
+ Some buttons are reserved by the compositor. These buttons may not be
+ assigned to any wp_tablet_pad_group. Compositors may broadcast this
+ event in the case of changes to the mapping of these reserved buttons.
+ If the compositor happens to reserve all buttons in a group, this event
+ will be sent with an empty array.
+ </description>
+ <arg name="buttons" type="array" summary="buttons in this group"/>
+ </event>
+
+ <event name="ring">
+ <description summary="ring announced">
+ Sent on wp_tablet_pad_group initialization to announce available rings.
+ One event is sent for each ring available on this pad group.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_pad_group.done event.
+ </description>
+ <arg name="ring" type="new_id" interface="zwp_tablet_pad_ring_v2"/>
+ </event>
+
+ <event name="strip">
+ <description summary="strip announced">
+ Sent on wp_tablet_pad initialization to announce available strips.
+ One event is sent for each strip available on this pad group.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_pad_group.done event.
+ </description>
+ <arg name="strip" type="new_id" interface="zwp_tablet_pad_strip_v2"/>
+ </event>
+
+ <event name="modes">
+ <description summary="mode-switch ability announced">
+ Sent on wp_tablet_pad_group initialization to announce that the pad
+ group may switch between modes. A client may use a mode to store a
+ specific configuration for buttons, rings and strips and use the
+ wl_tablet_pad_group.mode_switch event to toggle between these
+ configurations. Mode indices start at 0.
+
+ Switching modes is compositor-dependent. See the
+ wp_tablet_pad_group.mode_switch event for more details.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_pad_group.done event. This event is only sent when more than
+ more than one mode is available.
+ </description>
+ <arg name="modes" type="uint" summary="the number of modes"/>
+ </event>
+
+ <event name="done">
+ <description summary="tablet group description events sequence complete">
+ This event is sent immediately to signal the end of the initial
+ burst of descriptive events. A client may consider the static
+ description of the tablet to be complete and finalize initialization
+ of the tablet group.
+ </description>
+ </event>
+
+ <event name="mode_switch">
+ <description summary="mode switch event">
+ Notification that the mode was switched.
+
+ A mode applies to all buttons, rings and strips in a group
+ simultaneously, but a client is not required to assign different actions
+ for each mode. For example, a client may have mode-specific button
+ mappings but map the ring to vertical scrolling in all modes. Mode
+ indices start at 0.
+
+ Switching modes is compositor-dependent. The compositor may provide
+ visual cues to the client about the mode, e.g. by toggling LEDs on
+ the tablet device. Mode-switching may be software-controlled or
+ controlled by one or more physical buttons. For example, on a Wacom
+ Intuos Pro, the button inside the ring may be assigned to switch
+ between modes.
+
+ The compositor will also send this event after wp_tablet_pad.enter on
+ each group in order to notify of the current mode. Groups that only
+ feature one mode will use mode=0 when emitting this event.
+
+ If a button action in the new mode differs from the action in the
+ previous mode, the client should immediately issue a
+ wp_tablet_pad.set_feedback request for each changed button.
+
+ If a ring or strip action in the new mode differs from the action
+ in the previous mode, the client should immediately issue a
+ wp_tablet_ring.set_feedback or wp_tablet_strip.set_feedback request
+ for each changed ring or strip.
+ </description>
+ <arg name="time" type="uint" summary="the time of the event with millisecond granularity"/>
+ <arg name="serial" type="uint"/>
+ <arg name="mode" type="uint" summary="the new mode of the pad"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_tablet_pad_v2" version="1">
+ <description summary="a set of buttons, rings and strips">
+ A pad device is a set of buttons, rings and strips
+ usually physically present on the tablet device itself. Some
+ exceptions exist where the pad device is physically detached, e.g. the
+ Wacom ExpressKey Remote.
+
+ Pad devices have no axes that control the cursor and are generally
+ auxiliary devices to the tool devices used on the tablet surface.
+
+ A pad device has a number of static characteristics, e.g. the number
+ of rings. These capabilities are sent in an event sequence after the
+ wp_tablet_seat.pad_added event before any actual events from this pad.
+ This initial event sequence is terminated by a wp_tablet_pad.done
+ event.
+
+ All pad features (buttons, rings and strips) are logically divided into
+ groups and all pads have at least one group. The available groups are
+ notified through the wp_tablet_pad.group event; the compositor will
+ emit one event per group before emitting wp_tablet_pad.done.
+
+ Groups may have multiple modes. Modes allow clients to map multiple
+ actions to a single pad feature. Only one mode can be active per group,
+ although different groups may have different active modes.
+ </description>
+
+ <request name="set_feedback">
+ <description summary="set compositor feedback">
+ Requests the compositor to use the provided feedback string
+ associated with this button. This request should be issued immediately
+ after a wp_tablet_pad_group.mode_switch event from the corresponding
+ group is received, or whenever a button is mapped to a different
+ action. See wp_tablet_pad_group.mode_switch for more details.
+
+ Clients are encouraged to provide context-aware descriptions for
+ the actions associated with each button, and compositors may use
+ this information to offer visual feedback on the button layout
+ (e.g. on-screen displays).
+
+ Button indices start at 0. Setting the feedback string on a button
+ that is reserved by the compositor (i.e. not belonging to any
+ wp_tablet_pad_group) does not generate an error but the compositor
+ is free to ignore the request.
+
+ The provided string 'description' is a UTF-8 encoded string to be
+ associated with this ring, and is considered user-visible; general
+ internationalization rules apply.
+
+ The serial argument will be that of the last
+ wp_tablet_pad_group.mode_switch event received for the group of this
+ button. Requests providing other serials than the most recent one will
+ be ignored.
+ </description>
+ <arg name="button" type="uint" summary="button index"/>
+ <arg name="description" type="string" summary="button description"/>
+ <arg name="serial" type="uint" summary="serial of the mode switch event"/>
+ </request>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the pad object">
+ Destroy the wp_tablet_pad object. Objects created from this object
+ are unaffected and should be destroyed separately.
+ </description>
+ </request>
+
+ <event name="group">
+ <description summary="group announced">
+ Sent on wp_tablet_pad initialization to announce available groups.
+ One event is sent for each pad group available.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_pad.done event. At least one group will be announced.
+ </description>
+ <arg name="pad_group" type="new_id" interface="zwp_tablet_pad_group_v2"/>
+ </event>
+
+ <event name="path">
+ <description summary="path to the device">
+ A system-specific device path that indicates which device is behind
+ this wp_tablet_pad. This information may be used to gather additional
+ information about the device, e.g. through libwacom.
+
+ The format of the path is unspecified, it may be a device node, a
+ sysfs path, or some other identifier. It is up to the client to
+ identify the string provided.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_pad.done event.
+ </description>
+ <arg name="path" type="string" summary="path to local device"/>
+ </event>
+
+ <event name="buttons">
+ <description summary="buttons announced">
+ Sent on wp_tablet_pad initialization to announce the available
+ buttons.
+
+ This event is sent in the initial burst of events before the
+ wp_tablet_pad.done event. This event is only sent when at least one
+ button is available.
+ </description>
+ <arg name="buttons" type="uint" summary="the number of buttons"/>
+ </event>
+
+ <event name="done">
+ <description summary="pad description event sequence complete">
+ This event signals the end of the initial burst of descriptive
+ events. A client may consider the static description of the pad to
+ be complete and finalize initialization of the pad.
+ </description>
+ </event>
+
+ <enum name="button_state">
+ <description summary="physical button state">
+ Describes the physical state of a button that caused the button
+ event.
+ </description>
+ <entry name="released" value="0" summary="the button is not pressed"/>
+ <entry name="pressed" value="1" summary="the button is pressed"/>
+ </enum>
+
+ <event name="button">
+ <description summary="physical button state">
+ Sent whenever the physical state of a button changes.
+ </description>
+ <arg name="time" type="uint" summary="the time of the event with millisecond granularity"/>
+ <arg name="button" type="uint" summary="the index of the button that changed state"/>
+ <arg name="state" type="uint" enum="button_state"/>
+ </event>
+
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this pad is focused on the specified surface.
+ </description>
+ <arg name="serial" type="uint" summary="serial number of the enter event"/>
+ <arg name="tablet" type="object" interface="zwp_tablet_v2" summary="the tablet the pad is attached to"/>
+ <arg name="surface" type="object" interface="wl_surface" summary="surface the pad is focused on"/>
+ </event>
+
+ <event name="leave">
+ <description summary="enter event">
+ Notification that this pad is no longer focused on the specified
+ surface.
+ </description>
+ <arg name="serial" type="uint" summary="serial number of the leave event"/>
+ <arg name="surface" type="object" interface="wl_surface" summary="surface the pad is no longer focused on"/>
+ </event>
+
+ <event name="removed">
+ <description summary="pad removed event">
+ Sent when the pad has been removed from the system. When a tablet
+ is removed its pad(s) will be removed too.
+
+ When this event is received, the client must destroy all rings, strips
+ and groups that were offered by this pad, and issue wp_tablet_pad.destroy
+ the pad itself.
+ </description>
+ </event>
+ </interface>
+</protocol>
--- /dev/null
+Text input protocol
+
+Maintainers:
+Jan Arne Petersen <janarne@gmail.com>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="text_input_unstable_v1">
+
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <interface name="zwp_text_input_v1" version="1">
+ <description summary="text input">
+ An object used for text input. Adds support for text input and input
+ methods to applications. A text_input object is created from a
+ wl_text_input_manager and corresponds typically to a text entry in an
+ application.
+
+ Requests are used to activate/deactivate the text_input object and set
+ state information like surrounding and selected text or the content type.
+ The information about entered text is sent to the text_input object via
+ the pre-edit and commit events. Using this interface removes the need
+ for applications to directly process hardware key events and compose text
+ out of them.
+
+ Text is generally UTF-8 encoded, indices and lengths are in bytes.
+
+ Serials are used to synchronize the state between the text input and
+ an input method. New serials are sent by the text input in the
+ commit_state request and are used by the input method to indicate
+ the known text input state in events like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible changes
+ may be added together with the corresponding interface version bump.
+ Backward incompatible changes are done by bumping the version number in
+ the protocol and interface names and resetting the interface version.
+ Once the protocol is to be declared stable, the 'z' prefix and the
+ version number in the protocol and interface names are removed and the
+ interface version number is reset.
+ </description>
+
+ <request name="activate">
+ <description summary="request activation">
+ Requests the text_input object to be activated (typically when the
+ text entry gets focus).
+
+ The seat argument is a wl_seat which maintains the focus for this
+ activation. The surface argument is a wl_surface assigned to the
+ text_input object and tracked for focus lost. The enter event
+ is emitted on successful activation.
+ </description>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="deactivate">
+ <description summary="request deactivation">
+ Requests the text_input object to be deactivated (typically when the
+ text entry lost focus). The seat argument is a wl_seat which was used
+ for activation.
+ </description>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+
+ <request name="show_input_panel">
+ <description summary="show input panels">
+ Requests input panels (virtual keyboard) to show.
+ </description>
+ </request>
+
+ <request name="hide_input_panel">
+ <description summary="hide input panels">
+ Requests input panels (virtual keyboard) to hide.
+ </description>
+ </request>
+
+ <request name="reset">
+ <description summary="reset">
+ Should be called by an editor widget when the input state should be
+ reset, for example after the text was changed outside of the normal
+ input method flow.
+ </description>
+ </request>
+
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ Sets the plain surrounding text around the input position. Text is
+ UTF-8 encoded. Cursor is the byte offset within the
+ surrounding text. Anchor is the byte offset of the
+ selection anchor within the surrounding text. If there is no selected
+ text anchor, then it is the same as cursor.
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="uint"/>
+ </request>
+
+ <enum name="content_hint">
+ <description summary="content hint">
+ Content hint is a bitmask to allow to modify the behavior of the text
+ input.
+ </description>
+ <entry name="none" value="0x0" summary="no special behaviour"/>
+ <entry name="default" value="0x7" summary="auto completion, correction and capitalization"/>
+ <entry name="password" value="0xc0" summary="hidden and sensitive text"/>
+ <entry name="auto_completion" value="0x1" summary="suggest word completions"/>
+ <entry name="auto_correction" value="0x2" summary="suggest word corrections"/>
+ <entry name="auto_capitalization" value="0x4" summary="switch to uppercase letters at the start of a sentence"/>
+ <entry name="lowercase" value="0x8" summary="prefer lowercase letters"/>
+ <entry name="uppercase" value="0x10" summary="prefer uppercase letters"/>
+ <entry name="titlecase" value="0x20" summary="prefer casing for titles and headings (can be language dependent)"/>
+ <entry name="hidden_text" value="0x40" summary="characters should be hidden"/>
+ <entry name="sensitive_data" value="0x80" summary="typed text should not be stored"/>
+ <entry name="latin" value="0x100" summary="just latin characters should be entered"/>
+ <entry name="multiline" value="0x200" summary="the text input is multiline"/>
+ </enum>
+
+ <enum name="content_purpose">
+ <description summary="content purpose">
+ The content purpose allows to specify the primary purpose of a text
+ input.
+
+ This allows an input method to show special purpose input panels with
+ extra characters or to disallow some characters.
+ </description>
+ <entry name="normal" value="0" summary="default input, allowing all characters"/>
+ <entry name="alpha" value="1" summary="allow only alphabetic characters"/>
+ <entry name="digits" value="2" summary="allow only digits"/>
+ <entry name="number" value="3" summary="input a number (including decimal separator and sign)"/>
+ <entry name="phone" value="4" summary="input a phone number"/>
+ <entry name="url" value="5" summary="input an URL"/>
+ <entry name="email" value="6" summary="input an email address"/>
+ <entry name="name" value="7" summary="input a name of a person"/>
+ <entry name="password" value="8" summary="input a password (combine with password or sensitive_data hint)"/>
+ <entry name="date" value="9" summary="input a date"/>
+ <entry name="time" value="10" summary="input a time"/>
+ <entry name="datetime" value="11" summary="input a date and time"/>
+ <entry name="terminal" value="12" summary="input for a terminal"/>
+ </enum>
+
+ <request name="set_content_type">
+ <description summary="set content purpose and hint">
+ Sets the content purpose and content hint. While the purpose is the
+ basic purpose of an input field, the hint flags allow to modify some
+ of the behavior.
+
+ When no content type is explicitly set, a normal content purpose with
+ default hints (auto completion, auto correction, auto capitalization)
+ should be assumed.
+ </description>
+ <arg name="hint" type="uint"/>
+ <arg name="purpose" type="uint"/>
+ </request>
+
+ <request name="set_cursor_rectangle">
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is an RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate the
+ language of the currently edited document or in an instant message
+ application which tracks languages of contacts.
+ </description>
+ <arg name="language" type="string"/>
+ </request>
+
+ <request name="commit_state">
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ </request>
+
+ <request name="invoke_action">
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
+
+ <event name="enter">
+ <description summary="enter event">
+ Notify the text_input object when it received focus. Typically in
+ response to an activate request.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="leave">
+ <description summary="leave event">
+ Notify the text_input object when it lost focus. Either in response
+ to a deactivate request or when the assigned surface lost focus or was
+ destroyed.
+ </description>
+ </event>
+
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer an array of 0-terminated modifier names. The position in
+ the array is the index of the modifier as used in the modifiers
+ bitmask in the keysym event.
+ </description>
+ <arg name="map" type="array"/>
+ </event>
+
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notify when the visibility state of the input panel changed.
+ </description>
+ <arg name="state" type="uint"/>
+ </event>
+
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify when a new composing text (pre-edit) should be set around the
+ current cursor position. Any previously set composing text should
+ be removed.
+
+ The commit text can be used to replace the preedit text on reset
+ (for example on unfocus).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="style should be the same as in non-composing text"/>
+ <entry name="active" value="2"/>
+ <entry name="inactive" value="3"/>
+ <entry name="highlight" value="4"/>
+ <entry name="underline" value="5"/>
+ <entry name="selection" value="6"/>
+ <entry name="incorrect" value="7"/>
+ </enum>
+
+ <event name="preedit_styling">
+ <description summary="pre-edit styling">
+ Sets styling information on composing text. The style is applied for
+ length bytes from index relative to the beginning of the composing
+ text (as byte offset). Multiple styles can
+ be applied to a composing text by sending multiple preedit_styling
+ events.
+
+ This event is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint"/>
+ </event>
+
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ Sets the cursor position inside the composing text (as byte
+ offset) relative to the start of the composing text. When index is a
+ negative number no cursor is shown.
+
+ This event is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+
+ <event name="commit_string">
+ <description summary="commit">
+ Notify when text should be inserted into the editor widget. The text to
+ commit could be either just a single character after a key press or the
+ result of some composing (pre-edit). It could also be an empty text
+ when some text should be removed (see delete_surrounding_text) or when
+ the input cursor should be moved (see cursor_position).
+
+ Any previously set composing text should be removed.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ Notify when the cursor or anchor position should be modified.
+
+ This event should be handled as part of a following commit_string
+ event.
+ </description>
+ <arg name="index" type="int"/>
+ <arg name="anchor" type="int"/>
+ </event>
+
+ <event name="delete_surrounding_text">
+ <description summary="delete surrounding text">
+ Notify when the text around the current cursor position should be
+ deleted.
+
+ Index is relative to the current cursor (in bytes).
+ Length is the length of deleted text (in bytes).
+
+ This event should be handled as part of a following commit_string
+ event.
+ </description>
+ <arg name="index" type="int"/>
+ <arg name="length" type="uint"/>
+ </event>
+
+ <event name="keysym">
+ <description summary="keysym">
+ Notify when a key event was sent. Key events should not be used
+ for normal text input operations, which should be done with
+ commit_string, delete_surrounding_text, etc. The key event follows
+ the wl_keyboard key event convention. Sym is an XKB keysym, state a
+ wl_keyboard key_state. Modifiers are a mask for effective modifiers
+ (where the modifier indices are set by the modifiers_map event)
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="time" type="uint"/>
+ <arg name="sym" type="uint"/>
+ <arg name="state" type="uint"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
+
+ <event name="language">
+ <description summary="language">
+ Sets the language of the input text. The "language" argument is an
+ RFC-3066 format language tag.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </event>
+
+ <enum name="text_direction">
+ <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
+ <entry name="ltr" value="1" summary="left-to-right"/>
+ <entry name="rtl" value="2" summary="right-to-left"/>
+ </enum>
+
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing an input cursor on the correct side of
+ the editor when there is no input done yet and making sure neutral
+ direction text is laid out properly.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_text_input_manager_v1" version="1">
+ <description summary="text input manager">
+ A factory for text_input objects. This object is a global singleton.
+ </description>
+
+ <request name="create_text_input">
+ <description summary="create text input">
+ Creates a new text_input object.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_text_input_v1"/>
+ </request>
+ </interface>
+
+</protocol>
--- /dev/null
+xdg foreign protocol
+
+Maintainers:
+Jonas Ådahl <jadahl@gmail.com>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_foreign_unstable_v1">
+
+ <copyright>
+ Copyright © 2015-2016 Red Hat Inc.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <description summary="Protocol for exporting xdg surface handles">
+ This protocol specifies a way for making it possible to reference a surface
+ of a different client. With such a reference, a client can, by using the
+ interfaces provided by this protocol, manipulate the relationship between
+ its own surfaces and the surface of some other client. For example, stack
+ some of its own surface above the other clients surface.
+
+ In order for a client A to get a reference of a surface of client B, client
+ B must first export its surface using xdg_exporter.export. Upon doing this,
+ client B will receive a handle (a unique string) that it may share with
+ client A in some way (for example D-Bus). After client A has received the
+ handle from client B, it may use xdg_importer.import to create a reference
+ to the surface client B just exported. See the corresponding requests for
+ details.
+
+ A possible use case for this is out-of-process dialogs. For example when a
+ sandboxed client without file system access needs the user to select a file
+ on the file system, given sandbox environment support, it can export its
+ surface, passing the exported surface handle to an unsandboxed process that
+ can show a file browser dialog and stack it above the sandboxed client's
+ surface.
+
+ Warning! The protocol described in this file is experimental and backward
+ incompatible changes may be made. Backward compatible changes may be added
+ together with the corresponding interface version bump. Backward
+ incompatible changes are done by bumping the version number in the protocol
+ and interface names and resetting the interface version. Once the protocol
+ is to be declared stable, the 'z' prefix and the version number in the
+ protocol and interface names are removed and the interface version number is
+ reset.
+ </description>
+
+ <interface name="zxdg_exporter_v1" version="1">
+ <description summary="interface for exporting surfaces">
+ A global interface used for exporting surfaces that can later be imported
+ using xdg_importer.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_exporter object">
+ Notify the compositor that the xdg_exporter object will no longer be
+ used.
+ </description>
+ </request>
+
+ <request name="export">
+ <description summary="export a surface">
+ The export request exports the passed surface so that it can later be
+ imported via xdg_importer. When called, a new xdg_exported object will
+ be created and xdg_exported.handle will be sent immediately. See the
+ corresponding interface and event for details.
+
+ A surface may be exported multiple times, and each exported handle may
+ be used to create a xdg_imported multiple times. Only xdg_surface
+ surfaces may be exported.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_exported_v1"
+ summary="the new xdg_exported object"/>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="the surface to export"/>
+ </request>
+ </interface>
+
+ <interface name="zxdg_importer_v1" version="1">
+ <description summary="interface for importing surfaces">
+ A global interface used for importing surfaces exported by xdg_exporter.
+ With this interface, a client can create a reference to a surface of
+ another client.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_importer object">
+ Notify the compositor that the xdg_importer object will no longer be
+ used.
+ </description>
+ </request>
+
+ <request name="import">
+ <description summary="import a surface">
+ The import request imports a surface from any client given a handle
+ retrieved by exporting said surface using xdg_exporter.export. When
+ called, a new xdg_imported object will be created. This new object
+ represents the imported surface, and the importing client can
+ manipulate its relationship using it. See xdg_imported for details.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_imported_v1"
+ summary="the new xdg_imported object"/>
+ <arg name="handle" type="string"
+ summary="the exported surface handle"/>
+ </request>
+ </interface>
+
+ <interface name="zxdg_exported_v1" version="1">
+ <description summary="an exported surface handle">
+ A xdg_exported object represents an exported reference to a surface. The
+ exported surface may be referenced as long as the xdg_exported object not
+ destroyed. Destroying the xdg_exported invalidates any relationship the
+ importer may have established using xdg_imported.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="unexport the exported surface">
+ Revoke the previously exported surface. This invalidates any
+ relationship the importer may have set up using the xdg_imported created
+ given the handle sent via xdg_exported.handle.
+ </description>
+ </request>
+
+ <event name="handle">
+ <description summary="the exported surface handle">
+ The handle event contains the unique handle of this exported surface
+ reference. It may be shared with any client, which then can use it to
+ import the surface by calling xdg_importer.import. A handle may be
+ used to import the surface multiple times.
+ </description>
+ <arg name="handle" type="string" summary="the exported surface handle"/>
+ </event>
+ </interface>
+
+ <interface name="zxdg_imported_v1" version="1">
+ <description summary="an imported surface handle">
+ A xdg_imported object represents an imported reference to surface exported
+ by some client. A client can use this interface to manipulate
+ relationships between its own surfaces and the imported surface.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_imported object">
+ Notify the compositor that it will no longer use the xdg_imported
+ object. Any relationship that may have been set up will at this point
+ be invalidated.
+ </description>
+ </request>
+
+ <request name="set_parent_of">
+ <description summary="set as the parent of some surface">
+ Set the imported surface as the parent of some surface of the client.
+ The passed surface must be a toplevel xdg_surface. Calling this function
+ sets up a surface to surface relation with the same stacking and positioning
+ semantics as xdg_surface.set_parent.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="the child surface"/>
+ </request>
+
+ <event name="destroyed">
+ <description summary="the imported surface handle has been destroyed">
+ The imported surface handle has been destroyed and any relationship set
+ up has been invalidated. This may happen for various reasons, for
+ example if the exported surface or the exported surface handle has been
+ destroyed, if the handle used for importing was invalid.
+ </description>
+ </event>
+ </interface>
+
+</protocol>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_foreign_unstable_v2">
+
+ <copyright>
+ Copyright © 2015-2016 Red Hat Inc.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <description summary="Protocol for exporting xdg surface handles">
+ This protocol specifies a way for making it possible to reference a surface
+ of a different client. With such a reference, a client can, by using the
+ interfaces provided by this protocol, manipulate the relationship between
+ its own surfaces and the surface of some other client. For example, stack
+ some of its own surface above the other clients surface.
+
+ In order for a client A to get a reference of a surface of client B, client
+ B must first export its surface using xdg_exporter.export_toplevel. Upon
+ doing this, client B will receive a handle (a unique string) that it may
+ share with client A in some way (for example D-Bus). After client A has
+ received the handle from client B, it may use xdg_importer.import_toplevel
+ to create a reference to the surface client B just exported. See the
+ corresponding requests for details.
+
+ A possible use case for this is out-of-process dialogs. For example when a
+ sandboxed client without file system access needs the user to select a file
+ on the file system, given sandbox environment support, it can export its
+ surface, passing the exported surface handle to an unsandboxed process that
+ can show a file browser dialog and stack it above the sandboxed client's
+ surface.
+
+ Warning! The protocol described in this file is experimental and backward
+ incompatible changes may be made. Backward compatible changes may be added
+ together with the corresponding interface version bump. Backward
+ incompatible changes are done by bumping the version number in the protocol
+ and interface names and resetting the interface version. Once the protocol
+ is to be declared stable, the 'z' prefix and the version number in the
+ protocol and interface names are removed and the interface version number is
+ reset.
+ </description>
+
+ <interface name="zxdg_exporter_v2" version="1">
+ <description summary="interface for exporting surfaces">
+ A global interface used for exporting surfaces that can later be imported
+ using xdg_importer.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_exporter object">
+ Notify the compositor that the xdg_exporter object will no longer be
+ used.
+ </description>
+ </request>
+
+ <request name="export_toplevel">
+ <description summary="export a toplevel surface">
+ The export_toplevel request exports the passed surface so that it can later be
+ imported via xdg_importer. When called, a new xdg_exported object will
+ be created and xdg_exported.handle will be sent immediately. See the
+ corresponding interface and event for details.
+
+ A surface may be exported multiple times, and each exported handle may
+ be used to create a xdg_imported multiple times. Only xdg_toplevel
+ equivalent surfaces may be exported.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_exported_v2"
+ summary="the new xdg_exported object"/>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="the surface to export"/>
+ </request>
+ </interface>
+
+ <interface name="zxdg_importer_v2" version="1">
+ <description summary="interface for importing surfaces">
+ A global interface used for importing surfaces exported by xdg_exporter.
+ With this interface, a client can create a reference to a surface of
+ another client.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_importer object">
+ Notify the compositor that the xdg_importer object will no longer be
+ used.
+ </description>
+ </request>
+
+ <request name="import_toplevel">
+ <description summary="import a toplevel surface">
+ The import_toplevel request imports a surface from any client given a handle
+ retrieved by exporting said surface using xdg_exporter.export_toplevel.
+ When called, a new xdg_imported object will be created. This new object
+ represents the imported surface, and the importing client can
+ manipulate its relationship using it. See xdg_imported for details.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_imported_v2"
+ summary="the new xdg_imported object"/>
+ <arg name="handle" type="string"
+ summary="the exported surface handle"/>
+ </request>
+ </interface>
+
+ <interface name="zxdg_exported_v2" version="1">
+ <description summary="an exported surface handle">
+ A xdg_exported object represents an exported reference to a surface. The
+ exported surface may be referenced as long as the xdg_exported object not
+ destroyed. Destroying the xdg_exported invalidates any relationship the
+ importer may have established using xdg_imported.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="unexport the exported surface">
+ Revoke the previously exported surface. This invalidates any
+ relationship the importer may have set up using the xdg_imported created
+ given the handle sent via xdg_exported.handle.
+ </description>
+ </request>
+
+ <event name="handle">
+ <description summary="the exported surface handle">
+ The handle event contains the unique handle of this exported surface
+ reference. It may be shared with any client, which then can use it to
+ import the surface by calling xdg_importer.import_toplevel. A handle
+ may be used to import the surface multiple times.
+ </description>
+ <arg name="handle" type="string" summary="the exported surface handle"/>
+ </event>
+ </interface>
+
+ <interface name="zxdg_imported_v2" version="1">
+ <description summary="an imported surface handle">
+ A xdg_imported object represents an imported reference to surface exported
+ by some client. A client can use this interface to manipulate
+ relationships between its own surfaces and the imported surface.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_imported object">
+ Notify the compositor that it will no longer use the xdg_imported
+ object. Any relationship that may have been set up will at this point
+ be invalidated.
+ </description>
+ </request>
+
+ <request name="set_parent_of">
+ <description summary="set as the parent of some surface">
+ Set the imported surface as the parent of some surface of the client.
+ The passed surface must be a xdg_toplevel equivalent. Calling this
+ function sets up a surface to surface relation with the same stacking
+ and positioning semantics as xdg_toplevel.set_parent.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="the child surface"/>
+ </request>
+
+ <event name="destroyed">
+ <description summary="the imported surface handle has been destroyed">
+ The imported surface handle has been destroyed and any relationship set
+ up has been invalidated. This may happen for various reasons, for
+ example if the exported surface or the exported surface handle has been
+ destroyed, if the handle used for importing was invalid.
+ </description>
+ </event>
+ </interface>
+
+</protocol>
--- /dev/null
+xdg_output protocol
+
+Maintainers:
+Olivier Fourdan <ofourdan@redhat.com>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_output_unstable_v1">
+
+ <copyright>
+ Copyright © 2017 Red Hat Inc.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <description summary="Protocol to describe output regions">
+ This protocol aims at describing outputs in a way which is more in line
+ with the concept of an output on desktop oriented systems.
+
+ Some information are more specific to the concept of an output for
+ a desktop oriented system and may not make sense in other applications,
+ such as IVI systems for example.
+
+ Typically, the global compositor space on a desktop system is made of
+ a contiguous or overlapping set of rectangular regions.
+
+ Some of the information provided in this protocol might be identical
+ to their counterparts already available from wl_output, in which case
+ the information provided by this protocol should be preferred to their
+ equivalent in wl_output. The goal is to move the desktop specific
+ concepts (such as output location within the global compositor space,
+ the connector name and types, etc.) out of the core wl_output protocol.
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible
+ changes may be added together with the corresponding interface
+ version bump.
+ Backward incompatible changes are done by bumping the version
+ number in the protocol and interface names and resetting the
+ interface version. Once the protocol is to be declared stable,
+ the 'z' prefix and the version number in the protocol and
+ interface names are removed and the interface version number is
+ reset.
+ </description>
+
+ <interface name="zxdg_output_manager_v1" version="1">
+ <description summary="manage xdg_output objects">
+ A global factory interface for xdg_output objects.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_output_manager object">
+ Using this request a client can tell the server that it is not
+ going to use the xdg_output_manager object anymore.
+
+ Any objects already created through this instance are not affected.
+ </description>
+ </request>
+
+ <request name="get_xdg_output">
+ <description summary="create an xdg output from a wl_output">
+ This creates a new xdg_output object for the given wl_output.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_output_v1"/>
+ <arg name="output" type="object" interface="wl_output"/>
+ </request>
+ </interface>
+
+ <interface name="zxdg_output_v1" version="1">
+ <description summary="compositor logical output region">
+ An xdg_output describes part of the compositor geometry.
+
+ This typically corresponds to a monitor that displays part of the
+ compositor space.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_output object">
+ Using this request a client can tell the server that it is not
+ going to use the xdg_output object anymore.
+ </description>
+ </request>
+
+ <event name="logical_position">
+ <description summary="position of the output within the global compositor space">
+ The position event describes the location of the wl_output within
+ the global compositor space.
+
+ The logical_position event is sent after creating an xdg_output
+ (see xdg_output_manager.get_xdg_output) and whenever the location
+ of the output changes within the global compositor space.
+ </description>
+ <arg name="x" type="int"
+ summary="x position within the global compositor space"/>
+ <arg name="y" type="int"
+ summary="y position within the global compositor space"/>
+ </event>
+
+ <event name="logical_size">
+ <description summary="size of the output in the global compositor space">
+ The logical_size event describes the size of the output in the
+ global compositor space.
+
+ For example, a surface without any buffer scale, transformation
+ nor rotation set, with the size matching the logical_size will
+ have the same size as the corresponding output when displayed.
+
+ Most regular Wayland clients should not pay attention to the
+ logical size and would rather rely on xdg_shell interfaces.
+
+ Some clients such as Xwayland, however, need this to configure
+ their surfaces in the global compositor space as the compositor
+ may apply a different scale from what is advertised by the output
+ scaling property (to achieve fractional scaling, for example).
+
+ For example, for a wl_output mode 3840×2160 and a scale factor 2:
+
+ - A compositor not scaling the surface buffers will advertise a
+ logical size of 3840×2160,
+
+ - A compositor automatically scaling the surface buffers will
+ advertise a logical size of 1920×1080,
+
+ - A compositor using a fractional scale of 1.5 will advertise a
+ logical size to 2560×1620.
+
+ The logical_size event is sent after creating an xdg_output
+ (see xdg_output_manager.get_xdg_output) and whenever the logical
+ size of the output changes, either as a result of a change in the
+ applied scale or because of a change in the corresponding output
+ mode(see wl_output.mode) or transform (see wl_output.transform).
+ </description>
+ <arg name="width" type="int"
+ summary="width in global compositor space"/>
+ <arg name="height" type="int"
+ summary="height in global compositor space"/>
+ </event>
+
+ <event name="done">
+ <description summary="all information about the output have been sent">
+ This event is sent after all other properties of an xdg_output
+ have been sent.
+
+ This allows changes to the xdg_output properties to be seen as
+ atomic, even if they happen via multiple events.
+ </description>
+ </event>
+
+ </interface>
+</protocol>
--- /dev/null
+xdg shell protocol
+
+Maintainers:
+Jasper St. Pierre <jstpierre@mecheye.net>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_shell_unstable_v5">
+
+ <copyright>
+ Copyright © 2008-2013 Kristian Høgsberg
+ Copyright © 2013 Rafael Antognolli
+ Copyright © 2013 Jasper St. Pierre
+ Copyright © 2010-2013 Intel Corporation
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <interface name="xdg_shell" version="1">
+ <description summary="create desktop-style surfaces">
+ xdg_shell allows clients to turn a wl_surface into a "real window"
+ which can be dragged, resized, stacked, and moved around by the
+ user. Everything about this interface is suited towards traditional
+ desktop environments.
+ </description>
+
+ <enum name="version">
+ <description summary="latest protocol version">
+ The 'current' member of this enum gives the version of the
+ protocol. Implementations can compare this to the version
+ they implement using static_assert to ensure the protocol and
+ implementation versions match.
+ </description>
+ <entry name="current" value="5" summary="Always the latest version"/>
+ </enum>
+
+ <enum name="error">
+ <entry name="role" value="0" summary="given wl_surface has another role"/>
+ <entry name="defunct_surfaces" value="1" summary="xdg_shell was destroyed before children"/>
+ <entry name="not_the_topmost_popup" value="2" summary="the client tried to map or destroy a non-topmost popup"/>
+ <entry name="invalid_popup_parent" value="3" summary="the client specified an invalid popup parent surface"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy xdg_shell">
+ Destroy this xdg_shell object.
+
+ Destroying a bound xdg_shell object while there are surfaces
+ still alive created by this xdg_shell object instance is illegal
+ and will result in a protocol error.
+ </description>
+ </request>
+
+ <request name="use_unstable_version">
+ <description summary="enable use of this unstable version">
+ Negotiate the unstable version of the interface. This
+ mechanism is in place to ensure client and server agree on the
+ unstable versions of the protocol that they speak or exit
+ cleanly if they don't agree. This request will go away once
+ the xdg-shell protocol is stable.
+ </description>
+ <arg name="version" type="int"/>
+ </request>
+
+ <request name="get_xdg_surface">
+ <description summary="create a shell surface from a surface">
+ This creates an xdg_surface for the given surface and gives it the
+ xdg_surface role. A wl_surface can only be given an xdg_surface role
+ once. If get_xdg_surface is called with a wl_surface that already has
+ an active xdg_surface associated with it, or if it had any other role,
+ an error is raised.
+
+ See the documentation of xdg_surface for more details about what an
+ xdg_surface is and how it is used.
+ </description>
+ <arg name="id" type="new_id" interface="xdg_surface"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="get_xdg_popup">
+ <description summary="create a popup for a surface">
+ This creates an xdg_popup for the given surface and gives it the
+ xdg_popup role. A wl_surface can only be given an xdg_popup role
+ once. If get_xdg_popup is called with a wl_surface that already has
+ an active xdg_popup associated with it, or if it had any other role,
+ an error is raised.
+
+ This request must be used in response to some sort of user action
+ like a button press, key press, or touch down event.
+
+ See the documentation of xdg_popup for more details about what an
+ xdg_popup is and how it is used.
+ </description>
+ <arg name="id" type="new_id" interface="xdg_popup"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ <arg name="parent" type="object" interface="wl_surface"/>
+ <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
+ <arg name="serial" type="uint" summary="the serial of the user event"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ </request>
+
+ <event name="ping">
+ <description summary="check if the client is alive">
+ The ping event asks the client if it's still alive. Pass the
+ serial specified in the event back to the compositor by sending
+ a "pong" request back with the specified serial.
+
+ Compositors can use this to determine if the client is still
+ alive. It's unspecified what will happen if the client doesn't
+ respond to the ping request, or in what timeframe. Clients should
+ try to respond in a reasonable amount of time.
+
+ A compositor is free to ping in any way it wants, but a client must
+ always respond to any xdg_shell object it created.
+ </description>
+ <arg name="serial" type="uint" summary="pass this to the pong request"/>
+ </event>
+
+ <request name="pong">
+ <description summary="respond to a ping event">
+ A client must respond to a ping event with a pong request or
+ the client may be deemed unresponsive.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the ping event"/>
+ </request>
+ </interface>
+
+ <interface name="xdg_surface" version="1">
+ <description summary="A desktop window">
+ An interface that may be implemented by a wl_surface, for
+ implementations that provide a desktop-style user interface.
+
+ It provides requests to treat surfaces like windows, allowing to set
+ properties like maximized, fullscreen, minimized, and to move and resize
+ them, and associate metadata like title and app id.
+
+ The client must call wl_surface.commit on the corresponding wl_surface
+ for the xdg_surface state to take effect. Prior to committing the new
+ state, it can set up initial configuration, such as maximizing or setting
+ a window geometry.
+
+ Even without attaching a buffer the compositor must respond to initial
+ committed configuration, for instance sending a configure event with
+ expected window geometry if the client maximized its surface during
+ initialization.
+
+ For a surface to be mapped by the compositor the client must have
+ committed both an xdg_surface state and a buffer.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the xdg_surface">
+ Unmap and destroy the window. The window will be effectively
+ hidden from the user's point of view, and all state like
+ maximization, fullscreen, and so on, will be lost.
+ </description>
+ </request>
+
+ <request name="set_parent">
+ <description summary="set the parent of this surface">
+ Set the "parent" of this surface. This window should be stacked
+ above a parent. The parent surface must be mapped as long as this
+ surface is mapped.
+
+ Parent windows should be set on dialogs, toolboxes, or other
+ "auxiliary" surfaces, so that the parent is raised when the dialog
+ is raised.
+ </description>
+ <arg name="parent" type="object" interface="xdg_surface" allow-null="true"/>
+ </request>
+
+ <request name="set_title">
+ <description summary="set surface title">
+ Set a short title for the surface.
+
+ This string may be used to identify the surface in a task bar,
+ window list, or other user interface elements provided by the
+ compositor.
+
+ The string must be encoded in UTF-8.
+ </description>
+ <arg name="title" type="string"/>
+ </request>
+
+ <request name="set_app_id">
+ <description summary="set application ID">
+ Set an application identifier for the surface.
+
+ The app ID identifies the general class of applications to which
+ the surface belongs. The compositor can use this to group multiple
+ surfaces together, or to determine how to launch a new application.
+
+ For D-Bus activatable applications, the app ID is used as the D-Bus
+ service name.
+
+ The compositor shell will try to group application surfaces together
+ by their app ID. As a best practice, it is suggested to select app
+ ID's that match the basename of the application's .desktop file.
+ For example, "org.freedesktop.FooViewer" where the .desktop file is
+ "org.freedesktop.FooViewer.desktop".
+
+ See the desktop-entry specification [0] for more details on
+ application identifiers and how they relate to well-known D-Bus
+ names and .desktop files.
+
+ [0] http://standards.freedesktop.org/desktop-entry-spec/
+ </description>
+ <arg name="app_id" type="string"/>
+ </request>
+
+ <request name="show_window_menu">
+ <description summary="show the window menu">
+ Clients implementing client-side decorations might want to show
+ a context menu when right-clicking on the decorations, giving the
+ user a menu that they can use to maximize or minimize the window.
+
+ This request asks the compositor to pop up such a window menu at
+ the given position, relative to the local surface coordinates of
+ the parent surface. There are no guarantees as to what menu items
+ the window menu contains.
+
+ This request must be used in response to some sort of user action
+ like a button press, key press, or touch down event.
+ </description>
+ <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
+ <arg name="serial" type="uint" summary="the serial of the user event"/>
+ <arg name="x" type="int" summary="the x position to pop up the window menu at"/>
+ <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
+ </request>
+
+ <request name="move">
+ <description summary="start an interactive move">
+ Start an interactive, user-driven move of the surface.
+
+ This request must be used in response to some sort of user action
+ like a button press, key press, or touch down event. The passed
+ serial is used to determine the type of interactive move (touch,
+ pointer, etc).
+
+ The server may ignore move requests depending on the state of
+ the surface (e.g. fullscreen or maximized), or if the passed serial
+ is no longer valid.
+
+ If triggered, the surface will lose the focus of the device
+ (wl_pointer, wl_touch, etc) used for the move. It is up to the
+ compositor to visually indicate that the move is taking place, such as
+ updating a pointer cursor, during the move. There is no guarantee
+ that the device focus will return when the move is completed.
+ </description>
+ <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
+ <arg name="serial" type="uint" summary="the serial of the user event"/>
+ </request>
+
+ <enum name="resize_edge">
+ <description summary="edge values for resizing">
+ These values are used to indicate which edge of a surface
+ is being dragged in a resize operation.
+ </description>
+ <entry name="none" value="0"/>
+ <entry name="top" value="1"/>
+ <entry name="bottom" value="2"/>
+ <entry name="left" value="4"/>
+ <entry name="top_left" value="5"/>
+ <entry name="bottom_left" value="6"/>
+ <entry name="right" value="8"/>
+ <entry name="top_right" value="9"/>
+ <entry name="bottom_right" value="10"/>
+ </enum>
+
+ <request name="resize">
+ <description summary="start an interactive resize">
+ Start a user-driven, interactive resize of the surface.
+
+ This request must be used in response to some sort of user action
+ like a button press, key press, or touch down event. The passed
+ serial is used to determine the type of interactive resize (touch,
+ pointer, etc).
+
+ The server may ignore resize requests depending on the state of
+ the surface (e.g. fullscreen or maximized).
+
+ If triggered, the client will receive configure events with the
+ "resize" state enum value and the expected sizes. See the "resize"
+ enum value for more details about what is required. The client
+ must also acknowledge configure events using "ack_configure". After
+ the resize is completed, the client will receive another "configure"
+ event without the resize state.
+
+ If triggered, the surface also will lose the focus of the device
+ (wl_pointer, wl_touch, etc) used for the resize. It is up to the
+ compositor to visually indicate that the resize is taking place,
+ such as updating a pointer cursor, during the resize. There is no
+ guarantee that the device focus will return when the resize is
+ completed.
+
+ The edges parameter specifies how the surface should be resized,
+ and is one of the values of the resize_edge enum. The compositor
+ may use this information to update the surface position for
+ example when dragging the top left corner. The compositor may also
+ use this information to adapt its behavior, e.g. choose an
+ appropriate cursor image.
+ </description>
+ <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
+ <arg name="serial" type="uint" summary="the serial of the user event"/>
+ <arg name="edges" type="uint" summary="which edge or corner is being dragged"/>
+ </request>
+
+ <enum name="state">
+ <description summary="types of state on the surface">
+ The different state values used on the surface. This is designed for
+ state values like maximized, fullscreen. It is paired with the
+ configure event to ensure that both the client and the compositor
+ setting the state can be synchronized.
+
+ States set in this way are double-buffered. They will get applied on
+ the next commit.
+
+ Desktop environments may extend this enum by taking up a range of
+ values and documenting the range they chose in this description.
+ They are not required to document the values for the range that they
+ chose. Ideally, any good extensions from a desktop environment should
+ make its way into standardization into this enum.
+
+ The current reserved ranges are:
+
+ 0x0000 - 0x0FFF: xdg-shell core values, documented below.
+ 0x1000 - 0x1FFF: GNOME
+ 0x2000 - 0x2FFF: EFL
+ </description>
+ <entry name="maximized" value="1" summary="the surface is maximized">
+ <description summary="the surface is maximized">
+ The surface is maximized. The window geometry specified in the configure
+ event must be obeyed by the client.
+ </description>
+ </entry>
+ <entry name="fullscreen" value="2" summary="the surface is fullscreen">
+ <description summary="the surface is fullscreen">
+ The surface is fullscreen. The window geometry specified in the configure
+ event must be obeyed by the client.
+ </description>
+ </entry>
+ <entry name="resizing" value="3" summary="the surface is being resized">
+ <description summary="the surface is being resized">
+ The surface is being resized. The window geometry specified in the
+ configure event is a maximum; the client cannot resize beyond it.
+ Clients that have aspect ratio or cell sizing configuration can use
+ a smaller size, however.
+ </description>
+ </entry>
+ <entry name="activated" value="4" summary="the surface is now activated">
+ <description summary="the surface is now activated">
+ Client window decorations should be painted as if the window is
+ active. Do not assume this means that the window actually has
+ keyboard or pointer focus.
+ </description>
+ </entry>
+ </enum>
+
+ <event name="configure">
+ <description summary="suggest a surface change">
+ The configure event asks the client to resize its surface or to
+ change its state.
+
+ The width and height arguments specify a hint to the window
+ about how its surface should be resized in window geometry
+ coordinates. See set_window_geometry.
+
+ If the width or height arguments are zero, it means the client
+ should decide its own window dimension. This may happen when the
+ compositor need to configure the state of the surface but doesn't
+ have any information about any previous or expected dimension.
+
+ The states listed in the event specify how the width/height
+ arguments should be interpreted, and possibly how it should be
+ drawn.
+
+ Clients should arrange their surface for the new size and
+ states, and then send a ack_configure request with the serial
+ sent in this configure event at some point before committing
+ the new surface.
+
+ If the client receives multiple configure events before it
+ can respond to one, it is free to discard all but the last
+ event it received.
+ </description>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ <arg name="states" type="array"/>
+ <arg name="serial" type="uint"/>
+ </event>
+
+ <request name="ack_configure">
+ <description summary="ack a configure event">
+ When a configure event is received, if a client commits the
+ surface in response to the configure event, then the client
+ must make an ack_configure request sometime before the commit
+ request, passing along the serial of the configure event.
+
+ For instance, the compositor might use this information to move
+ a surface to the top left only when the client has drawn itself
+ for the maximized or fullscreen state.
+
+ If the client receives multiple configure events before it
+ can respond to one, it only has to ack the last configure event.
+
+ A client is not required to commit immediately after sending
+ an ack_configure request - it may even ack_configure several times
+ before its next surface commit.
+
+ The compositor expects that the most recently received
+ ack_configure request at the time of a commit indicates which
+ configure event the client is responding to.
+ </description>
+ <arg name="serial" type="uint" summary="the serial from the configure event"/>
+ </request>
+
+ <request name="set_window_geometry">
+ <description summary="set the new window geometry">
+ The window geometry of a window is its "visible bounds" from the
+ user's perspective. Client-side decorations often have invisible
+ portions like drop-shadows which should be ignored for the
+ purposes of aligning, placing and constraining windows.
+
+ The window geometry is double buffered, and will be applied at the
+ time wl_surface.commit of the corresponding wl_surface is called.
+
+ Once the window geometry of the surface is set once, it is not
+ possible to unset it, and it will remain the same until
+ set_window_geometry is called again, even if a new subsurface or
+ buffer is attached.
+
+ If never set, the value is the full bounds of the surface,
+ including any subsurfaces. This updates dynamically on every
+ commit. This unset mode is meant for extremely simple clients.
+
+ If responding to a configure event, the window geometry in here
+ must respect the sizing negotiations specified by the states in
+ the configure event.
+
+ The arguments are given in the surface local coordinate space of
+ the wl_surface associated with this xdg_surface.
+
+ The width and height must be greater than zero.
+ </description>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="set_maximized">
+ <description summary="maximize the window">
+ Maximize the surface.
+
+ After requesting that the surface should be maximized, the compositor
+ will respond by emitting a configure event with the "maximized" state
+ and the required window geometry. The client should then update its
+ content, drawing it in a maximized state, i.e. without shadow or other
+ decoration outside of the window geometry. The client must also
+ acknowledge the configure when committing the new content (see
+ ack_configure).
+
+ It is up to the compositor to decide how and where to maximize the
+ surface, for example which output and what region of the screen should
+ be used.
+
+ If the surface was already maximized, the compositor will still emit
+ a configure event with the "maximized" state.
+ </description>
+ </request>
+
+ <request name="unset_maximized">
+ <description summary="unmaximize the window">
+ Unmaximize the surface.
+
+ After requesting that the surface should be unmaximized, the compositor
+ will respond by emitting a configure event without the "maximized"
+ state. If available, the compositor will include the window geometry
+ dimensions the window had prior to being maximized in the configure
+ request. The client must then update its content, drawing it in a
+ regular state, i.e. potentially with shadow, etc. The client must also
+ acknowledge the configure when committing the new content (see
+ ack_configure).
+
+ It is up to the compositor to position the surface after it was
+ unmaximized; usually the position the surface had before maximizing, if
+ applicable.
+
+ If the surface was already not maximized, the compositor will still
+ emit a configure event without the "maximized" state.
+ </description>
+ </request>
+
+ <request name="set_fullscreen">
+ <description summary="set the window as fullscreen on a monitor">
+ Make the surface fullscreen.
+
+ You can specify an output that you would prefer to be fullscreen.
+ If this value is NULL, it's up to the compositor to choose which
+ display will be used to map this surface.
+
+ If the surface doesn't cover the whole output, the compositor will
+ position the surface in the center of the output and compensate with
+ black borders filling the rest of the output.
+ </description>
+ <arg name="output" type="object" interface="wl_output" allow-null="true"/>
+ </request>
+ <request name="unset_fullscreen" />
+
+ <request name="set_minimized">
+ <description summary="set the window as minimized">
+ Request that the compositor minimize your surface. There is no
+ way to know if the surface is currently minimized, nor is there
+ any way to unset minimization on this surface.
+
+ If you are looking to throttle redrawing when minimized, please
+ instead use the wl_surface.frame event for this, as this will
+ also work with live previews on windows in Alt-Tab, Expose or
+ similar compositor features.
+ </description>
+ </request>
+
+ <event name="close">
+ <description summary="surface wants to be closed">
+ The close event is sent by the compositor when the user
+ wants the surface to be closed. This should be equivalent to
+ the user clicking the close button in client-side decorations,
+ if your application has any...
+
+ This is only a request that the user intends to close your
+ window. The client may choose to ignore this request, or show
+ a dialog to ask the user to save their data...
+ </description>
+ </event>
+ </interface>
+
+ <interface name="xdg_popup" version="1">
+ <description summary="short-lived, popup surfaces for menus">
+ A popup surface is a short-lived, temporary surface that can be
+ used to implement menus. It takes an explicit grab on the surface
+ that will be dismissed when the user dismisses the popup. This can
+ be done by the user clicking outside the surface, using the keyboard,
+ or even locking the screen through closing the lid or a timeout.
+
+ When the popup is dismissed, a popup_done event will be sent out,
+ and at the same time the surface will be unmapped. The xdg_popup
+ object is now inert and cannot be reactivated, so clients should
+ destroy it. Explicitly destroying the xdg_popup object will also
+ dismiss the popup and unmap the surface.
+
+ Clients will receive events for all their surfaces during this
+ grab (which is an "owner-events" grab in X11 parlance). This is
+ done so that users can navigate through submenus and other
+ "nested" popup windows without having to dismiss the topmost
+ popup.
+
+ Clients that want to dismiss the popup when another surface of
+ their own is clicked should dismiss the popup using the destroy
+ request.
+
+ The parent surface must have either an xdg_surface or xdg_popup
+ role.
+
+ Specifying an xdg_popup for the parent means that the popups are
+ nested, with this popup now being the topmost popup. Nested
+ popups must be destroyed in the reverse order they were created
+ in, e.g. the only popup you are allowed to destroy at all times
+ is the topmost one.
+
+ If there is an existing popup when creating a new popup, the
+ parent must be the current topmost popup.
+
+ A parent surface must be mapped before the new popup is mapped.
+
+ When compositors choose to dismiss a popup, they will likely
+ dismiss every nested popup as well. When a compositor dismisses
+ popups, it will follow the same dismissing order as required
+ from the client.
+
+ The x and y arguments passed when creating the popup object specify
+ where the top left of the popup should be placed, relative to the
+ local surface coordinates of the parent surface. See
+ xdg_shell.get_xdg_popup.
+
+ The client must call wl_surface.commit on the corresponding wl_surface
+ for the xdg_popup state to take effect.
+
+ For a surface to be mapped by the compositor the client must have
+ committed both the xdg_popup state and a buffer.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="remove xdg_popup interface">
+ This destroys the popup. Explicitly destroying the xdg_popup
+ object will also dismiss the popup, and unmap the surface.
+
+ If this xdg_popup is not the "topmost" popup, a protocol error
+ will be sent.
+ </description>
+ </request>
+
+ <event name="popup_done">
+ <description summary="popup interaction is done">
+ The popup_done event is sent out when a popup is dismissed by the
+ compositor. The client should destroy the xdg_popup object at this
+ point.
+ </description>
+ </event>
+
+ </interface>
+</protocol>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_shell_unstable_v6">
+
+ <copyright>
+ Copyright © 2008-2013 Kristian Høgsberg
+ Copyright © 2013 Rafael Antognolli
+ Copyright © 2013 Jasper St. Pierre
+ Copyright © 2010-2013 Intel Corporation
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <interface name="zxdg_shell_v6" version="1">
+ <description summary="create desktop-style surfaces">
+ xdg_shell allows clients to turn a wl_surface into a "real window"
+ which can be dragged, resized, stacked, and moved around by the
+ user. Everything about this interface is suited towards traditional
+ desktop environments.
+ </description>
+
+ <enum name="error">
+ <entry name="role" value="0" summary="given wl_surface has another role"/>
+ <entry name="defunct_surfaces" value="1"
+ summary="xdg_shell was destroyed before children"/>
+ <entry name="not_the_topmost_popup" value="2"
+ summary="the client tried to map or destroy a non-topmost popup"/>
+ <entry name="invalid_popup_parent" value="3"
+ summary="the client specified an invalid popup parent surface"/>
+ <entry name="invalid_surface_state" value="4"
+ summary="the client provided an invalid surface state"/>
+ <entry name="invalid_positioner" value="5"
+ summary="the client provided an invalid positioner"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy xdg_shell">
+ Destroy this xdg_shell object.
+
+ Destroying a bound xdg_shell object while there are surfaces
+ still alive created by this xdg_shell object instance is illegal
+ and will result in a protocol error.
+ </description>
+ </request>
+
+ <request name="create_positioner">
+ <description summary="create a positioner object">
+ Create a positioner object. A positioner object is used to position
+ surfaces relative to some parent surface. See the interface description
+ and xdg_surface.get_popup for details.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_positioner_v6"/>
+ </request>
+
+ <request name="get_xdg_surface">
+ <description summary="create a shell surface from a surface">
+ This creates an xdg_surface for the given surface. While xdg_surface
+ itself is not a role, the corresponding surface may only be assigned
+ a role extending xdg_surface, such as xdg_toplevel or xdg_popup.
+
+ This creates an xdg_surface for the given surface. An xdg_surface is
+ used as basis to define a role to a given surface, such as xdg_toplevel
+ or xdg_popup. It also manages functionality shared between xdg_surface
+ based surface roles.
+
+ See the documentation of xdg_surface for more details about what an
+ xdg_surface is and how it is used.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_surface_v6"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="pong">
+ <description summary="respond to a ping event">
+ A client must respond to a ping event with a pong request or
+ the client may be deemed unresponsive. See xdg_shell.ping.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the ping event"/>
+ </request>
+
+ <event name="ping">
+ <description summary="check if the client is alive">
+ The ping event asks the client if it's still alive. Pass the
+ serial specified in the event back to the compositor by sending
+ a "pong" request back with the specified serial. See xdg_shell.ping.
+
+ Compositors can use this to determine if the client is still
+ alive. It's unspecified what will happen if the client doesn't
+ respond to the ping request, or in what timeframe. Clients should
+ try to respond in a reasonable amount of time.
+
+ A compositor is free to ping in any way it wants, but a client must
+ always respond to any xdg_shell object it created.
+ </description>
+ <arg name="serial" type="uint" summary="pass this to the pong request"/>
+ </event>
+ </interface>
+
+ <interface name="zxdg_positioner_v6" version="1">
+ <description summary="child surface positioner">
+ The xdg_positioner provides a collection of rules for the placement of a
+ child surface relative to a parent surface. Rules can be defined to ensure
+ the child surface remains within the visible area's borders, and to
+ specify how the child surface changes its position, such as sliding along
+ an axis, or flipping around a rectangle. These positioner-created rules are
+ constrained by the requirement that a child surface must intersect with or
+ be at least partially adjacent to its parent surface.
+
+ See the various requests for details about possible rules.
+
+ At the time of the request, the compositor makes a copy of the rules
+ specified by the xdg_positioner. Thus, after the request is complete the
+ xdg_positioner object can be destroyed or reused; further changes to the
+ object will have no effect on previous usages.
+
+ For an xdg_positioner object to be considered complete, it must have a
+ non-zero size set by set_size, and a non-zero anchor rectangle set by
+ set_anchor_rect. Passing an incomplete xdg_positioner object when
+ positioning a surface raises an error.
+ </description>
+
+ <enum name="error">
+ <entry name="invalid_input" value="0" summary="invalid input provided"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_positioner object">
+ Notify the compositor that the xdg_positioner will no longer be used.
+ </description>
+ </request>
+
+ <request name="set_size">
+ <description summary="set the size of the to-be positioned rectangle">
+ Set the size of the surface that is to be positioned with the positioner
+ object. The size is in surface-local coordinates and corresponds to the
+ window geometry. See xdg_surface.set_window_geometry.
+
+ If a zero or negative size is set the invalid_input error is raised.
+ </description>
+ <arg name="width" type="int" summary="width of positioned rectangle"/>
+ <arg name="height" type="int" summary="height of positioned rectangle"/>
+ </request>
+
+ <request name="set_anchor_rect">
+ <description summary="set the anchor rectangle within the parent surface">
+ Specify the anchor rectangle within the parent surface that the child
+ surface will be placed relative to. The rectangle is relative to the
+ window geometry as defined by xdg_surface.set_window_geometry of the
+ parent surface. The rectangle must be at least 1x1 large.
+
+ When the xdg_positioner object is used to position a child surface, the
+ anchor rectangle may not extend outside the window geometry of the
+ positioned child's parent surface.
+
+ If a zero or negative size is set the invalid_input error is raised.
+ </description>
+ <arg name="x" type="int" summary="x position of anchor rectangle"/>
+ <arg name="y" type="int" summary="y position of anchor rectangle"/>
+ <arg name="width" type="int" summary="width of anchor rectangle"/>
+ <arg name="height" type="int" summary="height of anchor rectangle"/>
+ </request>
+
+ <enum name="anchor" bitfield="true">
+ <entry name="none" value="0"
+ summary="the center of the anchor rectangle"/>
+ <entry name="top" value="1"
+ summary="the top edge of the anchor rectangle"/>
+ <entry name="bottom" value="2"
+ summary="the bottom edge of the anchor rectangle"/>
+ <entry name="left" value="4"
+ summary="the left edge of the anchor rectangle"/>
+ <entry name="right" value="8"
+ summary="the right edge of the anchor rectangle"/>
+ </enum>
+
+ <request name="set_anchor">
+ <description summary="set anchor rectangle anchor edges">
+ Defines a set of edges for the anchor rectangle. These are used to
+ derive an anchor point that the child surface will be positioned
+ relative to. If two orthogonal edges are specified (e.g. 'top' and
+ 'left'), then the anchor point will be the intersection of the edges
+ (e.g. the top left position of the rectangle); otherwise, the derived
+ anchor point will be centered on the specified edge, or in the center of
+ the anchor rectangle if no edge is specified.
+
+ If two parallel anchor edges are specified (e.g. 'left' and 'right'),
+ the invalid_input error is raised.
+ </description>
+ <arg name="anchor" type="uint" enum="anchor"
+ summary="bit mask of anchor edges"/>
+ </request>
+
+ <enum name="gravity" bitfield="true">
+ <entry name="none" value="0"
+ summary="center over the anchor edge"/>
+ <entry name="top" value="1"
+ summary="position above the anchor edge"/>
+ <entry name="bottom" value="2"
+ summary="position below the anchor edge"/>
+ <entry name="left" value="4"
+ summary="position to the left of the anchor edge"/>
+ <entry name="right" value="8"
+ summary="position to the right of the anchor edge"/>
+ </enum>
+
+ <request name="set_gravity">
+ <description summary="set child surface gravity">
+ Defines in what direction a surface should be positioned, relative to
+ the anchor point of the parent surface. If two orthogonal gravities are
+ specified (e.g. 'bottom' and 'right'), then the child surface will be
+ placed in the specified direction; otherwise, the child surface will be
+ centered over the anchor point on any axis that had no gravity
+ specified.
+
+ If two parallel gravities are specified (e.g. 'left' and 'right'), the
+ invalid_input error is raised.
+ </description>
+ <arg name="gravity" type="uint" enum="gravity"
+ summary="bit mask of gravity directions"/>
+ </request>
+
+ <enum name="constraint_adjustment" bitfield="true">
+ <description summary="constraint adjustments">
+ The constraint adjustment value define ways the compositor will adjust
+ the position of the surface, if the unadjusted position would result
+ in the surface being partly constrained.
+
+ Whether a surface is considered 'constrained' is left to the compositor
+ to determine. For example, the surface may be partly outside the
+ compositor's defined 'work area', thus necessitating the child surface's
+ position be adjusted until it is entirely inside the work area.
+
+ The adjustments can be combined, according to a defined precedence: 1)
+ Flip, 2) Slide, 3) Resize.
+ </description>
+ <entry name="none" value="0">
+ <description summary="don't move the child surface when constrained">
+ Don't alter the surface position even if it is constrained on some
+ axis, for example partially outside the edge of a monitor.
+ </description>
+ </entry>
+ <entry name="slide_x" value="1">
+ <description summary="move along the x axis until unconstrained">
+ Slide the surface along the x axis until it is no longer constrained.
+
+ First try to slide towards the direction of the gravity on the x axis
+ until either the edge in the opposite direction of the gravity is
+ unconstrained or the edge in the direction of the gravity is
+ constrained.
+
+ Then try to slide towards the opposite direction of the gravity on the
+ x axis until either the edge in the direction of the gravity is
+ unconstrained or the edge in the opposite direction of the gravity is
+ constrained.
+ </description>
+ </entry>
+ <entry name="slide_y" value="2">
+ <description summary="move along the y axis until unconstrained">
+ Slide the surface along the y axis until it is no longer constrained.
+
+ First try to slide towards the direction of the gravity on the y axis
+ until either the edge in the opposite direction of the gravity is
+ unconstrained or the edge in the direction of the gravity is
+ constrained.
+
+ Then try to slide towards the opposite direction of the gravity on the
+ y axis until either the edge in the direction of the gravity is
+ unconstrained or the edge in the opposite direction of the gravity is
+ constrained.
+ </description>
+ </entry>
+ <entry name="flip_x" value="4">
+ <description summary="invert the anchor and gravity on the x axis">
+ Invert the anchor and gravity on the x axis if the surface is
+ constrained on the x axis. For example, if the left edge of the
+ surface is constrained, the gravity is 'left' and the anchor is
+ 'left', change the gravity to 'right' and the anchor to 'right'.
+
+ If the adjusted position also ends up being constrained, the resulting
+ position of the flip_x adjustment will be the one before the
+ adjustment.
+ </description>
+ </entry>
+ <entry name="flip_y" value="8">
+ <description summary="invert the anchor and gravity on the y axis">
+ Invert the anchor and gravity on the y axis if the surface is
+ constrained on the y axis. For example, if the bottom edge of the
+ surface is constrained, the gravity is 'bottom' and the anchor is
+ 'bottom', change the gravity to 'top' and the anchor to 'top'.
+
+ If the adjusted position also ends up being constrained, the resulting
+ position of the flip_y adjustment will be the one before the
+ adjustment.
+ </description>
+ </entry>
+ <entry name="resize_x" value="16">
+ <description summary="horizontally resize the surface">
+ Resize the surface horizontally so that it is completely
+ unconstrained.
+ </description>
+ </entry>
+ <entry name="resize_y" value="32">
+ <description summary="vertically resize the surface">
+ Resize the surface vertically so that it is completely unconstrained.
+ </description>
+ </entry>
+ </enum>
+
+ <request name="set_constraint_adjustment">
+ <description summary="set the adjustment to be done when constrained">
+ Specify how the window should be positioned if the originally intended
+ position caused the surface to be constrained, meaning at least
+ partially outside positioning boundaries set by the compositor. The
+ adjustment is set by constructing a bitmask describing the adjustment to
+ be made when the surface is constrained on that axis.
+
+ If no bit for one axis is set, the compositor will assume that the child
+ surface should not change its position on that axis when constrained.
+
+ If more than one bit for one axis is set, the order of how adjustments
+ are applied is specified in the corresponding adjustment descriptions.
+
+ The default adjustment is none.
+ </description>
+ <arg name="constraint_adjustment" type="uint"
+ summary="bit mask of constraint adjustments"/>
+ </request>
+
+ <request name="set_offset">
+ <description summary="set surface position offset">
+ Specify the surface position offset relative to the position of the
+ anchor on the anchor rectangle and the anchor on the surface. For
+ example if the anchor of the anchor rectangle is at (x, y), the surface
+ has the gravity bottom|right, and the offset is (ox, oy), the calculated
+ surface position will be (x + ox, y + oy). The offset position of the
+ surface is the one used for constraint testing. See
+ set_constraint_adjustment.
+
+ An example use case is placing a popup menu on top of a user interface
+ element, while aligning the user interface element of the parent surface
+ with some user interface element placed somewhere in the popup surface.
+ </description>
+ <arg name="x" type="int" summary="surface position x offset"/>
+ <arg name="y" type="int" summary="surface position y offset"/>
+ </request>
+ </interface>
+
+ <interface name="zxdg_surface_v6" version="1">
+ <description summary="desktop user interface surface base interface">
+ An interface that may be implemented by a wl_surface, for
+ implementations that provide a desktop-style user interface.
+
+ It provides a base set of functionality required to construct user
+ interface elements requiring management by the compositor, such as
+ toplevel windows, menus, etc. The types of functionality are split into
+ xdg_surface roles.
+
+ Creating an xdg_surface does not set the role for a wl_surface. In order
+ to map an xdg_surface, the client must create a role-specific object
+ using, e.g., get_toplevel, get_popup. The wl_surface for any given
+ xdg_surface can have at most one role, and may not be assigned any role
+ not based on xdg_surface.
+
+ A role must be assigned before any other requests are made to the
+ xdg_surface object.
+
+ The client must call wl_surface.commit on the corresponding wl_surface
+ for the xdg_surface state to take effect.
+
+ Creating an xdg_surface from a wl_surface which has a buffer attached or
+ committed is a client error, and any attempts by a client to attach or
+ manipulate a buffer prior to the first xdg_surface.configure call must
+ also be treated as errors.
+
+ For a surface to be mapped by the compositor, the following conditions
+ must be met: (1) the client has assigned a xdg_surface based role to the
+ surface, (2) the client has set and committed the xdg_surface state and
+ the role dependent state to the surface and (3) the client has committed a
+ buffer to the surface.
+ </description>
+
+ <enum name="error">
+ <entry name="not_constructed" value="1"/>
+ <entry name="already_constructed" value="2"/>
+ <entry name="unconfigured_buffer" value="3"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_surface">
+ Destroy the xdg_surface object. An xdg_surface must only be destroyed
+ after its role object has been destroyed.
+ </description>
+ </request>
+
+ <request name="get_toplevel">
+ <description summary="assign the xdg_toplevel surface role">
+ This creates an xdg_toplevel object for the given xdg_surface and gives
+ the associated wl_surface the xdg_toplevel role.
+
+ See the documentation of xdg_toplevel for more details about what an
+ xdg_toplevel is and how it is used.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_toplevel_v6"/>
+ </request>
+
+ <request name="get_popup">
+ <description summary="assign the xdg_popup surface role">
+ This creates an xdg_popup object for the given xdg_surface and gives the
+ associated wl_surface the xdg_popup role.
+
+ See the documentation of xdg_popup for more details about what an
+ xdg_popup is and how it is used.
+ </description>
+ <arg name="id" type="new_id" interface="zxdg_popup_v6"/>
+ <arg name="parent" type="object" interface="zxdg_surface_v6"/>
+ <arg name="positioner" type="object" interface="zxdg_positioner_v6"/>
+ </request>
+
+ <request name="set_window_geometry">
+ <description summary="set the new window geometry">
+ The window geometry of a surface is its "visible bounds" from the
+ user's perspective. Client-side decorations often have invisible
+ portions like drop-shadows which should be ignored for the
+ purposes of aligning, placing and constraining windows.
+
+ The window geometry is double buffered, and will be applied at the
+ time wl_surface.commit of the corresponding wl_surface is called.
+
+ Once the window geometry of the surface is set, it is not possible to
+ unset it, and it will remain the same until set_window_geometry is
+ called again, even if a new subsurface or buffer is attached.
+
+ If never set, the value is the full bounds of the surface,
+ including any subsurfaces. This updates dynamically on every
+ commit. This unset is meant for extremely simple clients.
+
+ The arguments are given in the surface-local coordinate space of
+ the wl_surface associated with this xdg_surface.
+
+ The width and height must be greater than zero. Setting an invalid size
+ will raise an error. When applied, the effective window geometry will be
+ the set window geometry clamped to the bounding rectangle of the
+ combined geometry of the surface of the xdg_surface and the associated
+ subsurfaces.
+ </description>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="ack_configure">
+ <description summary="ack a configure event">
+ When a configure event is received, if a client commits the
+ surface in response to the configure event, then the client
+ must make an ack_configure request sometime before the commit
+ request, passing along the serial of the configure event.
+
+ For instance, for toplevel surfaces the compositor might use this
+ information to move a surface to the top left only when the client has
+ drawn itself for the maximized or fullscreen state.
+
+ If the client receives multiple configure events before it
+ can respond to one, it only has to ack the last configure event.
+
+ A client is not required to commit immediately after sending
+ an ack_configure request - it may even ack_configure several times
+ before its next surface commit.
+
+ A client may send multiple ack_configure requests before committing, but
+ only the last request sent before a commit indicates which configure
+ event the client really is responding to.
+ </description>
+ <arg name="serial" type="uint" summary="the serial from the configure event"/>
+ </request>
+
+ <event name="configure">
+ <description summary="suggest a surface change">
+ The configure event marks the end of a configure sequence. A configure
+ sequence is a set of one or more events configuring the state of the
+ xdg_surface, including the final xdg_surface.configure event.
+
+ Where applicable, xdg_surface surface roles will during a configure
+ sequence extend this event as a latched state sent as events before the
+ xdg_surface.configure event. Such events should be considered to make up
+ a set of atomically applied configuration states, where the
+ xdg_surface.configure commits the accumulated state.
+
+ Clients should arrange their surface for the new states, and then send
+ an ack_configure request with the serial sent in this configure event at
+ some point before committing the new surface.
+
+ If the client receives multiple configure events before it can respond
+ to one, it is free to discard all but the last event it received.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the configure event"/>
+ </event>
+ </interface>
+
+ <interface name="zxdg_toplevel_v6" version="1">
+ <description summary="toplevel surface">
+ This interface defines an xdg_surface role which allows a surface to,
+ among other things, set window-like properties such as maximize,
+ fullscreen, and minimize, set application-specific metadata like title and
+ id, and well as trigger user interactive operations such as interactive
+ resize and move.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the xdg_toplevel">
+ Unmap and destroy the window. The window will be effectively
+ hidden from the user's point of view, and all state like
+ maximization, fullscreen, and so on, will be lost.
+ </description>
+ </request>
+
+ <request name="set_parent">
+ <description summary="set the parent of this surface">
+ Set the "parent" of this surface. This window should be stacked
+ above a parent. The parent surface must be mapped as long as this
+ surface is mapped.
+
+ Parent windows should be set on dialogs, toolboxes, or other
+ "auxiliary" surfaces, so that the parent is raised when the dialog
+ is raised.
+ </description>
+ <arg name="parent" type="object" interface="zxdg_toplevel_v6" allow-null="true"/>
+ </request>
+
+ <request name="set_title">
+ <description summary="set surface title">
+ Set a short title for the surface.
+
+ This string may be used to identify the surface in a task bar,
+ window list, or other user interface elements provided by the
+ compositor.
+
+ The string must be encoded in UTF-8.
+ </description>
+ <arg name="title" type="string"/>
+ </request>
+
+ <request name="set_app_id">
+ <description summary="set application ID">
+ Set an application identifier for the surface.
+
+ The app ID identifies the general class of applications to which
+ the surface belongs. The compositor can use this to group multiple
+ surfaces together, or to determine how to launch a new application.
+
+ For D-Bus activatable applications, the app ID is used as the D-Bus
+ service name.
+
+ The compositor shell will try to group application surfaces together
+ by their app ID. As a best practice, it is suggested to select app
+ ID's that match the basename of the application's .desktop file.
+ For example, "org.freedesktop.FooViewer" where the .desktop file is
+ "org.freedesktop.FooViewer.desktop".
+
+ See the desktop-entry specification [0] for more details on
+ application identifiers and how they relate to well-known D-Bus
+ names and .desktop files.
+
+ [0] http://standards.freedesktop.org/desktop-entry-spec/
+ </description>
+ <arg name="app_id" type="string"/>
+ </request>
+
+ <request name="show_window_menu">
+ <description summary="show the window menu">
+ Clients implementing client-side decorations might want to show
+ a context menu when right-clicking on the decorations, giving the
+ user a menu that they can use to maximize or minimize the window.
+
+ This request asks the compositor to pop up such a window menu at
+ the given position, relative to the local surface coordinates of
+ the parent surface. There are no guarantees as to what menu items
+ the window menu contains.
+
+ This request must be used in response to some sort of user action
+ like a button press, key press, or touch down event.
+ </description>
+ <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
+ <arg name="serial" type="uint" summary="the serial of the user event"/>
+ <arg name="x" type="int" summary="the x position to pop up the window menu at"/>
+ <arg name="y" type="int" summary="the y position to pop up the window menu at"/>
+ </request>
+
+ <request name="move">
+ <description summary="start an interactive move">
+ Start an interactive, user-driven move of the surface.
+
+ This request must be used in response to some sort of user action
+ like a button press, key press, or touch down event. The passed
+ serial is used to determine the type of interactive move (touch,
+ pointer, etc).
+
+ The server may ignore move requests depending on the state of
+ the surface (e.g. fullscreen or maximized), or if the passed serial
+ is no longer valid.
+
+ If triggered, the surface will lose the focus of the device
+ (wl_pointer, wl_touch, etc) used for the move. It is up to the
+ compositor to visually indicate that the move is taking place, such as
+ updating a pointer cursor, during the move. There is no guarantee
+ that the device focus will return when the move is completed.
+ </description>
+ <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
+ <arg name="serial" type="uint" summary="the serial of the user event"/>
+ </request>
+
+ <enum name="resize_edge">
+ <description summary="edge values for resizing">
+ These values are used to indicate which edge of a surface
+ is being dragged in a resize operation.
+ </description>
+ <entry name="none" value="0"/>
+ <entry name="top" value="1"/>
+ <entry name="bottom" value="2"/>
+ <entry name="left" value="4"/>
+ <entry name="top_left" value="5"/>
+ <entry name="bottom_left" value="6"/>
+ <entry name="right" value="8"/>
+ <entry name="top_right" value="9"/>
+ <entry name="bottom_right" value="10"/>
+ </enum>
+
+ <request name="resize">
+ <description summary="start an interactive resize">
+ Start a user-driven, interactive resize of the surface.
+
+ This request must be used in response to some sort of user action
+ like a button press, key press, or touch down event. The passed
+ serial is used to determine the type of interactive resize (touch,
+ pointer, etc).
+
+ The server may ignore resize requests depending on the state of
+ the surface (e.g. fullscreen or maximized).
+
+ If triggered, the client will receive configure events with the
+ "resize" state enum value and the expected sizes. See the "resize"
+ enum value for more details about what is required. The client
+ must also acknowledge configure events using "ack_configure". After
+ the resize is completed, the client will receive another "configure"
+ event without the resize state.
+
+ If triggered, the surface also will lose the focus of the device
+ (wl_pointer, wl_touch, etc) used for the resize. It is up to the
+ compositor to visually indicate that the resize is taking place,
+ such as updating a pointer cursor, during the resize. There is no
+ guarantee that the device focus will return when the resize is
+ completed.
+
+ The edges parameter specifies how the surface should be resized,
+ and is one of the values of the resize_edge enum. The compositor
+ may use this information to update the surface position for
+ example when dragging the top left corner. The compositor may also
+ use this information to adapt its behavior, e.g. choose an
+ appropriate cursor image.
+ </description>
+ <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat of the user event"/>
+ <arg name="serial" type="uint" summary="the serial of the user event"/>
+ <arg name="edges" type="uint" summary="which edge or corner is being dragged"/>
+ </request>
+
+ <enum name="state">
+ <description summary="types of state on the surface">
+ The different state values used on the surface. This is designed for
+ state values like maximized, fullscreen. It is paired with the
+ configure event to ensure that both the client and the compositor
+ setting the state can be synchronized.
+
+ States set in this way are double-buffered. They will get applied on
+ the next commit.
+ </description>
+ <entry name="maximized" value="1" summary="the surface is maximized">
+ <description summary="the surface is maximized">
+ The surface is maximized. The window geometry specified in the configure
+ event must be obeyed by the client.
+ </description>
+ </entry>
+ <entry name="fullscreen" value="2" summary="the surface is fullscreen">
+ <description summary="the surface is fullscreen">
+ The surface is fullscreen. The window geometry specified in the configure
+ event must be obeyed by the client.
+ </description>
+ </entry>
+ <entry name="resizing" value="3" summary="the surface is being resized">
+ <description summary="the surface is being resized">
+ The surface is being resized. The window geometry specified in the
+ configure event is a maximum; the client cannot resize beyond it.
+ Clients that have aspect ratio or cell sizing configuration can use
+ a smaller size, however.
+ </description>
+ </entry>
+ <entry name="activated" value="4" summary="the surface is now activated">
+ <description summary="the surface is now activated">
+ Client window decorations should be painted as if the window is
+ active. Do not assume this means that the window actually has
+ keyboard or pointer focus.
+ </description>
+ </entry>
+ </enum>
+
+ <request name="set_max_size">
+ <description summary="set the maximum size">
+ Set a maximum size for the window.
+
+ The client can specify a maximum size so that the compositor does
+ not try to configure the window beyond this size.
+
+ The width and height arguments are in window geometry coordinates.
+ See xdg_surface.set_window_geometry.
+
+ Values set in this way are double-buffered. They will get applied
+ on the next commit.
+
+ The compositor can use this information to allow or disallow
+ different states like maximize or fullscreen and draw accurate
+ animations.
+
+ Similarly, a tiling window manager may use this information to
+ place and resize client windows in a more effective way.
+
+ The client should not rely on the compositor to obey the maximum
+ size. The compositor may decide to ignore the values set by the
+ client and request a larger size.
+
+ If never set, or a value of zero in the request, means that the
+ client has no expected maximum size in the given dimension.
+ As a result, a client wishing to reset the maximum size
+ to an unspecified state can use zero for width and height in the
+ request.
+
+ Requesting a maximum size to be smaller than the minimum size of
+ a surface is illegal and will result in a protocol error.
+
+ The width and height must be greater than or equal to zero. Using
+ strictly negative values for width and height will result in a
+ protocol error.
+ </description>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="set_min_size">
+ <description summary="set the minimum size">
+ Set a minimum size for the window.
+
+ The client can specify a minimum size so that the compositor does
+ not try to configure the window below this size.
+
+ The width and height arguments are in window geometry coordinates.
+ See xdg_surface.set_window_geometry.
+
+ Values set in this way are double-buffered. They will get applied
+ on the next commit.
+
+ The compositor can use this information to allow or disallow
+ different states like maximize or fullscreen and draw accurate
+ animations.
+
+ Similarly, a tiling window manager may use this information to
+ place and resize client windows in a more effective way.
+
+ The client should not rely on the compositor to obey the minimum
+ size. The compositor may decide to ignore the values set by the
+ client and request a smaller size.
+
+ If never set, or a value of zero in the request, means that the
+ client has no expected minimum size in the given dimension.
+ As a result, a client wishing to reset the minimum size
+ to an unspecified state can use zero for width and height in the
+ request.
+
+ Requesting a minimum size to be larger than the maximum size of
+ a surface is illegal and will result in a protocol error.
+
+ The width and height must be greater than or equal to zero. Using
+ strictly negative values for width and height will result in a
+ protocol error.
+ </description>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="set_maximized">
+ <description summary="maximize the window">
+ Maximize the surface.
+
+ After requesting that the surface should be maximized, the compositor
+ will respond by emitting a configure event with the "maximized" state
+ and the required window geometry. The client should then update its
+ content, drawing it in a maximized state, i.e. without shadow or other
+ decoration outside of the window geometry. The client must also
+ acknowledge the configure when committing the new content (see
+ ack_configure).
+
+ It is up to the compositor to decide how and where to maximize the
+ surface, for example which output and what region of the screen should
+ be used.
+
+ If the surface was already maximized, the compositor will still emit
+ a configure event with the "maximized" state.
+ </description>
+ </request>
+
+ <request name="unset_maximized">
+ <description summary="unmaximize the window">
+ Unmaximize the surface.
+
+ After requesting that the surface should be unmaximized, the compositor
+ will respond by emitting a configure event without the "maximized"
+ state. If available, the compositor will include the window geometry
+ dimensions the window had prior to being maximized in the configure
+ request. The client must then update its content, drawing it in a
+ regular state, i.e. potentially with shadow, etc. The client must also
+ acknowledge the configure when committing the new content (see
+ ack_configure).
+
+ It is up to the compositor to position the surface after it was
+ unmaximized; usually the position the surface had before maximizing, if
+ applicable.
+
+ If the surface was already not maximized, the compositor will still
+ emit a configure event without the "maximized" state.
+ </description>
+ </request>
+
+ <request name="set_fullscreen">
+ <description summary="set the window as fullscreen on a monitor">
+ Make the surface fullscreen.
+
+ You can specify an output that you would prefer to be fullscreen.
+ If this value is NULL, it's up to the compositor to choose which
+ display will be used to map this surface.
+
+ If the surface doesn't cover the whole output, the compositor will
+ position the surface in the center of the output and compensate with
+ black borders filling the rest of the output.
+ </description>
+ <arg name="output" type="object" interface="wl_output" allow-null="true"/>
+ </request>
+ <request name="unset_fullscreen" />
+
+ <request name="set_minimized">
+ <description summary="set the window as minimized">
+ Request that the compositor minimize your surface. There is no
+ way to know if the surface is currently minimized, nor is there
+ any way to unset minimization on this surface.
+
+ If you are looking to throttle redrawing when minimized, please
+ instead use the wl_surface.frame event for this, as this will
+ also work with live previews on windows in Alt-Tab, Expose or
+ similar compositor features.
+ </description>
+ </request>
+
+ <event name="configure">
+ <description summary="suggest a surface change">
+ This configure event asks the client to resize its toplevel surface or
+ to change its state. The configured state should not be applied
+ immediately. See xdg_surface.configure for details.
+
+ The width and height arguments specify a hint to the window
+ about how its surface should be resized in window geometry
+ coordinates. See set_window_geometry.
+
+ If the width or height arguments are zero, it means the client
+ should decide its own window dimension. This may happen when the
+ compositor needs to configure the state of the surface but doesn't
+ have any information about any previous or expected dimension.
+
+ The states listed in the event specify how the width/height
+ arguments should be interpreted, and possibly how it should be
+ drawn.
+
+ Clients must send an ack_configure in response to this event. See
+ xdg_surface.configure and xdg_surface.ack_configure for details.
+ </description>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ <arg name="states" type="array"/>
+ </event>
+
+ <event name="close">
+ <description summary="surface wants to be closed">
+ The close event is sent by the compositor when the user
+ wants the surface to be closed. This should be equivalent to
+ the user clicking the close button in client-side decorations,
+ if your application has any.
+
+ This is only a request that the user intends to close the
+ window. The client may choose to ignore this request, or show
+ a dialog to ask the user to save their data, etc.
+ </description>
+ </event>
+ </interface>
+
+ <interface name="zxdg_popup_v6" version="1">
+ <description summary="short-lived, popup surfaces for menus">
+ A popup surface is a short-lived, temporary surface. It can be used to
+ implement for example menus, popovers, tooltips and other similar user
+ interface concepts.
+
+ A popup can be made to take an explicit grab. See xdg_popup.grab for
+ details.
+
+ When the popup is dismissed, a popup_done event will be sent out, and at
+ the same time the surface will be unmapped. See the xdg_popup.popup_done
+ event for details.
+
+ Explicitly destroying the xdg_popup object will also dismiss the popup and
+ unmap the surface. Clients that want to dismiss the popup when another
+ surface of their own is clicked should dismiss the popup using the destroy
+ request.
+
+ The parent surface must have either the xdg_toplevel or xdg_popup surface
+ role.
+
+ A newly created xdg_popup will be stacked on top of all previously created
+ xdg_popup surfaces associated with the same xdg_toplevel.
+
+ The parent of an xdg_popup must be mapped (see the xdg_surface
+ description) before the xdg_popup itself.
+
+ The x and y arguments passed when creating the popup object specify
+ where the top left of the popup should be placed, relative to the
+ local surface coordinates of the parent surface. See
+ xdg_surface.get_popup. An xdg_popup must intersect with or be at least
+ partially adjacent to its parent surface.
+
+ The client must call wl_surface.commit on the corresponding wl_surface
+ for the xdg_popup state to take effect.
+ </description>
+
+ <enum name="error">
+ <entry name="invalid_grab" value="0"
+ summary="tried to grab after being mapped"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="remove xdg_popup interface">
+ This destroys the popup. Explicitly destroying the xdg_popup
+ object will also dismiss the popup, and unmap the surface.
+
+ If this xdg_popup is not the "topmost" popup, a protocol error
+ will be sent.
+ </description>
+ </request>
+
+ <request name="grab">
+ <description summary="make the popup take an explicit grab">
+ This request makes the created popup take an explicit grab. An explicit
+ grab will be dismissed when the user dismisses the popup, or when the
+ client destroys the xdg_popup. This can be done by the user clicking
+ outside the surface, using the keyboard, or even locking the screen
+ through closing the lid or a timeout.
+
+ If the compositor denies the grab, the popup will be immediately
+ dismissed.
+
+ This request must be used in response to some sort of user action like a
+ button press, key press, or touch down event. The serial number of the
+ event should be passed as 'serial'.
+
+ The parent of a grabbing popup must either be an xdg_toplevel surface or
+ another xdg_popup with an explicit grab. If the parent is another
+ xdg_popup it means that the popups are nested, with this popup now being
+ the topmost popup.
+
+ Nested popups must be destroyed in the reverse order they were created
+ in, e.g. the only popup you are allowed to destroy at all times is the
+ topmost one.
+
+ When compositors choose to dismiss a popup, they may dismiss every
+ nested grabbing popup as well. When a compositor dismisses popups, it
+ will follow the same dismissing order as required from the client.
+
+ The parent of a grabbing popup must either be another xdg_popup with an
+ active explicit grab, or an xdg_popup or xdg_toplevel, if there are no
+ explicit grabs already taken.
+
+ If the topmost grabbing popup is destroyed, the grab will be returned to
+ the parent of the popup, if that parent previously had an explicit grab.
+
+ If the parent is a grabbing popup which has already been dismissed, this
+ popup will be immediately dismissed. If the parent is a popup that did
+ not take an explicit grab, an error will be raised.
+
+ During a popup grab, the client owning the grab will receive pointer
+ and touch events for all their surfaces as normal (similar to an
+ "owner-events" grab in X11 parlance), while the top most grabbing popup
+ will always have keyboard focus.
+ </description>
+ <arg name="seat" type="object" interface="wl_seat"
+ summary="the wl_seat of the user event"/>
+ <arg name="serial" type="uint" summary="the serial of the user event"/>
+ </request>
+
+ <event name="configure">
+ <description summary="configure the popup surface">
+ This event asks the popup surface to configure itself given the
+ configuration. The configured state should not be applied immediately.
+ See xdg_surface.configure for details.
+
+ The x and y arguments represent the position the popup was placed at
+ given the xdg_positioner rule, relative to the upper left corner of the
+ window geometry of the parent surface.
+ </description>
+ <arg name="x" type="int"
+ summary="x position relative to parent surface window geometry"/>
+ <arg name="y" type="int"
+ summary="y position relative to parent surface window geometry"/>
+ <arg name="width" type="int" summary="window geometry width"/>
+ <arg name="height" type="int" summary="window geometry height"/>
+ </event>
+
+ <event name="popup_done">
+ <description summary="popup interaction is done">
+ The popup_done event is sent out when a popup is dismissed by the
+ compositor. The client should destroy the xdg_popup object at this
+ point.
+ </description>
+ </event>
+
+ </interface>
+</protocol>
--- /dev/null
+Xwayland keyboard grabbing protocol
+
+Maintainers:
+Olivier Fourdan <ofourdan@redhat.com>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xwayland_keyboard_grab_unstable_v1">
+
+ <copyright>
+ Copyright © 2017 Red Hat Inc.
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice (including the next
+ paragraph) shall be included in all copies or substantial portions of the
+ Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+ </copyright>
+
+ <description summary="Protocol for grabbing the keyboard from Xwayland">
+ This protocol is application-specific to meet the needs of the X11
+ protocol through Xwayland. It provides a way for Xwayland to request
+ all keyboard events to be forwarded to a surface even when the
+ surface does not have keyboard focus.
+
+ In the X11 protocol, a client may request an "active grab" on the
+ keyboard. On success, all key events are reported only to the
+ grabbing X11 client. For details, see XGrabKeyboard(3).
+
+ The core Wayland protocol does not have a notion of an active
+ keyboard grab. When running in Xwayland, X11 applications may
+ acquire an active grab inside Xwayland but that cannot be translated
+ to the Wayland compositor who may set the input focus to some other
+ surface. In doing so, it breaks the X11 client assumption that all
+ key events are reported to the grabbing client.
+
+ This protocol specifies a way for Xwayland to request all keyboard
+ be directed to the given surface. The protocol does not guarantee
+ that the compositor will honor this request and it does not
+ prescribe user interfaces on how to handle the respond. For example,
+ a compositor may inform the user that all key events are now
+ forwarded to the given client surface, or it may ask the user for
+ permission to do so.
+
+ Compositors are required to restrict access to this application
+ specific protocol to Xwayland alone.
+
+ Warning! The protocol described in this file is experimental and
+ backward incompatible changes may be made. Backward compatible
+ changes may be added together with the corresponding interface
+ version bump.
+ Backward incompatible changes are done by bumping the version
+ number in the protocol and interface names and resetting the
+ interface version. Once the protocol is to be declared stable,
+ the 'z' prefix and the version number in the protocol and
+ interface names are removed and the interface version number is
+ reset.
+ </description>
+
+ <interface name="zwp_xwayland_keyboard_grab_manager_v1" version="1">
+ <description summary="context object for keyboard grab manager">
+ A global interface used for grabbing the keyboard.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the keyboard grab manager">
+ Destroy the keyboard grab manager.
+ </description>
+ </request>
+
+ <request name="grab_keyboard">
+ <description summary="grab the keyboard to a surface">
+ The grab_keyboard request asks for a grab of the keyboard, forcing
+ the keyboard focus for the given seat upon the given surface.
+
+ The protocol provides no guarantee that the grab is ever satisfied,
+ and does not require the compositor to send an error if the grab
+ cannot ever be satisfied. It is thus possible to request a keyboard
+ grab that will never be effective.
+
+ The protocol:
+
+ * does not guarantee that the grab itself is applied for a surface,
+ the grab request may be silently ignored by the compositor,
+ * does not guarantee that any events are sent to this client even
+ if the grab is applied to a surface,
+ * does not guarantee that events sent to this client are exhaustive,
+ a compositor may filter some events for its own consumption,
+ * does not guarantee that events sent to this client are continuous,
+ a compositor may change and reroute keyboard events while the grab
+ is nominally active.
+ </description>
+
+ <arg name="id" type="new_id" interface="zwp_xwayland_keyboard_grab_v1"/>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="surface to report keyboard events to"/>
+ <arg name="seat" type="object" interface="wl_seat"
+ summary="the seat for which the keyboard should be grabbed"/>
+ </request>
+ </interface>
+
+ <interface name="zwp_xwayland_keyboard_grab_v1" version="1">
+ <description summary="interface for grabbing the keyboard">
+ A global interface used for grabbing the keyboard.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the grabbed keyboard object">
+ Destroy the grabbed keyboard object. If applicable, the compositor
+ will ungrab the keyboard.
+ </description>
+ </request>
+ </interface>
+</protocol>
--- /dev/null
+prefix=@prefix@
+datarootdir=@datarootdir@
+pkgdatadir=${pc_sysrootdir}@datadir@/wayland-extension/protocol
+
+Name: Wayland Protocols
+Description: Wayland protocol files
+Version: @WAYLAND_PROTOCOLS_VERSION@
--- /dev/null
+#!/bin/sh -e
+
+if [ "x$SCANNER" = "x" ] ; then
+ echo "No scanner present, test skipped." 1>&2
+ exit 77
+fi
+
+$SCANNER client-header $1 /dev/null
+$SCANNER server-header $1 /dev/null
+$SCANNER code $1 /dev/null
projects / platform / core / uifw / wayland-extension.git / commitdiff