Using Win32::GuiTest

If you want to download this documentation in order to access it, when you are offline, you can get it from here. It is an HTML document, but in one chunk, so it is easier to get. I would like to have it converted to pdf but had no luck trying this, nor I had time to try harder. If you are experienced in converting docbook to pdf let me know.

You have to know perl in order to use this document effectively. As of this writing, there is no GUI or IDE allowing to record and playback automation scripts. Although I consider such tools less useful than it is believed, it is natural to expect that such a tool exists for Win32::GuiTest. Unfortunately such a tool does not exist. I also do not believe that you can be an effective test automator if you do not have programming skills.

For the most recent distributions (and the previous ones) you should look on Source Forge. Released packages contain standard directory structure created by h2xs and files Win32-GuiTest.ppd and Win32-GuiTest.tar.gz which are all that you need for ppm. See ppm documentation for details.

Please read these few comments since they may help you in better understanding of this document. They will also help you to further explore the topic of GUI automation.

I am using a term "Win32" to refer to Windows operating system family : windows 98/NT/2000/XP.

"Win32::GuiTest" refers to perl library.

If you read a description of a function and you find a sentence "This is a simple wrapper around Win32 function" that means that you can find more details on how the function works on Microsoft's MSDN. I intentionally refrained from providing a link for a function description, since it tends to change every 1-2 years. But if you enter www.msdn.com and make a search for a function, for example "SetForegroundWindow", you should get API description as a first result.

If you have further questions about how to use Win32::GuiTest or have some problem, which you don't know how to solve, please search perlguitest group at yahoo: http://groups.yahoo.com/group/perlguitest. Some obvious questions like "is Win32::GuiTest suitable for java (it isn't)" has been answered many, many times, so please spend this 5 minutes for doing a simple search.

If you can't find an answer, then post your question.

Please do not start by sending a question to me directly. If it is a simple question I will simply ignore it. If it is not a simple question I may consider helping you, but there is a cost involved. I am a busy person, and I am reluctant in doing somebody's else homework. However, I would love to see Win32::GuiTest being popular and widely used. Important factor in increasing software popularity is a good portfolio. And this is the price you will have to pay. If you want my bigger involvement in your specific problem I want you to write an article on how you use Win32::GuiTest in your company or at least providing me with some materials, which would allow me to write this article. And I will expect you to testify, that this is true. I think such an agreement is beneficial for all of us. The more popular the tool is, the more likely you are to get help next time you have a problem. Secondly, your company image will gain. Using Open Source is trendy, and you will look really smart if you show that instead of spending tons of dolars on comercial tools you could get the same value for free.

You may just read the tutorial. It should give a good understanding of how is GUI automation implemented. But it would be much more effective if you practice all examples, which are given in this document. In order to do it, you should have the following software in place:

Although it is not always true we can say that generally, all windows which are opened on your screen are system objects. Win32 keeps track of them and can give information about them. Let's practice from the very beginning. Launch the calculator application available in Win32 systems. On my machine it looks like this:

If it does not look like this on your machine, go to "View" menu in Calculator and choose "standard". Although keeping "scientific" will not do any harm, using the standard version will help us avoid confusion.

Now run WinSpy.

Click the "Full screen" button as shown above...

and then "More" to get the window given below:

On the right side, you can see a tree, reminding a tree of catalogs. Find an item, which is named exactly in the same way, as your Calculator window. The title of the window, also called caption is placed here. In my case it is "Calculator". If you use Win32 with different language, the title may differ. Whatever the title, try to find an item with this title in WinSpy tree.

Got it? Now place Calculator and WinSpy in a way that they don't overlap so you can see them both. Click on the item you've just found in WinSpy and click "Flash" button in the bottom right corner of WinSpy window. Did you notice that? Borders of Calculator were blinking for a moment. This feature helps you to make sure that the item from the tree relates to the right window. Try to experiment with other items. Go to the top of the tree. Choose "Desktop window" item. Click "Flash". Frame of the the whole screen blinks. Try with other items as well.

