Signed-off-by: Drew DeVault <[email protected]> --- This revision addresses much of Yong's feedback. It changes some of the language to more closely match other protocols, fixes a few typos, and clarifies some descriptions. I disagree with the use of a bitfield for anchors in xdg-shell et al, but I chose to reuse that design per Yong's suggestion, for the sake of consistency. I chose not to add many descriptions as Yong suggested, where I felt that the nature of the fields were self-evident.
Cheers! unstable/surface-layers/README | 4 + unstable/surface-layers/surface-layers.xml | 151 +++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+) create mode 100644 unstable/surface-layers/README create mode 100644 unstable/surface-layers/surface-layers.xml diff --git a/unstable/surface-layers/README b/unstable/surface-layers/README new file mode 100644 index 0000000..662f488 --- /dev/null +++ b/unstable/surface-layers/README @@ -0,0 +1,4 @@ +Surface layers protocol + +Maintainers: +Drew DeVault <[email protected]> diff --git a/unstable/surface-layers/surface-layers.xml b/unstable/surface-layers/surface-layers.xml new file mode 100644 index 0000000..fe621ef --- /dev/null +++ b/unstable/surface-layers/surface-layers.xml @@ -0,0 +1,151 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="surface_layers"> + + <copyright> + Copyright © 2017 Drew DeVault + + 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. + + 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. + </copyright> + + <interface name="surface_layers" version="1"> + <description summary="create surfaces that are layers of the desktop"> + Clients can use this interface to assign the surface_layer role to + wl_surfaces. Such surfaces are assigned to a "layer" of the output and + rendered with a defined z-depth respective to each other. They may also be + anchored to the edges and corners of a screen and specify input handling + semantics. This interface should be suitable for the implementation of + many desktop shell components, and a broad number of other applications + that interact with the desktop. + </description> + + <enum name="surface_layer"> + <description summary="available layers for surfaces"> + These values indicate which layers a surface can be rendered in. They + are ordered by z depth, bottom-most first. Traditional shell surfaces + will typically be rendered between the bottom and top layers. Multiple + surfaces can share a single layer. + </description> + + <entry name="background" value="0"/> + <entry name="bottom" value="1"/> + <entry name="top" value="2"/> + <entry name="overlay" value="3"/> + </enum> + + <request name="get_layer_surface"> + <descripton summary="create a layer_surface from a surface"> + Create a layer surface for an existing surface. This assigns the role of + layer_surface, or raises a protocol error if another role is already + assigned. + </description> + <arg name="id" type="new_id" interface="layer_surface"/> + <arg name="surface" type="object" interface="wl_surface"/> + <arg name="output" type="object" interface="wl_output"/> + <arg name="layer" type="uint" summary="surface_layer to add this surface to"/> + </request> + </interface> + + <interface name="layer_surface" version="1"> + <description summary="layer metadata interface"> + An interface that may be implemented by a wl_surface, for surfaces that + are designed to be rendered as a layer of a stacked desktop-like + environment. + </description> + + <enum name="input_devices"> + <descripton summary="types of input devices"> + These flags are a bitfield and are used by set_interactive to specify + what sorts of input the surface should interact with. + </description> + <arg name="none" value="0x0" /> + <arg name="pointer" value="0x1" /> + <arg name="keyboard" value="0x2" /> + <arg name="touch" value="0x4" /> + </enum> + + <request name="set_interactivity"> + <description summary="indicates that this surface is interactive"> + This request indicates to the compositor what kind of interactivity this + surface requires. This may be changed at runtime. Note that whether or + not the compositor chooses to send the surface input events at any given + time is implementation-dependent. Any events from input devices you do not + ask for will be passed along to other clients, also in an + implementation-dependent way. + + By convention, conventional compositors will send input events to + surfaces below the shell surface layer when there are no shell surfaces + or when the surface is clicked (and thus receives focus). Above the + shell surface layer, the topmost surface receives all input of the types + it requests. + </description> + <arg name="types" type="uint" summary="mask of input devices to use"/> + </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="configures the anchor point of the surface"> + Requests that the compositor anchor the surface to the specified edges + and corners. If two orthoginal edges are specified (e.g. 'top' and + 'left'), then the anchor point will be the intersection of the edges + (e.g. the top left corner of the output); otherwise the anchor point + will be centered on that edge, or in the center if none is specified. + </description> + <arg name="anchor" type="uint"/> + </request> + + <request name="set_exclusive_zone"> + <description summary="configures the exclusive geometry of this surface"> + Requests that the compositor avoids occluding an area of the surface + with other surfaces. The compositor's use of this information is + implementation-dependent - do not assume that this region will not + actually be occluded. + + This value is only meaningful if the surface is anchored to an edge, + rather than a corner. The zone is the number of pixels from the edge + that are considered exclusive. + </description> + <arg name="zone" type="uint"/> + </request> + + <request name="set_margin"> + <description summary="sets a margin from the anchor point"> + Requests that the surface be placed some distance away from the anchor + point on the output, in pixels. + </description> + <arg name="horizontal" type="uint"/> + <arg name="vertical" type="uint"/> + </request> + </interface> + +</protocol> -- 2.11.0 _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
