<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
 <!ENTITY kappname "&pixie;">
 <!ENTITY % addindex "IGNORE">
 <!ENTITY % English "INCLUDE">
 <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V1.0//EN">
 %ents;

]>

<book lang="&language;">
<bookinfo>
<title>The Pixie Handbook</title>
<authorgroup>
<author>
<firstname>Jon</firstname>
<surname>Fox</surname>
<affiliation><address><email>jon.fox@bigfoot.com</email></address></affiliation>
</author>
</authorgroup>

<copyright>
<year>2001</year>
<holder>Jon Fox</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>08/02/2001</date>
<releaseinfo>1.0.00</releaseinfo>

<abstract>
<para>&pixie; is an image manager for &kde; that can be used as a simple, quick
viewer and editor for images, but it can also be used for managing large
numbers of image <quote>thumbnails</quote>.
</para></abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>Pixie</keyword>
<keyword>image</keyword>
<keyword>viewer</keyword>
<keyword>graphics</keyword>
</keywordset>

&kde-modespec;

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>


<screenshot>
<screeninfo>A screenshot of &pixie;:</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="pixie.png" format="PNG">
</imageobject>
<textobject>
<phrase>Screenshot</phrase>
</textobject>
<caption><para>A Screenshot of &pixie;</para></caption>
</mediaobject>
</screenshot>

<para>&pixie; is an image manager for &kde;.  It can be used as a simple, quick
viewer and editor for images, but it can also be used for managing large numbers
of image <quote>thumbnails</quote>.  It currently offers over 30 image effects
and enhancements, as well as extensive color editing for both image-wide and
individual colors.  Web designers will find &pixie; particularly useful, as it
can play animated &GIF;s and supports transparency.  It also offers quick access
to frequently-used directories, via its <quote>HotList</quote> directory
bookmarking feature.</para>

</chapter>

<chapter id="getting-started">
<title>Getting Started</title>

<para>Like most &kde; applications, you can start &pixie; in different
ways:</para>

<itemizedlist>
<listitem><para>by typing from a command line</para></listitem>
<listitem><para>by launching it from the &kde; <guimenu>K</guimenu> menu, or
</para></listitem>
<listitem><para>by using &kde;'s <quote>drag-and-drop</quote>
interface.</para></listitem>
</itemizedlist>

<para>All three are described in the following sections.</para>

<sect1 id="startup">
<title>Starting &pixie;</title>

<para>When &pixie; starts, the first thing you see is an Image window with the
&pixie; logo and some basic instructions:</para>

<screenshot>
<screeninfo>Image Window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="startup.png" format="PNG">
</imageobject>
<textobject>
<phrase>Image window</phrase>
</textobject>
<caption><para>Image Window</para></caption>
</mediaobject>
</screenshot>

<para>To open and close the <guilabel>Viewer/Editor</guilabel> window with menus
and controls, &RMB; click the Image window.  A new
<guilabel>Viewer/Editor</guilabel> window pops up, which is described at length
in this handbook:</para>

<screenshot>
<screeninfo>Viewer Editor</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="pixie.png" format="PNG">
</imageobject>
<textobject>
<phrase>The <guilabel>Viewer/Editor</guilabel></phrase>
</textobject>
<caption><para>The <guilabel>Viewer/Editor</guilabel></para></caption>
</mediaobject>
</screenshot>

<para>Note that unlike most &kde; applications, the
<guilabel>Viewer/Editor</guilabel> window is not the main window of &pixie;.
You can click the <guiicon>close window</guiicon> button on the upper right of
the <guilabel>Viewer/Editor</guilabel> window, and &pixie; remains running.  The
Image window is the functional center of &pixie;, so when you close the Image
window, you are exiting from &pixie;.</para>

</sect1>

<sect1 id="drag-and-drop">
<title>Drag and Drop</title>

<para>&pixie; uses the &kde; Drag and Drop protocol. Files may be dragged and
dropped onto &kde; from the Desktop, from the &konqueror; file-and-web browser,
or from a remote &FTP; site opened in one of &konqueror;'s windows.</para>

</sect1>

<sect1 id="command-line-options">
<title>Command Line Options</title>

<para>Though &pixie; can be started from the <guimenu>K</guimenu> menu or from a
desktop icon, it can also be opened at the command line prompt of a terminal
window.  There are a few useful options available for doing this.</para>

<sect2 id="specify-a-file">
<title>Specify a File</title>

<para>By specifying the path and name of a particular file, the user can have
Pixie open that file immediately upon startup.  Here's an example of
opening an existing image file with &pixie; from the command line:</para>

<informalexample>
<screen><prompt>%</prompt> <userinput><command>pixie</command> <filename>./docs/my-dog.png</filename></userinput></screen>
</informalexample>

