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