NAME

Win32::FindWindow - find windows on Win32 systems

SYNOPSIS

    use Win32::FindWindow qw/find_window find_windows/;
    
    $window = find_window();
    $window = find_window( classname  => 'ExploreWClass' );
    $window = find_window( basename   => qr/^Explorer.EXE$/
                         , filename   => qr/^C:\\WINDOWS\\.*/
                         , windowtext => qr/^C:\\$/
                         , classname  => qr/^ExploreWClass$/ );
    
    @windows = find_windows();
    @windows = find_windows( windowtext => qr/ - Microsoft Internet Explorer$/ );
    @windows = find_windows( basename   => 'mspaint.exe'
                           , filename   => 'C:\\WINDOWS\\system32\\mspaint.exe'
                           , windowtext => qr/^.+$/
                           , classname  => 'MSPaintApp' );
    
    $window->basename;
    $window->filename;
    $window->windowtext;
    $window->classname;
    $window->hwnd;
    $window->pid;

DESCRIPTION

This module provides routines for finding windows on Win32 systems.

FUNCTIONS

find_window()

Returns Win32::FindWindow objects by supplied search parameters. The parameters are as follows:

    basename
    filename
    windowtext
    classname
    hwnd
    pid

SCALAR or Regexp value can be specified as search conditions for finding window. Like this:

    $window = find_window( basename => 'wmplayer.exe' );
    $window = find_window( windowtext => qr/^Windows Media/ );

find_windows()

Same as find_window() except it returns multiple objects as ARRAY.

    @windows = find_windows( basename   => 'mspaint.exe'
                           , filename   => 'C:\\WINDOWS\\system32\\mspaint.exe'
                           , windowtext => qr/^.+$/
                           , classname  => 'MSPaintApp' );

METHODS

    $window = find_window( ... );
    
    # accessors (read-only)
    $window->basename;
    $window->filename;
    $window->windowtext;
    $window->classname;
    $window->hwnd;
    $window->pid;

Accessor methods is being offered as shown in the above. These are read-only.

GLOBAL VARIABLES

$ENCODING

    # how to use regexp with wide characters
    # e.g. pattern matching the character that starts by Japanese `スタート'
    use Win32::FindWindow qw/find_windows/;
    use utf8;
    use encoding 'utf8', STDOUT => 'cp932';
    $Win32::FindWindow::ENCODING = 'cp932';
    @windows = find_windows( classname  => 'Button'
                           , windowtext => qr/^スタート/ );

A string value that shows system encodings. Defaults to 'cp1252'. Set your system's codepage string that module Encode supported. Because this module uses Encode::decode() internally.

$LENGTH_MAX

A numerical value that shows length of temporary string buffer. Defaults to 1024. This is used by GetClassName(), EnumProcessModules(), GetModuleFileNameEx() and GetModuleBaseName().

SEE ALSO

Win32::API, Win32::API::Callback, Class::Accessor::Fast, Encode, How To Enumerate Windows Using the WIN32 API: http://support.microsoft.com/kb/183009

AUTHOR

Michiya Honda <pia@cpan.org>

LICENCE

This library is free software, licensed under the same terms with Perl. See perlartistic.