src/xaut_mouse.h

   1 /***************************************************************************
   2  *   Copyright (C) 2009 by Chris Parker                                    *
   3  *   chrsprkr3@gmail.com                                                   *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the Python License version 2.5 or later.        *
   7  *                                                                         *
   8  *   This program is distributed in the hope that it will be useful,       *
   9  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  10  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                  *
  11  ***************************************************************************/
  12
  13 /*
  14 $URL$
  15 $Author$
  16 $Date$
  17 $Rev$
  18 */
  19
  20 /**
  21  * Various ways of getting information about and manipulating the mouse.
  22  */
  23
  24 #ifndef XAUT_MOUSE_H_
  25 #define XAUT_MOUSE_H_
  26
  27 #include <X11/extensions/XTest.h>
  28
  29 #include "xaut.h"
  30
  31 /**
  32  * How long to wait between at each pixel movement in milliseconds.
  33  * 0 means move the mouse instantly.
  34  * 10 is the default, and moves the mouse fairly rapidly.
  35  * Anything greater than about 100 will start being annoying.
  36  * Does not make any changes if delay is less than zero.  Regardless,
  37  * this function always returns the current delay.
  38  *
  39  * @param delay the number of milliseconds
  40  * @return the delay which may or may not have changed
  41  */
  42 short mouse_move_delay(short delay);
  43
  44 /**
  45  * How long the mouse button stays down when "clicked" in milliseconds.
  46  * Default is 10 milliseconds, and usually works with most applications.
  47  * Does not make any changes if delay is less than zero.  Regardless,
  48  * this function always returns the current delay.
  49  *
  50  * @param delay the number of milliseconds
  51  * @return the delay which may or may not have changed
  52  */
  53 short mouse_down_delay(short delay);
  54
  55 /**
  56  * The number of milliseconds delay between clicks in a multi-click event.
  57  * Default is 10 milliseconds, and usually works with most applications.
  58  * Does not make any changes if delay is less than zero.  Regardless,
  59  * this function always returns the current delay.
  60  *
  61  * @delay the number of milliseconds
  62  * @return the delay which may or may not have changed
  63  */
  64 short mouse_click_delay(short delay);
  65
  66 /**
  67  * Performs a mouse click.
  68  * In pseudo-code this performs the following:<pre>
  69  * for i = 1 to count
  70  *     mouse_down(btn)
  71  *     sleep_millis(mouse_down_delay)
  72  *     mouse_up(btn)
  73  *     if count > i
  74  *         sleep_millis(mouse_click_delay)
  75  *     endif
  76  * next</pre>
  77  * @param btn the button to click
  78  * @param count the number of clicks
  79  * @return boolean indication of success
  80  */
  81 BOOL mouse_click(unsigned short btn, unsigned short count);
  82
  83 /**
  84  * Presses down and does not release the button pointed to by btn.
  85  * Note that this MUST be followed by a call to mouse_up, otherwise
  86  * the mouse will stay down until a sequence of events causes X11 to
  87  * reset mouse status.
  88  * @param btn the button to press down
  89  * @return boolean indication of success
  90  */
  91 BOOL mouse_down(unsigned short btn);
  92
  93 /**
  94  * Moves the mouse to the coordinates supplied.
  95  * Note that impossible coordinates are "normalized" before use.
  96  * If win is NULL or an invalid handle, the mouse is moved relative to
  97  * the display.  If win resolves to a valid window, then the mouse moves
  98  * relative to the coordinates based on the upper left of the supplied
  99  * window.
 100  *
 101  * @param newX the desired new X coordinate
 102  * @param newY the desired new Y coordinate
 103  * @param win the window the movement is relative to (optional in scripts)
 104  * @return a boolean indication of success
 105  */
 106 BOOL move_mouse(int newX, int newY, Window win);
 107
 108 /**
 109  * Releases a previously pressed mouse button.
 110  * This call MUST follow a call to mouse_down, otherwise
 111  * the mouse will stay down until a sequence of events causes X11 to
 112  * reset mouse status.
 113  * @param btn the button to release
 114  * @return boolean indication of success
 115  */
 116 BOOL mouse_up(unsigned short btn);
 117
 118 /**
 119  * Finds the current x coordinate of the mouse relative to the display.
 120  * Note that if the window is non-zero, the function
 121  * makes the coordinates relative to the window.
 122  * @param win the window the coordinates are relative to
 123  * @return the current x coordinate in pixels
 124  */
 125 int mouse_x(Window win);
 126
 127 /**
 128  * Finds the current y coordinate of the mouse relative to the display.
 129  * Note that if the window is non-zero, the function
 130  * makes the coordinates relative to the window.
 131  * @param win the window the coordinates are relative to
 132  * @return the current y coordinate in pixels
 133  */
 134 int mouse_y(Window win);
 135
 136 /**
 137  * Performs the actual mouse movement.
 138  * Moves the mouse immediately to the coordinates
 139  * supplied.
 140  * @param newX the desired new X coordinate
 141  * @param newY the desired new Y coordinate
 142  * @return a boolean indication of success
 143  */
 144 BOOL _do_movement(int newX, int newY);
 145
 146 /**
 147  * Calculates a gradient movement for the mouse.
 148  * @param targX the x coordinate of where we want the mouse to go
 149  * @param targY the y  coordinate of where we want the mouse to go
 150  * @param xResp what the next x movement should be
 151  * @param yResp what the next y movement should be
 152  */
 153 void _gradientMovement(int targX, int targY, int *xResp, int *yResp);
 154
 155 /**
 156  * Puts both the x and y coordinates into the array supplied.
 157  * MUST be at least a two element array.  Puts the
 158  * values into the first two elements.  Note that if
 159  * the window is non-zero, the function makes the coordinates
 160  * relative to the window.
 161  * @param ret the place to put the values.
 162  * @param win the window the coordinates are relative to
 163  */
 164 void _mouse_xy(int *ret, Window win);
 165
 166 #endif /* XAUT_MOUSE_H_ */