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 | 381 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 382 insertions(+), 1 deletion(-) create mode 100644 protocol/xdg-surface.xml
diff --git a/protocol/Makefile.am b/protocol/Makefile.am index e8b6290..9d27a2d 100644 --- a/protocol/Makefile.am +++ b/protocol/Makefile.am @@ -1,4 +1,4 @@ -dist_pkgdata_DATA = wayland.xml wayland.dtd +dist_pkgdata_DATA = wayland.xml wayland.dtd xdg-surface.xml if HAVE_XMLLINT .PHONY: validate diff --git a/protocol/xdg-surface.xml b/protocol/xdg-surface.xml new file mode 100644 index 0000000..8e29751 --- /dev/null +++ b/protocol/xdg-surface.xml @@ -0,0 +1,381 @@ +<?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"/> + <art name="cursor_surface" type="object" interface="wl_surface" summary="the cursor surface used during the movement"/> + </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"/> + <art name="cursor_surface" type="object" interface="wl_surface" summary="the cursor surface used during the resizing"/> + </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 transient or popup. It supports + surface states though, like maximized, minimized and fullscreen. + </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="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_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_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> + + <enum name="state"> + <description summary="surface states"> + Basic window states that can be set/unset by the client, and/or + requested by the compositor. + </description> + <entry name="maximized" value="0" summary="surface is maximized"/> + <entry name="fullscreen" value="1" summary="surface is fullscreen"/> + <entry name="minimized" value="2" summary="surface is minimized"/> + <entry name="always_above" value="3" summary="surface is always on top"/> + <entry name="always_below" value="4" summary="surface is always below"/> + <entry name="sticky" value="5" summary="surface is visible on all desktops"/> + </enum> + + <request name="state_set"> + <description summary="set the surface state"> + Set the surface state. + </description> + <arg name="state" type="uint"/> + </request> + + <request name="state_unset"> + <description summary="set the surface state"> + Unset the surface state. + </description> + <arg name="state" type="uint"/> + </request> + + <request name="set_fullscreen_method"> + <description summary="set the fullscreen method used by this surface"> + The fullscreen method set here will be used when the surface state is + set to fullscreen. + + This call has no effect on non-fullscreen surfaces, but the method set + here will be used later if the surface ever becomes fullscreen. If the + surface is already in a fullscreen state, it will start using this + method, instead of the current one. + + Default is (?). + </description> + <arg name="method" type="uint"/> + </request> + + <request name="set_fullscreen_framerate"> + <description summary="set the fullscreen framerate used by this surface"> + See set_fullscreen_method above. + </description> + <arg name="framerate" type="uint"/> + </request> + + <request name="set_output"> + <description summary="set the default output used by this surface"> + Set the default output used by this surface when it is first mapped. + + If this value is NULL (default), it's up to the compositor to choose + which display will be used to map this surface. + + When fullscreen state is set on this surface, the output set with this + method will be used. Otherwise, the output where the surface is + currently mapped will be used. + + Same for maximized state. + </description> + <arg name="output" type="object" interface="wl_output" allow-null="true"/> + </request> + + <request name="demands_attention"> + <description summary="surface demanding attention"> + The demands_attention request indicates that activity has + occurred in the surface that is important to the client. It + informs the compositor that the user should be informed about + this surface alert. + </description> + </request> + + <request name="take_focus"> + <description summary="take keyboard focus"> + The surface request keyboard focus to itself. The compositor + will likely give keyboard focus to that surface. + </description> + </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> + + <event name="activated"> + <description summary="surface was activated"> + The activated event is sent when this surface has been + activated, by clicking or touching or alt-tabbing (or hovering + in case of sloppy focus). + + The surface has received keyboard focus. + </description> + </event> + + <event name="deactivated"> + <description summary="surface was activated"> + The activate event is sent when this surface has been deactivated, + because another surface has been activated. + + When this event is received, the surface no longer has keyboard + focus. If necessary, the surface can request keyboard focus + again by calling xdg_surface.take_focus. + </description> + </event> + + <event name="state_update"> + <description summary="surface should be maximized"> + </description> + <arg name="state" type="uint"/> + <arg name="enabled" type="uint"/> + </event> + </interface> +</protocol> -- 1.8.3.1 _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
