<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">NAME
    Win32::GuiTest - Perl GUI Test Utilities

SYNOPSIS
      use Win32::GuiTest qw(FindWindowLike GetWindowText 
        SetForegroundWindow SendKeys);

      $Win32::GuiTest::debug = 0; # Set to "1" to enable verbose mode

      my @windows = FindWindowLike(0, "^Microsoft Excel", "^XLMAIN\$");
      for (@windows) {
          print "$_&gt;\t'", GetWindowText($_), "'\n";
          SetForegroundWindow($_);
          SendKeys("%fn~a{TAB}b{TAB}{BS}{DOWN}");
      }

INSTALLATION
        perl makefile.pl
        nmake
        nmake test
        nmake install

    If you're using ActivePerl 5.6
    (http://www.activestate.com/Products/ActivePerl/index.html) you can
    install the binary package I'm including instead. You'll need to enter
    PPM (Perl Package Manager) from the command-line. Once you have
    extracted the files I send you to a directory of your machine, enter PPM
    and do like this:

        C:\TEMP&gt;ppm
        PPM interactive shell (2.0) - type 'help' for available commands.
        PPM&gt; install C:\temp\win32-guitest.ppd
        Install package 'C:\temp\win32-guitest.ppd?' (y/N): Y
        Retrieving package 'C:\temp\win32-guitest.ppd'...
        Writing C:\Perl\site\lib\auto\Win32\GuiTest\.packlist
        PPM&gt;

    I extracted them to 'c:\temp', please use the directory where you
    extracted the files instead.

DESCRIPTION
    Most GUI test scripts I have seen/written for Win32 use some variant of
    Visual Basic (e.g. MS-VB or MS-Visual Test). The main reason is the
    availability of the SendKeys function.

    A nice way to drive Win32 programs from a test script is to use OLE
    Automation (ActiveX Scripting), but not all Win32 programs support this
    interface. That's where SendKeys comes handy.

    Some time ago Al Williams published a Delphi version in Dr. Dobb's
    (http://www.ddj.com/ddj/1997/careers1/wil2.htm). I ported it to C and
    packaged it using h2xs...

    The tentative name for this module is Win32::GuiTest (mostly because I
    plan to include more GUI testing functions).

VERSION
        0.07

CHANGES
    0.01 Wed Aug 12 21:58:13 1998

        - original version; created by h2xs 1.18

    0.02 Sun Oct 25 20:18:17 1998

        - Added several Win32 API functions (typemap courtesy 
          of Win32::APIRegistry):
            SetForegroundWindow
            GetDesktopWindow 
            GetWindow 
            GetWindowText 
            GetClassName 
            GetParent
            GetWindowLong
            SetFocus

        - Ported FindWindowLike (MS-KB, Article ID: Q147659) from VB to
          Perl. Instead of using "like", I used Perl regexps. Why
          didn't Jeffrey Friedl include VB in "Mastering Regular
          Expressions"? ;-). 
        
    0.03 Sun Oct 31 18:31:52 1999

        - Perhaps first version released thru CPAN (user: erngui).

        - Changed name from Win32::Test to Win32::GuiTest

        - Fixed bug: using strdup resulted in using system malloc and 
          perl's free, resulting in a runtime error.  
          This way we always use perl's malloc. Got the idea from
          'ext\Dynaloader\dl_aix.xs:calloc'.

    0.04 Fri Jan 7 17:44:00 2000

        - Fixed Compatibility with ActivePerl 522. Thanks to
          Johannes Maehner &lt;johanm@camline.com&gt; for the initial patch.
          There were two main issues: 
            /1/ ActivePerl (without CAPI=TRUE) compiles extensions in C++ mode 
                (some casts from void*, etc.. were needed).
            /2/ The old typemap + buffers.h I was using had been rendered
                incompatible by changes in ActivePerl. As the incompatible typemaps
                were redundant, I deleted them. 
          Now it works on ActivePerl (both using 'perl makefile.pl' 
          and 'perl makefile.pl CAPI=TRUE') and on CPAN perl 
          (http://www.perl.com/CPAN/src/stable.zip). 

        - As requests for changes keep comming in, I've decided to put it all
          under version control (cvs if you're curious about it).   

    0.05 Sat Mar 11 23:11:42 2000

        - Added support for sending function keys (e.g. "%{F4}"). A new test 
          script is added to the distribution (eg\notepad.pl) to test
          this functionality.

        - Code cleanup to make adding new keywords easier.

    0.06 Sun Mar 12 01:51:18 2000

        - Added support for sending mouse events.
          Thanks to Ben Shern &lt;shernbj@louisville.stortek.com&gt; for the idea 
          and original code. Also added 'eg\paint.pl' to the distribution to
          test this functionality.

        - Code cleanup.

    0.07 Sun Nov 19 13:02:00 2000

        - Added MouseMoveAbsPix to allow moving the mouse to an absolute pixel 
          coordinate instead of using mouse_event's (0, 0) to (65535, 65535) 
          coordinates.
          Thanks to Phill Wolf &lt;pbwolf@bellatlantic.net&gt; for the idea 
          and original code. Also added 'eg\paint_abs.pl' to the distribution 
          to test this functionality.

        - Added binaries for the ActivePerl distribution. 
    
FUNCTIONS
    $debug  When set enables the verbose mode.

    SendKeys KEYS
            Sends keystrokes to the active window as if typed at the
            keyboard. The keystrokes to send are specified in KEYS. There
            are several characters that have special meaning. This allows
            sending control codes and modifiers:

                    ~ means ENTER
                    + means SHIFT 
                    ^ means CTRL 
                    % means ALT

            The parens allow character grouping. You may group several
            characters, so that a specific keyboard modifier applies to all
            of them.

            E.g. SendKeys("ABC") &lt;=&gt; SendKeys("+(abc)")

            The curly braces are used to quote special characters
            (SendKeys("{+}{{}") sends a '+' and a '{'). You can also use
            them to specify certain named actions:

                    Name              Action

                    {BACKSPACE}       Backspace
                    {BS}              Backspace
                    {BKSP}            Backspace
                    {BREAK}           Break
                    {CAPS}            Caps Lock
                    {DELETE}          Delete
                    {DOWN}            Down arrow
                    {END}             End
                    {ENTER}           Enter (same as ~)
                    {ESCAPE}          Escape
                    {HELP}            Help key
                    {HOME}            Home
                    {INSERT}          Insert
                    {LEFT}            Left arrow
                    {NUMLOCK}         Num lock
                    {PGDN}            Page down
                    {PGUP}            Page up
                    {PRTSCR}          Print screen
                    {RIGHT}           Right arrow
                    {SCROLL}          Scroll lock
                    {TAB}             Tab
                    {UP}              Up arrow
                    {PAUSE}           Pause
                {F1}              Function Key 1
                ...               ...
                {F24}             Function Key 24

            All these named actions take an optional integer argument, like
            in {RIGHT 5}. For all of them, except PAUSE, the argument means
            a repeat count. For PAUSE it means the number of milliseconds
            SendKeys should pause before proceding.

            In this implementation, SendKeys always returns after sending
            the keystrokes. There is no way to tell if an application has
            processed those keys when the function returns.

    SendMouse COMMAND
            This function emulates mouse input. The COMMAND parameter is a
            string containing one or more of the following substrings:
            {LEFTDOWN} left button down {LEFTUP} left button up {MIDDLEDOWN}
            middle button down {MIDDLEUP} middle button up {RIGHTDOWN} right
            button down {RIGHTUP} right button up {LEFTCLICK} left button
            single click {MIDDLECLICK} middle button single click
            {RIGHTCLICK} right button single click {ABSx,y} move to absolute
            coordinate ( x, y ) {RELx,y} move to relative coordinate ( x, y
            )

            Note: Absolute mouse coordinates range from 0 to 65535. Relative
            coordinates can be positive or negative. If you need pixel
            coordinates you can use MouseMoveAbsPix.

            Also equivalent low-level functions are available:

                SendLButtonUp()
                    SendLButtonDown()
                    SendMButtonUp()
                    SendMButtonDown()
                    SendRButtonUp()
                    SendRButtonDown()
                    SendMouseMoveRel(x,y)
                SendMouseMoveAbs(x,y)

    MouseMoveAbsPix(X,Y)
    Move the mouse cursor to the screen pixel indicated as parameter.

        # Moves to x=200, y=100 in pixel coordinates.
        MouseMoveAbsPix(200, 100); 
        
    FindWindowLike WINDOW, TITLEPATTERN, CLASSPATTERN, CHILDID
    Finds the window handles of the windows matching the specified
    parameters and returns them as a list.

    You may specify the handle of the window to search under. The routine
    searches through all of this windows children and their children
    recursively. If 'undef' then the routine searches through all windows.
    There is also a regexp used to match against the text in the window
    caption and another regexp used to match against the text in the window
    class. If you pass a child ID number, the functions will only match
    windows with this id. In each case undef matches everything.

COPYRIGHT
    The SendKeys function is based on the Delphi sourcecode published by Al
    Williams (http://www.al-williams.com/awc/) in Dr.Dobbs
    (http://www.ddj.com/ddj/1997/careers1/wil2.htm).

    Copyright (c) 1998-2000 Ernesto Guisado. All rights reserved. This
    program is free software; You may distribute it and/or modify it under
    the same terms as Perl itself.

AUTHOR
    Ernesto Guisado &lt;erngui@acm.org&gt;, &lt;http://www.geocities.com/erngui&gt;

</pre></body></html>