<para>If the file that you typed doesn't exist yet, &pixie; creates a new blank
file for you, using the name that you typed.</para>

</sect2>

<sect2 id="editing-files-on-the-internet">
<title>Edit a file on the internet</title>

<para>&pixie; can even be used to open image files on the internet, if you have
an active connection to the internet at the time.  For example, type the command
shown below to open the the &kde; home page's banner image in &pixie;:</para>

<informalexample>
<screen>
<prompt>% </prompt><userinput><command>pixie</command> <filename>http://www.kde.org/img/full_logo.jpg</filename></userinput></screen>
</informalexample>

</sect2>

<sect2>
<title>Other Command Line Options</title>

<para>The following command line help options are available:</para>

<variablelist>
<varlistentry>
<term><userinput><command>pixie</command>
<option>--help</option></userinput></term>
<listitem>
<para>lists the most basic options available at the command line</para> 
</listitem>
</varlistentry>

<varlistentry>
<term><userinput><command>pixie</command>
<option>--help-qt</option></userinput></term>
<listitem>
<para>lists the options available for changing the way &pixie; interacts
with &Qt;</para>
</listitem>
</varlistentry>

<varlistentry>
<term><userinput><command>pixie</command>
<option>--help-kde</option></userinput></term>
<listitem>
<para>lists the options available for changing the way &pixie;
interacts with &kde;</para>
</listitem>
</varlistentry>

<varlistentry>
<term><userinput><command>pixie</command>
<option>--help-all</option></userinput></term>
<listitem>
<para>lists all of &pixie;'s command line options</para>
</listitem>
</varlistentry>

<varlistentry>
<term><userinput><command>pixie</command>
<option>--version</option></userinput></term>
<listitem>
<para>Lists version information for &Qt;, &kde;, and &pixie;.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><userinput><command>pixie</command>
<option>-v</option></userinput></term>
<listitem>
<para>Same as for <option>--version</option> above.</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>
</sect1>

<sect1 id="key-bindings">
<title>Key Bindings</title>

<para>&pixie; honors the following key bindings.</para>

<!-- LW: Actually, they can't...
<para>Like most &kde; apps, these keys can be customised from the "Look and
Feel" section of "Preferences" on the KDE program menu.</para> -->

<informaltable>
<tgroup cols="2">

<thead>
<row>
<entry>Key Binding</entry>
<entry>Action</entry>
</row>
</thead>

<tbody>

<row>
<entry><keycombo>&Ctrl;<keycap>O</keycap></keycombo></entry>
<entry><action>Open an image file, and display it in a new
window.</action></entry> </row>

<row>
<entry><keycombo>&Ctrl;<keycap>S</keycap></keycombo></entry>
<entry><action>Save the file to disk.</action></entry>
</row>

<row>
<entry><keycombo>&Ctrl;<keycap>P</keycap></keycombo></entry>
<entry><action>Print the image.</action></entry>
</row>

<row>
<entry><keycombo>&Ctrl;<keycap>A</keycap></keycombo></entry>
<entry><action>Select all images in the <guilabel>Viewer/Editor</guilabel>
list.</action></entry>
</row>

<row>
<entry><keycombo>&Ctrl;<keycap>C</keycap></keycombo></entry>
<entry><action>Copy the selected area of image</action> to the &kde;
clipboard.</entry> 
</row>

<row>
<entry><keycombo>&Ctrl;<keycap>V</keycap></keycombo></entry>
<entry><action>Paste the selected area of image</action> from the &kde;
clipboard.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect1>

</chapter>

<chapter id="toolbar-menu-entries">
<title>The Toolbar and Menu Entries</title>

<sect1 id="viewer-editor-toolbar">
<title>The <guilabel>Viewer/Editor</guilabel> Toolbar</title>

<para>The <guilabel>Viewer/Editor</guilabel> Toolbar comprises the following buttons:</para>

<para><inlinemediaobject><imageobject><imagedata fileref="open-save-print.png"
format="PNG"></imageobject></inlinemediaobject> <action>Open image file from
disk, save files and print images</action></para>

<para><inlinemediaobject><imageobject><imagedata fileref="toggle.png"
format="PNG"></imageobject></inlinemediaobject> <action>Switch Image window to
the next image in the list</action></para>

<para><inlinemediaobject><imageobject><imagedata fileref="reload.png"
format="PNG"></imageobject> </inlinemediaobject> <action>Revert to last saved
version of image file</action></para>

<para><inlinemediaobject><imageobject><imagedata fileref="copy-paste.png"
format="PNG"></imageobject></inlinemediaobject> <action>Copy and
paste</action></para>

