index.xml.in

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY date "February 2009">
  <!ENTITY version "@PACKAGE_VERSION@">
  <!ENTITY application "@PACKAGE_NAME@">
]>
<article id="index" lang="en">

  <!-- Header -->
  <articleinfo>
    <title>Xfce4 Screenshooter</title>

    <pubdate>&date;</pubdate>

    <copyright>
      <year>2008</year>
      <year>2009</year>
      <holder>Jérôme Guelfucci</holder>
    </copyright>

    <copyright>
      <year>2009</year>
      <holder>Sam Swift</holder>
    </copyright>

    <legalnotice id="legalnotice">
      <para>
        Permission is granted to copy, distribute and/or modify this document
        under the terms of the GNU Free Documentation License, Version 1.1 or
        any later version published by the Free Software Foundation; with no
        Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
        Texts. The complete license text is available from the <ulink
        type="http" url="http://www.gnu.org/">Free Software Foundation</ulink>.
      </para>
    </legalnotice>

    <authorgroup>
      <author>
        <firstname>Jérôme</firstname>
        <surname>Guelfucci</surname>
        <affiliation>
          <address><email>jeromeg@xfce.org</email></address>
        </affiliation>
      </author>
      <author>
        <firstname>Sam</firstname>
        <surname>Swift</surname>
        <affiliation>
          <address><email>renmush@gmail.com</email></address>
        </affiliation>
      </author>
    </authorgroup>

    <releaseinfo>
      This manual describes version &version; of Xfce4 Screenshooter.
    </releaseinfo>
  </articleinfo>

  <sect1 id="intro">
    <title>Introduction to Xfce4 Screenshooter</title>

    <para>
      This application allows you to capture the entire screen, the
      active window or a selected region. You can set the delay that
      elapses before the screenshot is taken and the action to be
      performed afterwards: save the screenshot to a PNG file, copy it
      to the clipboard, open it using another application, or host it on
      <ulink type="http" url="http://www.zimagez.com">ZimageZ</ulink>,
      a free online image hosting service.
    </para>

    <para>
      A plugin for the Xfce panel is also available.
    </para>

  </sect1>

  <sect1 id="using-the-application">
    <title>Using the application</title>

    <sect2 id="user-interface">
      <title>Via the user interface</title>

      <para>
        To launch the application, use the "Screenshot" item in the
        "Accessories" category of Xfce's main menu.
      </para>

      <para>
        This window will be displayed:
      </para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/xfce4-screenshooter-dialog1.png" format="PNG"/>
          </imageobject>

          <textobject>
            <phrase>The window of Xfce4 Screenshooter</phrase>
          </textobject>
        </mediaobject>
      </screenshot>

      <sect4 id="region-to-capture">
        <title>Region to capture</title>

        <para>
          The <emphasis>"Region to capture"</emphasis> section allows
          you to set what the screenshot will be taken of:
        </para>

        <itemizedlist>
          <listitem>
            "Entire screen" takes a screenshot of the whole screen as
            you see it.
          </listitem>
          <listitem>
            "Active window" takes a screenshot of the active window.
            This will be the one that was active before this dialog
            appeared, or if you set a delay, the one that is active
            after the delay.
          </listitem>
          <listitem>
            "Select a region" allows you to select a region to be
            captured by clicking and dragging a rectangle over the area
            of screen that you wish to capture, before releasing the
            mouse button.
          </listitem>
        </itemizedlist>
      </sect4>

      <sect4 id="include-pointer">
        <title>Capturing the pointer</title>

        <para>
          The <emphasis>"Capture the mouse pointer"</emphasis>
          option allows you to select whether or not the screenshot will
          include the mouse pointer.
        </para>
      </sect4>

      <sect4 id="delay">
        <title>Delay before capturing</title>

        <para>
          The <emphasis>"Delay before capturing"</emphasis>
          section allows you to set the delay that will elapse between
          pressing the <emphasis>"OK"</emphasis> button and screenshot
          being taken. This delay will allow you to open menus or to
          perform whatever action you require to see displayed in the
          screenshot.
        </para>
      </sect4>
    </sect2>
    
    <sect3 id="after-capturing">
      <title>After capturing</title>
      
      <para>
        After pressing the <emphasis>"OK"</emphasis> button a second
        window will be displayed:
      </para>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/xfce4-screenshooter-dialog2.png" format="PNG"/>
          </imageobject>

          <textobject>
            <phrase>The window of Xfce4 Screenshooter after taking a
            screenshot</phrase>
          </textobject>
        </mediaobject>
      </screenshot>

      <sect4 id="preview">
        <title>Preview</title> 

        <para>
          The <emphasis>"Preview"</emphasis> section displays a
          thumbnail of the screenshot.
        </para>
      </sect4>

      <sect4 id="action">
        <title>Action</title>

        <para>
          The <emphasis>"Action"</emphasis> section allows you to choose
          what should be performed on the screenshot.
        </para>

        <sect5 id="save">
          <title>Save</title>

          <para>
            The <emphasis>"Save"</emphasis> option will save the
            screenshot to a PNG file. A save dialog will be
            displayed. You will be able to set the save location, and
            the name of the file.
          </para>

          <para>
            Xfce4 Screenshooter is also able to save the screenshot to
            any remote file system supported by GVfs, such as FTP, SAMBA,
            SFTP, remote computers accessible via SSH... You just need to
            connect this remote file system using
            <emphasis>gvfs-connect</emphasis> or
            <ulink type="http" url="http://www.uvena.de/gigolo/">Gigolo</ulink>
            and it will be available in the left column of the save dialog.
          </para>
        </sect5>

        <sect5 id="copy-to-clipboard">
          <title>Copy to the clipboard</title>

          <para>
            The <emphasis>"Copy to the clipboard"</emphasis> option
            allows you to paste the screenshot in another application,
            such as a word processor. This option is only available when
            a clipboard manager is running.
          </para>
        </sect5>

        <sect5 id="open-with">
          <title>Open with</title>

          <para>
            The <emphasis>"Open with"</emphasis> option saves the
            screenshot to the system's temporary directory and opens it
            with the application chosen from the drop-down list.
            Applications which support images are automatically detected
            and added to the drop-down list.
          </para>
        </sect5>

        <sect5 id="zimagez">
          <title>Host on ZimageZ</title>
          
          <para>
            The <emphasis>"Host on ZimageZ"</emphasis> option allow you
            to host your screenshot on this free online hosting service,
            so that you can share it easily with other people. ZimageZ
            automatically generates a large and a small thumbnail of your
            screenshot, which can be used to create thumbnails pointing
            to the full size screenshot.
          </para>

          <para>
            After pressing the <emphasis>"OK"</emphasis> button, you
            will be shown this dialog:
          </para>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/xfce4-screenshooter-zimagez-login-dialog.png" format="PNG"/>
              </imageobject>

              <textobject>
                <phrase>The dialog to host a screenshot on ZimageZ</phrase>
              </textobject>
            </mediaobject>
          </screenshot>

          <para>
            If you do not have a ZimageZ user name, you will need to create
            one on the <ulink type="http" url="http://www.zimagez.com">
            ZimageZ website</ulink>. Several languages are available on
            this website, you can switch between using the menu up
            right. You must fill all fields of this dialog. Once you
            click the <emphasis>"OK"</emphasis> button, the upload will
            start.
          </para>
          
          <para>
            The dialog below will give you the links to the full size
            screenshot, the large thumbnail, the small thumbnails, as
            well examples of HTML and BBcode to create a thumbnail
            pointing to the full size screenshot:
          </para>

          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="images/xfce4-screenshooter-zimagez-result-dialog.png" format="PNG"/>
              </imageobject>

              <textobject>
                <phrase>The dialog giving the links to your screenshot on ZimageZ</phrase>
              </textobject>
            </mediaobject>
          </screenshot>

        </sect5>
      </sect4>
    </sect3>

    <sect2 id="command-line">
      <title>Via command line</title>

      <para>
        Command line options allow you to take screenshots quickly. They
        also allow you to configure the Print Screen key on the upper
        right of most keyboards so that it takes screenshots. To do so,
        configure the key-bindings of your desktop environment so that
        it launches xfce4-screenshooter with one or several of the
        following options when the Prt Scrn key is pressed.
      </para>

      <sect3 id="options">
        <title>The command line options</title>

        <sect4 id="w-option">
          <title>The -w option</title>

          <para>
            The <emphasis>-w</emphasis> option allows you to take a
            screenshot of the active window.
          </para>
        </sect4>

        <sect4 id="f-option">
          <title>The -f option</title>

          <para>
            The <emphasis>-f</emphasis> option allows you to take a
            screenshot of the entire screen.
          </para>
        </sect4>

        <sect4 id="r-option">
          <title>The -r option</title>

          <para>
            The <emphasis>-r</emphasis> option allows you to select a
            region to be captured by clicking and dragging a rectangle
            over the area of screen that you wish to capture, before
            releasing the mouse button.
          </para>
        </sect4>

        <sect4 id="d-option">
          <title>The -d option</title>

          <para>
            The <emphasis>-d</emphasis> option followed by a positive
            integer allows you to set the delay before taking the
            screenshot when the <emphasis>-w</emphasis>, the
            <emphasis>-f</emphasis> or the <emphasis>-r</emphasis>
            option is given.
          </para>
        </sect4>

        <sect4 id="s-option">
          <title>The -s option</title>

          <para>
            The <emphasis>-s</emphasis> option followed by the path to
            an existing folder allows you to set where the screenshots
            are saved. This option only has an effect if the
            <emphasis>-w</emphasis>, the <emphasis>-f</emphasis> or
            the <emphasis>-r</emphasis> option is given.
          </para>
        </sect4>

        <sect4 id="o-option">
          <title>The -o option</title>

          <para>
            If the <emphasis>-o</emphasis> option is given, followed by
            an application name, the screenshot will be saved to the
            system's temporary directory and opened with the application
            whose name is to be given after <emphasis>-o</emphasis>.
            This option only has an effect if the
            <emphasis>-w</emphasis>, the <emphasis>-f</emphasis> or the
            <emphasis>-r</emphasis> option is given.
          </para>
        </sect4>

        <sect4 id="u-option">
          <title> The -u option</title>

          <para>
            If the <emphasis>-u</emphasis> option is given, the screenshot
            will be hosted on ZimageZ. See above for more details.
            This option only has an effect if the
            <emphasis>-w</emphasis>, the <emphasis>-f</emphasis> or the
            <emphasis>-r</emphasis> option is given.
          </para>
        </sect4>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="panel-plugin">
    <title>Using the Xfce panel plugin</title>

    <sect2 id="add">
      <title>Adding the plugin</title>

      <para>
        To add the plugin to the panel, right click on the panel and
        select <emphasis>"Add New Item"</emphasis>. Select the plugin
        named <emphasis>"Screenshot"</emphasis>, and add it.
      </para>
    </sect2>

    <sect2 id="set">
      <title>Configuring the plugin</title>

      <para>
        You can configure how screenshots are taken by right clicking on
        the plugin and selecting <emphasis>"Properties"</emphasis>. A
        preferences dialog similar to the dialog of the main application
        will appear. Please have a look above for the different
        preferences.
      </para>
    </sect2>

    <sect2 id="use">
      <title>Using the plugin</title>

      <para>
        To take a screenshot, just click on the plugin. You can use the
        scroll wheel on the plugin button to switch between the different
        regions to be captured.
      </para>
    </sect2>

  </sect1>

</article>