Add section about setting cursor images to spec

spec/main.tex

@@ -125,7 +125,7 @@ created by the client
 \item set cursor
 \end{itemize}
 
-\subsection{Input Group}
+\subsection{Input}
 
 global object
 
@@ -138,6 +138,29 @@ global object
 \item multi pointer wayland
 \end{itemize}
 
+A surface can change the pointer image when the surface is the pointer
+focus of the input device.  Wayland doesn't automatically change the
+pointer image when a pointer enters a surface, but expects the
+application to set the cursor it wants in response the the motion
+event.  The rationale is that a client has to manage changing pointer
+images for UI elements within the surface in response to motion events
+anyway, so we'll make that the only mechanism for setting changing the
+pointer image.  If the server receives a request to set the pointer
+image after the surface loses pointer focus, the request is ignored.
+To the client this will look like it successfully set the pointer
+image.
+
+The compositor will revert the pointer image back to a default image
+when no surface has the pointer focus for that device.  Clients can
+revert the pointer image back to the default image by setting a NULL
+image.
+
+What if the pointer moves from one window which has set a special
+pointer image to a surface that doesn't set an image in response to
+the motion event?  The new surface will be stuck with the special
+pointer image.  We can't just revert the pointer image on leaving a
+surface, since if we immediately enter a surface that sets a different
+image, the image will flicker.  Broken app, I suppose.
 
 \subsection{Output}
 
@@ -182,36 +205,36 @@ Issues:
 
 New objects, requests and events:
 
-  - New toplevel dnd global.  One method, creates a drag object:
+\begin{itemize}
-
+\item New toplevel dnd global.  One method, creates a drag object:
-	dnd.start(new object id, surface, input device, mime types), 
+  \texttt{dnd.start(new object id, surface, input device, mime
-
+    types)}. Starts drag for the device, if it's grabbed by the
-    Starts drag for the device, if it's grabbed by the surface. drag
+  surface. drag ends when button is released.  Caller is responsible
-    ends when button is released.  Caller is responsible for
+  for destroying the drag object.
-    destroying the drag object.
 
-  - Drag object methods:
+\item Drag object methods:
 
-	drag.destroy(id), destroy drag object.
+  \texttt{drag.destroy(id)}, destroy drag object.
 
-	drag.send(id, data), send drag data.
+  \texttt{drag.send(id, data)}, send drag data.
 
-	drag.accept(id, mime type), accept drag offer, called by
+  \texttt{drag.accept(id, mime type)}, accept drag offer, called by
-	target surface.
+  target surface.
 
-  - drag object events:
+\item Drag object events:
 
-	drag.offer(id, mime-types), sent to potential destination
+  \texttt{drag.offer(id, mime-types)}, sent to potential destination
-	surfaces to offer drag data.  If the device leaves the window
+  surfaces to offer drag data.  If the device leaves the window or the
-	or the originator cancels the drag, this event is sent with
+  originator cancels the drag, this event is sent with mime-types =
-	mime-types = NULL.
+  NULL.
 
-	drag.target(id, mime-type), sent to drag originator when a
+  \texttt{drag.target(id, mime-type)}, sent to drag originator when a
-	target surface has accepted the offer. if a previous target
+  target surface has accepted the offer. if a previous target goes
-	goes away, this event is sent with mime-type = NULL.
+  away, this event is sent with mime-type = NULL.
 
-	drag.data(id, data), sent to target, contains dragged data.
+  \texttt{drag.data(id, data)}, sent to target, contains dragged data.
-	ends transaction on the target side.
+  ends transaction on the target side.
+\end{itemize}
 
 Sequence of events:
 
@@ -222,17 +245,18 @@ Sequence of events:
   application to decide whether or not a draggable object within the
   surface was clicked.
 
-\item The initiator creates a drag object by calling the create\_drag
+\item The initiator creates a drag object by calling the
-  method on the dnd global object.  As for any client created object,
+  \texttt{create\_drag} method on the dnd global object.  As for any
-  the client allocates the id.  The create\_drag method also takes the
+  client created object, the client allocates the id.  The
-  originating surface, the device that's dragging and the mime-types
+  \texttt{create\_drag} method also takes the originating surface, the
-  supported.  If the surface has indeed grabbed the device passed in,
+  device that's dragging and the mime-types supported.  If the surface
-  the server will create an active drag object for the device.  If the
+  has indeed grabbed the device passed in, the server will create an
-  grab was released in the meantime, the drag object will be
+  active drag object for the device.  If the grab was released in the
-  in-active, that is, the same state as when the grab is released.  In
+  meantime, the drag object will be in-active, that is, the same state
-  that case, the client will receive a button up event, which will let
+  as when the grab is released.  In that case, the client will receive
-  it know that the drag finished.  To the client it will look like the
+  a button up event, which will let it know that the drag finished.
-  drag was immediately cancelled by the grab ending.
+  To the client it will look like the drag was immediately cancelled
+  by the grab ending.
 
   The special mime-type application/x-root-target indicates that the
   initiator is looking for drag events to the root window as well.