<para><inlinemediaobject><imageobject><imagedata fileref="sharp-bright.png"
format="PNG"></imageobject></inlinemediaobject> <action>Adjust sharpness and
brightness</action></para>

<para><inlinemediaobject><imageobject><imagedata fileref="scale.png"
format="PNG"></imageobject></inlinemediaobject> <action>Scale or flip the
image</action></para>

<para><inlinemediaobject><imageobject><imagedata fileref="clone.png"
format="PNG"></imageobject></inlinemediaobject> <action>Create a new, separate
copy of the Image window</action></para>

</sect1>

<sect1 id="file">
<title>The <guimenu>File</guimenu> Menu</title>

<variablelist>

<varlistentry>
<term id="take-a-screenshot">
<menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>Take a screenshot...</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para><action>This allows a snapshot image to be taken, either of a single
application window, or of the entire desktop.</action></para>

<screenshot>
<screeninfo>Screenshot Dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="screenshot.png" format="PNG">
</imageobject>
<textobject>
<phrase>Screenshot Dialog</phrase>
</textobject>
<caption><para>Screenshot Dialog</para></caption>
</mediaobject>
</screenshot>

<para>You can also tick a box on this dialog to hide all &pixie; windows from the
resulting snapshot.  Once you have <quote>grabbed</quote> an image this way, you
can edit and save the result with &pixie;.</para> 
</listitem> 
</varlistentry>

<varlistentry>
<term id="slideshow">
<menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>Slideshow...</guimenuitem>
</menuchoice>
</term> 
<listitem> 
<para><action>This runs a slideshow of all the image windows currently
open. </action>  When this menu item is chosen, a dialog prompts you to enter
the number of seconds between image changes, and whether you want the slideshow
to repeat until told to stop.</para> 

<para>To stop a looping slideshow, return to the <guimenu>File</guimenu> menu:
you'll see the Slideshow entry has changed to <guimenuitem>Stop
Slideshow</guimenuitem>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term id="open">
<menuchoice>
<shortcut>
<keycombo>&Ctrl;<keycap>O</keycap></keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>O</accel>pen</guimenuitem>
</menuchoice>
</term>
<listitem>
<para><action>This command opens a file.</action> It displays a file-open dialog
box, which allows you to navigate the file system and choose the file you wish
to open.</para>

<para>The file-open dialog operates like a small file manager. Click on
directories displayed in the central window to enter that directory, displaying
its contents. There is an entry/dropdown box which allows you to directly type
in the location and name of the file.  By clicking the arrow at the side, you
can choose from a dropdown list of recently used locations.</para>

<screenshot>
<screeninfo>File Open Dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="open.png" format="PNG">
</imageobject>
<textobject>
<phrase>File Open Dialog</phrase>
</textobject>
<caption><para>The File Open Dialog</para></caption>
</mediaobject>
</screenshot>

<para> Below this is a filter into which you can either type directly, or choose
from a dropdown list of common and recent filter types.  A filter allows files
of one type at a time to be displayed in the central window. </para> 

<para>For example, if the filter <literal role="extension">*.png</literal> was
chosen, then only files with the <literal role="extension">.png</literal>
extension would be visible in the selection window.</para>

<para>The toolbar on this dialog has <guiicon>left</guiicon> and
<guiicon>right</guiicon> arrow buttons that let the user move back and forth
through previously selected directories, as well as an <guiicon>up</guiicon>
arrow button for moving up the directory tree. </para>

<para>The button with the <guiicon>little house</guiicon> takes the user to his
or her home directory.</para>

<para>The button with the <guiicon>two arrows curved in on each other</guiicon>
updates the view of the current directory, to show new files (and remove deleted
files) from the dialog's file view.</para>

<para>The <guiicon>bookmark</guiicon> button lets the user set a new bookmark at
the current directory, or go to one that was previously set.</para>

<para>Finally there is a drop-down box on the toolbar, with a list of some
commonly used directories.</para>

<note><para>There is also an <guiicon>Open</guiicon> button on the <link
linkend="viewer-editor-toolbar">toolbar of the
<guilabel>Viewer/Editor</guilabel></link> window.</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term id="save">
<menuchoice>
<shortcut>
<keycombo>&Ctrl;<keycap>S</keycap></keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>S</accel>ave</guimenuitem>
</menuchoice>
</term>
<listitem>
<para><action>This saves the current image.</action> If the image has already
been saved, then this will overwrite the previously saved file without asking
for your consent.</para> 

<para>If it is the first time that a new image has been saved, the <link
linkend="save-as">Save as...</link> dialog will be invoked.</para>

<note><para>There is also a <guiicon>Save</guiicon> button on the <link
linkend="viewer-editor-toolbar">toolbar of the
<guilabel>Viewer/Editor</guilabel></link> window.</para></note> 
</listitem> 
</varlistentry>