Once you played a little bit, we can come back to Calculator.

Imagine that you want to automate the following scenario:

It requires that you press the following keys: 2, +, 5 and =.

If a user want to do such an operation on Calculator, he/she has to do the following:

Actually, in the step one, clicking on the opened application (or using Alt-Tab to switch to this application) is a way of doing something important. You move the "input focus" to Calculator. In Win32, window needs to have a focus in order to receive all input from the keyboard. When you have several applications opened, and you type something, only one application, this with the input focus, actually react on what you type.

OK. We have prepared the first test case scenario. Let's write a perl script, which will do it for us. Let's assume that Calculator application is opened when the perl script starts.

Firstly the script has to move the input focus to Calculator. But which window is Calculator? And how to manipulate this window?

We will need to use the function FindWindowLike:

    use Win32::GuiTest qw( FindWindowLike );
    use strict;
    my @whnds = FindWindowLike( undef, "^Calculator" );
    if( !@whnds ){
        die "Cannot find window with title/caption Calculator\n";
    }else{
        printf( "Window handle of calculator application is %x\n", $whnds[ 0 ] );
    }

Of course, if you are using Win32 for different language (like Polish), You will have to change the search title to the right one ("Kalkulator" for Polish).

FindWindowLike returns a list of window handles. Window handle uniquely identifies a window in the system. In any time, there could be only one window with the given window handle, which is a long number.

Why does it return a list? We want only one window, don't we? FindWindowLike is a flexible function, which allows to specify search conditions for the group of windows. In that case, it will return handles of all windows, which satisfy these conditions. In our call, we specify that we are looking for a window with title "Calculator". In most cases only Calculator window will match. However, if there is another window opened which contains "Calculator" string in its title, its handle will also be returned. The second parameter of FindWindowLike function is treated as a regular expression to match with all windows' titles.

Try to run it now. If your calculator application is opened you should get something like:

Window handle of calculator application is 103B6 (hex). Note that it matches the window handle shown by WinSpy on the picture above. Remember - WinSpy shows most of numbers in hexadecimal notation. For perl, the default notations is decimal. Keep that in mind while looking for reasons, why perl script does not display the handle displayed by WinSpy.

So we have found the window. Now we have to move focus to the window and then type the right keys.

We move focus using function SetForegroundWindow. And we send keys using SendKeys.

Our script will look like this:

    use Win32::GuiTest qw( FindWindowLike
                           SetForegroundWindow
                           SendKeys );
    use strict;
    my @whnds = FindWindowLike( undef, "^Calculator" );
    if( !@whnds ){
        die "Cannot find window with title/caption Calculator\n";
    }else{
        printf( "Window handle of calculator application is %x\n", $whnds[ 0 ] );
    }

    SetForegroundWindow( $whnds[ 0 ] );
    SendKeys( "2{+}5=" );

SetForegroundWindow takes a handle to a window, which should receive the input focus. The SendKeys sends the keys to the window, which has the input focus. "+" has a special meaning for SendKeys so it has to be taken in braces.

Let's try. When you run the script, the Calculator's window will move to front and then it will display "7" (before it displays "7", it will also display "2" and "5", however it would be done so quickly, that you will not notice that).

That was easy. Let's go a step further. You can input data into Calculator in 2 ways - by keyboard or by clicking the right buttons on calculator's panel. It's time to test the second way of using Calculator.

Have a look at WinSpy again. Notice that Calculator item in WinSpy tree has a plus. Plus suggests that you can expand an item and find something more in it. Let's do it.

You can see more items. What are they? Well, check it yourself. Try to highlight them and see what blinks. You will quickly realize that these items are Calculator's buttons and display. They are windows too! Windows, which have some characteristics different from Calculator's main window, but they are windows.

Find the window, which is a "2" button. Click it. Look what WinSpy says about it. It gives you the window handle. It also display information about control id.

