[PATCH] xdg_shell: Add a new shell protocol.
Kristian Høgsberg
krh at bitplanet.net
Fri Jul 5 14:09:38 PDT 2013
Just a quick comment - I've been itching to rename wl_shell_surface so
something more concise, so I'd like to go with xdg_surface instead of
xdg_shell_surface.
Kristian
On Fri, Jul 5, 2013 at 3:39 PM, <antognolli at gmail.com> wrote:
> From: Rafael Antognolli <rafael.antognolli at intel.com>
>
> 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.
> ---
> configure.ac | 1 +
> protocol/Makefile.am | 3 +
> protocol/xdg_shell.xml | 326 ++++++++++++++++++++++++++++++++++++++++++++
> src/Makefile.am | 2 +-
> src/wayland-xdg-shell.pc.in | 10 ++
> 5 files changed, 341 insertions(+), 1 deletion(-)
> create mode 100644 protocol/xdg_shell.xml
> create mode 100644 src/wayland-xdg-shell.pc.in
>
> diff --git a/configure.ac b/configure.ac
> index 7ca70da..0347d77 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -140,6 +140,7 @@ AC_CONFIG_FILES([Makefile
> src/wayland-client-uninstalled.pc
> src/wayland-server.pc
> src/wayland-client.pc
> + src/wayland-xdg-shell.pc
> src/wayland-version.h
> protocol/Makefile
> tests/Makefile])
> diff --git a/protocol/Makefile.am b/protocol/Makefile.am
> index 08690b3..9b70518 100644
> --- a/protocol/Makefile.am
> +++ b/protocol/Makefile.am
> @@ -1 +1,4 @@
> EXTRA_DIST = wayland.xml
> +
> +protocoldir = $(datadir)/wayland/protocol
> +protocol_DATA = xdg_shell.xml
> diff --git a/protocol/xdg_shell.xml b/protocol/xdg_shell.xml
> new file mode 100644
> index 0000000..6d28b28
> --- /dev/null
> +++ b/protocol/xdg_shell.xml
> @@ -0,0 +1,326 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="wayland">
> +
> + <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_shell_surface with
> + a basic surface.
> + </description>
> +
> + <request name="get_shell_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_shell_surface"/>
> + <arg name="surface" type="object" interface="wl_surface"/>
> + </request>
> + </interface>
> +
> + <interface name="xdg_shell_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_shell_surface_destroy() must be called before destroying
> + the wl_surface object.
> + </description>
> +
> + <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>
> diff --git a/src/Makefile.am b/src/Makefile.am
> index 4fa7425..6953fe4 100644
> --- a/src/Makefile.am
> +++ b/src/Makefile.am
> @@ -33,7 +33,7 @@ libwayland_client_la_SOURCES = \
> wayland-client.c
>
> pkgconfigdir = $(libdir)/pkgconfig
> -pkgconfig_DATA = wayland-client.pc wayland-server.pc
> +pkgconfig_DATA = wayland-client.pc wayland-server.pc wayland-xdg-shell.pc
>
> AM_CPPFLAGS = $(FFI_CFLAGS)
> AM_CFLAGS = $(GCC_CFLAGS)
> diff --git a/src/wayland-xdg-shell.pc.in b/src/wayland-xdg-shell.pc.in
> new file mode 100644
> index 0000000..e89a596
> --- /dev/null
> +++ b/src/wayland-xdg-shell.pc.in
> @@ -0,0 +1,10 @@
> +prefix=@prefix@
> +exec_prefix=@exec_prefix@
> +libdir=@libdir@
> +includedir=@includedir@
> +datadir=@datadir@
> +protocol_path=${datadir}/wayland/protocol/
> +
> +Name: Wayland XDG Shell
> +Description: XDG Shell protocol
> +Version: 0.1
> --
> 1.7.11.7
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list