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

NAME

Win32::CtrlGUI::Window - OO interface for controlling Win32 GUI windows

VERSION

This document describes version 0.32 of Win32::CtrlGUI::Window, released January 10, 2015 as part of Win32-CtrlGUI version 0.32.

SYNOPSIS

  use Win32::CtrlGUI

  my $window = Win32::CtrlGUI::wait_for_window(qr/Notepad/);
  $window->send_keys("!fx");

DESCRIPTION

Win32::CtrlGUI::Window objects represent GUI windows, and are used to interact with those windows.

METHODS

_new

This method is titled _new because it would rarely get called by user-level code. It takes a passed window handle and returns a Win32::CtrlGUI::Window object.

handle

This method returns the window's handle. Rarely used because the numification operator for Win32::CtrlGUI::Window is overloaded to call it.

text

This method returns the window's text. Rarely used because the stringification operator for Win32::CtrlGUI::Window is overloaded to call it. Thus, instead of writing print $window->text,"\n";, one can simply write print $window,"\n"; If you want to print out the handle number, write print $window->handle,"\n" or print int($window),"\n".

If the window no longer exists, the method will return undef;

exists

Calls Win32::Setupsup::WaitForWindowClose with a timeout of 1ms to determine whether the window still exists or not. Returns true if the Win32::CtrlGUI::Window object still refers to an existing window, returns false if it does not.

send_keys

The send_keys method sends keystrokes to the window. The first parameter is the text to send. The second parameter is optional and specifies the interval between sending keystrokes, in milliseconds.

If the window no longer exists, this method will die with the error "Win32::CtrlGUI::Window::send_keys called on non-existent window handle handle."

I found the SendKeys syntax used by Win32::Setupsup to be rather unwieldy. I missed the syntax used in WinBatch, so I implemented a conversion routine. At the same time, I extended the syntax a little. I think you'll like the result.

The meta-characters are:

!

Holds the Alt key down for the next character

^

Holds the Ctrl key down for the next character

+

Holds the Shift key down for the next character

{ and }

Used to send special characters, sequences, or for sleeping

The !, ^, and + characters can be combined. For instance, to send a Ctrl-Shift-F7, one uses the sequence ^+{F7}.

