[PATCH 02/20] mi: Add a few comments explaining various cursor move functions.
Peter Hutterer
peter.hutterer at who-t.net
Thu Feb 17 19:52:09 PST 2011
Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
mi/mipointer.c | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++------
1 files changed, 138 insertions(+), 15 deletions(-)
diff --git a/mi/mipointer.c b/mi/mipointer.c
index 5ee456c..a3c26d03 100644
--- a/mi/mipointer.c
+++ b/mi/mipointer.c
@@ -23,6 +23,29 @@ used in advertising or otherwise to promote the sale, use or other dealings
in this Software without prior written authorization from The Open Group.
*/
+/**
+ * @file
+ * This file contains functions to move the pointer on the screen and/or
+ * restrict its movement. These functions are divided into two sets:
+ * Screen-specific functions that are used as function pointers from other
+ * parts of the server (and end up heavily wrapped by e.g. animcur and
+ * xfixes):
+ * miPointerConstrainCursor
+ * miPointerCursorLimits
+ * miPointerDisplayCursor
+ * miPointerRealizeCursor
+ * miPointerUnrealizeCursor
+ * miPointerSetCursorPosition
+ * miRecolorCursor
+ * miPointerDeviceInitialize
+ * miPointerDeviceCleanup
+ * If wrapped, these are the last element in the wrapping chain. They may
+ * call into sprite-specific code through further function pointers though.
+ *
+ * The second type of functions are those that are directly called by the
+ * DIX, DDX and some drivers.
+ */
+
#ifdef HAVE_DIX_CONFIG_H
#include <dix-config.h>
#endif
@@ -126,6 +149,12 @@ miPointerInitialize (ScreenPtr pScreen,
return TRUE;
}
+/**
+ * Destroy screen-specific information.
+ *
+ * @param index Screen index of the screen in screenInfo.screens[]
+ * @param pScreen The actual screen pointer
+ */
static Bool
miPointerCloseScreen (int index, ScreenPtr pScreen)
{
@@ -201,6 +230,15 @@ miPointerDisplayCursor (DeviceIntPtr pDev, ScreenPtr pScreen, CursorPtr pCursor)
return TRUE;
}
+/**
+ * Set up the constraints for the given device. This function does not
+ * actually constrain the cursor but merely copies the given box to the
+ * internal constraint storage.
+ *
+ * @param pDev The device to constrain to the box
+ * @param pBox The rectangle to constrain the cursor to
+ * @param pScreen Used for copying screen confinement
+ */
static void
miPointerConstrainCursor (DeviceIntPtr pDev, ScreenPtr pScreen, BoxPtr pBox)
{
@@ -212,7 +250,17 @@ miPointerConstrainCursor (DeviceIntPtr pDev, ScreenPtr pScreen, BoxPtr pBox)
pPointer->confined = PointerConfinedToScreen(pDev);
}
-/*ARGSUSED*/
+/**
+ * Should calculate the box for the given cursor, based on screen and the
+ * confinement given. But we assume that whatever box is passed in is valid
+ * anyway.
+ *
+ * @param pDev The device to calculate the cursor limits for
+ * @param pScreen The screen the confinement happens on
+ * @param pCursor The screen the confinement happens on
+ * @param pHotBox The confinement box for the cursor
+ * @param[out] pTopLeftBox The new confinement box, always *pHotBox.
+ */
static void
miPointerCursorLimits(DeviceIntPtr pDev, ScreenPtr pScreen, CursorPtr pCursor,
BoxPtr pHotBox, BoxPtr pTopLeftBox)
@@ -220,6 +268,27 @@ miPointerCursorLimits(DeviceIntPtr pDev, ScreenPtr pScreen, CursorPtr pCursor,
*pTopLeftBox = *pHotBox;
}
+/**
+ * Set the device's cursor position to the x/y position on the given screen.
+ * Generates and event if required.
+ *
+ * This function is called from:
+ * - sprite init code to place onto initial position
+ * - the various WarpPointer implementations (core, XI, Xinerama, dmx,…)
+ * - during the cursor update path in CheckMotion
+ * - in the Xinerama part of NewCurrentScreen
+ * - when a RandR/RandR1.2 mode was applied (it may have moved the pointer, so
+ * it's set back to the original pos)
+ *
+ * @param pDev The device to move
+ * @param pScreen The screen the device is on
+ * @param x The x coordinate in per-screen coordinates
+ * @param y The y coordinate in per-screen coordinates
+ * @param generateEvent True if the pointer movement should generate an
+ * event.
+ *
+ * @return TRUE in all cases
+ */
static Bool
miPointerSetCursorPosition(DeviceIntPtr pDev, ScreenPtr pScreen,
int x, int y, Bool generateEvent)
@@ -236,9 +305,13 @@ miPointerSetCursorPosition(DeviceIntPtr pDev, ScreenPtr pScreen,
return TRUE;
}
-/* Set up sprite information for the device.
- This function will be called once for each device after it is initialized
- in the DIX.
+/**
+ * Set up sprite information for the device.
+ * This function will be called once for each device after it is initialized
+ * in the DIX.
+ *
+ * @param pDev The newly created device
+ * @param pScreen The initial sprite scree.
*/
static Bool
miPointerDeviceInitialize(DeviceIntPtr pDev, ScreenPtr pScreen)
@@ -273,8 +346,12 @@ miPointerDeviceInitialize(DeviceIntPtr pDev, ScreenPtr pScreen)
return TRUE;
}
-/* Clean up after device.
- This function will be called once before the device is freed in the DIX
+/**
+ * Clean up after device.
+ * This function will be called once before the device is freed in the DIX
+ *
+ * @param pDev The device to be removed from the server
+ * @param pScreen Current screen of the device
*/
static void
miPointerDeviceCleanup(DeviceIntPtr pDev, ScreenPtr pScreen)
@@ -290,7 +367,17 @@ miPointerDeviceCleanup(DeviceIntPtr pDev, ScreenPtr pScreen)
}
-/* Once signals are ignored, the WarpCursor function can call this */
+/**
+ * Warp the pointer to the given position on the given screen. May generate
+ * an event, depending on whether we're coming from miPointerSetPosition.
+ *
+ * Once signals are ignored, the WarpCursor function can call this
+ *
+ * @param pDev The device to warp
+ * @param pScreen Screen to warp on
+ * @param x The x coordinate in per-screen coordinates
+ * @param y The y coordinate in per-screen coordinates
+ */
void
miPointerWarpCursor (DeviceIntPtr pDev, ScreenPtr pScreen, int x, int y)
@@ -323,16 +410,11 @@ miPointerWarpCursor (DeviceIntPtr pDev, ScreenPtr pScreen, int x, int y)
UpdateSpriteForScreen (pDev, pScreen) ;
}
-/*
- * Pointer/CursorDisplay interface routines
- */
-
-/*
- * miPointerUpdateSprite
+/**
+ * Syncronize the sprite with the cursor.
*
- * Syncronize the sprite with the cursor - called from ProcessInputEvents
+ * @param pDev The device to sync
*/
-
void
miPointerUpdateSprite (DeviceIntPtr pDev)
{
@@ -409,6 +491,14 @@ miPointerUpdateSprite (DeviceIntPtr pDev)
}
}
+/**
+ * Set the device to the coordinates on the given screen.
+ *
+ * @param pDev The device to move
+ * @param screen_no Index of the screen to move to
+ * @param x The x coordinate in per-screen coordinates
+ * @param y The y coordinate in per-screen coordinates
+ */
void
miPointerSetScreen(DeviceIntPtr pDev, int screen_no, int x, int y)
{
@@ -427,12 +517,18 @@ miPointerSetScreen(DeviceIntPtr pDev, int screen_no, int x, int y)
pPointer->limits.y2 = pScreen->height;
}
+/**
+ * @return The current screen of the VCP
+ */
ScreenPtr
miPointerCurrentScreen (void)
{
return miPointerGetScreen(inputInfo.pointer);
}
+/**
+ * @return The current screen of the given device or NULL.
+ */
ScreenPtr
miPointerGetScreen(DeviceIntPtr pDev)
{
@@ -484,6 +580,18 @@ miPointerMoveNoEvent (DeviceIntPtr pDev, ScreenPtr pScreen,
pPointer->pScreen = pScreen;
}
+/**
+ * Set the devices' cursor position to the given x/y position.
+ *
+ * This function is called during the pointer update path in
+ * GetPointerEvents and friends (and the same in the xwin DDX).
+ *
+ * @param pDev The device to move
+ * @param[in,out] x The x coordiante in screen coordinates (in regards to total
+ * desktop size)
+ * @param[in,out] y The y coordiante in screen coordinates (in regards to total
+ * desktop size)
+ */
void
miPointerSetPosition(DeviceIntPtr pDev, int *x, int *y)
{
@@ -537,6 +645,12 @@ miPointerSetPosition(DeviceIntPtr pDev, int *x, int *y)
miPointerMoveNoEvent(pDev, pScreen, *x, *y);
}
+/**
+ * Get the current position of the device in desktop coordinates.
+ *
+ * @param x Return value for the current x coordinate in desktop coordiates.
+ * @param y Return value for the current y coordinate in desktop coordiates.
+ */
void
miPointerGetPosition(DeviceIntPtr pDev, int *x, int *y)
{
@@ -550,6 +664,15 @@ void darwinEvents_lock(void);
void darwinEvents_unlock(void);
#endif
+/**
+ * Move the device's pointer to the x/y coordinates on the given screen.
+ * This function generates and enqueues pointer events.
+ *
+ * @param pDev The device to move
+ * @param pScreen The screen the device is on
+ * @param x The x coordinate in per-screen coordinates
+ * @param y The y coordinate in per-screen coordinates
+ */
void
miPointerMove (DeviceIntPtr pDev, ScreenPtr pScreen, int x, int y)
{
--
1.7.4
More information about the xorg-devel
mailing list