Imager::Screenshot - screenshot to an Imager image
use Imager::Screenshot 'screenshot'; # whole screen my $img = screenshot(); # Win32 window my $img2 = screenshot(hwnd => $hwnd); # X11 window my $img3 = screenshot(display => $display, id => $window_id); # X11 tools my $display = Imager::Screenshot::x11_open(); Imager::Screenshot::x11_close($display); # test for win32 support if (Imager::Screenshot->have_win32) { ... } # test for x11 support if (Imager::Screenshot->have_x11) { ... }
Imager::Screenshot captures either a desktop or a specified window and returns the result as an Imager image.
Currently the image is always returned as a 24-bit image.
Retrieve a screenshot under Win32, if window handle is zero, capture the desktop.
By default, window decorations are not captured, if the decor parameter is set to true then window decorations are included.
decor
Retrieve a screenshot under X11, if id is zero, capture the root window. display object is a integer version of an X11 Display * , if this isn't supplied screenshot() will attempt connect to the the display specified by $ENV{DISPLAY}.
Display *
screenshot()
Note: taking a screenshot of a remote display is slow.
Retrieve a screenshot of a Tk widget, under Win32 or X11, depending on how Tk has been built.
If Tk was built for X11 then the display parameter applies.
If Tk was built for Win32 then the decor parameter applies.
If no id, hwnd or widget parameter is supplied:
id
hwnd
widget
if Win32 support is compiled, return screenshot(hwnd => 0).
if X11 support is compiled, return screenshot(id => 0).
otherwise, die.
You can also supply the following parameters to retrieve a subset of the window:
left
top
right
bottom
If left or top is negative, then treat that as from the right/bottom edge of the window.
If right ot bottom is zero or negative then treat as from the right/bottom edge of the window.
So setting all 4 values to 0 retrieves the whole window.
# a 10-pixel wide right edge of the window my $right_10 = screenshot(left => -10, ...); # the top-left 100x100 portion of the window my $topleft_100 = screenshot(right => 100, bottom => 100, ...); # 10x10 pixel at the bottom right corner my $bott_right_10 = screenshot(left => -10, top => -10, ...);
If screenshot() fails, it will return nothing, and the cause of the failure can be retrieved via Imager->errstr, so typical use could be:
my $img = screenshot(...) or die Imager->errstr;
Returns true if Win32 support is available.
Returns true if X11 support is available.
Attempts to open a connection to either the display name in $ENV{DISPLAY} or the supplied display name. Returns a value suitable for the display parameter of screenshot, or undef.
Closes a display returned by Imager::Screenshot::x11_open().
screenshot() sets a number of tags in the images it returns, these are:
ss_left - the distance between the left side of the window and the left side of the captured area. The same value as the left parameter when that is positive.
ss_top - the distance between the top side of the window the top side of the captured area. The same value at the top parameter when that is positive.
ss_window_width - the full width of the window.
ss_window_height - the full height of the window.
ss_type - the type of capture done, either "Win32" or "X11".
To cheaply get the window size you can capture a single pixel:
my $im = screenshot(right => 1, bottom => 1); my $window_width = $im->tags(name => 'ss_window_width'); my $window_height = $im->tags(name => 'ss_window_height');
It's possible to have more than one grab driver available, for example, Win32 and X11, and which is used can have an effect on the result.
Under Win32, if there's a screesaver running, then you grab the results of the screensaver.
Grabbing the root window on a rootless server (eg. Cygwin/X) may not grab the background that you see. In fact, when I tested under Cygwin/X I got the xterm window contents even when the Windows screensaver was running. The root window captured appeared to be that generated by my window manager.
Grabbing a window with other windows overlaying it will capture the content of those windows where they hide the window you want to capture. You may want to raise the window to top. This may be a security concern if the overlapping windows contain any sensitive information - true for any screen capture.
Imager::Screenshot is licensed under the same terms as Perl itself.
Future plans include:
OS X support - I need to find out which APIs to use to do this. I found some information on the APIs used for this, but don't have a Mac I can test on.
window name searches - currently screenshot() requires a window identifier of some sort, it would be more usable if we could supply some other identifier, either a window title or a window class name.
Tony Cook <tonyc@cpan.org>
To install Imager::Screenshot, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Imager::Screenshot
CPAN shell
perl -MCPAN -e shell install Imager::Screenshot
For more information on module installation, please visit the detailed CPAN module installation guide.