<varlistentry>
<term id="save-as">
<menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>Save <accel>A</accel>s</guimenuitem>
</menuchoice>
</term>
<listitem>
<para><action>This allows a document to be saved with a new file name.</action>
This is done by means of the file dialog box described above in the <link
linkend="open">Open</link> section of this help file.</para>
</listitem>
</varlistentry>

<varlistentry>
<term id="print">
<menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>Print...</guimenuitem>
</menuchoice>
</term> 
<listitem><para><action>This opens a print dialog allowing the user to specify
what, where, and how to print; whether to print in color or in
grayscale.</action> The user can choose between the standard
<command>lp</command> or to print to a file or custom command. The print dialog
also offers a choice of whether to print the whole document or a range of
pages.</para>

<note><para>There is also a <guiicon>Print</guiicon> button on the <link
linkend="viewer-editor-toolbar">toolbar of the
<guilabel>Viewer/Editor</guilabel></link> window.</para></note>

</listitem>
</varlistentry>

<varlistentry>
<term id="exit">
<menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>E<accel>x</accel>it</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para>This <action>closes</action> &pixie;.</para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="edit-basics">

<title>The <guimenu>Edit</guimenu> Menu: Basics</title>

<variablelist>
<varlistentry>
<term id="copy">
<menuchoice>
<shortcut>
<keycombo>&Ctrl;<keycap>C</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Copy</guimenuitem>
</menuchoice>
</term>
<listitem>
<para><action>This copies the currently selected image</action> to the &kde;
clipboard, so that it may be pasted elsewhere.  The clipboard is a feature of
&kde; that works invisibly to provide a way to transfer data between
applications.</para>

<note><para>There is also a <guiicon>Copy</guiicon> button on the <link
linkend="viewer-editor-toolbar">toolbar of the
<guilabel>Viewer/Editor</guilabel></link> window.</para></note>

</listitem> 
</varlistentry>

<varlistentry>
<term id="paste">
<menuchoice>
<shortcut>
<keycombo>&Ctrl;<keycap>V</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Paste</guimenuitem></menuchoice>
</term>
<listitem>
<para><action>This will insert the contents of the clipboard at the
cursor position.</action> The clipboard is feature of &kde; that works invisibly
to provide a way to transfer data between applications.</para>

<note><para>There is also a <guiicon>Paste</guiicon> button on the <link
linkend="viewer-editor-toolbar">toolbar of the
<guilabel>Viewer/Editor</guilabel></link> window.</para></note>

</listitem>
</varlistentry>

<varlistentry>
<term id="select-all">
<menuchoice>
<shortcut>
<keycombo>&Ctrl;<keycap>A</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Select All</guimenuitem>
</menuchoice>
</term>
<listitem>
<para><action>This will select all files listed</action> in the
<guilabel>Viewer/Editor</guilabel>.</para></listitem> 
</varlistentry>

<varlistentry>
<term id="unselect-all">
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Unselect All</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para><action>This will unselect all previously selected files</action> in the
<guilabel>Viewer/Editor</guilabel> list.</para>
</listitem> 
</varlistentry>
</variablelist>

</sect1>

<sect1 id="edit-advanced">
<title>The <guimenu>Edit</guimenu> Menu: Advanced Editing</title>

<variablelist>

<varlistentry>
<term id="crop">
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Crop</guimenuitem></menuchoice></term>
<listitem>
<para>This command <quote>crops</quote> the picture, <action>cutting away all
but the region you select.</action> Using your mouse, you select a region in the
Image window.  Moving to the <guilabel>Viewer/Editor</guilabel> window, select
<menuchoice><guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Crop</guimenuitem></menuchoice>, and the Image window crops down
to the chosen size. The resulting cropped image can then be saved using <link
linkend="save-as">Save As...</link></para>
</listitem> 
</varlistentry> 

<varlistentry>
<term id="scale">
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Scale...</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para>This command allows you to <action>shrink or grow the image to a precise
size.</action> When <guimenuitem>Scale...</guimenuitem> is chosen, an
<guilabel>Image Size</guilabel> dialog opens allowing you to specify the exact
size of the image in pixels:</para>

<screenshot>
<screeninfo><guilabel>Image Size</guilabel> Dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="image-size.png" format="PNG">
</imageobject>
<textobject>
<phrase><guilabel>Image Size</guilabel> Dialog</phrase>
</textobject>
<caption><para>The <guilabel>Image Size</guilabel> Dialog.</para></caption>
</mediaobject>
</screenshot>

<para>The resulting image is not cropped, but rather shrunk, to the size that
you choose. If you want to scale the image proportionately without distortion,
then you must calculate the pixel ratio to be entered, and ensure that it
matches the current ratio used by the image.</para>

