Win32::CtrlGUI::Window - OO interface for controlling Win32 GUI windows
This document describes version 0.32 of Win32::CtrlGUI::Window, released January 10, 2015 as part of Win32-CtrlGUI version 0.32.
use Win32::CtrlGUI my $window = Win32::CtrlGUI::wait_for_window(qr/Notepad/); $window->send_keys("!fx");
Win32::CtrlGUI::Window objects represent GUI windows, and are used to interact with those windows.
Win32::CtrlGUI::Window
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.
_new
This method returns the window's handle. Rarely used because the numification operator for Win32::CtrlGUI::Window is overloaded to call it.
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".
print $window->text,"\n";
print $window,"\n";
print $window->handle,"\n"
print int($window),"\n"
If the window no longer exists, the method will return undef;
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.
Win32::Setupsup::WaitForWindowClose
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.
send_keys
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.
SendKeys
Win32::Setupsup
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
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}.
!
^
+
^+{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).
{DOWN 15}
{* 5}
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{2.5}C:\\Foo.txt{1}{ENTER}")
$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.
Returns a list of the window's child windows. They are, of course, Win32::CtrlGUI::Window objects.
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.
Win32::CtrlGUI::wait_for_window
Calls Win32::Setupsup::SetFocus on the window. See the Win32::Setupsup::SetFocus documentation for caveats concerning this method.
Win32::Setupsup::SetFocus
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."
Calls Win32::Setupsup::GetWindowProperties on the window. Passes the list of requested properties and returns the list of returned values in the same order.
Win32::Setupsup::GetWindowProperties
Scalar variant of the above.
Calls Win32::Setupsup::SetWindowProperties on the window.
Win32::Setupsup::SetWindowProperties
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."
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.
Win32::API
SendMessage
The passed parameters are:
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.
N
P
DWORD
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).
WM_GETTEXT
WM_RBUTTONDOWN
These will be passed directly into the SendMessage call as the two message parameters.
This is the PostMessage version of send_message.
PostMessage
send_message
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.
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_GETCOUNT
LB_GETTEXTLEN
LB_GETTEXT
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_GETCURSEL
LB_GETSELCOUNT
LB_GETSELITEMS
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.
LB_SETCURSEL
LB_SETSEL
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_GETCOUNT
CB_GETLBTEXTLEN
CB_GETLBTEXT
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_GETCURSEL
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.
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.
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.
Win32::CtrlGUI::Window requires no configuration files or environment variables.
None reported.
No bugs have been reported.
Toby Ovod-Everett <toby AT ovod-everett.org>
<toby AT ovod-everett.org>
Win32::CtrlGUI is now maintained by Christopher J. Madsen <perl AT cjmweb.net>
<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.
<bug-Win32-CtrlGUI AT rt.cpan.org>
You can follow or contribute to Win32-CtrlGUI's development at http://github.com/madsen/win32-ctrlgui.
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.
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.
To install Win32::CtrlGUI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::CtrlGUI
CPAN shell
perl -MCPAN -e shell install Win32::CtrlGUI
For more information on module installation, please visit the detailed CPAN module installation guide.