Window stacking

[Bill Spitzak]

Rather than rant about it, here is my edit of the wl_shell protocol xml:

<?xml version="1.0" encoding="UTF-8"?>

   <interface name="wl_shell" version="?">

     <enum name="window_part">
       <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"/>
       <entry name="title" value="11"/>
       <entry name="contents" value="12"/>
     </enum>

     <!-- Client informs the compositor that it did not do anything
          with the event, and therefore the compositor should handle
          it. For mouse clicks this may produce a drag or resize or
          raise of windows. (replaces the start_move_resize event).
     -->
     <request name="button">
       <arg name="time" type="uint"/>
       <arg name="input_device" type="object" interface="wl_input_device"/>
       <arg name="button" type="uint"/>
       <arg name="state" type="uint"/>
       <arg name="where" type="uint"/> <!-- where the pointer was -->
     </request>

     <!-- Client informs the compositor that it did not do anything
          with the event, and therefore the compositor should handle
          it. Should trigger window management shortcuts, etc.
     -->
     <request name="key">
       <arg name="time" type="uint"/>
       <arg name="input_device" type="object" interface="wl_input_device"/>
       <arg name="key" type="uint"/>
       <arg name="state" type="uint"/>
       <arg name="where" type="uint"/> <!-- where the pointer was -->
     </request>

     <!-- "raise" means "only change the window if it goes up".
          "lower" means "only change the window if it goes down."
     -->
     <enum name="reorder_operation">
       <entry name="raise_above" value="0"/>
       <entry name="raise_below" value="1"/>
       <entry name="lower_above" value="2"/>
       <entry name="lower_below" value="3"/>
     </enum>

     <!-- Change the stacking order of this window. Compositor MUST
          leave the client's windows in the order that these specify,
          and MUST NOT move windows in the opposite direction of the
          raise/lower spec. Sibling can be None to indicate "as high or
          low as possible", or can be a surface given in a
          restack_notify, or otherwise communicated by ipc from
          another process.

          To avoid blinking the client is expected to raise the
          top-most window first and put the others below it when
          raising a group. If the client is changing the buffer size it
          should send this immediately after for a raise, and
          immediately before for a lower.
     -->
     <request name="reorder">
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="operation" type="uint"/>
       <arg name="sibling" type="object" interface="wl_surface"/>
     </request>

     <!-- Compositor tells the client it wants a reorder done.
          Client should do something similar to the given surface,
          but may also choose to reorder, map, resize, redraw and
          otherwise change this and other surfaces.

          The sibling window might be some other window the compositor
          owns. These are used as barriers between layers.
     -->
     <event name="restack_notify">
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="operation" type="uint"/>
       <arg name="sibling" type="object" interface="wl_surface"/>
     </request>

     <!-- Client tells compostior it wants a restack_notify echoed
          back. Compositor may alter it. click-to-top may work
          better by sending the button event to the compositor.
     -->
     <event name="restack">
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="operation" type="uint"/>
       <arg name="sibling" type="object" interface="wl_surface"/>
     </request>

     <enum name="decoration_bits">
       <entry name="top" value="1"/>
       <entry name="bottom" value="2"/>
       <entry name="left" value="4"/>
       <entry name="right" value="8"/>
       <entry name="title" value="16"/>
     </enum>

     <!-- Compositor tells the client that it wants the surface
          resized/moved. It expects the client to respond with
          a wl_surface attach, though the client may just damage
          the buffer if it decides it does not have to move or
          resize the window.

          "where" is generally the part being dragged by the user.
          If the client wants a different than requested size, it
          is a hint for which corner/edge the compositor would
          prefer it moves.

          The decorations bitfield tells the client what decorations
          are to be drawn. This is intended to remove borders that are
          off the edge of the screen when the window is maximized or
          snapped to the edges or tiled against other windows. It can
          also remove the title bar for full-screen, and for
          experiments with compositor-side decorations. If an edge
          disappears the client should resize the surface so that the
          "contents" obey the "where" for resizing.
       -->
     <event name="configure_notify">
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="x" type="int"/>
       <arg name="y" type="int"/>
       <arg name="width" type="int"/>
       <arg name="height" type="int"/>
       <arg name="where" type="uint"/>
       <arg name="decorations" type="uint"/>
     </event>

     <!-- Client asks the compositor to respond with a similar
          configure event. Compositor may alter it to it's own
          restrictions. Full-screen is done by the client resizing
          to one of the outputs and turning off all the decorations,
          Windows-style maximize by turning off all except the title.
     -->
     <request name="configure">
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="x" type="int"/>
       <arg name="y" type="int"/>
       <arg name="width" type="int"/>
       <arg name="height" type="int"/>
       <arg name="where" type="uint"/>
       <arg name="decorations" type="uint"/>
     </request>

     <!-- Request from the compositor that the client attach a buffer
          to the surface, thus making it visible. The client may also
          decide to create/map other surfaces and resize and reorder
          them. The desktop should be remembered by the client and
          sent with any future map requests (unless it has a good
          reason to change it)
       -->
     <event name="map_notify">
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="desktop" type="uint"/>
     </event>

     <!-- Client asks compositor to echo back a map_notify. The
          desktop is a hint for any kind of paging window management.
       -->
     <request name="map">
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="desktop" type="uint"/>
     </request>

     <!-- Request from the compositor that the client detach the buffer
          making the surface invisible. Client may also
          destroy/unmap/resize this or other surfaces.
       -->
     <event name="unmap_notify">
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
     </event>

     <!-- Client asks compositor to echo back a map_notify. The
          compositor may resize a lot of windows including this one
          to make them all fit, before sending map_notify.
       -->
     <request name="unmap">
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
     </request>

     <!-- Compositor is attempting to close the window. If client does
          not respond to ping events the compositor may kill it, rather
          than just fall back to inactive-client behavior.
       -->
     <event name="close">
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
     </event>

     <!-- Name used by task manager and pager type api's, and by
          compositor-side decorations. This is assumed to be a UTF-8
          string, but compositors MUST display one glyph for each
          invalid byte rather than truncating or refusing to display
          invalid UTF-8. String is divided into several fields by NUL
          bytes (is this possible?) and the first one is a
          user-friendly readable title. Other fields may be interpreted
          using rules that have not been determined yet (can choose
          icons, etc).
       -->
     <request name="set_name">
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="value" type="string"/>
     </request>

     <!-- Request by client that compositor move input focus to this
          surface. Compositor MUST NOT raise or otherwise reorder the
          window (the client will send restack if it wants that).
          Compositors must either set the focus or send a dummy
          event saying the window lost the focus (this is so the
          client can pre-draw the focused state to speed things up).

          A client wanting point-to-type can do this in response to
          a pointer_focus event.

          A click-to-type client should only do this in the few cases
          where it wants to handle a mouse click and also wants it to
          move the focus, such as a click that moves a text insertion
          cursor. For clicks in "dead" areas that don't do anything
          else, the client shoudl use the button request.
       -->
     <request name="activate">
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="input_device" type="object" interface="wl_input_device"/>
       <arg name="time" type="uint"/>
     </request>

   </interface>