Each window has a control id. It does not have any particular meaning for main windows, however, it does for windows, which belong to other window (are children of other window). Such windows (belonging to other window) are also called controls. Control id is used to uniquely identify child window among other children on the same parent window (this is not always true. It may happen that a parent have several children with the same id). Find all buttons we need and write down their control ids. They should be:

Notice, that control ids are static. This means, they are always the same for each instance of the same application. Control id for "2" button is 7E on my machine and is also 7E on your machine. Control ids are given to controls when the program is designed. They are hard coded in the program. Window handles are not. If they are the same on my pictures and your machine it's a pure accident. Window handles are dynamic. A window is given a handle every time it is created by the system. If 2 instances of the same application are created (say, you will run Calculator twice), they will have totally different set of windows' handles.

Our "buttoned" test will look like this:

You push a button by calling PushChildButton. It takes 2 arguments : window handle of the window on which the button is placed (parent window), and the control id of the button you want to push.

Here is the code:

    use Win32::GuiTest qw( FindWindowLike
                           PushChildButton );
    use strict;
    
    my @whnds = FindWindowLike( undef, "^Calculator" );
    if( !@whnds ){
        die "Cannot find window with title/caption Calculator\n";
    }else{
        printf( "Window handle of calculator application is %x\n", $whnds[ 0 ] );
    }
    PushChildButton( $whnds[ 0 ], 126 ); # Button 2
    PushChildButton( $whnds[ 0 ], 92 );  # Button +
    PushChildButton( $whnds[ 0 ], 129 ); # Button 5
    PushChildButton( $whnds[ 0 ], 112 ); # Button =

Notice that you do not have to move the input focus to Calculator. That's because you specify exactly, which button in which window you want to push.

Run it. Again, Calculator should display 7.

We are now able, to make the script doing typing and pushing for us. The really automated test also requires that the results are automatically checked. So the thing we miss is checking if when adding 2 and 5 Calculator actually displays 7.

We have to go back to WinSpy again. On the very beginning of controls belonging to Calculator, there should be a control of type "Edit". As you may guess, Edit control is also a window, with some special features, like displaying a text. You get the contents of the Edit control by calling WMGetText. It takes as a parameter a window handle of the Edit control. So in order to use it in our code, we have to find out a window handle for the Edit control. We actually have to implement finding this handle. We cannot hard code it, since you never know what would be the window handle of any window. But when you have the control id and window handle of a window, which is a parent of the Edit control, you can easily get window handle of that control. The function, which is going to help you is again FindWindowLike.

First the script, then the explanation:

    
    use Win32::GuiTest qw( FindWindowLike
                           PushChildButton
                           WMGetText );
    use strict;

    my @whnds = FindWindowLike( undef, "^Calculator" );
    if( !@whnds ){
        die "Cannot find window with title/caption Calculator\n";
    }else{
        printf( "Window handle of calculator application is %x\n", $whnds[ 0 ] );
    }
    PushChildButton( $whnds[ 0 ], 126 ); # Button 2
    PushChildButton( $whnds[ 0 ], 92 );  # Button +
    PushChildButton( $whnds[ 0 ], 129 ); # Button 5
    PushChildButton( $whnds[ 0 ], 112 ); # Button =

    my $edit_ctrl_id = 403; #Edit window, 193 Hex
    my @edit = FindWindowLike( $whnds[ 0 ], undef, "^Edit", $edit_ctrl_id );
    if( !@edit ){
        die "Cannot find window handle for Edit control\n";
    }else{
        printf( "Edit window handle is %x\n", $edit[ 0 ] );
    }
    my $result = WMGetText( $edit[ 0 ] );
    if( $result != 7 ){
        print "Test failed. The result is $result and expected value was 7\n";
    }else{
        print "Success. The result is $result, which is as expected\n";
    }

Note, that in the second call of FindWindowLike you don't have to give "^Edit" regular expression as a class name. Parent window and control id, in that particular situation, is enough. But we will use this redundancy as a fuse.

As you can see, the only thing we add is finding window handle of edit window and then get text from this window. Then the text is compared with the expected value.

