path: root/gnome-users-guide/gnome-users-guide-1.4/C/applets/screenshooter-ug.sgml

  <sect2 id="screenshooter-applet">
   <title>ScreenShooter Applet</title>
 
   <para>
     <application>Screen-Shooter</application> is a handy little 
     screengrabber which is simple to use. It sits in your panel
     and you can click on it to take a screenshot of either the
     whole desktop or just a single window. 
   </para>

   <para>
     To add the applet to your <interface>panel</interface>, you can
     right-click on an empty part of the <interface>panel</interface> 
     and follow the sequence
    <menuchoice>
     <guimenu>Applets</guimenu>
     <guisubmenu>Utility</guisubmenu>
     <guimenuitem>ScreenShooter</guimenuitem>
    </menuchoice>.
   </para>

   <sect3 id="screenshooter-usage">
    <title>Usage</title>
    <itemizedlist>
     <listitem>   
      <para>
        To take a picture of the entire <interface>desktop</interface>,
        left-click on the <guibutton>image of a monitor</guibutton>. This
        button is the lower of the two on a normally-sized horizontal 
        <interface>panel</interface> and the right-hand button on a 
        narrow horizontal <interface>panel</interface> or a vertical
        <interface>panel</interface>.
      </para>
     </listitem>
     <listitem>
      <para>
        To take a picture of just one <interface>window</interface>,
        left-click on the <guibutton>image of a window</guibutton>.
        This button is the top one on a normally-sized horizontal 
        <interface>panel</interface> and the left-hand one on a narrow
        horizontal <interface>panel</interface> or a vertical
        <interface>panel</interface>. The button will stay pressed in
        and the cursor will change to a cross. Move the cursor to the 
        window you want a picture of, and click in that window to select 
        it. 
      </para>
     </listitem>
    </itemizedlist>

    <para>
       Right-clicking on the applet brings up a <guimenu>menu</guimenu>
       containing the usual options for an applet, including a
       <guimenuitem>Properties</guimenuitem> option 
       <link linkend="screenshooter-prefs">described below</link>.
    </para>
   </sect3> 
  
  <sect3 id="screenshooter-prefs">
   <title>Settings</title>
   <para>
     <application>Screen-Shooter</application> can be configured to do
     a number of different things. To configure
     <application>Screen-Shooter</application>, click on the applet
     with mouse button 3 (usually, right mouse button) and select
     <guimenuitem>Properties</guimenuitem> from the
     <guimenu>popup</guimenu> menu. The
     <interface>Preferences</interface> dialogue has seven sections
     described below. Five of these are visible initially: two more
     sections are available from a toggle in the first section. 
   </para>
  </sect3>
 
   <sect3 id="screenshooter-preferences-0">
    <title>General Preferences</title>
 
    <variablelist>
     <varlistentry>
      <term>
        <guilabel>Capture WM decorations when grabbing a window</guilabel>
      </term>
      <listitem>
       <para>
         The <guibutton>capture decorations</guibutton> checkbox controls 
         whether or not the <interface>titlebar</interface> and edges of a 
         <interface>window</interface> are included. It is only relevant
         when <application>Screen-Shooter</application> is taking a 
         picture of a single <interface>window</interface> rather than of
         the whole screen or of a rectangle you have selected. The default is 
         for this to be checked and for the <interface>titlebar</interface>
         and window borders to be included in the shot.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Give audio feedback using the keyboard bell
      </guilabel></term>
      <listitem>
       <para>
         The <guibutton>audio feedback</guibutton> checkbox controls 
         whether or not <application>Screen-Shooter</application> will 
         beep when it actually takes the shot. The default is to beep.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Display spurious options</guilabel></term>
      <listitem>
       <para>
         The <guibutton>spurious options</guibutton> checkbox controls whether
         some of <application>Screen-Shooter</application>'s more esoteric
         options are available. The default is off (i.e., they are not
         available). Checking this option makes two sections called 
         <link linkend="screenshooter-preferences-5">Spurious 1</link> and 
         <link linkend="screenshooter-preferences-6">Spurious 2</link> visible
         in the preferences dialogue.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Delay before taking shot</guilabel></term>
      <listitem>
       <para>
         When taking shots of the <interface>desktop</interface>, you can 
         set a delay between clicking on the
         <application>Screen-Shooter</application> and the shot being taken. 
         The delay can be up to one minute. This can be very useful when you 
         want to focus on a particular <interface>window</interface> or if 
         you want to bring up a <interface>menu</interface>. 
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Compression quality</guilabel></term>
      <listitem>
       <para>
         Compression quality does not refer to how tightly a file is
         compressed, but to how well it retains detail after
         compression. The higher the compression quality, the better
         the quality of the image, but the larger the size of the resulting 
         file. It is relevant when you are saving something as a JPEG,
         a MIFF or a PNG file. The default compression quality is 75&percnt;.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Create monochrome image</guilabel></term>
      <listitem>
       <para>
         A fairly self-explanatory option: if this is selected,
         the resulting image will be in monochrome. This is off by default.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Invert colours in image</guilabel></term>
      <listitem>
       <para>
         Another self-explanatory option: if this is selected, the colours 
         of the image are reversed so that white becomes black, pale purple 
         becomes greenish, and so on. Lovely -- but rarely useful! Off by 
         default.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </sect3>
 
   <sect3 id="screenshooter-preferences-1">
    <title>Files, Apps</title>
 
    <variablelist>
     <varlistentry>
      <term><guilabel>Directory to save file in</guilabel></term>
      <listitem>
       <para>
         The directory to save the shot in must exist already:
         <application>Screen-Shooter</application> will not create
         it for you. If you try to save it to somewhere that does 
         not exist, then no screenshot will be taken. The default 
         directory is <filename>~/</filename>: your home directory.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Filename for images</guilabel></term>
      <listitem>
       <para>
         <application>Screen-Shooter</application> is designed to allow the
	 user maximum flexibility in naming each shot. The filename field
	 (as well as the directory field) is passed to a shell for normal
	 shell expansion before being used. This allows you to use the
	 output of programs, scripts or environment variables to name your
	 shots. The reason for this is to allow unique filenames.
	 By default, Screen-Shooter will create a name which is based on 
         the time and date it was taken: this of course should always be
	 unique. The default filename is 
         <filename>`date +&percnt;Y_&percnt;m_&percnt;d_&percnt;H&percnt;M&percnt;S`_shot.jpg</filename>.
         As you can see, the filename includes the output of the date
	 command in order to generate a datestamp.
         So it makes up a name based on the date, using the format the
         percentage symbols and letters tell it. Then it adds the rest
         of the name from outside the backticks to the date it has used.
         Explanations of the cryptic percentage symbols can be found
         in <command>man date</command>, but the arguments in the
         default filename are:
       </para>
       <variablelist>
        <varlistentry>
         <term>&percnt;H</term>
         <listitem><para>The hour of the day (from 00 to 23)</para></listitem>
        </varlistentry>
        <varlistentry>
         <term>&percnt;M</term>
         <listitem><para>The minute of the hour (from 00 to 59)</para></listitem>
        </varlistentry>
        <varlistentry>
         <term>&percnt;S</term>
         <listitem><para>The second of the minute (from 00 to 60)</para></listitem>
        </varlistentry>
        <varlistentry>
         <term>&percnt;d</term>
         <listitem><para>The day of the month (from 01 to 31)</para></listitem>
        </varlistentry>
        <varlistentry>
         <term>&percnt;m</term>
         <listitem><para>The month of the year (from 01 to 12)</para></listitem>
        </varlistentry>
       <varlistentry>
         <term>&percnt;y</term>
         <listitem><para>The final two digits of the year</para></listitem>
        </varlistentry>
       </variablelist>
 
       <para>
         Other examples of filenames you might use are:
       </para>
       <itemizedlist>
        <listitem>
         <para><filename>screenshot-`date +&percnt;Y&percnt;m&percnt;d-&percnt;H&percnt;M&percnt;S`.jpg</filename></para>
        </listitem>
        <listitem>
         <para><filename>pic-`date +&percnt;H&percnt;M&percnt;S`.png</filename></para>
        </listitem>
	<listitem>
         <para><filename>myshot.jpg</filename></para>
        </listitem>
	<listitem>
         <para><filename>`my_own_script_to_create_a_filename`.jpg</filename></para>
        </listitem>
       </itemizedlist>
 
       <para>
         The filename suffix determines the filetype. Screen-Shooter
	 supports what can only be described as a ridiculous number of
	 different image formats. Try your luck. For a full list, type
	 <command>man convert</command>. You can even try .html to create a
	 client-side image map, and wild things like that.
       </para>
 
       <para>
         If your filename suffix is not something <application>Screen-Shooter
         </application> recognises, or you omit one, it will save the shot as a 
         MIFF file. Use the <command>convert</command> utility to change the
	 format later.
	 </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term>View screenshot after saving</term>
      <listitem>
       <para>
         The <guilabel>view screenshot</guilabel> checkbox is unchecked by 
         default. After checking it, you will get a view of the shot once it 
         has been taken. You need to specify a viewer for this: the default
         is <command>ee</command>, which launches the
         <application>Electric Eyes</application> image viewing program.
       </para>
      </listitem>
     </varlistentry>
 
    </variablelist>
   </sect3>
 
   <sect3 id="screen-shooter-preferences-2">
    <title>Thumbnails</title>
    
    <variablelist>
     <varlistentry>
      <term><guilabel>Create thumbnail of image too</guilabel></term>
      <listitem>
       <para>
         None of the other options on this page will have any effect
         if <guibutton>create thumbnail</guibutton> is not checked. 
         By default, it is off.
       </para>
      </listitem>    
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Thumbnail size</guilabel></term>
      <listitem>
       <para>
         This is the percentage of the original's size that the thumbnail
         will be. The default is 25&percnt;.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Thumbnail compression</guilabel></term>
      <listitem>
       <para>
         This is the quality of compression to use. As with the general
         preferences, the better the quality of the compression, the more
         detail will be preserved, and the bigger the thumbnail will be.
         The default for a thumbnail is 50&percnt;.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Prefix to attach to filename</guilabel></term>
      <listitem>
      <para>
        This is the prefix to attach to the thumbnail filename to distinguish
        it from the full-sized shot. If you leave this blank, the 
        thumbnail will overwrite the full-sized shot and you will lose
        the full-sized one. The default prefix is "thumb-".
      </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
	  <term><guilabel>Use high-quality intermediate for 
	      generating thumbnail</guilabel>
	  </term>
      <listitem>
      <para>
        The <guibutton>high-quality intermediate</guibutton> checkbox is off 
        by default. It generates a MIFF image whilst making the thumbnail. A 
        'lossy' file format refers to a file format where data and detail is 
        irretrievably lost, but which is typically much smaller than a 
        non-lossy format image of the same thing. The typical example of a 
        lossy file format is JPEG. 
      </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </sect3>
 
   <sect3 id="screenshooter-preferences-3">
    <title>Post-Processing</title>
    <note>
     <para>
       These options <emphasis>munch</emphasis> processing power compared
       with the options in previous sections. They work by producing an
       intermediate image of the screenshot, and then performing actions
       upon it. Once any of these options are enabled, the shot will take
       longer to complete, due to the extra processing involved.
     </para>  
    </note>
    
    <variablelist>
     <varlistentry>
      <term><guilabel>Normalize image</guilabel></term>
      <listitem>
      <para>
        The <guibutton>normalize image</guibutton> checkbox transforms the 
        image to span the full range of colour values.
        Default is off.
      </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Equalize image</guilabel></term>
      <listitem>
       <para>
         The <guibutton>equalize image</guibutton> checkbox enables 
         histogram-based image equalization, which is a process which
         compensates for low contrast in an image and brings out more
         detail. Default is off.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Enhance image</guilabel></term>
      <listitem>
       <para>
         The <guibutton>enhance image</guibutton> checkbox tells 
         <application>Screen-Shooter</application> to clean up
	 the image as best it can, and try to remove any noise.
	 Default is off.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Despeckle image</guilabel></term>
      <listitem>
       <para>
         The <guibutton>despeckle image</guibutton> checkbox reduces 
         spotting by removing single pixels which are very different in 
         colour from their surroundings. The default is off.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Sharpen image by factor</guilabel></term>
      <listitem>
       <para>
         Sharpening the image sharpens the image. The default is a factor
	 of zero, but it can be raised to 100&percnt;.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Rotate image clockwise</guilabel></term>
      <listitem>
       <para>
         This is how many degrees clockwise to rotate the image. The 
         default is 0: unrotated.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Adjust gamma</guilabel></term>
      <listitem>
       <para>
         The <guibutton>gamma</guibutton> checkbox enables you to adjust the
         gamma. The gamma value is a value to do with the intensity
         of the lightness of an image (and rather complicated). The
         range <application>Screen-Shooter</application> provides is
         from 0.8 to 2.3 with a default of 1.6. This is not a linear
         (straight) scale so you will need to experiment. Lowering the 
         gamma produces a darker image. Raising it produces a lighter one.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </sect3>
 
   <sect3 id="screenshooter-preferences-4">
    <title>Frills</title>
    <variablelist>
     <varlistentry>
      <term><guilabel>Create frame around image</guilabel></term>
      <listitem>
       <para>
         The <guibutton>create frame</guibutton> checkbox is off by default. 
         Checking it produces a frame around the shot taken. This frame is 
         always grey, but <link linkend="screenshooter-authors">Tom 
         Gilbert</link> notes, <quote>if anybody requests it, I'll add 
         options for setting its colour</quote>.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Frame width</guilabel></term>
      <listitem>
       <para>
         This determines the size of the frame in pixels. The range
         is from one pixel to fifty. The default frame is six pixels.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Flip image vertically</guilabel></term>
      <listitem>
       <para>
         This gives a vertical mirror image of the shot. It can be combined
         with the following option. The default is unchecked.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Flip image horizontally</guilabel></term>
      <listitem>
       <para>
         This gives a horizontal mirror image of the shot. It can be combined 
         with the preceding option. The default is unchecked.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Emboss image</guilabel></term>
      <listitem>
       <para>
         Embossing an image produces an image drained of most colour and
         drawn in relief. The default is unchecked.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Send image and thumbnail to...</guilabel></term>
      <listitem>
       <para>
         By placing a script or program name in the box and checking the
         <guibutton>send to</guibutton> checkbox, you can invoke that script 
         or program to be automatically run on the image and thumbnail.
         This could be used to print the image out automatically,
         to invoke a script to catalogue the files, or to add the
         pictures to a website automatically. A sample script for the
         latter is available with <application>Screen-Shooter</application>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </sect3>
 
   <sect3 id="screenshooter-preferences-5">
    <title>Spurious options: part 1</title>
    <note>
      <para>
        Tom Gilbert says, <quote>These options are all just plain silly. But 
        they're fun. So I included them</quote>. They also munch processing 
        power in the same manner as the post-processing options above.
      </para>
    </note>

    <para>
      To make use of any of the options listed in this section and the
      next section, you need to have selected <guibutton>Display spurious
      options</guibutton> in the <link
      linkend="screenshooter-preferences-0">General Preferences</link> 
      section. They will not be available otherwise. 
    </para>

 
    <variablelist>
     <varlistentry>
      <term><guilabel>Blur image</guilabel></term>
      <listitem>
       <para>
         The <guibutton>blur image</guibutton> checkbox is off by default and 
         the blur factor is set to zero. By checking the checkbox and altering
         the blur factor you can blur the image. Even at the highest
         rating (100), a typical font on a typical terminal window is
         still just about decipherable.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Create charcoal effect</guilabel></term>
      <listitem>
       <para>
         The <guibutton>charcoal</guibutton> checkbox is off by default and
         the charcoal factor is set to zero. Charcoaling produces a
         monochrome image with a slight smudginess which increases
         with the charcoal factor. It does not deal with highlighted
         text very well, though. The maximum factor for this is 100.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Find edges</guilabel></term>
      <listitem>
       <para>
         The <guibutton>find edges</guibutton> checkbox is off by default and 
         the factor is set to zero. Using it produces a monochrome image
         where, rather than highlighting areas of different colours, it
         highlights the edges and borders between areas of different
         colour. Very interesting on maps and astronomical photos. The
         maximum factor for this is 100.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Implode image</guilabel></term>
      <listitem>
       <para>
         The <guibutton>implode image</guibutton> checkbox is off by default 
         and the factor is set to zero. Using it warps the resulting 
         screenshot as if a weight had been pressed into the centre of the 
         shot. The maximum factor for this is 100.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </sect3>
 
   <sect3 id="screenshooter-preferences-6">
    <title>Spurious options: part 2</title>
 
    <variablelist>
     <varlistentry>
      <term><guilabel>Create painted effect</guilabel></term>
      <listitem>
       <para>
         The <guibutton>painted effect</guibutton> checkbox is off by default 
         and the radius to paint around each pixel is set to zero. Checking 
         it with a radius of about 5 produces an effect like an Impressionist
         painting. Checking it with a radius of about 50 will eat your
         CPU cycles like mad for ten minutes on a reasonably powerful
         machine. The maximum radius is 100, but you will need either
         a large machine or a lot of patience for that.
       </para>
      </listitem>
     </varlistentry>
   
     <varlistentry>
      <term><guilabel>Solarise image</guilabel></term>
      <listitem>
       <para>
         The <guibutton>solarise</guibutton> checkbox is off by default and 
         the factor is set to zero. Solarising is an effect first noticed 
         in developing photographs from negatives. It results in a 
         negative image with different colouring from that of the
         "inverted colours" option in the general preferences. A
         solarise factor of 5 will produce startling results, but the 
         maximum factor is 100.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Spread image pixels</guilabel></term>
      <listitem>
       <para>
         The <guibutton>spread image</guibutton> checkbox is off by default 
         and the factor is set to zero. The result of spreading the image
         pixels by a radius of about 5 is similar to looking through
         lightly frosted glass; for heavily-frosted glass, try 25.
         The maximum is 100.
       </para>
      </listitem>
     </varlistentry>
 
     <varlistentry>
      <term><guilabel>Swirl pixels</guilabel></term>
      <listitem>
       <para>
         The <guibutton>swirl pixels</guibutton> checkbox is off by default 
         and the factor is set to zero. Swirling the pixels results in a
         distorted image similar to an imploded image except that it 
         swirls around the central point rather than stretching to
         it. A radius of 20 produces an effect like a fairground distorting 
         mirror, only not a mirror-image; 90 a much increased version 
         (although text is still legible); at 180 the entire image is 
         warped; and at the maximum of 360 a spiral effect is created.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </sect3>

  <sect3 id="screenshooter-bugs">
   <title>Known bugs and limitations</title>

   <itemizedlist>
    <listitem>
     <para>
       Often screenshots saved in PNG format show incorrectly in
       <application>Netscape</application> or the <application>GNOME Help 
       Browser</application>. This is due to bugs in Netscape and 
       and GNOME image libraries, not to bugs in 
       <application>Screen-Shooter</application>. You can view such
       screenshots in a different image-viewing program; or you can try 
       changing image compression level in the <link
       linkend="screenshooter-preferences-0">Preferences dialogue box</link>,
       which sometimes helps.
     </para>
    </listitem>
   </itemizedlist>
  </sect3>
       
  <sect3 id="screenshooter-authors">
    <title>Authors</title>
    <para>
      The <application>Screen-Shooter</application> applet was
      written by Tom Gilbert
      (<email>gilbertt@tomgilbert.freeserve.co.uk</email>).  
      Please report bugs in the Screen-Shooter applet to the
      <ulink type="http" url="http://bugs.gnome.org">GNOME bug
      tracking system</ulink>. You can do this by following the
      guidelines on that site or by using
      <application>bug-buddy</application>
      from the command-line. For the package, put gnome-applets.
    </para> 
    <para>
      This manual was written by 
      Telsa Gwynne (<email>telsa@linuxchix.org</email>) and 
      Tom Gilbert (<email>gilbertt@tomgilbert.freeserve.co.uk</email>).
      Please send all comments and suggestions regarding this manual to 
      the <ulink type="http"
      url="http://www.gnome.org/gdp">GNOME Documentation Project</ulink> 
      by sending an email to <email>docs@gnome.org</email>. You can also
      submit comments online by using the <ulink type="http"
      url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status
      Table</ulink>.
    </para>
   </sect3>
  --> 
 </sect2>