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

  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.

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.

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.

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

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.

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.

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;

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;

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

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;

Scalar variant of the above.

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

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.

This is the PostMessage version of 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.

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.

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.

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.

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.

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.