You should get something like this:

Note: this time main window handle is different. This is because I closed Calculator and ran it again. As you already know, it was given a different window handle during the second run.

Congratulations! You've done the fully automated GUI test.

As you can see, the basic concepts behind automated GUI testing are not that difficult. However, I have some bad news for you. Gui testing is more complex then it appears after reading this tutorial. The one object - one window pattern is not followed even for some basic controls. One of them is toolbar. If you examine with WinSpy any application containing a toolbar, you will see that WinSpy sees only one window - the toolbar. Buttons on the toolbar are not separate windows. So you can't work with a toolbar in a way you did with calculator. We need to use some more sophisticated mechanisms.

Also, some types of applications are seen by the system as one window with no children. Java applications behave this way. No matter how many controls they have, they are seen as single window by Win32 (and, what follows, by WinSpy).

But there is still much interesting stuff you can do with Win32::GuiTest perl module.

What you got in this tutorial should be enough to do simple test scripts. However, if you plan to perform some more serious testing of applications, which are more complex than calculator, sooner or later the knowledge from the first part of this tutorial will be insufficient. Have a look at the functions' descriptions in the appendix.

The next part of this tutorial addresses dealing with advanced controls. It is significantly more advanced then the first part of the tutorial. You don't have to understand it in order to be able to do useful/advanced automation using Win32::GuiTest. However, it does address some issues, which may appear useful, when you deal with custom, non-standard controls. It also explains in more detail, how Windows controls work. Although it is not going to answer all your questions, it should give you a background for finding a solution to some problems you will encounter. In order to understand the next part of the tutorial you should have some knowledge (or at least a will to understand) of C, perl (of course) and perl internals. I will do my best to make it simple, but if you have some programming skills it will definitely help.

Fasten your sitbelts...

In general (and this is a pretty good generalization) you communicate with windows by sending messages. Whatever you want from a control (which is a window too) - you send it a message. You send a message using SendMessage function. You can follow the link but I will place a function description here, so it's easier to check:

Message id is integer identifying a command, wParam and lParam are additional command's parameters. Their meaning depends on the command (message id). The important thing to remember is that all parameters are numbers. Some of them can be interpreted as pointers, but they are numbers. The best way to explain it would be an example. Imagine that you want to control and Edit Box control. Again, we will use calculator as an example application. We want to get contents of the display. We have done this already in the first part of the tutorial, but we did that by calling Win32::GuiTest function, which did all the messaging for us. Now we will do it ourselves, in order to better understand how it all works.

