switch from EXTRA_META to META_MERGE

[imager-screenshot.git] / Screenshot.pm

diff --git a/Screenshot.pm b/Screenshot.pm
index c8ecd4ac50a592d67aabf05e4425bfcfdc850aa5..6f99518d4bb82d4579b4c4841db75fc2e91cbf6f 100644 (file)
--- a/Screenshot.pm
+++ b/Screenshot.pm
@@ -10,7 +10,7 @@ push @ISA, 'Exporter';
 BEGIN {
   require Exporter;
   @ISA = qw(Exporter);
-  $VERSION = '0.004';
+  $VERSION = '0.007';
   eval {
     # try XSLoader first, DynaLoader has annoying baggage
     require XSLoader;
@@ -69,8 +69,6 @@ sub screenshot {
       }
 
       my $id_hex = $opts{widget}->id;
-      $opts{widget}->can('frame') 
-        and $id_hex = $opts{widget}->frame;
       
       # is there a way to get the display pointer from Tk?
       $result = _x11($opts{display}, hex($id_hex), $opts{left}, $opts{top},
@@ -184,9 +182,22 @@ the display specified by $ENV{DISPLAY}.
 
 Note: taking a screenshot of a remote display is slow.
 
+=item screenshot widget => I<widget>
+
+=item screenshot widget => I<widget>, display => I<display>
+
+=item screenshot widget => I<widget>, decor => I<capture decorations>
+
+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.
+
 =item screenshot
 
-If no C<id> or C<hwnd> parameter is supplied:
+If no C<id>, C<hwnd> or C<widget> parameter is supplied:
 
 =over
 
@@ -244,6 +255,11 @@ So setting all 4 values to 0 retrieves the whole window.
   # 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;
+
 =item have_win32
 
 Returns true if Win32 support is available.
@@ -319,10 +335,36 @@ 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.
+
 =head1 LICENSE
 
 Imager::Screenshot is licensed under the same terms as Perl itself.
 
+=head1 TODO
+
+Future plans include:
+
+=over
+
+=item *
+
+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.
+
+=item *
+
+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.
+
+=back
+
 =head1 AUTHOR
 
 Tony Cook <tonyc@cpan.org>