NAME
    Win32::ActAcc - `Active Accessibility' for task automation, GUI testing

SYNOPSIS
    *   Active Accessibility client API

         use Win32::OLE;
         use Win32::ActAcc;
         Win32::OLE->Initialize();
         $ao = AccessibleObjectFromPoint(320,240);
         @children = $ao->AccessibleChildren();
         $hwnd = $ao->WindowFromAccessibleObject();
         $ao2 = AccessibleObjectFromWindow($hwnd);

    *   IAccessible

         print $ao->get_accName() . "\n";
         print $ao->get_accValue() . "\n";
         print $ao->get_accDefaultAction() . "\n";
         $statebits = $ao->get_accState();
         $rolenum = $ao->get_accRole();
         $ch1 = $ao->accNavigate(NAVDIR_FIRSTCHILD());
         $p = $ao->get_accParent();

    *   WinEvents

         $aoNotepad = Win32::ActAcc::waitForEvent(
            +{ 'event'=>EVENT_OBJECT_SHOW(),
               'name'=>qr/Notepad/,
               'role'=>ROLE_SYSTEM_WINDOW()});

    *   Iterators

        Win32::ActAcc's iterators can drill into menus and outlines, in
        addition to the Active Accessibility object hierarchy.

         # display children of $ao
         my $iter = $ao->iterator();
         $iter->open();
         my $aoi;
         while ($aoi = $iter->nextAO())
         {
             print $aoi->describe() . "\n";
         }
         $iter->close();

    *   Finding accessible objects

         # find any descendant
         $notepadTextArea = $aoNotepad->drill("{editable text}", +{'max'=>1, 'min'=>1});

         # find immediate child
         $AimConversation = $aoIM->dig( +[ +{'role'=>ROLE_SYSTEM_WINDOW(), 'name'=>qr/\<HTML\>/ } ] );

         # follow path
         $tray = Win32::ActAcc::Desktop()->dig([ 
                    +{'role'=>Win32::ActAcc::ROLE_SYSTEM_WINDOW(), 'name'=>'', 'state'=>+{'mask'=>Win32::ActAcc::STATE_SYSTEM_INVISIBLE(), 'value'=>0}}, 
                    +{'role'=>Win32::ActAcc::ROLE_SYSTEM_WINDOW(), 'name'=>'', 'state'=>+{'mask'=>Win32::ActAcc::STATE_SYSTEM_INVISIBLE(), 'value'=>0}}, 
                    +{'role'=>Win32::ActAcc::ROLE_SYSTEM_WINDOW(), 'name'=>'', 'state'=>+{'mask'=>Win32::ActAcc::STATE_SYSTEM_INVISIBLE(), 'value'=>0}}, 
                    +{'role'=>Win32::ActAcc::ROLE_SYSTEM_WINDOW(), 'name'=>'Tray', 'state'=>+{'mask'=>Win32::ActAcc::STATE_SYSTEM_INVISIBLE(), 'value'=>0}}, 
                    +{'role'=>Win32::ActAcc::ROLE_SYSTEM_PAGETABLIST(), 'state'=>+{'mask'=>Win32::ActAcc::STATE_SYSTEM_INVISIBLE(), 'value'=>0}} ], 
                +{'max'=>1,'min'=>1} );

    *   Task-automation conveniences

         use Win32::OLE;
         use Win32::ActAcc;
         use Win32::ActAcc::Shell2000;
         #
         Win32::OLE->Initialize();
         $menu = Win32::ActAcc::Shell2000::StartButtonMenu();
         Win32::ActAcc::clearEvents();
         $menu->menuPick([ qr/^Programs/, qr/Accessories/i, qr/Notepad/i ]);
         $aoNotepad = Win32::ActAcc::waitForEvent(
            +{ 'event'=>EVENT_OBJECT_SHOW(),
               'name'=>qr/Notepad/,
               'role'=>ROLE_SYSTEM_WINDOW()});
         $aoNotepad->menuPick(+["File", "Exit"]);

    *   Tools and samples

        *   aaDigger.pl shows how to traverse the tree of accessible objects.

        *   aaEvents.pl shows you the WinEvents that reflect what you're doing
            with the GUI.

        *   aaWhereAmI.pl shows how to link a pixel location with its
            accessible object.

        *   elizaNotepad.pl, just for fun, uses Notepad as the user interface
            to Chatbot::Eliza.

        See under the section on "Tools" for more about aaDigger, aaEvents,
        and aaWhereAmI.

    You'll want to additionally use Win32::GuiTest, and other Win32 modules,
    if you want your script to click, type, manipulate the clipboard, etc.

    For full documentation, refer to ActAcc.html inside the zip. You will also
    find many useful samples in the '.t' (test-case) files.

INSTALLATION
    You can install Win32::ActAcc by compiling it from source code, or, if you
    have ActivePerl, you can install it using PPM, in which case you don't
    need a C++ compiler.

  Installation from source code

     perl makefile.pl
     nmake 
     nmake install
     nmake test

    Yes, you have to install it before you test it. Otherwise it can't find
    its DLL. Probably someone will figure out how to fix this.

    The test is tenuous. It will probably work only with Windows 2000, since
    the design and operation of Notepad changes subtly from version to
    version. You must have Win32::GuiTest 0.6 or later.

    Prerequisites:

    *   You may need Visual C++ 6.0 SP 4. The C/C++ part of Win32::ActAcc
        might not be portable to other compilers.

    *   You need the July 2000 "Platform SDK". Earlier versions of the Active
        Accessibility SDK could give problems compiling.

    *   The test suite requires Notepad.exe and Explorer.exe on the path.
        Also, it requires Win32::GuiTest.

    *   The Eliza-AOLInstantMessenger sample requires up-to-date HTML parsing
        modules. It will tell you if yours are missing or out-of-date.

  Installation for ActivePerl users (PPM)

    ActivePerl users can install Win32::ActAcc using PPM.

    1   Unzip the zip (Win32-ActAcc-n.n.zip). Make sure your unzip program
        preserved the directory tree: for example, you should see
        Win32-ActAcc.tar.gz in an "x86" subdirectory under the directory that
        contains ActAcc.html (the documentation).

    2   Open a command prompt window.

    3   In the command prompt, "cd" to the directory that contains
        ActAcc.html.

    4   In the command prompt, issue the following command.

         ppm install --location=. Win32-ActAcc

    To check the installation, you may try aaDigger.pl. The test suite (nmake
    test) doesn't seem to work if you do the ppm installation.

  Files Installed

    *   In bin: aaDigger.bat and aaDigger.pl, aaEvents.bat and aaEvents.pl,
        aaWhereAmI.bat and aaWhereAmI.pl

    *   In site\lib\Win32: aaDigger.pl, aaEvents.pl, aaWhereAmI.pl, ActAcc.pm,
        ActAcc.pod

        In site\lib\Win32\ActAcc: aaExplorer.pm

    *   In site\lib\auto\Win32\ActAcc: ActAcc.dll, ActAccEM.dll

COPYRIGHT
    Copyright 2001, Phill Wolf. All rights reserved, including, without
    limitation, motion-picture rights.

    You may use Win32::ActAcc under the terms of the Artistic License, as
    specified in the README file of the Perl distribution.

AUTHOR
    Phill Wolf, pbwolf@cpan.org

