From: Rafael Antognolli <[email protected]> xdg_shell is a protocol aimed to substitute wl_shell in the long term, but will not be part of the wayland core protocol. It starts as a non-stable API, aimed to be used as a development place at first, and once features are defined as required by several desktop shells, we can finally make it stable. --- protocol/Makefile.am | 2 +- protocol/xdg-surface.xml | 336 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 337 insertions(+), 1 deletion(-) create mode 100644 protocol/xdg-surface.xml
diff --git a/protocol/Makefile.am b/protocol/Makefile.am index cc9cd1c..5f26d77 100644 --- a/protocol/Makefile.am +++ b/protocol/Makefile.am @@ -1 +1 @@ -dist_pkgdata_DATA = wayland.xml +dist_pkgdata_DATA = wayland.xml xdg-surface.xml diff --git a/protocol/xdg-surface.xml b/protocol/xdg-surface.xml new file mode 100644 index 0000000..4d2cc1b --- /dev/null +++ b/protocol/xdg-surface.xml @@ -0,0 +1,336 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="xdg_surface"> + + <copyright> + Copyright © 2008-2013 Kristian Høgsberg + Copyright © 2013 Rafael Antognolli + Copyright © 2010-2013 Intel Corporation + + 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="xdg_shell" version="1"> + <description summary="create desktop-style surfaces"> + This interface is implemented by servers that provide + desktop-style user interfaces. + + It allows clients to associate a xdg_surface with + a basic surface. + </description> + + <request name="get_xdg_surface"> + <description summary="create a shell surface from a surface"> + Create a shell surface for an existing surface. + + Only one shell surface can be associated with a given surface. + </description> + <arg name="id" type="new_id" interface="xdg_surface"/> + <arg name="surface" type="object" interface="wl_surface"/> + </request> + </interface> + + <interface name="xdg_surface" version="1"> + + <description summary="desktop-style metadata interface"> + 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 toplevel, fullscreen + or popup windows, move, resize or maximize them, associate + metadata like title and class, etc. + + On the server side the object is automatically destroyed when + the related wl_surface is destroyed. On client side, + xdg_surface_destroy() must be called before destroying + the wl_surface object. + </description> + + <request name="destroy" type="destructor"> + <description summary="remove xdg_surface interface"> + The xdg_surface interface is removed from the wl_surface object + that was turned into a xdg_surface with + xdg_shell.get_xdg_surface request. The xdg_surface properties, + like maximized and fullscreen, are lost. The wl_surface loses + its role as a xdg_surface. The wl_surface is unmapped. + </description> + </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. + </description> + <arg name="serial" type="uint" summary="serial of the ping event"/> + </request> + + <request name="move"> + <description summary="start an interactive move"> + Start a pointer-driven move of the surface. + + This request must be used in response to a button press event. + The server may ignore move requests depending on the state of + the surface (e.g. fullscreen or maximized). + </description> + <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/> + <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/> + </request> + + <enum name="resize"> + <description summary="edge values for resizing"> + These values are used to indicate which edge of a surface + is being dragged in a resize operation. The server may + use this information to adapt its behavior, e.g. choose + an appropriate cursor image. + </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 pointer-driven resizing of the surface. + + This request must be used in response to a button press event. + The server may ignore resize requests depending on the state of + the surface (e.g. fullscreen or maximized). + </description> + <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/> + <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/> + <arg name="edges" type="uint" summary="which edge or corner is being dragged"/> + </request> + + <request name="set_toplevel"> + <description summary="make the surface a toplevel surface"> + Map the surface as a toplevel surface. + + A toplevel surface is not fullscreen, maximized or transient. + </description> + </request> + + <enum name="transient"> + <description summary="details of transient behaviour"> + These flags specify details of the expected behaviour + of transient surfaces. Used in the set_transient request. + </description> + <entry name="inactive" value="0x1" summary="do not set keyboard focus"/> + </enum> + + <request name="set_transient"> + <description summary="make the surface a transient surface"> + Map the surface relative to an existing surface. + + The x and y arguments specify the locations of the upper left + corner of the surface relative to the upper left corner of the + parent surface, in surface local coordinates. + + The flags argument controls details of the transient behaviour. + </description> + + <arg name="parent" type="object" interface="wl_surface"/> + <arg name="x" type="int"/> + <arg name="y" type="int"/> + <arg name="flags" type="uint"/> + </request> + + <enum name="fullscreen_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="scale" value="1" summary="scale, preserve the surface's aspect ratio and center on output"/> + <entry name="driver" value="2" summary="switch output mode to the smallest mode that can fit the surface, add black borders to compensate size mismatch"/> + <entry name="fill" value="3" summary="no upscaling, center on output and add black borders to compensate size mismatch"/> + </enum> + + <request name="set_fullscreen"> + <description summary="make the surface a fullscreen surface"> + Map the surface as a fullscreen surface. + + If an output parameter is given then the surface will be made + fullscreen on that output. If the client does not specify the + output then the compositor will apply its policy - usually + choosing the output on which the surface has the biggest surface + area. + + The client may specify a method to resolve a size conflict + between the output size and the surface size - this is provided + through the method parameter. + + The framerate parameter is used only when the method is set + to "driver", to indicate the preferred framerate. A value of 0 + indicates that the app does not care about framerate. The + framerate is specified in mHz, that is framerate of 60000 is 60Hz. + + A method of "scale" or "driver" implies a scaling operation of + the surface, either via a direct scaling operation or a change of + the output mode. This will override any kind of output scaling, so + that mapping a surface with a buffer size equal to the mode can + fill the screen independent of buffer_scale. + + A method of "fill" means we don't scale up the buffer, however + any output scale is applied. This means that you may run into + an edge case where the application maps a buffer with the same + size of the output mode but buffer_scale 1 (thus making a + surface larger than the output). In this case it is allowed to + downscale the results to fit the screen. + + The compositor must reply to this request with a configure event + with the dimensions for the output on which the surface will + be made fullscreen. + </description> + <arg name="method" type="uint"/> + <arg name="framerate" type="uint"/> + <arg name="output" type="object" interface="wl_output" allow-null="true"/> + </request> + + <request name="set_popup"> + <description summary="make the surface a popup surface"> + Map the surface as a popup. + + A popup surface is a transient surface with an added pointer + grab. + + An existing implicit grab will be changed to owner-events mode, + and the popup grab will continue after the implicit grab ends + (i.e. releasing the mouse button does not cause the popup to + be unmapped). + + The popup grab continues until the window is destroyed or a + mouse button is pressed in any other clients window. A click + in any of the clients surfaces is reported as normal, however, + clicks in other clients surfaces will be discarded and trigger + the callback. + + The x and y arguments specify the locations of the upper left + corner of the surface relative to the upper left corner of the + parent surface, in surface local coordinates. + </description> + + <arg name="seat" type="object" interface="wl_seat" summary="the wl_seat whose pointer is used"/> + <arg name="serial" type="uint" summary="serial of the implicit grab on the pointer"/> + <arg name="parent" type="object" interface="wl_surface"/> + <arg name="x" type="int"/> + <arg name="y" type="int"/> + <arg name="flags" type="uint"/> + </request> + + <request name="set_maximized"> + <description summary="make the surface a maximized surface"> + Map the surface as a maximized surface. + + If an output parameter is given then the surface will be + maximized on that output. If the client does not specify the + output then the compositor will apply its policy - usually + choosing the output on which the surface has the biggest surface + area. + + The compositor will reply with a configure event telling + the expected new surface size. The operation is completed + on the next buffer attach to this surface. + + A maximized surface typically fills the entire output it is + bound to, except for desktop element such as panels. This is + the main difference between a maximized shell surface and a + fullscreen shell surface. + + The details depend on the compositor implementation. + </description> + <arg name="output" type="object" interface="wl_output" 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_class"> + <description summary="set surface class"> + Set a class for the surface. + + The surface class identifies the general class of applications + to which the surface belongs. A common convention is to use + the file name (full path if non-standard location) of the + applications .desktop file as the class. + </description> + <arg name="class_" type="string"/> + </request> + + <event name="ping"> + <description summary="ping client"> + Ping a client to check if it is receiving events and sending + requests. A client is expected to reply with a pong request. + </description> + <arg name="serial" type="uint"/> + </event> + + <event name="configure"> + <description summary="suggest resize"> + The configure event asks the client to resize its surface. + + The size is a hint, in the sense that the client is free to + ignore it if it doesn't resize, pick a smaller size (to + satisfy aspect ratio or resize in steps of NxM pixels). + + The edges parameter provides a hint about how the surface + was resized. The client may use this information to decide + how to adjust its content to the new size (e.g. a scrolling + area might adjust its content position to leave the viewable + content unmoved). + + The client is free to dismiss all but the last configure + event it received. + + The width and height arguments specify the size of the window + in surface local coordinates. + </description> + + <arg name="edges" type="uint"/> + <arg name="width" type="int"/> + <arg name="height" type="int"/> + </event> + + <event name="popup_done"> + <description summary="popup interaction is done"> + The popup_done event is sent out when a popup grab is broken, + that is, when the users clicks a surface that doesn't belong + to the client owning the popup surface. + </description> + </event> + </interface> +</protocol> -- 1.8.3.1 _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
