interface/wx/uiaction.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        uiaction.h
   3 // Purpose:     interface of wxUIActionSimulator
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxUIActionSimulator
  10
  11     wxUIActionSimulator is a class used to simulate user interface actions
  12     such as a mouse click or a key press.
  13
  14     Common usage for this class would be to provide playback and record (aka
  15     macro recording) functionality for users, or to drive unit tests by
  16     simulating user sessions.
  17
  18     See the @ref page_samples_uiaction for an example of using this class.
  19
  20     @since 2.9.2
  21
  22     @library{wxcore}
  23 */
  24
  25 class wxUIActionSimulator
  26 {
  27 public:
  28     /**
  29         Default constructor.
  30     */
  31     wxUIActionSimulator();
  32
  33     /**
  34         Move the mouse to the specified coordinates.
  35
  36         @param x
  37             x coordinate to move to, in screen coordinates.
  38
  39         @param y
  40             y coordinate to move to, in screen coordinates.
  41     */
  42     bool MouseMove(long x, long y);
  43
  44     /**
  45         Move the mouse to the specified coordinates.
  46
  47         @param point
  48             Point to move to, in screen coordinates.
  49     */
  50     bool MouseMove(const wxPoint& point);
  51
  52     /**
  53         Press a mouse button.
  54
  55         @param button
  56             Button to press. Valid constants are @c wxMOUSE_BTN_LEFT,
  57             @c wxMOUSE_BTN_MIDDLE, and @c wxMOUSE_BTN_RIGHT.
  58     */
  59     bool MouseDown(int button = wxMOUSE_BTN_LEFT);
  60
  61     /**
  62         Release a mouse button.
  63
  64         @param button
  65             Button to press. See wxUIActionSimulator::MouseDown for a list of
  66             valid constants.
  67     */
  68     bool MouseUp(int button = wxMOUSE_BTN_LEFT);
  69     /**
  70         Click a mouse button.
  71
  72         @param button
  73             Button to press. See wxUIActionSimulator::MouseDown for a list of
  74             valid constants.
  75     */
  76     bool MouseClick(int button = wxMOUSE_BTN_LEFT);
  77     /**
  78         Double-click a mouse button.
  79
  80         @param button
  81             Button to press. See wxUIActionSimulator::MouseDown for a list of
  82             valid constants.
  83     */
  84     bool MouseDblClick(int button = wxMOUSE_BTN_LEFT);
  85
  86     /**
  87         Perform a drag and drop operation.
  88
  89         @param x1
  90             x start coordinate, in screen coordinates.
  91
  92         @param y1
  93             y start coordinate, in screen coordinates.
  94
  95         @param x2
  96             x destination coordinate, in screen coordinates.
  97
  98         @param y2
  99             y destination coordinate, in screen coordinates.
 100
 101         @param button
 102             Button to press. See wxUIActionSimulator::MouseDown for a list of
 103             valid constants.
 104     */
 105     bool MouseDragDrop(long x1, long y1, long x2, long y2,
 106                        int button = wxMOUSE_BTN_LEFT);
 107
 108     /**
 109         Press a key.
 110
 111         If you are using modifiers then it needs to be paired with an identical
 112         KeyUp or the modifiers will not be released (MSW and OSX).
 113
 114         @param keycode
 115             Key to operate on, as an integer. It is interpreted as a wxKeyCode.
 116
 117         @param modifiers
 118             A combination of ::wxKeyModifier flags to be pressed with the given
 119             keycode.
 120     */
 121     bool KeyDown(int keycode, int modifiers = wxMOD_NONE);
 122
 123     /**
 124         Release a key.
 125
 126         @param keycode
 127             Key to operate on, as an integer. It is interpreted as a wxKeyCode.
 128
 129         @param modifiers
 130             A combination of ::wxKeyModifier flags to be pressed with the given
 131             keycode.
 132     */
 133     bool KeyUp(int keycode, int modifiers = wxMOD_NONE);
 134
 135     /**
 136         Press and release a key.
 137
 138         @param keycode
 139             Key to operate on, as an integer. It is interpreted as a wxKeyCode.
 140
 141         @param modifiers
 142             A combination of ::wxKeyModifier flags to be pressed with the given
 143             keycode.
 144     */
 145     bool Char(int keycode, int modifiers = wxMOD_NONE);
 146
 147     /**
 148         Emulate typing in the keys representing the given string.
 149
 150         Currently only the ASCII letters, digits and characters for the definition
 151         of numbers (i.e. characters @c a-z @c A-Z @c 0-9 @c + @c - @c . @c , @c 'space')
 152         are supported.
 153
 154         @param text
 155             The string to type.
 156     */
 157     bool Text(const wxString& text);
 158 };
 159