=encoding euc-jp

=head1 名前

Win32::GuiTest - Perl GUI テスト ユーティリティー

=head1 概要

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

  $Win32::GuiTest::debug = 0; # 冗長モードにするためには"1"に設定

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

=head1 インストール方法

    perl makefile.pl
    nmake
    nmake test
    nmake install

=begin original

If you are using ActivePerl 5.6 
(http://www.activestate.com/Products/ActivePerl/index.html) 
you can install the binary package I am including instead. You will 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:

=end original

ActivePerl 5.6を使っているのであれば、
(http://www.activestate.com/Products/ActivePerl/index.html) 
私が代わりに入れているバイナリ・パッケージをインストールすることができます。
コマンドラインからPPM(Perl Package Manger)と入力する必要があります。
私が送ったファイルを解凍し、あなたのマシンのディレクトリに入れた後、
PPMと入力し以下のようにしてください:

    C:\TEMP>ppm
    PPM interactive shell (2.0) - type 'help' for available commands.
    PPM> 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>

=begin original

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

=end original

私は'c:\temp'に解凍しました。あなたが解凍したディレクトリを代わりに
使ってください。


=head1 説明

=begin original

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.

=end original

私がこれまで見てきた/書いてきた、ほとんどのWin32用のGUIテストスクリプトは
なんらかのVisual Basicの一種(例えば MS-VB あるいは MS-Visual Testなど）を
使っていました。その主な理由はSendKeys関数が使えるということです。

=begin original

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.

=end original

テストスクリプトからWin32プログラムを動かす素晴らしい方法は、OLEオートメーション
(ActiveXスクリプティング）です。しかし全てのWin32プログラムがこのインターフェースを
サポートしているわけではありません。それこどSendkeysが役に立つのです。

=begin original

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...

=end original

以前Al WilliamsはDr. Dobb'sでDelphi版を公開しました
(http://www.ddj.com/ddj/1997/careers1/wil2.htm)。私はそれをCに移植し、
h2xsを使ってパッケージ化しました...

=begin original

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

=end original

私は迷いながらもこのモジュールの名前をWin32::GuiTestとしました(私がより多くの
GUIテスト機能を入れることを考えているのが主な理由です)。

=begin original

I've created a Yahoo Group for the module that you can join at
   http://groups.yahoo.com/group/perlguitest/join

=end original

みなさんが参加することができる、このモジュールのためのYahooグループを作成
しています
   http://groups.yahoo.com/group/perlguitest/join

=head1 バージョン

    1.3

=head1 変更履歴

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 VB's "like", I used Perl regexps.
    
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 <johanm@camline.com> 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 <shernbj@louisville.stortek.com> 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 <pbwolf@bellatlantic.net> 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. 

0.08 Sun Dec 17 19:33:07 2000

    - Added WMGetText to allow getting the content of an EDIT window. See 
      'eg\notepad_text.pl' for more details. 
      Thanks to Mauro <m_servizi@yahoo.it> from Italy for the idea. 

0.09 Thu Jan 4 22:30:50 2001

    - Added {SPC} action to sendkeys to simulate hitting the spacebar.
      Thanks to Sohrab Niramwalla <sohrab.niramwalla@utoronto.ca> for the 
      idea. 

1.00 Sun May 13 22:02:01 2001

    - Fixed a bug in FindWindowLike that caused duplicated window handles to
      be returned.

    - Simplified the logic in FindWindowLike.

    - Added IsChild and GetChildDepth functions. Exported GetChildWindows.

    - Added more tests (tightening the net in XP-speak)

    - Added 'eg\spy--.pl' to the distribution.

1.10 Sun Jun 17 19:54:27 2001

    - Added GetWindowRect, GetScreenRes, ScreenToNorm and NormToScreen,
      following suggestion and code from Frank van Dijk <fvdijk@oke.nl>.

    - Added SendMessage, PostMessage, GetCursorPos, AttachWin,
      additional SendKeys flags (Windows keys and context menu),
      WMSetText, GetCaretPos, GetFocus, GetActiveWindow, GetForegroundWindow,
      SetActiveWindow, EnableWindow, IsWindowEnabled, IsWindowVisible and
      ShowWindow (+ constants to use it).

      Thanks to Jarek Jurasz <jurasz@imb.uni-karlsruhe.de> for all of them.

      Jarek also provided two scripts: 'eg\showmouse.pl' and 'eg\showwin.pl'.
      I found showwin very interesting (if somewhat dangerous!).

      He also fixed an export list problem (WMGetKey was mentioned instead
      of WMGetText) and added export tags :ALL and :SW, so that full module
      functionality can be imported with

                   use Win32::GuiTest qw(:ALL :SW);

    - Added IsWindow, ScreenToClient, ClientToScreen, IsCheckedButton and
      IsGrayedButton.

    - SendKeys now takes an optional parameter to change the default 50 ms
      delay between keystrokes. Suggested by Wilson P. Snyder II
      <wsnyder@world.std.com>.

1.20 Wed Jul 18 20:44:11  2001

    - Added GetComboText, GetComboContents, GetListText and GetListContents
      to allow easy extraction of data from list and combo boxes.

    - Added 'eg\fonts.pl' to show the new functionality. This script opens
      the Notepad "Font" dialog and prints to stdout the contents of the Font
      combobox.

    - Fixed bug in SendMessage (and others), where the return value was lost
      Caused by a missing OUTPUT tag.

    - Added IsKeyPressed function. Suggested by Rudi Farkas.
      See 'eg\keypress.pl' for a demo. Works even if the script
      is running in the background.

1.30 Sat Dec  1 20:50:02 2001

    - Fixed bad POD formating. Added podchecker and html pod generation to makedist.bat.

    - Added PushButton and PushChildButton. Based on code from an anonymous contributor. Thanks!
      See 'eg\pushbutton.pl' for an example.

    - Fixed a problem when building with Active State, build 526.

=head1 関数

=over 8


=item $debug

=begin original

When set enables the verbose mode.

=end original

設定すると冗長モードになります。


=item SendKeys KEYS [DELAY]

=begin original

Sends keystrokes to the active window as if typed at the keyboard using the
optional delay between keystrokes (default is 50 ms and should be OK for
most uses). 

=end original

オプションでキーストロークの間に遅延(=delay)を入れながら、アクティブな
ウィンドウにまるでキボードから打ち込んだようにキーストロークを送信します。
（デフォルトは50msでほとんどの利用では大丈夫でしょう）

=begin original

The keystrokes to send are specified in KEYS. There are several
characters that have special meaning. This allows sending control codes 
and modifiers:

=end original


送信されるキーストロークはKEYSで指定されます。いくつかの特別な意味を持つ
文字があります。これにより制御コードや修飾子も送信することができます:

=begin original

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

=end original

    ~ は ENTER を
    + は SHIFT を
    ^ は CTRL を
    % は ALT を、それぞれ意味します

=begin original

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

=end original

括弧により文字をグループ化することができます。いくつかの文字をグループに
することができ、特定のキーボードの修飾子をそれらの全てに適用することが
できます。

=begin original

E.g. SendKeys("ABC") is equivalent to SendKeys("+(abc)")

=end original

例. SendKeys("ABC") は SendKeys("+(abc)") でも同じです

=begin original

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

=end original

大括弧は特殊文字を引用するために使われます(SendKeys("{+}{{}") は
は'+'と'{'を送信します)。またそれらを使って名前が付けられたアクションを
使うことが出来ます。

=begin original

	Name          Action

=end original

    名前          アクション

=begin original

	{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
        {SPC}         Spacebar
        {SPACE}       Spacebar
        {SPACEBAR}    Spacebar
        {LWI}         Left Windows Key
        {RWI}         Right Windows Key 
        {APP}         Open Context Menu Key

=end original

    {BACKSPACE}   Backspace
    {BS}          Backspace
    {BKSP}        Backspace
    {BREAK}       Break
    {CAPS}        Caps Lock
    {DELETE}      Delete
    {DOWN}        下矢印
    {END}         End
    {ENTER}       Enter (~を同じ)
    {ESCAPE}      Escape
    {HELP}        Helpキー
    {HOME}        Home
    {INSERT}      Insert
    {LEFT}        左矢印
    {NUMLOCK}     Num lock
    {PGDN}        Page down
    {PGUP}        Page up
    {PRTSCR}      Print screen
    {RIGHT}       右矢印
    {SCROLL}      Scroll lock
    {TAB}         Tab
    {UP}          上矢印
    {PAUSE}       Pause
    {F1}          Function Key 1
    ...           ...
    {F24}         Function Key 24
    {SPC}         空白
    {SPACE}       空白
    {SPACEBAR}    空白
    {LWI}         左Windowsキー
    {RWI}         右Windowsキー
    {APP}         オープン・コンテキスト・メニュー・キー

=begin original

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.

=end original

これらの全ての名前付きのアクションは、{RIGHT 5}のようにオプションで整数の
引数を取ります。PAUSEの除くこれらは全てにとって、引数は繰り返しの回数を
意味します。PAUSEにとっては先に進む前に中断するミリ秒数を意味します。

=begin original

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. 

=end original

この実装では、SendKeys常にキーストロークを送信した後、常に戻ります。
この関数が戻ってきて時、アプリケーションがそれらのキーを処理しおえているかを
知る方法はありません。

=back

=over 8

=item SendMouse COMMAND

=begin original

This function emulates mouse input.  The COMMAND parameter is a string
containing one or more of the following substrings:

=end original

この関数はマウス入力をエミュレートします。COMMANDパラメータは
１つあるいはそれ以上の文字列が入った文字列です:

        {LEFTDOWN}    左ボタンのダウン
        {LEFTUP}      左ボタンのアップ
        {MIDDLEDOWN}  中ボタンのダウン
        {MIDDLEUP}    中ボタンのアップ
        {RIGHTDOWN}   右ボタンのダウン
        {RIGHTUP}     右ボタンのアップ
        {LEFTCLICK}   左ボタンのシングルクリック
        {MIDDLECLICK} 中ボタンのシングルクリック
        {RIGHTCLICK}  右ボタンのシングルクリック
        {ABSx,y}      絶対座標( x, y )に移動
        {RELx,y}      相対座標( x, y )に移動

=begin original

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.

=end original

注意: 絶対マウス座標の範囲は0から65535になります。
      相対座標は正にも負にもすることができます。
      ピクセル座標が必要であれば、MouseMoveAbsPixを使うことが出来ます。

=begin original

Also equivalent low-level functions are available:

=end original

同等の低レベルの関数を利用することもできます:

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

=back

=over 8

=item MouseMoveAbsPix(X,Y)

=begin original

Move the mouse cursor to the screen pixel indicated as parameter.

=end original

パラメータとして指定された画面上のピクセルにマウスカーソルを
移動します。

=begin original

    # Moves to x=200, y=100 in pixel coordinates.
    MouseMoveAbsPix(200, 100); 

=end original

    # ピクセル座標での x=200, y=100 に移動します。
    MouseMoveAbsPix(200, 100); 
    


=item FindWindowLike WINDOW, TITLEPATTERN, CLASSPATTERN, CHILDID 

=begin original

Finds the window handles of the windows matching the specified parameters and
returns them as a list. 

=end original

指定されたパラメータにマッチするウィンドウのウィンドウ・ハンドルを探し、
それをリストで返します。

=begin original

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.

=end original

下方に検索するウィンドウのハンドルを指定することが出来ます。このルーチンは
このウィンドウの全ての子供とさらにその子供を再帰的に検索していきます。
もし'undef'であれば、このルーチンは全てのウィンドウを探していきます。
Windowのキャプションの文字列にマッチさせるために使われる正規表現もあります。
子供ID番号を渡すと、この関数はそのIDを追ったウィンドウにのみマッチします。
いずれもundefは全てにマッチします。

=back 

=over 8

=item PushButton BUTTON [, DELAY]


    PushChildButton(GetForegroundWindow, BUTTON, DELAY)

と同じです。

=back

=over 8

=item PushChildButton( parent, button [, delay] )

=begin original

Allows generating a mouse click on a particular button.

=end original

特定のボタンへのマウスクリックを生成することを可能にします。

=begin original

parent - the parent window of the button

=end original

parent - そのボタンの親ウィンドウ

=begin original

button - either the text in a button (e.g. "Yes") or the control ID
of a button.

=end original

button - ボタンのテキスト(例えば "Yes")あるいは、ボタンの
コントロールIDのどちらかです。

=begin original

delay - the time (0.25 means 250 ms) to wait between the mouse down
and the mouse up event. This is useful for debugging.

=end original

delay - マウスダウンとマウスアップイベントの間の時間
(0.25 は 250 ms を意味します)を意味します。これはデバッグのときに
便利です。

=back

=head1 著作権(=COPYRIGHT)

The SendKeys function is based on the Delphi sourcecode
published by Al Williams  E<lt>http://www.al-williams.com/awc/E<gt> 
in Dr.Dobbs  E<lt>http://www.ddj.com/ddj/1997/careers1/wil2.htmE<gt>.

Copyright (c) 1998-2001 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.

=head1 作者(AUTHOR)

Ernesto Guisado E<lt>erngui@acm.orgE<gt>, E<lt>http://triumvir.orgE<gt>

=head1 翻訳者

川合孝典(GCD00051@nifty.ne.jp)