Revision: 4492
Author: robotframework
Date: Thu Dec 9 08:23:22 2010
Log: regen
http://code.google.com/p/robotframework/source/detail?r=4492
Modified:
/trunk/doc/libraries/Screenshot.html
=======================================
--- /trunk/doc/libraries/Screenshot.html Tue Dec 7 13:13:50 2010
+++ /trunk/doc/libraries/Screenshot.html Thu Dec 9 08:23:22 2010
@@ -92,18 +92,39 @@
supported
<h2 id="introduction">Introduction</h2>
-<p>A test library for taking full-screen screenshots of the desktop.<br />
+<p>A test library for taking screenshots and embedding them into log
files.<br />
<br />
-<span class="name">Screenshot</span> is Robot Framework's standard library
that provides keywords to capture and store screenshots of the whole
desktop.<br />
+<b>Using with Jython</b><br />
<br />
On Jython this library uses Java AWT APIs. They are always available and
thus no external modules are needed.<br />
<br />
-On Python you need to have one of the following modules installed to be
able to use this library:<br />
+<b>Using with Python</b><br />
+<br />
+On Python you need to have one of the following modules installed to be
able to use this library. The first module that is found will be used.<br />
+<br />
- wxPython :: <a href="http://wxpython.org";>http://wxpython.org</a> ::
Required also by RIDE so many Robot Framework users already have this
module installed.<br />
- PyGTK :: <a href="http://pygtk.org";>http://pygtk.org</a> :: This module
is available by default on most Linux distributions.<br />
- Python Imaging Library (PIL) :: <a
href="http://www.pythonware.com/products/pil";>http://www.pythonware.com/products/pil</a> ::
This module can take screenshots only on Windows.<br />
<br />
-The support for using this library on Python was added in Robot Framework
2.5.5.</p>
+Python support was added in Robot Framework 2.5.5.<br />
+<br />
+<b>Where screenshots are saved</b><br />
+<br />
+By default screenshots are saved into the same directory where the Robot
Framework log file is written. If no log is created, screenshots are saved
into the directory where the XML output file is written.<br />
+<br />
+It is possible to specify a custom location for screenshots using <span
class="name">screenshot_directory</span> argument in <a href="#importing"
class="name">importing</a> and <a href="#Set Screenshot Directory"
class="name">Set Screenshot Directory</a> keyword during execution. It is
also possible to save screenshots using an absolute path.<br />
+<br />
+Note that prior to Robot Framework 2.5.5 the default screenshot location
was system's temporary directory.<br />
+<br />
+<b>Changes in Robot Framework 2.5.5</b><br />
+<br />
+This library was heavily enhanced in Robot Framework 2.5.5 release. The
changes are listed below and explained more thoroughly in affected
places.<br />
+<br />
+- The support for using this library on Python (see above) was added.<br />
+- The default location where screenshots are saved was changed (see
above).<br />
+- New <a href="#Take Screenshot" class="name">Take Screenshot</a> and <a
href="#Take Screenshot Without Embedding" class="name">Take Screenshot
Without Embedding</a> keywords were added. These keywords should be used
for taking screenshots in the future. Other screenshot taking keywords will
be deprecated and removed later.<br />
+- <span class="name">log_file_directory</span> argument was deprecated
everywhere it was used.<br />
+</p>
<h2 id="importing">Importing</h2>
<table border="1" class="keywords">
@@ -112,12 +133,10 @@
<th class="doc">Documentation</th>
</tr>
<tr>
- <td class="arg">default_directory=None, log_file_directory=None</td>
- <td class="doc">Screenshot library can be imported with optional
arguments.<br />
+ <td class="arg">screenshot_directory=None,
log_file_directory=DEPRECATED</td>
+ <td class="doc">Configure where screenshots are saved.<br />
<br />
-If the <span class="name">default_directory</span> is provided, all the
screenshots are saved into that directory by default. Otherwise the default
location is the system temporary directory.<br />
-<br />
-<span class="name">log_file_directory</span> is used to create relative
paths when screenshots are logged. By default the paths to images in the
log file are absolute.<br />
+If <span class="name">screenshot_directory</span> is not given,
screenshots are saved into same directory as the log file. The directory
can also be set using <a href="#Set Screenshot Directory" class="name">Set
Screenshot Directory</a> keyword.<br />
<br />
Examples (use only one of these):<br />
<br />
@@ -132,23 +151,17 @@
<td>Library</td>
<td>Screenshot</td>
<td></td>
-<td></td>
+<td># Default location</td>
</tr>
<tr>
<td>Library</td>
<td>Screenshot</td>
-<td>${CURDIR}/images</td>
-<td></td>
-</tr>
-<tr>
-<td>Library</td>
-<td>Screenshot</td>
-<td>${OUTPUTDIR}</td>
-<td>${OUTPUTDIR}</td>
+<td>${TEMPDIR}</td>
+<td># System temp (this was default prior to 2.5.5)</td>
</tr>
</table>
<br />
-It is also possible to set these directories using <a href="#Set
Screenshot Directories" class="name">Set Screenshot Directories</a>
keyword.</td>
+<span class="name">log_file_directory</span> has been deprecated in 2.5.5
release and has no effect. The information provided with it earlier is
nowadays got automatically. This argument will be removed in the 2.6
release.</td>
</tr>
</table>
@@ -160,7 +173,13 @@
·
<a href="#Save Screenshot To" title="Saves a screenshot to the specified
file.">Save Screenshot To</a>
·
-<a href="#Set Screenshot Directories" title="Used to set
`default_directory` and
`log_file_directory`.">Set Screenshot Directories</a>
+<a href="#Set Screenshot Directories" title="*DEPRECATED* Use `Set
Screenshot Directory` keyword
instead.">Set Screenshot Directories</a>
+ ·
+<a href="#Set Screenshot Directory" title="Sets the directory where
screenshots are saved.">Set Screenshot Directory</a>
+ ·
+<a href="#Take Screenshot" title="Takes a screenshot and embeds it into
the log file.">Take Screenshot</a>
+ ·
+<a href="#Take Screenshot Without Embedding" title="Takes a screenshot and
links it from the log
file.">Take Screenshot Without Embedding</a>
</div>
<h2>Keywords</h2>
@@ -172,67 +191,97 @@
</tr>
<tr>
<td class="kw"><a name="Log Screenshot"></a>Log Screenshot</td>
- <td class="arg">basename=screenshot, directory=None,
log_file_directory=None, width=100%</td>
+ <td class="arg">basename=screenshot, directory=None,
log_file_directory=DEPRECATED, width=100%</td>
<td class="doc">Takes a screenshot and logs it to Robot Framework's log
file.<br />
<br />
-Saves the files as defined in the keyword <a href="#Save Screenshot"
class="name">Save Screenshot</a> and creates a picture to Robot Framework's
log. <span class="name">directory</span> defines the directory where the
screenshots are saved. By default, its value is <span
class="name">default_directory</span>, which is set at the library import
or with the keyword <a href="#Set Screenshot Directories" class="name">Set
Screenshot Directories</a>. <span class="name">log_file_directory</span> is
used to create relative paths to the pictures. This allows moving the log
and pictures to different machines and having still working pictures. If
<span class="name">log_file_directory</span> is not given or set (in the
same way as <span class="name">default_directory</span> is set), the paths
are absolute.<br />
+<b>This keyword is obsolete.</b> Use <a href="#Take Screenshot"
class="name">Take Screenshot</a> or <a href="#Take Screenshot Without
Embedding" class="name">Take Screenshot Without Embedding</a> instead. This
keyword will be deprecated in Robot Framework 2.6 and removed later.<br />
<br />
-The path where the screenshot is saved is returned.</td>
+<span class="name">log_file_directory</span> has been deprecated in 2.5.5
release and has no effect. The information provided with it earlier is
nowadays got automatically.</td>
</tr>
<tr>
<td class="kw"><a name="Save Screenshot"></a>Save Screenshot</td>
<td class="arg">basename=screenshot, directory=None</td>
<td class="doc">Saves a screenshot with a generated unique name.<br />
<br />
-The unique name is derived based on the provided <span
class="name">basename</span> and <span class="name">directory</span> passed
in as optional arguments. If a <span class="name">directory</span> is
provided, the screenshot is saved under that directory. Otherwise, the
<span class="name">default_directory</span> set during the library import
or by the keyword <a href="#Set Screenshot Directories" class="name">Set
Screenshot Directories</a> is used. If a <span class="name">basename</span>
for the screenshot file is provided, a unique filename is determined by
appending an underscore and a running counter. Otherwise, the <span
class="name">basename</span> defaults to 'screenshot'.<br />
+<b>This keyword is obsolete.</b> Use <a href="#Take Screenshot"
class="name">Take Screenshot</a> or <a href="#Take Screenshot Without
Embedding" class="name">Take Screenshot Without Embedding</a> instead. This
keyword will be deprecated in Robot Framework 2.6 and removed later.</td>
+</tr>
+<tr>
+ <td class="kw"><a name="Save Screenshot To"></a>Save Screenshot To</td>
+ <td class="arg">path</td>
+ <td class="doc">Saves a screenshot to the specified file.<br />
+<br />
+<b>This keyword is obsolete.</b> Use <a href="#Take Screenshot"
class="name">Take Screenshot</a> or <a href="#Take Screenshot Without
Embedding" class="name">Take Screenshot Without Embedding</a> instead. This
keyword will be deprecated in Robot Framework 2.6 and removed later.</td>
+</tr>
+<tr>
+ <td class="kw"><a name="Set Screenshot Directories"></a>Set Screenshot
Directories</td>
+ <td class="arg">default_directory=None,
log_file_directory=DEPRECATED</td>
+ <td class="doc"><b>DEPRECATED</b> Use <a href="#Set Screenshot
Directory" class="name">Set Screenshot Directory</a> keyword instead.</td>
+</tr>
+<tr>
+ <td class="kw"><a name="Set Screenshot Directory"></a>Set Screenshot
Directory</td>
+ <td class="arg">path</td>
+ <td class="doc">Sets the directory where screenshots are saved.<br />
+<br />
+It is possible to use <span class="name">/</span> as a path separator in
all operating systems. Path to the old directory is returned.<br />
+<br />
+The directory can also be set in <a href="#importing"
class="name">importing</a>.</td>
+</tr>
+<tr>
+ <td class="kw"><a name="Take Screenshot"></a>Take Screenshot</td>
+ <td class="arg">name=screenshot, width=800px</td>
+ <td class="doc">Takes a screenshot and embeds it into the log file.<br />
+<br />
+Name of the file where the screenshot is stored is derived from <span
class="name">name</span>. If <span class="name">name</span> ends with
extension <span class="name">.jpg</span> or <span
class="name">.jpeg</span>, the screenshot will be stored with that name.
Otherwise a unique name is created by adding underscore, a running index
and extension to the <span class="name">name</span>.<br />
+<br />
+The name will be interpreted to be relative to the directory where the log
file is written. It is also possible to use absolute paths.<br />
+<br />
+<span class="name">width</span> specifies the size of the screenshot in
the log file.<br />
<br />
The path where the screenshot is saved is returned.<br />
<br />
-Examples:<br />
+Examples: (LOGDIR is determined automatically by the library)<br />
<table border="1" class="doc">
<tr>
-<td>Save Screenshot</td>
-<td>mypic</td>
-<td>/home/user</td>
+<td>Take Screenshot</td>
+<td></td>
<td># (1)</td>
</tr>
<tr>
-<td>Save Screenshot</td>
+<td>Take Screenshot</td>
<td>mypic</td>
-<td></td>
<td># (2)</td>
</tr>
<tr>
-<td>Save Screenshot</td>
-<td></td>
-<td></td>
+<td>Take Screenshot</td>
+<td>${TEMPDIR}/mypic</td>
<td># (3)</td>
</tr>
+<tr>
+<td>Take Screenshot</td>
+<td>pic.jpg</td>
+<td># (4)</td>
+</tr>
</table>
=><br />
-1. /home/user/mypic_1.jpg, /home/user/mypic_2.jpg, ...<br />
-2. /tmp/mypic_1.jpg, /tmp/mypic_2.jpg, ...<br />
-3. /tmp/screenshot_1.jpg, /tmp/screenshot_2.jpg, ...</td>
-</tr>
-<tr>
- <td class="kw"><a name="Save Screenshot To"></a>Save Screenshot To</td>
- <td class="arg">path</td>
- <td class="doc">Saves a screenshot to the specified file.<br />
+1. LOGDIR/screenshot_1.jpg,LOGDIR/screenshot_2.jpg, ...<br />
+2. LOGDIR/mypic_1.jpg, LOGDIR/mypic_2.jpg, ...<br />
+3. /tmp/mypic_1.jpg, /tmp/mypic_2.jpg, ...<br />
+4. LOGDIR/pic.jpg, LOGDIR/pic.jpg, ...<br />
<br />
-The directory holding the file must exist or an exception is raised.</td>
+Screenshots can be only taken in JPEG format. It is possible to use <span
class="name">/</span> as a path separator in all operating systems.</td>
</tr>
<tr>
- <td class="kw"><a name="Set Screenshot Directories"></a>Set Screenshot
Directories</td>
- <td class="arg">default_directory=None, log_file_directory=None</td>
- <td class="doc">Used to set <span class="name">default_directory</span>
and <span class="name">log_file_directory</span>.<br />
+ <td class="kw"><a name="Take Screenshot Without Embedding"></a>Take
Screenshot Without Embedding</td>
+ <td class="arg">name=screenshot</td>
+ <td class="doc">Takes a screenshot and links it from the log file.<br />
<br />
-See the <a href="#importing" class="name">library importing</a> for
details.</td>
+This keyword is otherwise identical to <a href="#Take Screenshot"
class="name">Take Screenshot</a> but the saved screenshot is not embedded
into the log file. The screenshot is linked so it is nevertheless easily
available.</td>
</tr>
</table>
<p id="footer">
-Altogether 4 keywords.<br />
+Altogether 7 keywords.<br />
Generated by <a
href="http://code.google.com/p/robotframework/wiki/LibraryDocumentationTool";>libdoc.py</a>
-on 2010-12-07 23:13:33.
+on 2010-12-09 18:22:22.
</p>
</body>
</html>
