/ 
Win32-Screenshot-1.20
River stage one • 2 direct dependents • 2 total dependents
/ Win32::Screenshot

NAME

Win32::Screenshot - Capture and process the screen, window or rectangle

SYNOPSIS

use Win32::Screenshot;

$image = CaptureRect( $x, $y, $width, $height );
$image->Write('screenshot.png');

DESCRIPTION

The package utilizes some Win32 API function and Image::Magick to let you capture the screen, a window or a part of it. The Capture*(...) functions returns a new Image::Magick object which you can easily use to modify the screenshot or to store it in the file. You can define your own post processing handlers and chain them in the list.

There are Perl equivalents of Win32 API functions for working with windows implemented in the package. These functions will allow easy identification of windows on the screen.

Image post-processing

The handler receives a reference to an Image::Magick object. If the handler returns such reference it will be used instead of the input one for further processing. It means that the handler can return completely different image.

The handlers are organized in a list @POST_PROCESS. The item of the list can be a string passed to eval or a code reference. The image will be passed to the handler as $_ for evals or $_[0] for subs.

If you want to modify the list just use push or direct access.

@POST_PROCESS = (
  'ppResize(0.5)',
  sub { $_[0]->Blur(); }
);

Handlers are executed starting with $POST_PROCESS[0]. The function CreateImage calls PostProcessImage function which manages the post-processing list. This function is called from all Capture*(...) functions, you don't have to call it explicitly.

See chapter "Post-processing handlers" for details on build-in handlers.

EXPORT

:default

CaptureRect CaptureScreen CaptureWindow CaptureWindowRect ListChilds ListWindows @POST_PROCESS

:raw

CaptureHwndRect CreateImage JoinRawData PostProcessImage

:pp

ppResize ppOuterGlow

:api

BringWindowToTop FindWindow GetActiveWindow GetClientRect GetCursorPos GetDesktopWindow GetForegroundWindow GetTopWindow GetWindow GetWindowRect GetWindowText IsVisible Minimize Restore ScrollWindow ShowWindow WindowFromPoint

:gw_const

GW_CHILD GW_HWNDFIRST GW_HWNDLAST GW_HWNDNEXT GW_HWNDPREV GW_OWNER

:sw_const

SW_HIDE SW_MAXIMIZE SW_MINIMIZE SW_RESTORE SW_SHOW SW_SHOWDEFAULT SW_SHOWMAXIMIZED SW_SHOWMINIMIZED SW_SHOWMINNOACTIVE SW_SHOWNA SW_SHOWNOACTIVATE SW_SHOWNORMAL

Screen capture functions

All these functions return a new Image::Magick object on success or undef on failure. These function are exported by default.

CaptureRect( $x, $y, $width, $height )

Captures part of the screen. The [0, 0] coordinate is the upper-left corner of the screen. The [$x, $y] defines the the upper-left corner of the rectangle to be captured.

CaptureScreen( )

Captures whole screen including the taskbar.

CaptureWindow( $hwnd | $title )

Captures whole window including title and border. Pass the window handle or the window title as the function parameter. If the parameter is a number it will be used directly as a handle to identify the window, if it's something different a FindWindow( ) function will be utilized to find the handle.

CaptureWindowRect( $hwnd | $title, $x, $y, $width, $height )

Captures a part of the window. Pass the window handle or the window title as the function parameter. If the parameter is a number it will be used directly as a handle to identify the window, if it's something different a FindWindow( ) function will be utilized to find the handle. The [0, 0] coordinate is the upper-left corner of the window. The [$x, $y] defines the the upper-left corner of the rectangle to be captured.

Capturing helper functions

Functions for working with raw bitmap data. These functions are not exported by default, import them with :raw tag.

CaptureHwndRect( $hwnd, $x, $y, $width, $height )

The function captures the part of the screen and returns a list of ($width, $height, $screendata). Where $width and $height are the dimensions of the bitmap in pixels and $screendata is a buffer filled with RGBA (4-bytes) data representing the bitmap (Alpha is always 0xFF).

JoinRawData( $width1, $width2, $height, $raw1, $raw2 )

The function joins two bitmaps of the same height and return the new bitmap data.

CreateImage( $width, $height, $rawdata )

Creates a new Image::Magick object from provided data and calls all listed post-processing handlers. The function returns the processed object.

PostProcessImage( $image )

Calls all listed post-processing handlers. The function returns the processed object.

Post-processing handlers

See Image::Magick for other image processing functions. Typically you can use methods like Label, Quantize and Set to post-process all captured images and then simply Write the image to the file.