<para>To calculate this manually, note the size displayed in the <guilabel>Image
Size</guilabel> dialog, divide the width by the height, and use this ratio as a
divisor when entering the new dimensions.</para> 

<para>For example, in the Image Size dialog above: width / height = 800 / 600.
To maintain proportion when shrinking an image to a width of 500 pixels, one
would divide 500 by (800/600) to get 375, hence the new pixel ratio would be 500
by 375.</para>

<para>For a simpler way to scale images proportionally, see below for <link
linkend="ten-larger">10% Larger</link> and <link linkend="ten-smaller">10%
smaller</link>.</para>

<para>You can also manually scale an image by simply dragging the lower right
corner window of the Image window to the size you require, then saving the
result. </para> 
</listitem>
</varlistentry>

<varlistentry>
<term id="ten-larger">
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>10% Larger</guimenuitem>
</menuchoice> 
</term>
<listitem> 
<para>This command <action>proportionally scales the image 10% larger.</action>
Similar to the <link linkend="scale"><guimenuitem>Scale</guimenuitem></link>
command, this is a simpler way of scaling up the image in 10% increments.</para> 

<note><para>There is also a <guiicon>Scale 10% Larger</guiicon> button on the
<link linkend="viewer-editor-toolbar">toolbar of the
<guilabel>Viewer/Editor</guilabel></link> window.</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term id="ten-smaller">
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>10% Smaller</guimenuitem>
</menuchoice> 
</term>
<listitem> 
<para>This command <action>proportionally scales the image 10% smaller.</action>
Similar to the <link linkend="scale"><guimenuitem>Scale</guimenuitem></link>
command, this is a simpler way of scaling down the image in 10%
increments.</para> 

<note><para>There is also a <guiicon>Scale 10% Smaller</guiicon> button on the
toolbar of the <guilabel>Viewer/Editor</guilabel> window.</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term id="double-size">
<menuchoice>
<shortcut>
<keycap>&gt;</keycap>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Double Size</guimenuitem>
</menuchoice> 
</term>
<listitem> 
<para>This command <action>proportionally scales the image 100% larger.</action>
Similar to the <link linkend="scale"><guimenuitem>Scale</guimenuitem></link> 
command, this is a simpler way of scaling the image in 100% increments.</para>
</listitem>
</varlistentry>

<varlistentry>
<term id="half-size">
<menuchoice>
<shortcut>
<keycap>&lt;</keycap>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Half Size</guimenuitem>
</menuchoice> 
</term>
<listitem> 
<para>This command <action>proportionally scales the image 50% smaller.</action>
Similar to the <link linkend="scale"><guimenuitem>Scale</guimenuitem></link>
command, this is a simpler way of scaling down the image in 50%
increments.</para>
</listitem>
</varlistentry>

<varlistentry>
<term id="horizontal-flip">
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Horizontal Flip</guimenuitem>
</menuchoice> 
</term>
<listitem> 
<para>This command <quote>flips</quote> the image by 180 degrees,
<action>producing a mirror-image horizontal to the original.</action></para>

<note><para>There is also a <guiicon>Horizontal Flip</guiicon> button on the
toolbar of the Viewer/Editor window.</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term id="vertical-flip">
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Vertical Flip</guimenuitem>
</menuchoice> 
</term>
<listitem> 
<para>This command <quote>flips</quote> the image by 180 degrees,
<action>producing a mirror-image vertical to the original.</action></para>

<note><para>There is also a <guiicon>Vertical Flip</guiicon> button on the
toolbar of the <guilabel>Viewer/Editor</guilabel> window.</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term id="rotate-45">
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Rotate 45 degrees</guimenuitem>  
</menuchoice> 
</term>
<listitem> 
<para>This command <action>rotates the image clockwise by 45
degrees.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term id="invert">
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Invert</guimenuitem>
</menuchoice> 
</term>
<listitem> 
<para>This command <action>inverts all colors in the image</action>, producing a
result simlar to a color film negative.</para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="configure">

<title>The <guimenu>Configure</guimenu> Menu</title>

<para>The <guimenu>Configuration</guimenu> menu: to be added in an upcoming
release of &pixie;</para> 

</sect1>

<sect1 id="windows">

<title>The <guimenu>Windows</guimenu> Menu</title>

<sect2 id="thumbnail-viewer">
<title><guimenuitem>The Thumbnail Viewer</guimenuitem></title>

<variablelist>

<varlistentry>
<term id="thumbnail-viewer-overview">
<menuchoice>
<guimenu><accel>W</accel>indows</guimenu>
<guimenuitem>Thumbnail viewer</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para>The Thumbnail Viewer lets you use &pixie; as a powerful image manager.
&pixie; can display image files as <quote>thumbnail images</quote>thumbnail>,
allowing you to review and use large numbers of images at a glance.</para>

