The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Win32-GUITaskAutomate-0.06
River stage zero No dependents
++
/ Win32::GUITaskAutomate

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, <zoffix at cpan.org>

BUGS

Please report any bugs or feature requests to bug-win32-guitaskautomate at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Win32-GUITaskAutomate. 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:

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.