org.freedesktop.wayland.client.WlSubsurfaceEvents Maven / Gradle / Ivy
Show all versions of wayland Show documentation
package org.freedesktop.wayland.client;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
//
//
// Copyright © 2008-2011 Kristian Høgsberg
// Copyright © 2010-2011 Intel Corporation
// Copyright © 2012-2013 Collabora, Ltd.
//
// 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.
//
/**
* sub-surface interface to a wl_surface
*
*
* An additional interface to a wl_surface object, which has been
* made a sub-surface. A sub-surface has one parent surface. A
* sub-surface's size and position are not limited to that of the parent.
* Particularly, a sub-surface is not automatically clipped to its
* parent's area.
*
* A sub-surface becomes mapped, when a non-NULL wl_buffer is applied
* and the parent surface is mapped. The order of which one happens
* first is irrelevant. A sub-surface is hidden if the parent becomes
* hidden, or if a NULL wl_buffer is applied. These rules apply
* recursively through the tree of surfaces.
*
* The behaviour of wl_surface.commit request on a sub-surface
* depends on the sub-surface's mode. The possible modes are
* synchronized and desynchronized, see methods
* wl_subsurface.set_sync and wl_subsurface.set_desync. Synchronized
* mode caches the wl_surface state to be applied when the parent's
* state gets applied, and desynchronized mode applies the pending
* wl_surface state directly. A sub-surface is initially in the
* synchronized mode.
*
* Sub-surfaces have also other kind of state, which is managed by
* wl_subsurface requests, as opposed to wl_surface requests. This
* state includes the sub-surface position relative to the parent
* surface (wl_subsurface.set_position), and the stacking order of
* the parent and its sub-surfaces (wl_subsurface.place_above and
* .place_below). This state is applied when the parent surface's
* wl_surface state is applied, regardless of the sub-surface's mode.
* As the exception, set_sync and set_desync are effective immediately.
*
* The main surface can be thought to be always in desynchronized mode,
* since it does not have a parent in the sub-surfaces sense.
*
* Even if a sub-surface is in desynchronized mode, it will behave as
* in synchronized mode, if its parent surface behaves as in
* synchronized mode. This rule is applied recursively throughout the
* tree of surfaces. This means, that one can set a sub-surface into
* synchronized mode, and then assume that all its child and grand-child
* sub-surfaces are synchronized, too, without explicitly setting them.
*
* If the wl_surface associated with the wl_subsurface is destroyed, the
* wl_subsurface object becomes inert. Note, that destroying either object
* takes effect immediately. If you need to synchronize the removal
* of a sub-surface to the parent surface update, unmap the sub-surface
* first by attaching a NULL wl_buffer, update parent, and then destroy
* the sub-surface.
*
* If the parent wl_surface object is destroyed, the sub-surface is
* unmapped.
*
*/
public interface WlSubsurfaceEvents {
int VERSION = 1;
}