<para>Here is the Thumbnail Viewer's thumbnail management window:</para>

<screenshot>
<screeninfo>Thumbnails</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="thumbnails.png" format="PNG">
</imageobject>
<textobject>
<phrase>Thumbnail Viewer</phrase>
</textobject>
<caption><para>The Thumbnail Viewer</para></caption>
</mediaobject>
</screenshot>

</listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="thumbnail-viewer-toolbar">
<title>The Thumbnail Viewer Toolbar</title>

<para>The toolbar contains:</para>

<para><inlinemediaobject><imageobject><imagedata fileref="options.png"
format="PNG"></imageobject></inlinemediaobject> <guibutton>Options</guibutton>
menu (described below)</para>

<para><inlinemediaobject><imageobject><imagedata fileref="thumb-fm.png"
format="PNG"></imageobject></inlinemediaobject> File management buttons, to move
to parent and home directories</para>

<para><inlinemediaobject><imageobject><imagedata fileref="reload.png"
format="PNG"></imageobject> </inlinemediaobject> <guiicon>Reload
button</guiicon> to <action>refresh the display of the directory's
contents</action></para>

<para><inlinemediaobject><imageobject><imagedata fileref="thumbgen.png"
format="PNG"></imageobject></inlinemediaobject> <guiicon>Generate
Thumbnails</guiicon> button, to <action>generate thumbnail images in a viewed
directory</action></para>

<para><inlinemediaobject><imageobject><imagedata fileref="new-win.png"
format="PNG"></imageobject></inlinemediaobject> <guiicon>New Window</guiicon>
button, which <action>creates a new copy of the current Thumbnail Viewer
window</action></para>

<para><inlinemediaobject><imageobject><imagedata fileref="stop.png"
format="PNG"></imageobject></inlinemediaobject> <guiicon>Stop generating
thumbnails</guiicon>.  Useful when a large number of images is taking longer
than expected to thumbnail!</para>

</sect2>

<sect2 id="options-menu">
<title>The Thumbnail <guibutton>Options</guibutton> Menu</title>

<para>As shown above, when you first open the thumbnail viewer you will see a
basic view of your files wih no thumbnails. This allows more efficient
navigation through your file system.  When you open a directory containing image
files that you'd like to see in thumbnail, click the</para>

<para>There is only one menu in this window: the <guibutton>Options</guibutton>
menu button, built into the toolbar.</para>


<variablelist>
<varlistentry>
<term id="sorting">
<menuchoice>
<guimenu>Options</guimenu>
<guimenuitem>Sorting</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>This command sorts thumbnail images in ascending or descending order,
based on filename, size, or date.</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="thumbnail-size">
<menuchoice>
<guimenu>Options</guimenu>
<guimenuitem>Thumbnail Size</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>This command displays these thumbnails in three different sizes, and sorts
them in ascending or descending order based on filename, size, or date. You'll
need to generate thumbnails using the <guiicon>button</guiicon> on the <link
linkend="thumbnail-viewer-toolbar">Thumbnail Viewer Toolbar</link> for each size
you wish to view.  These thumbnails are persistent, meaning that once you've
generated thumbnail images for a directory, they'll still be there the next time
you use your computer.  You'll only need to regenerate again if you add new
images to a directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="img-folder-only">
<menuchoice>
<guimenu>Options</guimenu>
<guimenuitem>Images and Folders Only</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>This command automatically filters out everything but image files
and directories only from the thumbnail browser at the right of the
Thumbnails window.  This can be useful when you have a lot of documents and
images in the same directory, but only want to see image files in
&pixie;.</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="using-thumb-viewer">
<title>Using the Thumbnail Viewer</title>

<para>If you open more than one &pixie; thumbnail window, using the New Window
Button on the <link linkend="thumbnail-viewer-toolbar">Thumbnail Viewer
Toolbar</link>, you can drag and drop between them.</para>

<para>The left side of the window is a <guilabel>Directory Tree</guilabel> view,
allowing you to navigate your directories manually instead of clicking on
directories in the browser window.</para> 

<para>At the top of the <guilabel>Directory Tree</guilabel> you can choose to
switch between the default Tree view, or utilize the <link
linkend="hotlist"><guilabel>HotList</guilabel></link>.</para>

<para>At the lower left of the Thumbnail Viewer is the Preview window. Click
<guibutton>Enable Preview</guibutton> to see an image full-size before loading
it up in &pixie;'s main Image Window. A single click on an image puts it in the
Preview window; a double click loads it into the main Image Window.</para>

