add a readme and example for win32, convert files from Win32 to Unix
[imager-screenshot.git] / Screenshot.pm
index 9cb4cc7..d9192ea 100644 (file)
@@ -27,24 +27,53 @@ sub screenshot {
   # lose the class if called as a method\r
   @_ % 2 == 1 and shift;\r
 \r
-  my %opts = (decor => 1, @_);\r
+  my %opts = (decor => 0, display => 0, @_);\r
 \r
   my $result;\r
   if (!@_) {\r
     my $result =\r
-      defined &win32 ? win32(0) :\r
-       defined &x11 ? x11(0) :\r
+      defined &_win32 ? _win32(0) :\r
+       defined &_x11 ? _x11($opts{display}, 0) :\r
           die "No drivers enabled\n";\r
   }\r
   if (defined $opts{hwnd}) {\r
-    defined &win32\r
+    defined &_win32\r
       or die "Win32 driver not enabled\n";\r
-    $result = win32($opts{hwnd}, $opts{decor});\r
+    $result = _win32($opts{hwnd}, $opts{decor});\r
   }\r
   elsif (defined $opts{id}) { # X11 window id\r
-    defined &x11\r
+    defined &_x11\r
       or die "X11 driver not enabled\n";\r
-    $result = x11($opts{id});\r
+    $result = _x11($opts{display}, $opts{id});\r
+  }\r
+  elsif ($opts{widget}) {\r
+    # Perl/Tk widget\r
+    my $top = $opts{widget}->toplevel;\r
+    my $sys = $top->windowingsystem;\r
+    if ($sys eq 'win32') {\r
+      unless (defined &_win32) {\r
+        Imager->_set_error("Win32 Tk and Win32 support not built");\r
+        return;\r
+      }\r
+      $result = _win32(hex($opts{widget}->id));\r
+    }\r
+    elsif ($sys eq 'x11') {\r
+      unless (defined &_x11) {\r
+        Imager->_set_error("X11 Tk and X11 support not built");\r
+        return;\r
+      }\r
+\r
+      my $id_hex = $opts{widget}->id;\r
+      $opts{widget}->can('frame') \r
+        and $id_hex = $opts{widget}->frame;\r
+      \r
+      # is there a way to get the display pointer from Tk?\r
+      $result = _x11(0, hex($id_hex));\r
+    }\r
+    else {\r
+      Imager->_set_error("Unsupported windowing system '$sys'");\r
+      return;\r
+    }\r
   }\r
 \r
   unless ($result) {\r
@@ -56,14 +85,23 @@ sub screenshot {
 }\r
 \r
 sub have_win32 {\r
-  defined &win32;\r
+  defined &_win32;\r
 }\r
 \r
 sub have_x11 {\r
-  defined &x11;\r
+  defined &_x11;\r
+}\r
+\r
+sub x11_open {\r
+  my $display = _x11_open(@_);\r
+  unless ($display) {\r
+    Imager->_set_error(Imager->_error_as_msg);\r
+    return;\r
+  }\r
+\r
+  return $display;\r
 }\r
 \r
-# everything else is XS\r
 1;\r
 \r
 __END__\r
@@ -74,13 +112,101 @@ Imager::Screenshot - screenshot to an Imager image
 \r
 =head1 SYNOPSIS\r
 \r
-  use Imager::Screenshot 'screeshot';\r
+  use Imager::Screenshot 'screenshot';\r
 \r
   # whole screen\r
   my $img = screenshot();\r
 \r
+  # Win32 window\r
+  my $img2 = screenshot(hwnd => $hwnd);\r
+\r
+  # X11 window\r
+  my $img3 = screenshot(display => $display, id => $window_id);\r
+\r
+  # X11 tools\r
+  my $display = Imager::Screenshot::x11_open();\r
+  Imager::Screenshot::x11_close($display);\r
+\r
+  # test for win32 support\r
+  if (Imager::Screenshot->have_win32) { ... }\r
+\r
+  # test for x11 support\r
+  if (Imager::Screenshot->have_x11) { ... }\r
+  \r
+\r
 =head1 DESCRIPTION\r
 \r
+Imager::Screenshot captures either a desktop or a specified window and\r
+returns the result as an Imager image.\r
+\r
+Currently the image is always returned as a 24-bit image.\r
+\r
+=over\r
+\r
+=item screenshot hwnd => I<window handle>\r
+\r
+=item screenshot hwnd => I<window handle>, decor => <capture decorations>\r
+\r
+Retrieve a screenshot under Win32, if I<window handle> is zero,\r
+capture the desktop.\r
+\r
+By default, window decorations are not captured, if the C<decor>\r
+parameter is set to true then window decorations are included.\r
+\r
+=item screenshot id => I<window id>\r
+\r
+=item screenshot id => I<window id>, display => I<display object>\r
+\r
+Retrieve a screenshot under X11, if I<id> is zero, capture the root\r
+window.  I<display object> is a integer version of an X11 C< Display *\r
+>, if this isn't supplied C<screenshot()> will attempt connect to the\r
+the display specified by $ENV{DISPLAY}.\r
+\r
+=item screenshot\r
+\r
+If no parameters are supplied:\r
+\r
+=over\r
+\r
+=item *\r
+\r
+if Win32 support is compiled, return screenshot(hwnd => 0).\r
+\r
+=item *\r
+\r
+if X11 support is compiled, return screenshot(id => 0).\r
+\r
+=item *\r
+\r
+otherwise, die.\r
+\r
+=back\r
+\r
+=item have_win32\r
+\r
+Returns true if Win32 support is available.\r
+\r
+=item have_x11\r
+\r
+Returns true if X11 support is available.\r
+\r
+=item Imager::Screenshot::x11_open\r
+\r
+=item Imager::Screenshot::x11_open I<display name>\r
+\r
+Attempts to open a connection to either the display name in\r
+$ENV{DISPLAY} or the supplied display name.  Returns a value suitable\r
+for the I<display> parameter of screenshot, or undef.\r
+\r
+=item Imager::Screenshot::x11_close I<display>\r
+\r
+Closes a display returned by Imager::Screenshot::x11_open().\r
+\r
+=back\r
+\r
+=head1 LICENSE\r
+\r
+Imager::Screenshot is licensed under the same terms as Perl itself.\r
 \r
 =head1 AUTHOR\r
 \r