@@ -240,53 +264,56 @@ Sequence of events:
 \item To indicate the object being dragged, the initiator can replace
   the pointer image with an larger image representing the data being
   dragged with the cursor image overlaid.  The pointer image will
-  remain in place as long as the grab is in effect, since no other
+  remain in place as long as the grab is in effect, since the
-  surfaces receive enter/leave events.
+  initiating surface keeps pointer focus, and no other surface
+  receives enter events.
 
 \item As long as the grab is active (or until the initiator cancels
   the drag by destroying the drag object), the drag object will send
-  "offer" events to surfaces it moves across. As for motion events,
+  \texttt{offer} events to surfaces it moves across. As for motion
-  these events contain the surface local coordinates of the device as
+  events, these events contain the surface local coordinates of the
-  well as the list of mime-types offered.  When a device leaves a
+  device as well as the list of mime-types offered.  When a device
-  surface, it will send an offer event with an empty list of
+  leaves a surface, it will send an \texttt{offer} event with an empty
-  mime-types to indicate that the device left the surface.
+  list of mime-types to indicate that the device left the surface.
 
 \item If a surface receives an offer event and decides that it's in an
-  area that can accept a drag event, it should call the accept method
+  area that can accept a drag event, it should call the
-  on the drag object in the event.  The surface passes a mime-type in
+  \texttt{accept} method on the drag object in the event.  The surface
-  the request, picked from the list in the offer event, to indicate
+  passes a mime-type in the request, picked from the list in the offer
-  which of the types it wants.  At this point, the surface can update
+  event, to indicate which of the types it wants.  At this point, the
-  the appearance of the drop target to give feedback to the user that
+  surface can update the appearance of the drop target to give
-  the drag has a valid target.  If the offer event moves to a
+  feedback to the user that the drag has a valid target.  If the
-  different drop target (the surface decides the offer coordinates is
+  \texttt{offer} event moves to a different drop target (the surface
-  outside the drop target) or leaves the surface (the offer event has
+  decides the offer coordinates is outside the drop target) or leaves
-  an empty list of mime-types) it should revert the appearance of the
+  the surface (the offer event has an empty list of mime-types) it
-  drop target to the inactive state.  A surface can also decide to
+  should revert the appearance of the drop target to the inactive
-  retract its drop target (if the drop target disappears or moves, for
+  state.  A surface can also decide to retract its drop target (if the
-  example), by calling the accept method with a NULL mime-type.
+  drop target disappears or moves, for example), by calling the accept
-
+  method with a NULL mime-type.
-\item When a target surface sends an accept request, the drag object
+
-  will send a target event to the initiator surface.  This tells the
+\item When a target surface sends an \texttt{accept} request, the drag
-  initiator that the drag currently has a potential target and which
+  object will send a \texttt{target} event to the initiator surface.
-  of the offered mime-types the target wants.  The initiator can
+  This tells the initiator that the drag currently has a potential
-  change the pointer image or drag source appearance to reflect this
+  target and which of the offered mime-types the target wants.  The
-  new state.  If the target surface retracts its drop target of if the
+  initiator can change the pointer image or drag source appearance to
-  surface disappears, a target event with a NULL mime-type will be
+  reflect this new state.  If the target surface retracts its drop
-  sent.
+  target of if the surface disappears, a \texttt{target} event with a
+  NULL mime-type will be sent.
 
   If the initiator listed application/x-root-target as a valid
   mime-type, dragging into the root window will make the drag object
-  send a target event with the application/x-root-target mime-type.
+  send a \texttt{target} event with the application/x-root-target
+  mime-type.
 
 \item When the grab is released (indicated by the button release
   event), if the drag has an active target, the initiator calls the
-  send method on the drag object to send the data to be transferred by
+  \texttt{send} method on the drag object to send the data to be
-  the drag operation, in the format requested by the target.  The
+  transferred by the drag operation, in the format requested by the
-  initiator can then destroy the drag object by calling the destroy
+  target.  The initiator can then destroy the drag object by calling
-  method.
+  the \texttt{destroy} method.
 
-\item The drop target receives a data event from the drag object with
+\item The drop target receives a \texttt{data} event from the drag
-  the requested data.
+  object with the requested data.
 \end{itemize}
 
 MIME is defined in RFC's 2045-2049. A registry of MIME types is
@@ -380,6 +407,7 @@ what's currently implemented
 
 \subsection{Wayland System Compositor}
 
+\begin{itemize}
 \item implementation of the system compositor
 
 \item uses libudev, eagle (egl), evdev and drm