[wxWidgets.git] / interface / wx / uiaction.h

/////////////////////////////////////////////////////////////////////////////
// Name:        uiaction.h
// Purpose:     interface of wxUIActionSimulator
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxUIActionSimulator

    wxUIActionSimulator is a class used to simulate user interface actions
    such as a mouse click or a key press. 
    
    Common usages for this class would be to provide playback and record (aka macro recording)
    functionality for users, or to drive unit tests by simulating user sessions.
    
    See the uiaction sample for example usage of this class.
    
    NOTE: For keyboard operations, currently you must pass the keycode of the actual
    key on the keyboard. To simulate, e.g. IME actions, you'd need to simulate the actual
    keypresses needed to active the IME, then the keypresses needed to type and select
    the desired character.
    
    @library{wxcore}
*/

class wxUIActionSimulator
{
  public:
    /**
        Constructor.
    */
    wxUIActionSimulator();
    ~wxUIActionSimulator();
    
    /**
        Move the mouse to the specified coordinates.
        
        @param x
            x coordinate to move to, in screen coordinates.
            
        @param y
            y coordinate to move to, in screen coordinates.
    */
    bool        MouseMove(long x, long y);
    
    /**
        Press a mouse button.
        
        @param button
            Button to press. Valid constants are wxMOUSE_BTN_LEFT, wxMOUSE_BTN_MIDDLE, and wxMOUSE_BTN_RIGHT.
    */
    bool        MouseDown(int button = wxMOUSE_BTN_LEFT);
    
    /**
        Release a mouse button.
        
        @param button
            Button to press. See wxUIActionSimulator::MouseDown for a list of valid constants.
    */
    bool        MouseUp(int button = wxMOUSE_BTN_LEFT);
    /**
        Click a mouse button.
        
        @param button
            Button to press. See wxUIActionSimulator::MouseDown for a list of valid constants.
    */
    bool        MouseClick(int button = wxMOUSE_BTN_LEFT);
    /**
        Double-click a mouse button.
        
        @param button
            Button to press. See wxUIActionSimulator::MouseDown for a list of valid constants.
    */
    bool        MouseDblClick(int button = wxMOUSE_BTN_LEFT);

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