-
Notifications
You must be signed in to change notification settings - Fork 7
/
libcvautomation.h.in
505 lines (489 loc) · 31.4 KB
/
libcvautomation.h.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
/*
* =====================================================================================
*
* Filename: libcvautomation.h
*
* Description: Include wrapper for libcvautomation subsections
*
* Created: 06/21/2012 12:20:43 PM
* Revision: none
* Compiler: gcc
*
* Author: Bradlee Speice (), bspeice.nc@gmail.com
* Organization:
*
* =====================================================================================
*/
#ifndef LIBCVAUTOMATION_H
#define LIBCVAUTOMATION_H
#define LIBCVAUTOMATION_VERSION "@PACKAGE_VERSION@"
#define LIBCVAUTOMATION_BUGREPORT "@PACKAGE_BUGREPORT@"
/* C includes */
#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <limits.h>
/* Autoconf logic to select the correct OpenCV version */
@cv_headers@
/* X11 includes */
#include <X11/Xlib.h>
#include <X11/Xutil.h>
#include <X11/extensions/XTest.h>
/* Define another basic structure for points */
typedef struct {
int x, y;
} cvaPoint;
/* Define a basic structure to help us with using multiple-picture arguments
* Yes, it's a hackish implementation, nobody said you had to use this one. */
typedef struct {
/* Use one or the other of fileName or cvaImage - cvaImage takes priority */
IplImage *cvaImage;
char *fileName;
cvaPoint resultPoint;
int searchMethod;
int tolerance;
} cvautomationList;
/* Project component includes */
/* The includes come here to make sure all function prototypes have access
* to the cvautomationList struct */
#include <libcvautomation/libcvautomation-opencv.h>
#include <libcvautomation/libcvautomation-xlib.h>
#include <libcvautomation/libcvautomation-xtest.h>
#endif /* LIBCVAUTOMATION_H */
/* Doxygen information */
/** \file libcvautomation.h
* \brief The top-level include for all projects involving libcvautomation
* \details This source file includes all other files needed for libcvautomation projects, and also defines the cvautomationList and cvaPoint structs to be used among libcvautomation functions.
* \author Bradlee Speice
*/
/** \mainpage Libcvautomation
* \author Bradlee Speice <<a href="mailto:bspeice@uncc.edu">bspeice@uncc.edu</a>>
* \section intro Introduction
* Welcome to Libcvautomation!
* Libcvautomation is a GUI automation and testing tool based on image recognition and response. This program was designed as a direct replacement for <a href="http://sikuli.org">Sikuli</a> and <a href="https://wiki.ubuntu.com/Xpresser">Xpresser</a>. I was having incredible difficulty getting either of these solutions to work - Sikuli would crash whenever I tried to take a screenshot, and Xpresser was both too new for our Prominent North American Enterprise Linux systems, but also didn't work or \c import correctly. I really liked the way each of these programs approached GUI automation, but they simply didn't work. Additionally, I wanted to create a simple solution - it does what you want it to, and that's it.
* \section how_it_works How Libcvautomation Works
* Libcvautomation represents two software products coming together - <a href="http://opencv.willowgarage.com/wiki/">OpenCV</a> and the <a href="http://www.x.org/docs/Xext/xtest.pdf">XTest extension</a> to the X11 server. OpenCV is used for image recognition, and XTest is used to actually drive the X server. You can dig into \ref libcvautomation-xtest.h to get an idea of what all this library is capable of. <br>
* Basically what happens is that for whenever you need to do image recognition, OpenCV is used to find the images, and XTest is used to generate any events needed. Libcvautomation is mostly a wrapper to integrate both of these products, but also adds some functions like matchSubImage_X11() that allow you to match an image against the X11 root window in place. This means no more <tt>'xwd | convert "<out_name>"'</tt>.
* \section main_installing Installing Libcvautomation
* Installing Libcvautomation is easy. You can either manually install packages, add the Libcvautomation repository, or install from tarball (the first option is recommended).
* \subsection main_rpm Install Libcvautomation RPM Repository
* If you want to make sure that you're using the latest (stable) version of Libcvautomation, you can add the Libcvautomation repository to yum.
* First, a new configuration file for the Libcvautomation repository:
* \code sudo vim /etc/yum.repos.d/libcvautomation.repo \endcode
* After you have the file open, put the following content in it:
* \code [libcvautomation]
* name=Libcvautomation RPM repository
* baseurl=http://djbushido.github.com/libcvautomation/rpm
* enabled=1
* gpgcheck=0 \endcode
* And once this is done, clean out the cache, and you should be good to go!
* \code sudo yum clean all \endcode
* Finally, if you want to begin developing application tests, you will need the following packages: \c libcvautomation, and \c libcvautomation-examples.
* \subsection main_apt Install Libcvautomation APT Repository
* If you want to make sure that you're using the latest (stable) version of Libcvautomation, you can add the Libcvautomation repository to APT.
* First, open up your \c sources.list
* \code sudo vim /etc/apt/sources.list \endcode
* Add the following content at the end:
* \code #Libcvautomation Repository
* deb http://djbushido.github.com/libcvautomation/apt libcvautomation/
* deb-src http://djbushido.github.com/libcvautomation/apt libcvautomation-source/ \endcode
* Run an update to make sure your packages refresh, and then you should be good to go!
* \code sudo apt-get update \endcode
* Finally, if you want to begin developing application tests, you will need the following packages: \c libcvautomation-dev, and \c libcvautomation-examples.
* \subsection main_download Manual Download Packages
* If you want to manually download the packages, see the Github downloads page for libcvautomation: <a href="https://github.com/DjBushido/libcvautomation/downloads">https://github.com/DjBushido/libcvautomation/downloads</a>
* \subsection main_tarball Manual Tarball Installation
* If you want to install Libcvautomation via tarball, you can do that too. Download a release tarball from the Downloads page on Github: <a href="https://github.com/DjBushido/libcvautomation/downloads">https://github.com/DjBushido/libcvautomation/downloads</a>
* The source itself uses autotools, so it's incredibly easy to work with:
* \code cd <location_of_tarball>
* tar xf <tarball_file>
* cd libcvautomation-<release_number>
* ./configure
* make
* sudo make install \endcode
*
* \section main_using Using Libcvautomation And Writing Application Tests
* So how does one go about using libcvautomation? <br>
* I'm so glad you asked! I've provided a few reference programs - \c cva-match and \c cva-input - that can be used to demonstrate most of libcvautomation's capabilities. I've even provided a BASH wrapper to make it incredibly easy to use BASH with libcvautomation as well (requires that \c cva-match and \c cva-input are installed). Python bindings are even included too! <br>
* Bash wrapper documentation: \ref wrapper_functions <br>
* Python wrapper documentation: \ref libcvautomation_funcs.py <br>
* Finally, if you want to know how to write your own application tests, please see \ref writing_app_tests for more information on that. I've provided code to give you a basic idea of how they work.
* \section questions Questions? Comments? Concerns?
* Please send any feedback to <<a href="mailto:bspeice@uncc.edu">bspeice@uncc.edu</a>>. Pull requests can be submitted to <a href="https://github.com/DjBushido/libcvautomation">my github repository</a>.*/
/** \page libcvautomation
* \author Bradlee Speice <<a href="mailto:bspeice@uncc.edu">bspeice@uncc.edu</a>>
* \section intro Introduction
* Welcome to Libcvautomation!
* Libcvautomation is a GUI automation and testing tool based on image recognition and response. This program was designed as a direct replacement for <a href="http://sikuli.org">Sikuli</a> and <a href="https://wiki.ubuntu.com/Xpresser">Xpresser</a>. I was having incredible difficulty getting either of these solutions to work - Sikuli would crash whenever I tried to take a screenshot, and Xpresser was both too new for our Prominent North American Enterprise Linux systems, but also didn't work or \c import correctly. I really liked the way each of these programs approached GUI automation, but they simply didn't work. Additionally, I wanted to create a simple solution - it does what you want it to, and that's it.
* \section how_it_works How Libcvautomation Works
* Libcvautomation represents two software products coming together - <a href="http://opencv.willowgarage.com/wiki/">OpenCV</a> and the <a href="http://www.x.org/docs/Xext/xtest.pdf">XTest extension</a> to the X11 server. OpenCV is used for image recognition, and XTest is used to actually drive the X server. You can dig into \ref libcvautomation-xtest.h to get an idea of what all this library is capable of. <br>
* Basically what happens is that for whenever you need to do image recognition, OpenCV is used to find the images, and XTest is used to generate any events needed. Libcvautomation is mostly a wrapper to integrate both of these products, but also adds some functions like matchSubImage_X11() that allow you to match an image against the X11 root window in place. This means no more <tt>'xwd | convert "<out_name>"'</tt>.
* \section main_using Using Libcvautomation And Writing Application Tests
* So how does one go about using libcvautomation? <br>
* I'm so glad you asked! I've provided a few reference programs - \c cva-match and \c cva-input - that can be used to demonstrate most of libcvautomation's capabilities. I've even provided a BASH wrapper to make it incredibly easy to use BASH with libcvautomation as well (requires that cva-match and cva-input are installed). Python bindings are even included too! <br>
* Finally, if you want to know how to write your own application tests, please see \ref writing_app_tests for more information on that. I've provided code to give you a basic idea of how they work.
* \section questions Questions? Comments? Concerns?
* Please send any feedback to <<a href="mailto:bspeice@uncc.edu">bspeice@uncc.edu</a>>. Pull requests can be submitted to <a href="https://github.com/DjBushido/libcvautomation">my github repository</a>.*/
/** \page writing_app_tests Writing Application Tests
* \author Bradlee Speice <<a href="mailto:bspeice@uncc.edu">bspeice@uncc.edu</a>>
* \date 7/30/2012
* \section audience Audience
* <ul>
* <li>This document was written for people with some intermediate knowledge of BASH.
* <li>Screenshot experience is required - being able to create screenshots of windows using <a href="http://www.gimp.org/">GIMP</a>, the \c import command from <a href="http://www.imagemagick.org/script/index.php">ImageMagick</a>, or something similar. <br>
* <li>Required for working with libcvautomation internals (not needed strictly for writing application testing):
* <ul>
* <li>Intermediate-level C knowledge required for interfacing with libcvautomation. There isn't much complicated going on with libcvautomation itself, but you need to know to use cvaOpenDisplay() for grabbing a display and then cvaCloseDisplay() for closing it later for example.
* <li>C++ is available, but currently only as <tt>extern "C"</tt> style bindings.
* <li>Python bindings are in progress as of time-of-writing
* </ul>
* </ul>
*
* \section purpose Purpose
* <ul>
* <li>This document is intended to outline the libcvautomation testing library for GUI applications and its two reference programs \c cva-match and \c cva-input
* <li>These programs allow you to automate mouse and keyboard events in response to what appears on screen - for example, clicking a button based on an image of that button on screen.
* </ul>
*
* \section using Using Libcvautomation
* <ul>
* <li>Since libcvautomation is a shared-object library intended to bundle a lot of functionality in one area, we must use external programs to agin access to the functions of libcvautomation.
* <li>Two reference programs have been included to make this easy - \c cva-match and \c cva-input
* <li>The reference programs are fairly full-featured, and expose most of libcvautomation:
* <ul>
* <li>\c cva-match allows you to match multiple image files against a root image providing very fine control over how specific the match is
* <li>\c cva-input allows you to drive the X11 server using the XTest extension - for example, clicking on a button from image, clicking a key on the keyboard, and more.
* </ul>
* <li>These two programs should implement all functionality needed for GUI automation. Please contact <a href="mailto:bspeice@uncc.edu">bspeice@uncc.edu</a> if you have suggestions for extra functionality, patches, comments, etc.
* <li>Finally, if you want to write your own programs using libcvautomation, the headers are located on your system. Use:
* \code #include <libcvautomation/libcvautomation.h> \endcode
* to include all necessary header files. See the "Files" tab above to get an idea of what functionality exists.
* \note Intermediate C or C++ knowledge is required for programming with libcvautomation. C++ is currently only supported through <tt>extern "C"</tt>, and full C++ bindings are not currently planned. Libcvautomation itself is incredibly simple, but interfaces with a few API's (Xlib, libcv) that it is helpful to have an idea of how to use.
*
* \section testing Application Testing
* Now we get into the good stuff. The basic process for application testing is as follows:
* <ul>
* <li>Create a sequence of screenshots for all mouse-clicks
* <li>Create a testing wrapper in BASH for automating the application
* <li>Test the wrapper and tune any necessary options
* </ul>
* \subsection screenshot_sequence Creating the Screenshot Sequence
* <ul>
* <li>This process creates a set of screenshots by which libcvautomation can drive the X11 server
* <li>The process is simple - create a screenshot of all buttons you would like to click in an application test, or location where you would like to move the mouse, etc.
* <li>This can be accomplished a number of different ways - using GIMP, the \c import command, or any other screenshot program. Additionally, libcvautomation will support any image format that OpenCV does. At the time of writing, these are:
* <ul>
* <li>Windows bitmaps - <tt>*.bmp</tt>, <tt>*.dib</tt>
* <li>JPEG files - <tt>*.jpeg</tt>, <tt>*.jpg</tt>, <tt>*.jpe</tt>
* <li>JPEG 2000 files - <tt>*.jp2</tt>
* <li>Portable Network Graphics - <tt>*.png</tt>
* <li>Portable image format - <tt>*.pbm</tt>, <tt>*.pgm</tt>, <tt>*.ppm</tt>
* <li>Sun rasters - <tt>*.sr</tt>, <tt>*.ras</tt>
* <li>TIFF files - <tt>*.tiff</tt>, <tt>*.tif</tt>
* </ul>
* <br>
* <li>Some tips on creating screenshots:
* <ul>
* <li>Use as distinct an image as possible in a screenshot. For example, the following images look very similar, but can do very different things:
* \image html print-printbutton1.png
* <br>
* \image html print-helpbutton.png
* <ul>
* <li>The large amount of grey-space in each of the images can be very confusing. While the text itself is different, the overwhelming amount of grey space can result in a false positive. Limiting the space of the screenshot can be useful:
* \image html print-printbutton2.png
* <br>
* \image html print-helpbutton.png
* <li>Limiting the button size in this case helps the program identify what button you want to click, but in general you want to include as much detail as possible.
* </ul>
* <br>
* <li>Be careful of where an image may appear multiple times in a screenshot. For example, a "Help" button on a dialog may get confused with the "Help" menu at the top of the screen.
* </ul>
*
* \subsection testing_wrapper Create a Testing Wrapper
* <ul>
* <li>This is where the BASH knowledge comes into play. We are going to write a script that will run your application test, to make sure that the GUI is functioning correctly.
* <li>The following is the (strongly) recommended process, but is not strictly necessary to follow this. The way I'm going to explain this is by giving an example test I wrote, and explain what is going on:
* \code
* #!/bin/bash
* #This is an application test involving libcvautomation and libreoffice
* . /etc/libcvautomation_funcs
* set -o errexit
*
* #Changing any wrapper parameters should go here
* TIMEOUT=30
*
*
* start_libreoffice_writer ()
* {
* mouse_click_image "screens/gnome-menu.png" "screens/kde-menu.png"
* mouse_click_image "screens/gnome-officeMenu.png" "screens/kde-officeMenu.png"
* mouse_hover_image "screens/gnome-LibreOfficeWriter.png" "screens/kde-LibreOfficeWriter.png"
* mouse_jiggle
* mouse_click
* }
*
* close_libreoffice_writer()
* {
* mouse_click_image "screens/gnome-fileMenu.png" "screens/kde-fileMenu.png"
* mouse_click_image "screens/gnome-fileExit.png" "screens/kde-fileExit.png"
* mouse_click_image "screens/gnome-discard.png" "screens/kde-discard.png"
* }
*
* start_libreoffice_writer
* close_libreoffice_writer
* \endcode
* <br>
* \code
* #!/bin/bash
* #This is an application test involving libcvautomation and libreoffice
* . /etc/libcvautomation_funcs
* set -o errexit
*
* #Changing any wrapper parameters should go here
* TIMEOUT=30
* \endcode
* <li>The purpose of these lines is just the standard BASH header. Additionally, we import a wrapper created for libcvautomation to make our job easier. Please note that this is the default directory for the wrapper, your installation may be different. Use the command <tt>locate libcvautomation_funcs</tt> to find it on your computer. The wrapper itself is a handful of macros used to make our job easy.
* <li>The \c set line will abort the test if an error is ever encountered - for example, no images are found.
* <li>Changing any wrapper parameters should go after sourcing the wrapper functions. See \ref appendix_variables for more information. We set the TIMEOUT to 30 seconds here, so that the wrapper will wait 30 seconds (max) for an image to appear before giving up. This way if LibreOffice takes 30 seconds to load, we will wait 30 seconds. If it takes only 5 seconds to load, we will click after those 5 seconds.
* <br><br>
* \code
* start_libreoffice_writer ()
* {
* mouse_click_image "screens/gnome-menu.png" "screens/kde-menu.png"
* mouse_click_image "screens/gnome-officeMenu.png" "screens/kde-officeMenu.png"
* mouse_hover_image "screens/gnome-LibreOfficeWriter.png" "screens/kde-LibreOfficeWriter.png"
* mouse_jiggle
* mouse_click
* }
* \endcode
* <li>This is the actual body of work done by libcvautomation
* <li>\c click_i is a function to click the mouse at an image - in this case, the gnome or kde menu.
* <ul>
* <li>Because of how the cva-input program is designed, you can give it multiple images, and it will only select the one currently available. See the \ref wrapper_functions for more information on how to use this (\c TOLERANCE specifically)
* <li>Additionally, the wrapper (by default) will wait for an image to appear before clicking on it. This way, you can string together click_i commands even when the program may need to wait a while on processing. Make sure to read up on the \c TIMEOUT option to learn how to use this.
* <li>By using the function \c click_i, we make things a bit more readable - the full command line is <tt>cva-input -s 'icmouseclick <filename>'</tt>
* <li>See the \ref wrapper_functions for a list of all functions available in the wrapper.
* </ul>
* <li>\c hover_i is a function to move the mouse to an image - in this case, move it over the LibreOffice menu item.
* <li>Then we jiggle the mouse to make sure that the item activates, click, and wait for the program to start up.
* <br><br>
* \code
* close_libreoffice_writer()
* {
* mouse_click_image "screens/gnome-fileMenu.png" "screens/kde-fileMenu.png"
* mouse_click_image "screens/gnome-fileExit.png" "screens/kde-fileExit.png"
* mouse_click_image "screens/gnome-discard.png" "screens/kde-discard.png"
* }
* \endcode
* <li>Use the \c click_i function to close down LibreOffice writer - Find the "File" menu, click "Exit", and then make sure to discard all changes.
* <br><br>
* \code
* start_libreoffice_writer
* close_libreoffice_writer
* \endcode
* <li>Actually run the functions given.
* <br><br>
* <li>Please note that this is a fairly trivial example. The full list of commands available in the wrapper is given in \ref wrapper_functions
* </ul>
*
* \subsection testing_test_wrapper Testing the Testing Wrapper
* <ul>
* <li>First things first, run through the testing wrapper to make sure that everything is O.K.
* <li>If you need to, there are a few environment variables you can set to change how the wrapper works. See \ref appendix_variables for more information on how these work.
* <li>A full list of commands provided by the wrapper is available at \ref appendix_functions
* </ul>
*
* \note These options are controlled using the testing script as demonstrated above. Any modifications to the following values should be done at the line: \code #Changing any wrapper parameters should go here \endcode
* </ul>
* \section wrapping_up Wrapping Up
* <ul>
* <li>At this point you should have all the information you need to write your own application tests. The libcvautomation library and reference programs were designed to be simple and powerful, but if you invest the time to learn them and some expert BASH scripting, you can do some very complex things.
* <ul>
* <li>For example, integrating a <a href="http://testanything.org/wiki/index.php/Tap-functions">Test Anything Protocol</a> wrapper into your scripts as well.
* </ul>
* <li>If you have questions, comments, concerns, suggestions, or feedback in general, feel free to let me know at <a href="mailto:bspeice@uncc.edu">bspeice@uncc.edu</a>.
* </ul>
*/
/** \page wrapper_functions Appendix of Wrapper Functions and Environment Variables
* \section appendix_variables Environment Variables
* \subsection appendix_search Search Method
* \code SEARCH_METHOD \endcode
* This controls how each of the functions searches for an image. See \ref libcvautomation_search_methods for more instruction on how to use this option.
*
* \subsection appendix_tolerance Tolerance
* \code TOLERANCE
* USE_SANE_TOLERANCE \endcode
* These control how tolerant each function is when searching for an image. Acceptable values are anywhere between \c INT_MIN to \c INT_MAX. See \ref libcvautomation_search_methods for more information on how the tolerance values work.
* Additionally, the cva-input and cva-match programs (which this wrapper depends on) implement a "sane-tolerance" option. This allows you to set a tolerance between 1 - 100, where: \f$ 1 \approx 0 \f$, and \f$ 100 \approx INT\_MAX \f$
* By default, functions will not use sane tolerance. To make the functions search using sane tolerance, set \code USE_SANE_TOLERANCE="yes" \endcode
*
* \subsection appendix_center Center
* \code USE_CENTER \endcode
* This controls whether each function will return a value based on the center of the sub-image, rather than the top-left corner.
* By default, functions will use center-based matching. To make the functions use the top-left corner, set \code USE_CENTER="" \endcode
*
* \subsection appendix_wait Wait
* \code USE_WAIT
* TIMEOUT \endcode
* These control how the "waitfor" function is used. By default, all image-matching functions will wait for an image to appear, and then click on it. This way, it won't click randomly if it can or can't find an image, and provides very easy error recognition. The functions will wait for a period of \c TIMEOUT seconds before complaining.
* To disable waiting before performing an action, set \code USE_WAIT="" \endcode
* \warning Without setting a tolerance value, the waitfor function becomes totally useless, as the first search will always find an image. <tt>Make sure to set the tolerance</tt> (or just leave it as the default value in the wrapper).
*
* \subsection appendix_output Output and Debugging
* \code OUTFILE
* ERRFILE \endcode
* These files control the reporting of libcvautomation_funcs. The wrapper generates a decent amount of output to help in debugging application tests, and by default these get redirected to /dev/null. To instead redirect them to a file, you can do something like this:
* \code OUTFILE=`mktemp`; echo "Logfile: " $OUTFILE
* ERRFILE=`mktemp`; echo "Error file: " $ERR_FILE \endcode
* This will redirect the output and error output to a file you own, and inform you of what that file is.
*
* \section appendix_functions Functions
* \subsection appendix_click Click the mouse
* \code mouse_down [mouse-button] \endcode
* Push the mouse button down where it is currently located, and leave it down.
* Optionally specify a mouse button to push down
* <br><br>
*
* \code mouse_up [mouse-button] \endcode
* Release a mouse button.
* Optionally specify a mouse button to release (default button 1).
* <br><br>
*
* \code mouse_click [mouse-button] \endcode
* Release the mouse button
* Optionally specify a mouse button to release
* <br><br>
*
* \code mouse_click_xy <x-coordinate> <y-coordinate> [mouse-button] \endcode
* Click the mouse on an absolute point on screen
* Optionally specify a mouse button to click
* \note The actual process is to move the mouse to the given location, then click there.
* <br><br>
*
* \code mouse_click_rxy <x-increment> <y-increment> [mouse-button] \endcode
* Click the mouse on the screen relative to where the mouse is at
* Optionally specify a mouse button to click
* \note The actual process is to move the mouse the given distance, then click there.
* \note Also, note that a positive \c x-increment moves the mouse to the right, and a positive \c y-increment moves the mouse down.
* <br><br>
*
* \code mouse_click_image <filename> [filename-2] ... [filename-n] \endcode
* Click the mouse on a screenshot from \c filename
* Optionally specify multiple files to search in.
* \note This is affected by the \c CENTER, \c TOLERANCE, and \c SEARCH_METHOD variables. See \ref appendix_variables for more information on these.
* <br><br>
*
* \code mouse_doubleclick [mouse-button] \endcode
* Click the mouse twice
* Optionally specify a mouse button to click
* <br><br>
*
* \code mouse_doubleclick_xy [mouse-button] \endcode
* Click the mouse twice on an absolute point on screen
* Optionally specify a mouse button to click
* \note The actual process is to move the mouse to the given location, then click there.
* <br><br>
*
* \code mouse_doubleclick_rxy [mouse-button] \endcode
* Click the mouse twice on a relative point on screen
* Optionally specify a mouse button to click
* <br><br>
*
* \code mouse_doubleclick_image <filename> [filename-2] ... [filename-n] \endcode
* Click the mouse twice on a screenshot from \c filename
* Optionally specify multiple files to search in.
* \note This is affected by the \c CENTER, \c TOLERANCE, and \c SEARCH_METHOD variables. See \ref appendix_variables for more information on these.
* <br><br>
*
* \subsection appendix_move Move the mouse
* \code mouse_hover_xy <x-coordinate> <y-increment> \endcode
* Move the mouse to a location on screen using absolute positioning
* <br><br>
*
* \code mouse_hover_rxy <x-increment> <y-increment> \endcode
* Move the mouse to a location on screen using relative positioning
* \note Note that a positive \c x-increment moves the mouse to the right, and a positive \c y-increment moves the mouse down.
* <br><br>
*
* \code mouse_hover_image <filename> [filename-2] ... [filename-n] \endcode
* Move the mouse to a location on screen based on screenshot
* Optionally specify multiple files to search in.
* \note This is affected by the \c CENTER, \c TOLERANCE, and \c SEARCH_METHOD variables. See \ref appendix_variables for more information on these.
* <br><br>
*
* \code mouse_jiggle \endcode
* Very simple wrapper to move the mouse 1 pixel right and 1 pixel down - useful for activating menu items.
* <br><br>
*
* \code mouse_scroll_up \endcode
* Scroll the mouse wheel up one
*
* \code mouse_scroll_down \endcode
* Scroll the mouse wheel down one
*
* \code mouse_drag_n_drop \endcode
* Drag one image to another - i.e. drag a file to a folder.
* \warning This function accepts only two arguments unlike other image functions - the first argument is the image to drag, the second is the image to drag to.
*
* \subsection appendix_find Find an Image
* \code image_location <filename> \endcode
* Get the location of an image on screen
* \note This is affected by the \c CENTER, \c TOLERANCE, and \c SEARCH_METHOD variables. See \ref appendix_variables for more information on these.
* <br><br>
*
* \code wait_for <filename> \endcode
* Wait for an image to display on screen, and then return
* \note This is affected by the \c TOLERANCE, \c SEARCH_METHOD, and \c TIMEOUT variables. See \ref appendix_variables for more information on these.
*
* \subsection appendix_keyboard Click the keyboard
* \code key_string "<string>" \endcode
* Enter a string of characters on the keyboard rather than a single character at a time.
* \warning This function <b>does not</b> accept key strings like "Space" as \c key_down, \c key_up, and \c key_click do. If you pass in "Space", that is exactly what will be typed.
* <br><br>
*
* \code key_down "<key-name>" \endcode
* Press a key down and leave it down
* \note This function accepts special keys like "Space" - see \ref xtest_key_strings for a full list of characters allowed.
* <br><br>
*
* \code key_up "<key-name>" \endcode
* Release a key
* \note This function accepts special keys like "Space" - see \ref xtest_key_strings for a full list of characters allowed.
* <br><br>
*
* \code key_click "<key-name>" \endcode
* Press a key down and then release it immediately after
* \note This function accepts special keys like "Space" - see \ref xtest_key_strings for a full list of characters allowed.
* <br><br>
*
* \subsection appendix_utilities Useful extras
*
* \code is_running "<process-name>" \endcode
* \code is_running "<process-id>" \endcode
* Check if a program name or PID is currently running
*
* \code notify "<string_to_display>" \endcode
* Display a notification to the user, and wait for a response
* \warning Uses \c zenity - if \c zenity isn't available, will return an error without pausing, and will not display anything.
*/
/** \def LIBCVAUTOMATION_VERSION
* \brief Define what version of Libcvautomation we are using
* \details This define provides access to what version of Libcvautomation we're using. All times that you need to know what it is should use this.
*/
/** \def LIBCVAUTOMATION_BUGREPORT
* \brief Define who to send bug reports to for Libcvautomation
* \details This define provides access to who should be emailed in case of a Libcvautomation bug. All times that you need to know what it is should use this.*/
/** \struct cvautomationList
* \brief Implements a structure to build an array for methods like matchSubImage_a()
* \details This structure is a simple way to wrap up all needed information for matching sub images in one location.
* \param cvaImage An image in IplImage format
* \param fileName The file location of an image to be loaded
* \param resultPoint Holder for a result - for example, storing where this sub image was located in its root image
* \param searchMethod The search method to use when searching for this sub image in a root image
* \param tolerance The tolerance to use when searching for this sub image in a root image
* \see \ref libcvautomation_search_methods
*/
/** \struct cvaPoint
* \brief Very simple structure to standardize how points are used in libcvautomation
* \param x An X-coordinate
* \param y A Y-coordinate */