<para>The right side of the Thumbnail Viewer is the thumbnail browser. You can
use this window to manage your images: use the browser for selecting
directories, copying, moving, and renaming files right in the thumbnail browser,
using either drag-and-drop or via the menus. &pixie; can also work transparently
with the &kde; file manager, &konqueror;. Simply drag the image file from the
Tree view in &pixie; to the directory you bring up in the &konqueror; file
manager.</para>

</sect2>

<sect2 id="hotlist">
<title>The &pixie; <guilabel>HotList</guilabel></title>

<para>Your &RMB; mouse button links the thumbnail browser window to your
<guilabel>HotList</guilabel>, giving you the power to instantly copy any number
of selected images to frequently-used directories.  You can also use the &RMB;
mouse button to rename and delete files, or popup a quick view of file
properties.</para>

<para>As you can see in the screenshot, the upper left of the Thumbnail
Viewer has a tab where you can select the <guilabel>HotList</guilabel>
view. Doing so gives you this instead of the tree view:</para>

<screenshot>
<screeninfo>Hotlist</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="hotlist.png" format="PNG">
</imageobject>
<textobject>
<phrase>Hotlist</phrase>
</textobject>
<caption><para>The &pixie; <guilabel>HotList</guilabel></para></caption>
</mediaobject>
</screenshot>

<para>Many users, especially those managing webpages, have lots of images to
sort through and organize.  The <guilabel>HotList</guilabel> can make this
management easier by letting you mark frequently-used folders and keep them
easily accessible for copying and moving files, switching to directories,
&etc;</para>

<para>Any folder can be put in the <guilabel>HotList</guilabel>. To do so simply
&RMB; click on the folder, choose <guimenuitem>Add to HotList
Group</guimenuitem>, and you'll be presented with a dialog asking you to name
the <guilabel>HotList</guilabel> entry. By default the name in the
<guilabel>HotList</guilabel> will be the same as the name of the folder, but you
can name it anything you like: any character on your keyboard is allowed,
including spaces.</para>

<para>Once done, you can easily copy or move items to that folder from anyplace
on your computer by drag-and-drop either from &pixie; windows or from the &kde;
file manager, &konqueror;. You can also access the <guilabel>HotList</guilabel>
by using the &RMB; mouse button on files. </para>

<para>You might use the <guilabel>HotList</guilabel> to give you quick access to
your main webpage, or the directories where you edit a lot of images. Your home
folder is always in the <guilabel>HotList</guilabel> by default.</para>

<para>Once a folder is in the <guilabel>HotList</guilabel>, you can either copy
or move files from anywhere on your hard drive by dragging them on one of the
items. Clicking on an item switches you to that item's folder.</para>

</sect2>

<sect2 id="image-color-editor">
<title>The <guilabel>Image Color</guilabel> Editor</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu><accel>W</accel>indows</guimenu>
<guimenuitem>Image color editor</guimenuitem>
</menuchoice>
</term>

<listitem><para>This command allows you to <action>precisely edit image-wide
colors .</action> Here is a screenshot of the <guilabel>Image Color</guilabel>
Editor:</para>

<screenshot>
<screeninfo><guilabel>Image Color</guilabel> Editor</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="image-edit.png" format="PNG">
</imageobject>
<textobject>
<phrase><guilabel>Image Color</guilabel> Editor</phrase>
</textobject>
<caption><para>The <guilabel>Image Color</guilabel> Editor</para></caption>
</mediaobject>
</screenshot>


<para>You can edit image-wide colors in both <acronym>RGB</acronym>, Dual
Channel <acronym>RGB</acronym> (Yellow, Cyan, and Magenta), and
<acronym>HSV</acronym> modes.</para>

<para>Simply drag the sliders until the preview image reaches the right
image-wide colors, or click the <guiicon>plus</guiicon> and
<guiicon>minus</guiicon> buttons either side of the sliders to adjust the values
in small increments.  To change the brightness of all colors at once, use the
<guibutton>Brighten</guibutton> and <guibutton>Dim</guibutton> buttons to the
right.</para>

<para>To revert to the original color value, click on the
<guiicon>Reload</guiicon> button to the left of the relevant slider.  To revert
all color values to the original values, click the <guibutton>Revert</guibutton>
button at the lower right of the dialog.</para>

<para>When you're satisfied with your new image-wide colors, press the
<guibutton>Done</guibutton> button, and your Image window will display the
results of your color edits.</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="individual-color-editor">
<title>The <guimenuitem>Individual Color</guimenuitem> Editor</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu><accel>W</accel>indows</guimenu>
<guimenuitem>Individual color editor</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>This command allows you to <action>precisely edit specific colors
.</action></para>

