In this article, we will describe the method to perform user mode region monitoring of the specified window.
This article will be useful for software developers who need run-time monitoring information about specified window position and its region on Windows OS.
A region is a rectangle, polygon, or ellipse (or a combination of two or more of these shapes) that can be filled, painted, inverted, framed, and used to perform hit testing (testing for the cursor location). In general, the window's region is the set of the rectangles that construct a visible part of the window.
The specified window's region monitoring, for example, can be used in Virtual channels development.
Virtual channels are software extensions that can be used to add functional enhancements to a Remote Desktop Services application. Examples of functional enhancements may include support of the special types of hardware, audio, or other additions to the core functionality provided by the Remote Desktop Services Remote Desktop Protocol (RDP).
To use virtual channels, you should provide the server-side and client-side modules of the virtual channels application. The server-side module can be a user-mode application or a kernel-mode driver. The client-side module should be a DLL.
Client side module as a rule is mstsc add-in. Sometimes such application needs to perform some action at the window's region changes. So we can monitor the server window and send information about its region to the client. On the client we can use the information to get visible parts of the server window.
For example, we need to improve video rendering in the terminal session. We can create some optimal scheme for data transporting from the server to the client and show the movie window on the client side instead of the server. This technique allows user to watch movie as on the local machine. The client video window should be drawn over the server one. But if the server window is partially hidden by some other windows, we should update our client window.
In this article, we present user adopted library to get run-time information about the window region.
Input information: Handle of the window to monitor, time out, observers to hold region and errors notifications.
Output information: Region data structure
RGNDATA, errors reports.
The separate thread starts in the library core. According to timeout, it collects information about the window's region and sends it to the observer. If we get some problems in the thread, we use
NotifyZero() method to send zero size region. Windows region APIs were used to collect this information (see references). Main steps are shown below:
- Get device context:
HDC hDC = ::GetDC(m_window);
- Create empty region:
HRGN hRgn = ::CreateRectRgn(0, 0, 0, 0);
- Copy region of the selected window:
::GetRandomRgn(hDC, hRgn, SYSRGN);
- Determine the size of region data:
DWORD size = GetRegionData(hRgn, 0, 0);
- Reserve buffer:
- Get region data:
RGNDATA * pRgnData =
GetRegionData(hRgn, size, pRgnData)
- Notify client via observer:
Public interface description
Callback interface to send region data to the client code:
virtual void WinEventNotify(const _RGNDATA *) = 0;
Callback interface to inform about errors:
virtual void OnWinEventError(__in const char *) = 0;
This method doesn't work on Windows 7 and higher systems if aero theme is selected.
In aero theme, window region always consists of one rectangle, even if a window is partially hidden by other windows. Windows 7 uses its core mechanism to show only visible parts. So the library will always report about one rectangle in the window region.
How To Use
To use this library, you should create core object and events observers. To create the core, use the next constructor:
IWinRegionObserver * pEventObserver,
DWORD TimeOut = 200
All data will be sent to the application by
In your client code, you can parse region information to determine visible parts of the window, for example. In our test application, we just write the number of rectangles, which construct the window region, to the log file.
MFC dialog-based application was created to demonstrate the library work. The main window of this application is monitored by the library. To see monitoring results, use log file in the sample folder.
For example, let’s suppose that we have a window.
We will use our library to monitor its region rectangles.
In this image, the visible region of the window consists of 1 rectangle.
In the next image, the region still consists of 1 rectangle.
But in the next image, the window region consists of 2 regions.
So, using this library, we can find visible regions and use this information in your program.
Library Build Requirements
BOOST_ROOT - should contain the path to the Boost directory
Preparing Build System
Before building the sample solution from the source code, you should perform several simple preliminary steps. First of all, you should install all the applications specified in the Software section, and set mentioned environment variables.
After that, you should build Boost libraries from the source code. To do this, go to the Boost directory (BOOST_ROOT) and invoke the following two commands one after another:
bjam.exe toolset=msvc --build-type=complete
For more detailed information, see the Boost documentation.
- 4th November, 2010: Initial post