The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Win32-CaptureIE-1.30
River stage zero No dependents
++
/ Win32::CaptureIE

NAME

Win32::CaptureIE - Capture web pages or its elements rendered by Internet Explorer

SYNOPSIS

  use Win32::CaptureIE;

  StartIE;
  Navigate('http://my.server/page.html');

  my $img = CaptureElement('tab_user_options');
  $img->Write("ie-elem.png");

  QuitIE;

DESCRIPTION

The package enables you to automatically create screenshots of your web server pages for the user guide or whatever you need it for. The best part is that you don't bother yourself with scrolling and object localization. Just tell the ID of the element and receive an Image::Magick object. The package will do all the scrolling work, it will take the screenshots and glue the parts together.

EXPORT

:default

CaptureArea CaptureBrowser CaptureElement CaptureElements CapturePage CaptureRows CaptureThumbshot GetDoc GetAll GetElement Navigate RunJS PopUp Wait QuitIE Refresh StartIE $Body $CaptureBorder $Doc $HWND_Browser $HWND_IE $IE $PopUp_HWND_Browser $PopUp_HWND_IE $PopUp_IE

Internet Explorer controlling functions

StartIE ( %params )

This function creates a new Internet Explorer process via Win32::OLE. You can specify width and height of the window as parameters.

  StartIE( width => 808, height => 600 );

The function will bring the window to the top and try to locate the child window where the page is rendered. The mouse cursor will be moved to the top left corner of the screen to not interfere with the browser.

QuitIE ( )

Terminates the Internet Explorer process and destroys the Win32::OLE object. Restores the original cursor position.

Loads the specified page and waits until the page is completely loaded. Then it will call GetDoc function.

RunJS ( $script )

Runs the specified JavaScript code in the browser and waits for 1 second.

Opens popup window by calling the code and redirects all other functions to that popup.

See chapter PopUp Handling for more info.

Wait ( [$seconds] )

Waits for specified time (default 1 second) while calling Win32::OLE->SpinMessageLoop to let IE to process the requests.

Refresh ( )

Refreshes the currently loaded page and calls GetDoc function.

GetDoc ( )

Loads $Doc and $Body global variables.

GetAll ( $tagName [, \$code [, $index ]] )

Returns the list of objects of specified tag name or N-th object from the list if $index is specified. The first element in the list has indx 0. The list is composed from document->all collection.

If you specify a code ref it will be used to limit the list in the same way grep does it.

  # get 3rd span element with class=label
  my $label = GetAll('SPAN', sub {$_->{className} eq 'label'}, 2 );
GetElement ( $id )

Returns the object of specified ID by calling document->getElementById().

Capturing functions

These function works like other Capture*(...) functions from Win32::Screenshot package.

CaptureArea ( $px, $py, $w, $h )

Capture selected area on page. The coordinates are relative to the tole left corner of the page. If the area is larger than the window the function will capture the whole area step by step by scrolling the window content (in all directions) and will return a complete image of the page.

CaptureBrowser ( )

Captures whole Internet Explorer window including the window title and border.

CaptureElement ( $id | $element [, \%args ] )

Captures the element specified by its ID or passed as reference to the element object. The function will scroll the page content to show the top of the element and scroll down and right step by step to get whole area occupied by the object.

It can capture a small surrounding area around the element specified by %args hash or $CaptureBorder global variable. It recognizes paramters border, border-left, border-top, border-right and border-bottom. The priority is border-* -> border -> $CaptureBorder.

CaptureElements ( $id1 | $element1, $id2 | $element2, ... [, \%args ] )

Captures all selected elements. The function captures the outter bounding box of all elements in the same way as CaptureElement captures only one.

CapturePage ( )

Captures whole page currently loaded in the Internet Explorer window. Only the page content will be captured - no window, no scrollbars. If the page is smaller than the window only the occupied part of the window will be captured. If the page is longer (scrollbars are active) the function will capture the whole page step by step by scrolling the window content (in all directions) and will return a complete image of the page.

CaptureRows ( $id | $element , @rows )

Captures the table specified by its ID or passed as reference to the table object. The function will scroll the page content to show the top of the table and scroll down and right step by step to get whole area occupied by the table. Than it will chop unwanted rows from the image and it will return the image of table containing only selected rows. Rows are numbered from zero.

It can capture a small surrounding area around the element specified by $CaptureBorder global variable.

CaptureThumbshot ( )

Resizes the window to set the client area to 800x600 pixels. Captures the client area where the page is rendered. No scrolling is done.

Global variables

$CaptureBorder

The function CaptureElement is able to capture the element and a small area around it. How much of surrounding space will be captured is defined by $CaptureBorder. It is not recommended to capture more than 3-5 pixels because parts of other elements could be captured as well. Default border is 1 pixel wide.

$IE

The function StartIE will create a new Internet Explorer process and its Win32::OLE reference will be stored in this variable. See the MSDN documentation for InternetExplorer object.

$Doc

The function GetDoc will assign $IE->{Document} into this variable. See the MSDN documentation for Document object.

$Body

The function GetDoc will assign $IE->{Document}->{Body} into this variable. See the MSDN documentation for BODY object.

$HWND_IE

The function StartIE will assign the handle of the Internet Explorer window into this variable from $IE->{HWND}.

$HWND_Browser

The function StartIE will try to find the largest child window and suppose that this is the area where is the page rendered. It is used to convert page coordinates to screen coordinates.

$PopUp_IE, $PopUp_HWND_IE, $PopUp_HWND_Browser

These variables has similar meaning as their namesakes but are related to the popup window. If $PopUp_IE is defined than all functions use it instead of $IE.

TIPS

Calling JavaScript functions

If you need to call a JavaScript function to get to anoter page or submit the form you can just use Navigate. Note that Win32::CaptureIE::Navigate() waits for page load complete but $IE->Navigate() do not.

  Navigate("javascript:form_submit('approve');");

If you need to wait for a while after the call use RunJS() function.

  RunJS("form_del();");
Capturing only a part of element

To capture only a part of the element set the border to negative values. But do not overdraw it, you still have to have something to capture.

  # capture messages between the toolbar and the 1st fieldset
  $img = CaptureElements('toolbar', GetAll('FIELDSET', 0),
    { border_top => -12, border_bottom => -64 }
  );
Process execution suspending

If you need to make the program sleep for a while do not use in-build sleep() function. Use Wait instead. It will periodically call Win32::OLE->SpinMessageLoop to process any signals comming from OLE interface.

  # wait 2 seconds
  Wait( 2 );

The package can handle capturing of popup window. Only one at a time and you have to spawn the window by using PopUp function. Any new window creation requests are denied by default! You shouldn't be bothered by popups you don't want.

  # get an element named 'clickme'
  my $button = GetElement('clickme');

  # create the popup window by clicking on the 'Click Me' button
  PopUp { $button->click(); };

  # let's capture the content of the popup window
  CapturePage()->Write('popup.png');

  # let's capture the element on the popup window
  CaptureElement('inputline')->Write('popup-inline.png');

  # let's do any other business with the popup window
  ...

  # done, shut it
  RunJS("window.close();");

  # capturing is redirected back to the main window
  CapturePage()->Write('main.png');

SEE ALSO

MSDN

http://msdn.microsoft.com/library You can find there the description of InternetExplorer object and DOM.

Win32::Screenshot

This package is used for capturing screenshots. Use its post-processing features for automatic screenshot modification.

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.