<para>Clicking on this command will first initiate a scan of all colors used in
your current Image window, with the dialog <msgtext><para>Finding all color
values...</para></msgtext>. On complex images, this scan could take a few
moments, so be patient.  Once this is complete, you will see a palette of all
colors in use.</para>

<para>Here is a screenshot of the <guilabel>Individual Colors</guilabel>
Editor:</para>

<screenshot>
<screeninfo>Figure 10, Individual Color Editor</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="ind-color-edit.png" format="PNG">
</imageobject>
<textobject>
<phrase>Hotlist</phrase>
</textobject>
<caption><para>The <guilabel>Individual Colors</guilabel>
Editor</para></caption>
</mediaobject>
</screenshot>

<para>You can edit individual colors in both <acronym>RGB</acronym> and
<acronym>HSV</acronym> modes, even in non-paletted high-color and true-color
images. Select the individual color you wish to edit, and enter the precise
value or drag the sliders until the individual color shown in the Image window
reaches the right color. Alternatively you can use the adjustment buttons to the
left of the sliders to adjust the values in small increments. </para>

<para>To revert all color values to the original values, click the
<guibutton>Revert</guibutton> button at the lower left of the dialog.</para>

<para>When you're satisfied with your new colors, press the
<guibutton>Done</guibutton> button.</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

</sect1>

<sect1 id="effects">
<title>The <guimenu>Effects</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term id="effects-command">
<menuchoice><guimenu>Effec<accel>t</accel>s</guimenu>
</menuchoice>
</term>

<listitem>

<para>&pixie; currently supports over 30 graphical effects that you can apply to
your images. Most can be applied either to an entire image, or to just an area
of the Image window selected with the mouse.</para>

<para>In order to support these effects, &pixie; uses a plug-in mechanism to
dynamically load and unload effect filters.</para>

<para>The best way to learn how to use the plug-ins is to try them: with your
image file opened in the Image window, choose an effect from the menu, and watch
the result.  Some plug-ins allow you to adjust a value applied to the effect.
The <guimenuitem>Swirl</guimenuitem> effect, for example brings up a dialog
asking you to <msgtext><para>Please select the degrees to
swirl</para></msgtext>.</para>

<para>Experiment with different values, and learn to use these powerful
effects.</para>

</listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="help">
<title>The <guimenuitem>Help</guimenuitem> Menu</title>

<variablelist>
<varlistentry>
<term id="contents">
<menuchoice>
<shortcut>
<keycombo><keycap>F1</keycap></keycombo>
</shortcut>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>C</accel>ontents</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>This invokes the &kde; help system starting at the &pixie; help
pages (this document).</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="report-bug">
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>R</accel>eport Bug...</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para><action>This allows you to easily report bugs</action> in &pixie; back to
the &kde;  Development Team.</para>
</listitem> 
</varlistentry>

<varlistentry>
<term id="about-pixie">
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>A</accel>bout Pixie</guimenuitem>
</menuchoice>
</term> 
<listitem>
<para><action>This displays version and author information.</action></para>
</listitem> 
</varlistentry>

<varlistentry>
<term id="about-kde">
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>About <accel>K</accel>DE</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>This displays the &kde; version and other basic information.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

</chapter>
<chapter id="credits">
<title>Credits and Licence</title>

<para>&pixie;</para>

<para>Program copyright 2001 Daniel M. DuLey,
<email>mosfet@kde.org</email></para>

<para>Contributors:</para>
<itemizedlist>
<listitem><para>Pixie logo by <email>artwiz@artramp.org</email></para>
</listitem>
</itemizedlist>

&underFDL;

&underGPL;

</chapter>

<appendix id="installation">
<title>Compilation and Installation</title>

<sect1 id="getting-pixie">
<title>How to obtain &pixie;</title>

<para>&pixie; is part of the &kde; project <ulink
url="http://www.kde.org">http://www.kde.org</ulink>.</para>

<para>All required libraries as well as &pixie; itself can be found in the
kdegraphics package on <ulink
url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the main
&FTP; site of the &kde; project. </para>

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>In order to successfully use &pixie;, you need &kde; 2.1.</para>

</sect1>

<sect1 id="compilation">
<title>Compilation and installation</title>

<para>In order to compile and install &pixie; on your system, type the following
in the base directory of the &pixie; distribution:</para>

<screen>
<prompt>%</prompt> <userinput><command>./configure</command></userinput>
<prompt>%</prompt> <userinput><command>make</command></userinput>
<prompt>%</prompt> <userinput><command>make</command> <option>install</option></userinput>
</screen>

<para>Since &pixie; uses <application>autoconf</application> and
<application>automake</application>, you should have no trouble compiling
it. Should you run into problems, please report them to the &kde; mailing
lists.</para>

</sect1>

</appendix>

</book>

<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