push @POST_PROCESS, sub {
  $_[0]->Quantize( colors=>80, dither=>0 );
  $_[0]->Set('quality', 100);
};
ppResize( $ratio )

Resizes the image by the specified ratio. It uses Lanczos filter and default ratio 0.74.

ppOuterGlow( $outercolor, $innercolor, $size )

Draws a glow around the screenshot. If any parameter is undef a default value is used. By default outercolor is white, the innercolor is a color of pixel on position [0, 0] and the glow is 17 pixels wide.

Windows helper functions

These function enumerates all windows and returns a LoH with windows properties.

for ( ListWindows( ) ) {
  printf "%1s %8d x:%-4d y:%-4d w:%-4d h:%-4d %s\n",
    $_->{visible} ? '#' : '-',
    $_->{hwnd},
    @{$_->{rect}},
    $_->{title}
  ;

  for (ListChilds($_->{hwnd})) {
    printf "    %1s %8d x:%-4d y:%-4d w:%-4d h:%-4d %s\n",
      $_->{visible} ? '#' : '-',
      $_->{hwnd},
      @{$_->{rect}},
      $_->{title}
    ;
  }
}

These functions are exported by default.

ListWindows( )

Lists all top windows on the desktop.

ListChilds( $hwnd )

Lists all child windows of the parent top window.

Win32 API functions

Look into Win32 API documentation for more details. These function are not exported by default, import them with :api tag.

WindowFromPoint( $x, $y )

The function retrieves a handle to the window that contains the specified point.

GetForegroundWindow( )

The function returns a handle to the foreground window (the window with which the user is currently working).

GetDesktopWindow( )

The GetDesktopWindow function returns a handle to the desktop window. The desktop window covers the entire screen. The desktop window is the area on top of which all icons and other windows are painted.

GetActiveWindow( )

The function retrieves the window handle to the active window attached to the calling thread's message queue.

GetWindow( $hwnd, GW_* constant )

The GetWindow function retrieves a handle to a window that has the specified relationship (Z-Order or owner) to the specified window

FindWindow( $class, $title )

The FindWindow function retrieves a handle to the top-level window whose class name and window name match the specified strings. This function does not search child windows. This function does not perform a case-sensitive search.

ShowWindow( $hwnd, SW_* constant )

The function sets the specified window's show state.

GetCursorPos( )

The function retrieves the cursor's position, in screen coordinates.

SetCursorPos( $x, $y )

The function moves the cursor to the specified screen coordinates.

GetClientRect( $hwnd )

The function retrieves the coordinates of a window's client area. The client coordinates specify the upper-left and lower-right corners of the client area. Because client coordinates are relative to the upper-left corner of a window's client area, the coordinates of the upper-left corner are (0,0).

GetWindowRect( $hwnd )

The function retrieves the dimensions of the bounding rectangle of the specified window. The dimensions are given in screen coordinates that are relative to the upper-left corner of the screen.

BringWindowToTop( $hwnd )

The function brings the specified window to the top of the Z order. If the window is a top-level window, it is activated. If the window is a child window, the top-level parent window associated with the child window is activated.

GetWindowText( $hwnd )

The function copies the text of the specified window's title bar (if it has one) into a buffer. If the specified window is a control, the text of the control is copied. However, GetWindowText cannot retrieve the text of a control in another application.

IsVisible( $hwnd )

The function retrieves the visibility state of the specified window. Calls IsWindowVisible API function.

GetTopWindow( )

The function examines the Z order of the child windows associated with the specified parent window and retrieves a handle to the child window at the top of the Z order.

Restore( )

The function restores a minimized (iconic) window to its previous size and position; it then activates the window. Calls OpenIcon API function.

Minimize( )

The function minimizes (but does not destroy) the specified window. Calls CloseWindow API function.

ScrollWindow( $hwnd, $dx, $dy )

The function scrolls the contents of the specified window's client area. Calls ScrollWindowEx API function.

SEE ALSO

Win32::GUI

It was a good inspiration for me. I borrowed some code from the module.

Image::Magick

The raw data from the screen are loaded into Image::Magick object. You have a lot of possibilities what to do with the captured image.

MSDN

http://msdn.microsoft.com/library

Win32::CaptureIE

Package that utilizes Win32::Screenshot to capture web pages or its parts rendered by Internet Explorer.

AUTHOR

P.Smejkal, <petr.smejkal@seznam.cz>

COPYRIGHT AND LICENSE

Copyright (C) 2004 by P.Smejkal

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.