You get a contents of an edit box by sending it a message WM_GETTEXT. If you do a search in MSDN you should find a detailed description of WM_GETTEXT (I intentionally refrain from giving you detailed link to message's documentation. Microsoft loves changing things, and documentation in no exception. Whatever link I give you, it will be broken in a year or two). It should look something like this:

If you send such a message then it is expected that 4th parameter is a pointer to the buffer to which the contents of edit box will be copied. If you use C, the code would look something like this:

    int main(int argc, char* argv[])
    {
        HWND hWnd = HWND( 0x204ba );
        char buffer[ 100 ];

        SendMessage( hWnd, WM_GETTEXT, 100, LPARAM( buffer ) );

        printf("The result from Calculator is %s\n", buffer );
        return 0;
    }

If you run it you should get the correct value printed on the screen. Note that you had to provide the window handle of an Edit control. You can get it easily using WinSpy. Implementing the mechanism for finding the window handle in C would take too much time and would distract us from the point.

We have the C code working. Let's quickly write an equivalent in perl:

    use Win32::GuiTest qw( SendMessage );
    use strict;
    # WM_GETTEXT is 0xD
    my $msg_id = 0xd;
    my $hwnd = 0x204ba;
    my $buffer = " " x 100;
    SendMessage( $hwnd, $msg_id, 100, $buffer ); 
    print "The result from Calculator is $buffer\n";

If you are lucky your test script will crash immediately. If not it will continue working, but something bad would happen behind the scenes anyway.

What is wrong with the code? In order to understand the problem we will have to talk a little bit about perl internals. In C code, buffer is a pointer to place in memory where the string is to be stored. In perl, a scalar value $buffer is internally represented as a structure. The structure stores information about the type, and other information and, of course, a pointer to a memory containing the actual value. But perl consider all these internals as something which is not your business. For you, scalar represents a value. So if you pass it to SendMessage it will try convert this value to lParam (which is actually long). Since the scalar is empty, the result of conversion will be 0, and this value will be send as pointer to buffer in which the contents of edit control will be stored. The result of SendMessage will be an attempt to write in address 0, which is rarely the thing you want.

So what shall we do? Shall we use reference to $buffer? No - it will not help, since references are like scalars - perl make them look like references, but behind the scenes there are still some structures involved. What we need is the pointer to the memory where the actual scalar's value is stored. Perl is not very supportive in finding this, but it is possible. You get this pointer using unpack function.

Note however, that perl assumes that you do not deal with it's internals, so it does not do any attempt to assure that such a pointer points to something useful all the time. If for example, you append something to scalar, which will force memory reallocation, the previous pointer will start pointing to nowhere. But if you get this pointer just before the call to SendMessage, the pointer should remain valid. Let's try:

    use Win32::GuiTest qw( SendMessage );
    use strict;
    # WM_GETTEXT is 0xD
    my $msg_id = 0xd;
    my $hwnd = 0x204ba;
    my $buffer = " " x 100;
    my $buf_ptr = pack( 'P', $buffer );
    my $ptr = unpack( 'L!', $buf_ptr );
    SendMessage( $hwnd, $msg_id, 100, $ptr ); 
    print "The result from Calculator is $buffer\n";

This time it worked.

Armed with this knowledge we can immediately jump to dealing with more sophisticated controls like ListView. Note: If you are familiar a little bit with dealing with advanced MS controls, you may consider following code snippets artificial. I will refer to some structures and I will ignore the fact that Microsoft provides some macros which simplifies sending messages. I am doing this only for educational purposes. I am using ListView as good example to illustrate controls internals.

Example of a ListView control is given below

As you see it is a commonly used control. Let's try to get a first item from such a list. If you look in the MSDN documentation you will find that in order to get an a text of an item from the list you have to send it a message LVM_GETITEMTEXT. This is what MSDN says about this message:

As you can see, wParam should be equal to an index of an item to be retrieved. lParam should point to a memory used for data interchange. However, ListView do not use plain character buffer. It uses LVITEM structure instead. LVITEM looks like this:

Not all members have to be populated when getting an item text. One of the fields, which have to populated is pszText. It should be a pointer to a memory, to which an item text will be copied.

How can you use C structures in perl? pack function comes to the rescue here. In order to get a better understanding of pack/unpack functions, read perlpacktut manual page. In short it works this way: physically, C structure is string of bytes. Structure is a notion provided by C, which helps humans to deal with data having several attributes. So if we want to populate a memory in a way that it looks exactly as if a particular C structure is placed there, we have to put contents of all structure's fields in this memory. You can refer to pack documentation, or simply trust me that the code below really sends a structure to a control.

    use Win32::GuiTest qw( :ALL );
    use strict;
    my $hwnd = 0x804ae;
    my $lvitem = "";
    my $item_text = " " x 100;

    $lvitem = pack( "L L L L L L L L L L", 
        0, #mask
        0, #iItem
        0, #iSubItem
        0, #state
        0, #stateMask
        unpack( 'L!', pack( 'P', $item_text ) ), #pszText
        100, #cchTextMax
        0, #iImage
        0, #lParam
        0, #iIndent
    );
    # LVM_GETITEMTEXT is 0x1000 + 45
    SendMessage( $hwnd, 0x1000 + 45, 0, unpack( 'L!', pack( 'P', $lvitem ) ) );
    print "List view item text is $item_text\n";

If you run it and if you are lucky enough, the application which hosts the list view control will crash immediately. If not, you still have good chances that something really bad has happened. But the nature of this problem is different from the problem with Edit control described earlier. If you look at SendMessage documentation you will read that for messages with id below WM_USER (which is 1024) Win32 will do a marshalling. For other messages you have to take care of it yourself. What is marshalling? Marshalling means sending data between processes. Not only bytes, but also objects, structures. Marshalling is not a technique. It is a notion of sending data. As we already know, SendMessage often expects lParam to be a pointer. But physically, lParam is only a long number. If you allocate a memory in process A, allocating function will return you the pointer to this memory in the address space of the calling process (i.e. process A). That's really important to understand. Remember that in Win32 there is no such thing like a global, universal memory addressing method, which would allow process to refer to any place of physical memory (or at least this mechanism is not promptly provided - I don't know. Waiting for your feedback). Each pointer is valid only in address space of one process. So if process A calls SendMessage on window owned by process B and pass a pointer to a memory, this pointer will not be valid in the address space of a process B, which hosts ListView or any other control. OK, so why our first example worked? Because WM_GETTEXT is below 1024. So Win32 did the marshalling itself.

