Fix up comments for event.c

dix/events.c

@@ -237,22 +237,24 @@ static int DontPropagateRefCnts[DNPMCOUNT];
  *     inputInfo.pointer 
  *     is the core pointer. Referred to as "virtual core pointer", "VCP",
  *     "core pointer" or inputInfo.pointer. There is exactly one core pointer,
- *     but multiple devices may send core events. If a device generates core
+ *     but multiple devices may send core events. The VCP is only used if no
- *     events, those events will appear to originate from the core pointer.
+ *     physical device is connected and does not have a visible cursor. 
+ *     Before the integration of MPX, any core request would operate on the
+ *     VCP/VCK. Core events would always come from one of those two. Now both
+ *     are only fallback devices if no physical devices are available.
  * 
  *     inputInfo.keyboard
  *     is the core keyboard ("virtual core keyboard", "VCK", "core keyboard").
  *     See inputInfo.pointer.
  * 
  *     inputInfo.devices
- *     linked list containing all devices including VCK and VCP. The VCK will
+ *     linked list containing all devices BUT NOT INCLUDING VCK and VCP. 
- *     always be the first entry, the VCP the second entry in the device list.
  *
  *     inputInfo.off_devices
  *     Devices that have not been initialized and are thus turned off.
  *
  *     inputInfo.numDevices
- *     Total number of devices.
+ *     Total number of devices (not counting VCP and VCK).
  */
 _X_EXPORT InputInfo inputInfo;
 
@@ -1387,11 +1389,12 @@ CheckGrabForSyncs(DeviceIntPtr thisDev, Bool thisMode, Bool otherMode)
 
 /**
  * Activate a pointer grab on the given device. A pointer grab will cause all
- * core pointer events to be delivered to the grabbing client only. Can cause
+ * core pointer events of this device to be delivered to the grabbing client only. 
- * the cursor to change if a grab cursor is set.
+ * No other device will send core events to the grab client while the grab is
+ * on, but core events will be sent to other clients.
+ * Can cause the cursor to change if a grab cursor is set.
  * 
- * As a pointer grab can only be issued on the core devices, mouse is always
+ * Extension devices are set up for ActivateKeyboardGrab().
- * inputInfo.pointer. Extension devices are set up for ActivateKeyboardGrab().
  * 
  * @param mouse The device to grab.
  * @param grab The grab structure, needs to be setup.
@@ -1433,8 +1436,7 @@ ActivatePointerGrab(DeviceIntPtr mouse, GrabPtr grab,
 /**
  * Delete grab on given device, update the sprite.
  *
- * As a pointer grab can only be issued on the core devices, mouse is always
+ * Extension devices are set up for ActivateKeyboardGrab().
- * inputInfo.pointer. Extension devices are set up for ActivateKeyboardGrab().
  */
 void
 DeactivatePointerGrab(DeviceIntPtr mouse)
