# The Pixie Handbook

Jon
Fox

    jon.fox@bigfoot.com

2001
Jon Fox
&FDLNotice;
08/02/2001
1.0.00

&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 thumbnails.

KDE
Pixie
image
viewer
graphics

&kde-modespec;

## Introduction

A screenshot of &pixie;:
Screenshot

A Screenshot of &pixie;

&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 thumbnails. 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 HotList directory bookmarking feature.

## Getting Started

Like most &kde; applications, you can start &pixie; in different ways:

- by typing from a command line

- by launching it from the &kde; K menu, or

- by using &kde;'s drag-and-drop interface.

All three are described in the following sections.

### Starting &pixie;

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

Image Window
Image window

Image Window

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

Viewer Editor
The Viewer/Editor

The Viewer/Editor

Note that unlike most &kde; applications, the Viewer/Editor window is not the main window of &pixie;. You can click the close window button on the upper right of the Viewer/Editor 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;.

### Drag and Drop

&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.

### Command Line Options

Though &pixie; can be started from the K 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.

#### Specify a File

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:

    % pixie ./docs/my-dog.png

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

#### Edit a file on the internet

&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;:

    % pixie http://www.kde.org/img/full_logo.jpg

#### Other Command Line Options

The following command line help options are available:

``pixie` `--help``

  lists the most basic options available at the command line

``pixie` `--help-qt``

  lists the options available for changing the way &pixie; interacts with &Qt;

``pixie` `--help-kde``

  lists the options available for changing the way &pixie; interacts with &kde;

``pixie` `--help-all``

  lists all of &pixie;'s command line options

``pixie` `--version``

  Lists version information for &Qt;, &kde;, and &pixie;.

``pixie` `-v``

  Same as for `--version` above.

### Key Bindings

&pixie; honors the following key bindings.

Key Binding | Action
--- | ---
&Ctrl;O | Open an image file, and display it in a new window.
&Ctrl;S | Save the file to disk.
&Ctrl;P | Print the image.
&Ctrl;A | Select all images in the Viewer/Editor list.
&Ctrl;C | Copy the selected area of image to the &kde; clipboard.
&Ctrl;V | Paste the selected area of image from the &kde; clipboard.

## The Toolbar and Menu Entries

### The Viewer/Editor Toolbar

The Viewer/Editor Toolbar comprises the following buttons:

Open image file from disk, save files and print images

Switch Image window to the next image in the list

Revert to last saved version of image file

Copy and paste

Adjust sharpness and brightness

Scale or flip the image

Create a new, separate copy of the Image window

### The File Menu

File Take a screenshot...

  This allows a snapshot image to be taken, either of a single application window, or of the entire desktop.

  Screenshot Dialog
  Screenshot Dialog

  Screenshot Dialog

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

File Slideshow...

  This runs a slideshow of all the image windows currently open. 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.

  To stop a looping slideshow, return to the File menu: you'll see the Slideshow entry has changed to Stop Slideshow.

&Ctrl;O File Open

  This command opens a file. It displays a file-open dialog box, which allows you to navigate the file system and choose the file you wish to open.

  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.

  File Open Dialog
  File Open Dialog

  The File Open Dialog

  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.

  For example, if the filter `*.png` was chosen, then only files with the `.png` extension would be visible in the selection window.

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

  The button with the little house takes the user to his or her home directory.

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

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

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

  There is also an Open button on the toolbar of the Viewer/Editor window.

&Ctrl;S File Save

  This saves the current image. If the image has already been saved, then this will overwrite the previously saved file without asking for your consent.

  If it is the first time that a new image has been saved, the Save as... dialog will be invoked.

  There is also a Save button on the toolbar of the Viewer/Editor window.

File Save As

  This allows a document to be saved with a new file name. This is done by means of the file dialog box described above in the Open section of this help file.

File Print...

  This opens a print dialog allowing the user to specify what, where, and how to print; whether to print in color or in grayscale. The user can choose between the standard `lp` 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.

  There is also a Print button on the toolbar of the Viewer/Editor window.

File Exit

  This closes &pixie;.

### The Edit Menu: Basics

&Ctrl;C Edit Copy

  This copies the currently selected image 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.

  There is also a Copy button on the toolbar of the Viewer/Editor window.

&Ctrl;V Edit Paste

  This will insert the contents of the clipboard at the cursor position. The clipboard is feature of &kde; that works invisibly to provide a way to transfer data between applications.

  There is also a Paste button on the toolbar of the Viewer/Editor window.

&Ctrl;A Edit Select All

  This will select all files listed in the Viewer/Editor.

Edit Unselect All

  This will unselect all previously selected files in the Viewer/Editor list.

### The Edit Menu: Advanced Editing

Edit Crop

  This command crops the picture, cutting away all but the region you select. Using your mouse, you select a region in the Image window. Moving to the Viewer/Editor window, select Edit Crop, and the Image window crops down to the chosen size. The resulting cropped image can then be saved using Save As...

Edit Scale...

  This command allows you to shrink or grow the image to a precise size. When Scale... is chosen, an Image Size dialog opens allowing you to specify the exact size of the image in pixels:

  Image Size Dialog
  Image Size Dialog

  The Image Size Dialog.

  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.

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

  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.

  For a simpler way to scale images proportionally, see below for 10% Larger and 10% smaller.

  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.

