NAME Win32::GUITaskAutomate - A module for automating GUI tasks. SYNOPSIS use Win32::GUITaskAutomate; my $robot = Win32::GUITaskAutomate->new( load => { pic1 => 'pic1.PNG', # load picture } ); $robot->find_do( 'pic1', # wait for loaded pic to appear [ { save => 1 }, # save mouse cursor position \ "ZOMG!!!!.pl", # put this text into clipboard { rmb => 1, x => 10, y => 20 }, # click right mouse button "{UP}{UP}~^v", # press UP arrow twice, ENTER and CTRL+V { lmb => 1, x => 100, y => 100 }, # click left mouse button { restore => 1 }, # restore original mouse cursor position ] ); my $clipboard_contents = $robot->get_clip; $robot->set_clip( "New clipboard contents" ); DESCRIPTION I wrote this module because I needed to automate certain GUI tasks in a limited amount of time. Win32::GUIRobot was very helpful to me with that, however I wanted some interface that would allow me to write "robot instructions" more easily and quickly. This is how Win32::GUITaskAutomate came to existance and I want to share it with the world, even though I do not have time to perfect it. METHODS new my $robot = Win32::GUITaskAutomate->new; my $robot = Win32::GUITaskAutomate->new( load => { pic1 => 'pic1.png', pic2 => 'pic2.png', pic3 => 'pic3.png', } ); This method creates a new Win32::GUITaskAutomate object. You may want to pass it an optional "load" argument which accepts a hashref with keys being the picture names (see "find_do" method below) and values being the filenames of those pictures. load $robot->load( { pic1 => 'pic1.png', pic2 => 'pic2.png' } ); This method loads image(s). It takes a hashref with picure names (see "find_do" method below) as keys and filenames as values. You may want to use "load" argument to the "new" method instead. do $robot->do( [ { lmb => 1, x => 10, y => 10 }, # click left mouse { rmb => 1, x => -10, y => -10 }, # right click { lmbd => 1, x => 10, y => 10 }, # left double click { mw => 2 }, # move mouse wheel. "{UP}{DOWN}~", # press Up, Down and Enter keys \ "Clip!", # copy text 'Clip!' into the clipboard [ 2 ], # wait for 2 seconds ], 400, 500 ); This method instructs your robot to do some "stuff". The first argument is an arrayref with instructions (See ROBOT INSTRUCTIONS below for descriptions). The second and third arguments are "x origin" and "y origin" respectively. Those two values will be basically added to any 'x' and 'y' values in the mouse related actions, they default to '0'. find_do $robot->find_do( 'picture_name', # name of the picture from ->load [ { lmb => 1, x => 10, y => 10 }, # left click "foos!" # type "foos!" ], $wait_time ); This method is similar to ->do method, except it first tries to find a picture on the screen. The ->load method as well as "load" argument to the ->new method is where you'd get your "picture name". The first argument to ->find_do method is picture name. The second argument is an arrayref with instructions (see ROBOT INSTRUCTIONS below). Third *optional* argument is the time in seconds to wait for the picture to appear on the screen, defaults to 100. The instructions will be passed to the ->do method when the picture is found, and 'origin x' and 'origin y' arguments will correspond to coordinates of where the picture was spotted. ROBOT INSTRUCTIONS Robot instructions are passed to ->do and ->find_do methods in the form of an arrayref, and are executed sequentually. Each element of the arrayref can be one of the following: A scalar "{UP}^l{DOWN}~" When an element is a scalar, the instruction will be interpreted as a request to press some keys, it will be sent directly to SendKeys() subroutine. See Win32::GuiTest "SendKeys" function for explanation of the keys A scalar reference \ "Clipper" When an element is a scalar reference, the content will be stuffed into the clipboard. If you want your robot to type up a large chunk of text, it will be significantly faster to drop that text into the clipboard and then issue a "^v" (CTRL+V) to paste it instead of asking the robot to type it all out key by key. An arrayref [10] When an element is an arrayref, it is interpreted as a request to sleep for that number of seconds, the request will be passed to "Win32::GUIRobot::Sleep" subroutine, not perl's "sleep". A hashref When an element is a hashref, it is interpreted as a mouse action (so far at least). One of the keys is an action key and the codes for those are: lmb Left Mouse Button rmb Right Mouse Button lmbd Left Mouse Button Double (double left click) rmbd Right Mouse Button Double (double right click) mw Mouse Wheel drag Left mouse button drag rdrag Right mouse button drag mdrag Middle mouse button drag save Save mouse cursor position restore Restore mouse cursor position to an earlier save setting ( see "save" ) General Principal for HashRef Instructions Hashref instructions deal with mouse actions. Some accept several arguments, which default to 0 if not specified. The arguments, unless specified otherwise, are offset coordinates relative to origin. By origin is understood either "origin x", and "origin y" coordinates of the ->do method, or the location where the image was found of the ->find_do method lmb (Left Mouse Button) { lmb => 1, x => 10, y => -22 } Key "lmb" stands for Left Mouse Button. It instructs the robot to make a left mouse click. The two optional arguments are "x" and "y" are the coordinates relative to the origin. Omitted arguments default to zero. The value for "lmb" key must be a *true value* in order for the instruction to be executed, this allows some dynamic decision making, such as: { lmb => $do_we_need_to_click.... rmb (Right Mouse Button) { rmb => 1, x => 10, y => -22 } Same as "lmb" except this instructs the robot to right click. mmb (Middle Mouse Button) { mmb => 1, x => 10, y => -22 } Same as "lmb" except this instructs the robot to middle click. lmbd (Left Mouse Button Double) { lmbd => 1, x => 10, y => -22 } Same as "lmb" except this instructs the robot to double left click. rmbd (Right Mouse Button Double) { rmbd => 1, x => 10, y => -22 } Same as "lmb" except this instructs the robot to double right click. mmbd (Middle Mouse Button Double) { mmbd => 1, x => 10, y => -22 } Same as "lmb" except this instructs the robot to double middle click. mw (Mouse Wheel) { mw => 2 } { mw => -10 } This argument instructs the robot to move the *mouse wheel*. It does not take any extra arguments. Positive values spin the wheel "up" and negative values spin the wheel "down". drag (Drag with left mouse button) { drag => 1, x => 1, y => 20, d_x => 100, d_y => -20 } { drag => 1, d_x => -100 } { drag => 1, x => 200, d_y => -200 } Instructs the robot to drag with left mouse button (as in left mouse button down => move mouse => left mouse button up). As with "lmb", the value for the "drag" key must be a *true value* in order for the instruction to be executed. Takes *four* optional arguments. They all will default to 0 if not specified. "x" and "y" are the starting point of the drag (relative to the origin) and "d_x" and "d_y" are ending points of the drag (again relative to the origin, not the place of the start of the drag). rdrag (Drag with right mouse button) { rdrag => 1, x => 1, y => 20, d_x => 100, d_y => -20 } { rdrag => 1, d_x => -100 } { rdrag => 1, x => 200, d_y => -200 } Same as "drag" except drags with right mouse button. mdrag (Drag with middle mouse button) { mdrag => 1, x => 1, y => 20, d_x => 100, d_y => -20 } { mdrag => 1, d_x => -100 } { mdrag => 1, x => 200, d_y => -200 } Same as "drag" except drags with middle mouse button. save { save => 1 } Instructs the robot to save current mouse cursor position. This is useful if you want your robot to do some mouse clickety and restore the original cursor position when finished (see "restore" below). The value of the key must be a true value or nothing will happen. restore { restore => 1 } Instructs the robot to restore saved mouse cursor position. This is useful if you want your robot to do some mouse clickety and restore the original cursor position when finished (see "save" above). The value of the key must be a true value or nothing will happen. If you never saved any positions with "save" (see above) nothing will happen. OTHER METHODS drag_mouse $robot->drag_mouse( 'Left', $x_from, $y_from, $x_to, $y_to ); Instructs the robot to make a mouse drag. First argument is the button to use for dragging. It can be either 'Left', 'Right' or 'Middle'. Sub will "croak" if incorrect button is passed (names are case *insensitive*). $x_from and $y_from are coordinates of the starting point of the drag and $x_to and $y_to are the endining points of the drag. All will default to zero if are not set. click_mouse $robot->click_mouse( $x, $y, $button, $times ) Instructs the robot to click the mouse. $x and $y are the coordinates of the click. $button is the button to press, can be either 'Left', 'Right' or 'Middle'. Sub will "croak" if incorrect button is passed (names are case *insensitive*). $times is the number of times to press the button, which defaults to 1 if not specified. $x and $y default to 0. set_clip $robot->set_clip( 'Text to put into the clipboard' ); Takes one argument which will be put into the clipboard. Technically this can be anything accepted by the Win32::Clipboard "Set()" method, but was tested only with textual content. get_clip my $clipboard_stuff = $robot->get_clip; Takes no arguments. Returns clipboard contents. Technically this may be anything returned by Win32::Clipboard "Get()" method, but was tested only with textual content. clip my $clipboard = $robot->clip; Returns Win32::Clipboard object if you'll ever need it. pics my $pics_ref = $robot->pics; Returns a hashref of loaded images. It's the one from the "load" option of the ->new methods as well as from the ->load method. You might want to check if a certain picture was already loaded. mouse_coords my $mouse_coords_ref = $robot->mouse_coords; $robot->mouse_coords( [ 200, 100 ] ); Returns an arrayref with two elements: x and y coordinates of the mouse cursor which were stored with "save" intruction (see ROBOT INSTRUCTIONS for more info). Will return "undef" if you never saved any positions and never set them with "mouse_coords()" method. Takes one *optional* argument which is an arrayref with two elements: x and y coordinates. *Note:* if you specificly set coordinates with this method they will distroy the ones that were saved with "save" robot instruction and will be used by "restore" robot instruction. EXAMPLES Here are some examples with explanations of how the robot would behave Example 1 use Win32::GUITaskAutomate; my $robot = Win32::GUITaskAutomate->new( load => { task => 'task.png', task2 => 'task2.png', } ); $robot->find_do( 'task', [ { lmb => 1, x => 5, y => 5 }, [2], ]); $robot->find_do( 'task2', [ "^t", [1.1], \ "Hello World!", "^v~", ]); The code is interpreted as follows: * Load two images from files 'task.png' and 'task2.png' and name them 'task' and 'task2' respectively. * Start watching the screen for 'task' image to appear with the default 100 second timeout. * When 'task' image is seen on screen, click left mouse button 5 pixels to the right and 5 pixels to the left of where the image was found (starting at the top left corner of the image) * Sleep for 2 seconds * Start watching the screen for 'task2' image to appear with the default 100 second timeout. * When found -- press "CTRL+T" key, wait for 1.1 seconds. * Push string "Hello World!" intro the clipboard, paste it with "CTRL+V" and press "ENTER" key. Example 2 use Win32::GUITaskAutomate; my $robot = Win32::GUITaskAutomate->new( load => { pic => 'pic1.png', } ); $robot->find_do( 'pic', { lmb => $do_click, x => 10, y => 20 }, "~{TAB}OH HAI~", { drag => $do_drag, d_x => 100, d_y => 200 }, ); if ( $do_click ) { $robot->load( { pic2 => 'pic2.png } ); $robot->find_do( "~~~{TAB}~", ); } The code is interpreted as follows, consider that $do_click variable is assigned to earlier in the source code from somewhere. * Load up image from file 'pic1.png' and give it name 'pic' * Start looking for 'pic' to appear on the screen. * When found, left click 10 pixels to the right and 20 pixels down relative to the left right corner of where we have spotted 'pic'. Note: the click will not happen if $do_click variable is set to a false value. * Press "ENTER", "TAB", type "OH HAI" and press "ENTER" again. * If variable $do_click is set to true value, load another image from file 'pic2.png' and name it 'pic2' * Start looking for 'pic2' to appear on the screen. * When it's found: press "ENTER" key three times, press "TAB" key and press "ENTER" again. SEE ALSO Win32::GUIRobot, Win32::GuiTest, Win32::Clipboard PREREQUISITES This module requires Win32::GUIRobot, Win32::Clipboard as well as Test::More for "make test" AUTHOR Zoffix Znet, "" BUGS Please report any bugs or feature requests to "bug-win32-guitaskautomate at rt.cpan.org", or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. SUPPORT You can find documentation for this module with the perldoc command. perldoc Win32::GUITaskAutomate You can also look for information at: * RT: CPAN's request tracker * AnnoCPAN: Annotated CPAN documentation * CPAN Ratings * Search CPAN COPYRIGHT & LICENSE Copyright 2008 Zoffix Znet, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.