Unfortunately, LVM_GETITEMTEXT, which returns an item from ListView is above WM_USER (1024). So we have to do marshalling ourselves. There are probably many ways of doing this but the most common are the following:

DLL injection using Win32 hooks allows you to intercept calls to some functions in other process and call functions in our process's address space instead. The good coverage of this topic can be found in "Programming Applications for Microsoft Windows, 4th edition" by Jeffrey Richter, chapter 22 "DLL Injection and API Hooking". It is already used in Win32::GuiTest. And it works well. The only disadvantage it has is that if you want to be able to send new messages, you have to make changes in Win32::GuiTest guts and recompile it. So it is not particularly good for experimenting with new controls.

The method I am going to present is based on some interesting mechanism provided by Win32: you can allocate memory in other process address space. Look at the code below:

    #include <windows.h>
    #include <commctrl.h>
    #include <stdio.h>

    int main(int argc, char* argv[])
    {
    
        HWND hWnd = HWND( 0x703F4 );
    
        LVITEM lvitem;
        char buffer[ 200 ];
    
        DWORD pid = 0;
        GetWindowThreadProcessId( hWnd, &pid );
        HANDLE hProcHnd = OpenProcess( PROCESS_ALL_ACCESS, FALSE, pid );
        LPVOID pLVI = VirtualAllocEx( hProcHnd, NULL, sizeof( LVITEM ), 
                       MEM_RESERVE | MEM_COMMIT, PAGE_READWRITE);
        LPVOID pBuffer = VirtualAllocEx( hProcHnd, NULL, 200, 
                       MEM_RESERVE | MEM_COMMIT, PAGE_READWRITE);
    
        lvitem.mask = 0;
        lvitem.iItem = 0;
        lvitem.iSubItem = 0;
        lvitem.state = 0;
        lvitem.stateMask = 0;
        lvitem.pszText = ( char *)pBuffer;
        lvitem.cchTextMax = 200;
        lvitem.iImage = 0;
        lvitem.lParam = 0;
        lvitem.iIndent = 0;
        DWORD copied = 0;
        WriteProcessMemory( hProcHnd, pLVI, &lvitem, sizeof( LVITEM ), &copied );
        SendMessage( hWnd, LVM_GETITEMTEXT, (WPARAM)0, (LPARAM)pLVI );
        ReadProcessMemory( hProcHnd, pBuffer, (LPVOID)buffer, 200, &copied );
        VirtualFreeEx( hProcHnd, pBuffer, 0, MEM_RELEASE );
        VirtualFreeEx( hProcHnd, pLVI, 0, MEM_RELEASE );
        printf( "The item is %s\n", buffer );
        return 0;
    }

This time it worked.