Edit 10% Larger

  This command proportionally scales the image 10% larger. Similar to the Scale command, this is a simpler way of scaling up the image in 10% increments.

  There is also a Scale 10% Larger button on the toolbar of the Viewer/Editor window.

Edit 10% Smaller

  This command proportionally scales the image 10% smaller. Similar to the Scale command, this is a simpler way of scaling down the image in 10% increments.

  There is also a Scale 10% Smaller button on the toolbar of the Viewer/Editor window.

> Edit Double Size

  This command proportionally scales the image 100% larger. Similar to the Scale command, this is a simpler way of scaling the image in 100% increments.

< Edit Half Size

  This command proportionally scales the image 50% smaller. Similar to the Scale command, this is a simpler way of scaling down the image in 50% increments.

Edit Horizontal Flip

  This command flips the image by 180 degrees, producing a mirror-image horizontal to the original.

  There is also a Horizontal Flip button on the toolbar of the Viewer/Editor window.

Edit Vertical Flip

  This command flips the image by 180 degrees, producing a mirror-image vertical to the original.

  There is also a Vertical Flip button on the toolbar of the Viewer/Editor window.

Edit Rotate 45 degrees

  This command rotates the image clockwise by 45 degrees.

Edit Invert

  This command inverts all colors in the image, producing a result simlar to a color film negative.

### The Configure Menu

The Configuration menu: to be added in an upcoming release of &pixie;

### The Windows Menu

#### The Thumbnail Viewer

Windows Thumbnail viewer

  The Thumbnail Viewer lets you use &pixie; as a powerful image manager. &pixie; can display image files as thumbnail imagesthumbnail>, allowing you to review and use large numbers of images at a glance.

  Here is the Thumbnail Viewer's thumbnail management window:

  Thumbnails
  Thumbnail Viewer

  The Thumbnail Viewer

#### The Thumbnail Viewer Toolbar

The toolbar contains:

Options menu (described below)

File management buttons, to move to parent and home directories

Reload button to refresh the display of the directory's contents

Generate Thumbnails button, to generate thumbnail images in a viewed directory

New Window button, which creates a new copy of the current Thumbnail Viewer window

Stop generating thumbnails. Useful when a large number of images is taking longer than expected to thumbnail!

#### The Thumbnail Options Menu

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

There is only one menu in this window: the Options menu button, built into the toolbar.

Options Sorting

  This command sorts thumbnail images in ascending or descending order, based on filename, size, or date.

Options Thumbnail Size

  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 button on the Thumbnail Viewer Toolbar 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.

Options Images and Folders Only

  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;.

#### Using the Thumbnail Viewer

If you open more than one &pixie; thumbnail window, using the New Window Button on the Thumbnail Viewer Toolbar, you can drag and drop between them.

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

At the top of the Directory Tree you can choose to switch between the default Tree view, or utilize the HotList.

At the lower left of the Thumbnail Viewer is the Preview window. Click Enable Preview 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.

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.

#### The &pixie; HotList

Your &RMB; mouse button links the thumbnail browser window to your HotList, 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.

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

Hotlist
Hotlist

The &pixie; HotList

Many users, especially those managing webpages, have lots of images to sort through and organize. The HotList 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;

Any folder can be put in the HotList. To do so simply &RMB; click on the folder, choose Add to HotList Group, and you'll be presented with a dialog asking you to name the HotList entry. By default the name in the HotList 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.

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 HotList by using the &RMB; mouse button on files.

You might use the HotList 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 HotList by default.

Once a folder is in the HotList, 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.

#### The Image Color Editor

Windows Image color editor

  This command allows you to precisely edit image-wide colors . Here is a screenshot of the Image Color Editor:

  Image Color Editor
  Image Color Editor

  The Image Color Editor

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

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

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

  When you're satisfied with your new image-wide colors, press the Done button, and your Image window will display the results of your color edits.

#### The Individual Color Editor

Windows Individual color editor

  This command allows you to precisely edit specific colors .

  Clicking on this command will first initiate a scan of all colors used in your current Image window, with the dialog

  Finding all color values...

  . 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.

  Here is a screenshot of the Individual Colors Editor:

  Figure 10, Individual Color Editor
  Hotlist

  The Individual Colors Editor

  You can edit individual colors in both RGB and HSV 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.

  To revert all color values to the original values, click the Revert button at the lower left of the dialog.

  When you're satisfied with your new colors, press the Done button.

### The Effects Menu

Effects

  &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.

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

  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 Swirl effect, for example brings up a dialog asking you to

  Please select the degrees to swirl

  .

  Experiment with different values, and learn to use these powerful effects.

### The Help Menu

F1 Help Contents

  This invokes the &kde; help system starting at the &pixie; help pages (this document).

Help Report Bug...

  This allows you to easily report bugs in &pixie; back to the &kde; Development Team.

Help About Pixie

  This displays version and author information.

Help About KDE

  This displays the &kde; version and other basic information.

## Credits and Licence

&pixie;

Program copyright 2001 Daniel M. DuLey, mosfet@kde.org

Contributors:

- Pixie logo by artwiz@artramp.org

&underFDL;

&underGPL;

## Compilation and Installation

### How to obtain &pixie;

&pixie; is part of the &kde; project http://www.kde.org.

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

### Requirements

In order to successfully use &pixie;, you need &kde; 2.1.

### Compilation and installation

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

    % ./configure
    % make
    % make install

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