interface/wx/uiaction.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        uiaction.h
   3 // Purpose:     interface of wxUIActionSimulator
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxUIActionSimulator
  11
  12     wxUIActionSimulator is a class used to simulate user interface actions
  13     such as a mouse click or a key press.
  14
  15     @note that this class is currently experimental and disabled by default,
  16     you must set @c wxUSE_UIACTIONSIMULATOR to 1 in your setup.h file or use
  17     configure @c --enable-uiactionsim option to enable it.
  18
  19     Common usages for this class would be to provide playback and record (aka macro recording)
  20     functionality for users, or to drive unit tests by simulating user sessions.
  21
  22     See the uiaction sample for example usage of this class.
  23
  24     NOTE: For keyboard operations, currently you must pass the keycode of the actual
  25     key on the keyboard. To simulate, e.g. IME actions, you'd need to simulate the actual
  26     keypresses needed to active the IME, then the keypresses needed to type and select
  27     the desired character.
  28
  29     @library{wxcore}
  30 */
  31
  32 class wxUIActionSimulator
  33 {
  34   public:
  35     /**
  36         Constructor.
  37     */
  38     wxUIActionSimulator();
  39     ~wxUIActionSimulator();
  40
  41     /**
  42         Move the mouse to the specified coordinates.
  43
  44         @param x
  45             x coordinate to move to, in screen coordinates.
  46
  47         @param y
  48             y coordinate to move to, in screen coordinates.
  49     */
  50     bool        MouseMove(long x, long y);
  51
  52     /**
  53         Press a mouse button.
  54
  55         @param button
  56             Button to press. Valid constants are wxMOUSE_BTN_LEFT, wxMOUSE_BTN_MIDDLE, and wxMOUSE_BTN_RIGHT.
  57     */
  58     bool        MouseDown(int button = wxMOUSE_BTN_LEFT);
  59
  60     /**
  61         Release a mouse button.
  62
  63         @param button
  64             Button to press. See wxUIActionSimulator::MouseDown for a list of valid constants.
  65     */
  66     bool        MouseUp(int button = wxMOUSE_BTN_LEFT);
  67     /**
  68         Click a mouse button.
  69
  70         @param button
  71             Button to press. See wxUIActionSimulator::MouseDown for a list of valid constants.
  72     */
  73     bool        MouseClick(int button = wxMOUSE_BTN_LEFT);
  74     /**
  75         Double-click a mouse button.
  76
  77         @param button
  78             Button to press. See wxUIActionSimulator::MouseDown for a list of valid constants.
  79     */
  80     bool        MouseDblClick(int button = wxMOUSE_BTN_LEFT);
  81
  82     /**
  83         Perform a drag and drop operation.
  84
  85         @param x1
  86             x start coordinate, in screen coordinates.
  87
  88         @param y1
  89             y start coordinate, in screen coordinates.
  90
  91         @param x2
  92             x desintation coordinate, in screen coordinates.
  93
  94         @param y2
  95             y destination coordinate, in screen coordinates.
  96
  97         @param button
  98             Button to press. See wxUIActionSimulator::MouseDown for a list of valid constants.
  99     */
 100     bool        MouseDragDrop(long x1, long y1, long x2, long y2, int button = wxMOUSE_BTN_LEFT);
 101
 102     /**
 103         Press a key.
 104
 105         @param keycode
 106             key to operate on, as an integer.
 107
 108         @param shiftDown
 109             true if the shift key should be pressed, false otherwise.
 110
 111         @param cmdDown
 112             true if the cmd key should be pressed, false otherwise.
 113
 114         @param altDown
 115             true if the alt key should be pressed, false otherwise.
 116     */
 117     bool        KeyDown(int keycode, bool shiftDown=false, bool cmdDown=false, bool altDown=false);
 118
 119     /**
 120         Release a key.
 121
 122         @param keycode
 123             key to operate on, as an integer.
 124
 125         @param shiftDown
 126             true if the shift key should be pressed, false otherwise.
 127
 128         @param cmdDown
 129             true if the cmd key should be pressed, false otherwise.
 130
 131         @param altDown
 132             true if the alt key should be pressed, false otherwise.
 133     */
 134     bool        KeyUp(int keycode, bool shiftDown=false, bool cmdDown=false, bool altDown=false);
 135
 136     /**
 137         Press and release a key.
 138
 139         @param keycode
 140             key to operate on, as an integer.
 141
 142         @param shiftDown
 143             true if the shift key should be pressed, false otherwise.
 144
 145         @param cmdDown
 146             true if the cmd key should be pressed, false otherwise.
 147
 148         @param altDown
 149             true if the alt key should be pressed, false otherwise.
 150     */
 151     bool        Char(int keycode, bool shiftDown=false, bool cmdDown=false, bool altDown=false);
 152 };
 153