Let me now explain the program step by step. Firstly we call GetWindowThreadProcessId. It returns a thread id and a process id which owns the window pointed by hWnd. We don't care about the thread id, but we will need process id. In order to manipulate other process's memory, we need a handle to this process. We get a handle to a process by calling OpenProcess and passing process id as a parameter. Then we can start allocating memory. We do it calling VirtualAllocEx. We do it twice - once for LVITEM structure, and second time for the buffer to which a control will copy the item's text. Then we populate a local copy of LVITEM structure with the correct values and we copy it to other process's address space, calling WriteProcessMemory. We are now ready to call SendMessage. We do it, passing it 0 as wParam (first element from the list) and pLVI as a lParam. pLVI is a pointer returned by VirtualAllocEx. This pointer is invalid in address space of process which calls VirtualAllocEx. But it is valid in the address space of the process which hosts the control we interact with. And this is what we want. Fine, but if we can't use the pointer in the calling process, how do we exchange data. How would we access from our process the data returned by the control? Well, we have done this already. ReadProcessMemory and WriteProcessMemory are functions, which allow us to copy data from other process address space to ours and vice versa. Once everything is done, we are good citizens and we free the allocated memory.

And now the equivalent perl code:

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

    my $hwnd = 0x10326; 
    my $lvitem = AllocateVirtualBuffer( $hwnd, 200 );
    my $text_buf = AllocateVirtualBuffer( $hwnd, 200 );
    my $str_buf = pack( "L L L L L L L L L L", 
        0, #mask
        0, #iItem
        0, #iSubItem
        0, #state
        0, #stateMask
        $text_buf->{ 'ptr' }, #pszText
        200, #cchTextMax
        0, #iImage
        0, #lParam
        0, #iIndent );

    WriteToVirtualBuffer( $lvitem, $str_buf );
    #LVM_GETITEMTEXT = 0x1000 + 45
    SendMessage( $hwnd, 0x1000 + 45, 0, $lvitem->{ 'ptr' } );
    my $value = ReadFromVirtualBuffer( $text_buf, 200 );
    $value =~ s/^(\w+)(.*)/$1/;
    FreeVirtualBuffer( $lvitem );
    FreeVirtualBuffer( $text_buf );
    print "The item is $value\n";

This code definitely needs some further explanations. There are few new functions used:

Note: As for now this functions are not a part of a standard distribution. If you are interested in using them, you can get the ppm package from here.

AllocateVirtualBuffer allocates the memory in the address space of a process, which owns the window pointed by handle $hwnd. It returns a reference to a hash, which contains 2 elements: 'process' being a process handle, returned by OpenProcess, and 'ptr', which is an actual pointer to a memory in other process's address space. Then we populate $str_buf string with bytes so it looks in memory exactly like LVITEM structure. Then we copy those bytes to other process's address space (by calling WriteToVirtualBuffer). Then we call SendMessage. And we get the returned data using ReadFromVirtualBuffer function. After we are done, we have to free allocated memory. And this is what is FreeVirtualBuffer function for.

Phew... that what was tough. Don't be frustrated if you did not get it after the first reading. Just read it again, and even better, try to run included example code.

One of the first questions you may ask, after reading this, would be: why should I bother using this if there are already Win32::GuiTest functions for manipulating List View? The answer is: you shouldn't. Existing Win32::GuiTest functions work pretty well, so there is no need to reinvent the wheel. I used List View in my example, because it is commonly available control, so any one can experiment with this.

You should consider using the method described above if you would like to send some less common messages to common controls. Or if you have a control from a third party (like winwidgets for example).

In order to do anything to any window you have to know it is window handle. Window handle is an integer number, which uniquely identifies a window in a system. If you have a look at Windows API you will notice, that most of functions operating on windows, require window handle of a window they are about to operate. The are 2 functions for finding windows handle in Win32::GuiTest:

Functions in this section apply to virtually every window

Funtions in this section are helpful when dealing with process related issues

This sections contains functions, which perform operations common for controls

The following controls are considered a common controls:

All controls, which are not common are described in this section.