The special characters sendable using the curly braces are:

  Alt         {ALT}
  Backspace   {BACKSPACE} or {BS} or {BACK}
  Clear       {CLEAR}
  Delete      {DELETE} or {DEL}
  Down Arrow  {DOWN} or {DN}
  End         {END}
  Enter       {ENTER} or {RET}
  Escape      {ESCAPE} or {ESC}
  F1->F12     {F1}->{F12}
  Help        {HELP}
  Home        {HOME} or {BEG}
  Insert      {INSERT} or {INS}
  Left Arrow  {LEFT}
  NumKey 0->9 {NUM0}->{NUM9}
  NumKey /*-+ {NUM/} or {NUM*} or {NUM-} or {NUM+}
  Page Down   {PGDN}
  Page Up     {PGUP}
  Right Arrow {RIGHT}
  Space       {SPACE} or {SP}
  Tab         {TAB}
  Up Arrow    {UP}

  !           {!}
  ^           {^}
  +           {+}
  }           {}}
  {           {{}

If the character name is followed by a space and an integer, the key will be repeated that many times. For instance, to send 15 down arrows keystrokes, use {DOWN 15}. To send 5 asterisks, use {* 5}. This doesn't work for sending multiple number keys (unless you use NUM0 or some such).

Finally, if the contents of the {} block are a number - either integer or floating point, a pause will be inserted at the point. For instance, $window->send_keys("!n{2.5}C:\\Foo.txt{1}{ENTER}") is equivalent to:

  $window->send_keys("!n");
  Win32::Sleep(2500);
  $window->send_keys("C:\\Foo.txt");
  Win32::Sleep(1000);
  $window->send_keys("{ENTER}");

Hope you like the work.

enum_child_windows

Returns a list of the window's child windows. They are, of course, Win32::CtrlGUI::Window objects.

If the window no longer exists, the method will return undef;

has_child

Checks to see whether the window has a child window matching the passed criteria. Same criteria options as found in Win32::CtrlGUI::wait_for_window. Returns 0 or 1.

If the window no longer exists, the method will return undef;

set_focus

Calls Win32::Setupsup::SetFocus on the window. See the Win32::Setupsup::SetFocus documentation for caveats concerning this method.

If the window no longer exists, this method will die with the error "Win32::CtrlGUI::Window::set_focus called on non-existent window handle handle."

get_properties

Calls Win32::Setupsup::GetWindowProperties on the window. Passes the list of requested properties and returns the list of returned values in the same order.

If the window no longer exists, the method will return undef;

get_property

Scalar variant of the above.

set_properties

Calls Win32::Setupsup::SetWindowProperties on the window.

If the window no longer exists, this method will die with the error "Win32::CtrlGUI::Window::set_properties called on non-existent window handle handle."

send_message

This requires Win32::API. This makes the SendMessage API call on the window handle in question. See the Win32 SDK for more information on what messages can be sent to windows and what their effects are.

The passed parameters are:

type

This should be a string consisting of two characters, both of which are either N or P. Pass N if the parameter is of type DWORD and P if the parameter is a string to which a pointer should be passed.

msg

This should be either the numerical value for the message or a string specifying the constant (it will be looked up in a table of known constants, such as WM_GETTEXT and WM_RBUTTONDOWN).

param1 and param2

These will be passed directly into the SendMessage call as the two message parameters.

post_message

This is the PostMessage version of send_message.

get_text

This makes use of the send_message method, and so it also requires Win32::API. It uses the WM_GETTEXT message to retrieve the text of a window or control. This has the advantage of retrieving the text of text boxes. Note that this method will block if called on hung windows.

lb_get_items

This makes use of the send_message method, and so it also requires Win32::API. It uses the LB_GETCOUNT, LB_GETTEXTLEN, and LB_GETTEXT messages to retrieve the text for the items in the list box. Note that this method will block if called on hung windows.

lb_get_selindexes

This makes use of the send_message method, and so it also requires Win32::API. It uses the LB_GETCURSEL, LB_GETSELCOUNT, and LB_GETSELITEMS messages to retrieve the indexes for the selected items in the list box. Note that this method will block if called on hung windows.

lb_set_selindexes

This makes use of the send_message method, and so it also requires Win32::API. It uses the LB_SETCURSEL, LB_GETCOUNT, and LB_SETSEL messages to specify the selected item(s) in the list box.

cb_get_items

This makes use of the send_message method, and so it also requires Win32::API. It uses the CB_GETCOUNT, CB_GETLBTEXTLEN, and CB_GETLBTEXT messages to retrieve the text for the items in the combo box. Note that this method will block if called on hung windows.

cb_get_selindex

This makes use of the send_message method, and so it also requires Win32::API. It uses the CB_GETCURSEL message to retrieve the index for the selected item in the combo box. Note that this method will block if called on hung windows.

cb_set_selindex

This makes use of the send_message method, and so it also requires Win32::API. It uses the LB_SETCURSEL message to specify the selected item in the combo box.

GLOBALS

$Win32::CtrlGUI::Window::sendkey_activate

I couldn't think of any reason that anyone would not want to activate the window before sending it keys (especially given the way this OO front-end works), but if you do find yourself in that situation, change this to 0.

$Win32::CtrlGUI::Window::sendkey_intvl

This global parameter specifies the default interval between keystrokes when executing a send_keys. The value is specified in milliseconds. The send_keys method also takes an optional parameter that will override this value. The default value is 0.

CONFIGURATION AND ENVIRONMENT

Win32::CtrlGUI::Window requires no configuration files or environment variables.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

Toby Ovod-Everett <toby AT ovod-everett.org>

Win32::CtrlGUI is now maintained by Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-Win32-CtrlGUI AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=Win32-CtrlGUI.

You can follow or contribute to Win32-CtrlGUI's development at http://github.com/madsen/win32-ctrlgui.

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Toby Ovod-Everett.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.