@@ -1651,7 +1653,7 @@ AllowSome(ClientPtr client,
 /**
  * Server-side protocol handling for AllowEvents request.
  *
- * Release some events from a frozen device. Only applicable for core devices.
+ * Release some events from a frozen device. 
  */
 int
 ProcAllowEvents(ClientPtr client)
@@ -2135,9 +2137,6 @@ FixUpEventFromWindow(
  * Deliver events caused by input devices. Called for all core input events
  * and XI events. No filtering of events happens before DeliverDeviceEvents(),
  * it will be called for any event that comes out of the event queue.
- * 
- * For all core events, dev is either inputInfo.pointer or inputInfo.keyboard.
- * For all extension events, dev is the device that caused the event.
  *
  * @param pWin Window to deliver event to.
  * @param xE Events to deliver.
@@ -2535,8 +2534,8 @@ void ReinitializeRootWindow(WindowPtr win, int xoff, int yoff)
 #endif
 
 /**
- * Set the given window to sane values, display the cursor in the center of
+ * Called from main() with the root window on the first screen. Used to do a
- * the screen. Called from main() with the root window on the first screen.
+ * lot more when MPX wasn't around yet. Things change.
  */
 void
 DefineInitialRootWindow(WindowPtr win)
@@ -2547,6 +2546,21 @@ DefineInitialRootWindow(WindowPtr win)
 
 }
 
+/**
+ * Initialize a sprite for the given device and set it to some sane values. If
+ * the device already has a sprite alloc'd, don't realloc but just reset to
+ * default values.
+ * If a window is supplied, the sprite will be initialized with the window's
+ * cursor and positioned in the center of the window's screen. The root window
+ * is a good choice to pass in here.
+ *
+ * It's a good idea to call it only for pointer devices, unless you have a
+ * really talented keyboard.
+ *
+ * @param pDev The device to initialize.
+ * @param pWin The window where to generate the sprite in.
+ * 
+ */
 void 
 InitializeSprite(DeviceIntPtr pDev, WindowPtr pWin)
 {
@@ -3824,7 +3838,7 @@ CommonAncestor(
 
 /**
  * Assembles an EnterNotify or LeaveNotify and sends it event to the client. 
- * The core devices are used to fill in the event fields.
+ * Uses the paired keyboard to get some additional information.
  */
 static void
 EnterLeaveEvent(
@@ -4453,7 +4467,7 @@ ProcSetInputFocus(client)
 /**
  * Server-side protocol handling for GetInputFocus request.
  * 
- * Sends the current input focus for the virtual core keyboard back to the
+ * Sends the current input focus for the client's keyboard back to the
  * client.
  */
 int
@@ -4481,8 +4495,8 @@ ProcGetInputFocus(ClientPtr client)
 /**
  * Server-side protocol handling for Grabpointer request.
  *
- * Sets an active grab on the inputInfo.pointer and returns success status to
+ * Sets an active grab on the client's ClientPointer and returns success
- * client.
+ * status to client.
  */
 int
 ProcGrabPointer(ClientPtr client)
@@ -4601,7 +4615,7 @@ ProcGrabPointer(ClientPtr client)
  * Changes properties of the grab hold by the client. If the client does not
  * hold an active grab on the device, nothing happens. 
  *
- * Works on the core pointer only.
+ * Works on the client's ClientPointer.
  */
 int
 ProcChangeActivePointerGrab(ClientPtr client)
@@ -4652,7 +4666,7 @@ ProcChangeActivePointerGrab(ClientPtr client)
 /**
  * Server-side protocol handling for UngrabPointer request.
  *
- * Deletes the pointer grab on the core pointer device.
+ * Deletes the pointer grab on the client's ClientPointer device.
  */
 int
 ProcUngrabPointer(ClientPtr client)
@@ -4676,7 +4690,7 @@ ProcUngrabPointer(ClientPtr client)
 /**
  * Sets a grab on the given device.
  * 
- * Called from ProcGrabKeyboard to work on the inputInfo.keyboard.
+ * Called from ProcGrabKeyboard to work on the client's keyboard.
  * Called from ProcXGrabDevice to work on the device specified by the client.
  * 
  * The parameters this_mode and other_mode represent the keyboard_mode and
@@ -4761,7 +4775,7 @@ GrabDevice(ClientPtr client, DeviceIntPtr dev,
 /**
  * Server-side protocol handling for GrabKeyboard request.
  *
- * Grabs the inputInfo.keyboad and returns success status to client.
+ * Grabs the client's keyboard and returns success status to client.
  */
 int
 ProcGrabKeyboard(ClientPtr client)
@@ -4795,7 +4809,7 @@ ProcGrabKeyboard(ClientPtr client)
 /**
  * Server-side protocol handling for UngrabKeyboard request.
  *
- * Deletes a possible grab on the inputInfo.keyboard.
+ * Deletes a possible grab on the client's keyboard.
  */
 int
 ProcUngrabKeyboard(ClientPtr client)
@@ -4819,7 +4833,8 @@ ProcUngrabKeyboard(ClientPtr client)
 /**
  * Server-side protocol handling for QueryPointer request.
  *
- * Returns the current state and position of the core pointer to the client. 
+ * Returns the current state and position of the client's ClientPointer to the
+ * client. 
  */
 int
 ProcQueryPointer(ClientPtr client)
@@ -5029,8 +5044,8 @@ ProcSendEvent(ClientPtr client)
 /**
  * Server-side protocol handling for UngrabKey request.
  *
- * Deletes a passive grab for the given key. Only works on the
+ * Deletes a passive grab for the given key. Works on the
- * inputInfo.keyboard.
+ * client's keyboard.
  */
 int
 ProcUngrabKey(ClientPtr client)
@@ -5077,8 +5092,8 @@ ProcUngrabKey(ClientPtr client)
 /**
  * Server-side protocol handling for GrabKey request.
  *
- * Creates a grab for the inputInfo.keyboard and adds it to the list of
+ * Creates a grab for the client's keyboard and adds it to the list of passive
- * passive grabs. 
+ * grabs. 
  */
 int
 ProcGrabKey(ClientPtr client)
@@ -5138,8 +5153,8 @@ ProcGrabKey(ClientPtr client)
 /**
  * Server-side protocol handling for GrabButton request.
  *
- * Creates a grab for the inputInfo.pointer and adds it as a passive grab to
+ * Creates a grab for the client's ClientPointer and adds it as a passive grab
- * the list.
+ * to the list.
  */
 int
 ProcGrabButton(ClientPtr client)
@@ -5217,7 +5232,7 @@ ProcGrabButton(ClientPtr client)
 /**
  * Server-side protocol handling for UngrabButton request.
  *
- * Deletes a passive grab on the inputInfo.pointer from the list.
+ * Deletes a passive grab on the client's ClientPointer from the list.
  */
 int
 ProcUngrabButton(ClientPtr client)
@@ -5597,6 +5612,12 @@ WriteEventsToClient(ClientPtr pClient, int count, xEvent *events)
 /*
  * Set the client pointer for the given client. Second parameter setter could
  * be used in the future to determine access rights. Unused for now.
+ *
+ * A client can have exactly one ClientPointer. Each time a
+ * request/reply/event is processed and the choice of devices is ambiguous
+ * (e.g. QueryPointer request), the server will pick the ClientPointer (see
+ * PickPointer()). 
+ * If a keyboard is needed, the first keyboard paired with the CP is used.
  */
 _X_EXPORT Bool
 SetClientPointer(ClientPtr client, ClientPtr setter, DeviceIntPtr device)