# The &kphotobook; Handbook

## Introduction

This handbook is intended to give an overview on the easy use of &kmyapplication;.

### What is &kmyapplication;?

&kmyapplication; is a powerful, easy to use, intuitive and fast application to manage and organize your photos. The main idea is to be able to annotate your photos with tags and to refind the photos using the given tags. The tags which can be created by yourself are arranged in a tree.

The &kmyapplication; GUI comes up with several points which makes the handling with many photos very easy. This is just a short excerpt of it's goodies:

- It is very easy to annotate tags to one or more images at a time

- It is very easy to find images by the given tags (actually one mouse click only is needed)

- It is very easy to edit the image database with an external program - it's saved as XML file

- ...

### History

The idea for a photo database and photo album program came up during September 2003. Having bought a digital camera a few months ago, the necessity for a program to manage all the taken photos became urgent.

At this time, we did not know about a comparable program for KDE. A few weeks later KimDaBa 1.0 was released. We looked into this program but decided to go on with the development of &kmyapplication; anyway because KimDaBa was not exactly what we needed.

In February 2004 a first alpha-version of Fotoon was released. Fotoon came closer to what our idea is... but not exactly. We decide - once again - to go on working on &kmyapplication; and to have a close eye on these other applications.

### Why another application to manage photos?

It's not easy to manage hundreds or even thousands of images. Other applications promote themselves to solve this problem. They say it'd be easy to manage such a huge amount of photos. Having looked at some of those other applications, we found that it was not that easy and not nearly as straight forward as we think such an application should be. Beside this, it is also very important that it is not only easy to manage the photos but also to be fast. Other applications provide the function to tag the pictures but do not offer this function in a really easy and fast way. Some others have the same approach as &kmyapplication;, but waiting for an application to become usable when no work is done on it is not really a great thing to do. :-)

### Basic Feature List

- creating an image database with images from several folders which can be added single or recursively

- annotate tags to the photos - this can be done for one photo only or for several photos at once

- there will be different kinds of tags: title, string, dates, numeric, enumeration and boolean

- there can be written a description for each image

- searching and filtering the photos using the given tags and description

- all pictures matching the chosen filter are displayed as thumbnails

- the pictures can be rotated (real, EXIF or database only)

- showing the EXIF informations of a selected file

- showing the pictures matching the filter in a slide show

- opening the files with a any desired program

- For a more complete feature and "to do" list, please visit the &kmyapplication; homepage.

- ...

### Evolution of &kmyapplication;

This is a quick overview of the evolution of &kmyapplication;

#### Version 0.0.3

Version 0.0.3 was the first release of &kmyapplication; and was released in February 2004. It did not provide many features but seemed quite stable already (probably because of the lack of features :-) ). The UI provided a source directory tree and a main window in which thumbnails of the images in the imported directories were shown. There was also a tag tree - it was hard coded at this time. V0.0.3 already had the ability to alter the thumbnail size with a ruler.

#### Version 0.0.4

Version 0.0.4 was released in March 2004. Besides the features of Version 0.0.3, we provided a functional tag tree with title tags and boolean tags, improved filter abilities, a few new icons and a new tool bar.

#### Version 0.0.5

Version 0.0.5 was released on March 11, 2004. Version 0.0.5 is the firs release as a tarball and is now also registered at kde-apps.org. KPhotoBook is usable by now. The trees for the Source Directory and the Tags are in separate Tabs now. There are several new icons and functions like unmark all tags (for example to show the pictures which have no tags yet). There is also a new configure dialog with heaps of options (mostly for the visual appearance). The toolbars are configurable as well.

## Using &kphotobook;

### The &kmyapplication; database

A &kmyapplication; database is stored as one XML-file. This file contains all source folders, tags and files belonging to this database. Of course it is possible to have several databases storing different types of photos (e.g. you could have a database for your private photos and a database for your business photos).

When a database has changed (tags or source folders were edited) the file must be saved. That means that changes are not automatically persisted. Each time a file is saved the old file is backed-up.

### Source Directories

The &kmyapplication; database contains all images of one ore more source folders. Source folders can be added recursively or single. Adding them recursively makes &kmyapplication; add the selected directory and all directories below it. When adding a folder recursively, hard- and soft-links are followed by default. To prevent endless loops &kmyapplication; tries to detect and suppress loops in the file system directory structure.

When restarting &kmyapplication; every source folder will be rescanned and new found sub-folders and files will be added to the database. This function can also be executed manually. Missed directories of files will not automatically be removed from the database to prevent loss of the association between files and tags.

#### The Source Directory Tree

The Source Directory Tree shows all the source directories which are added to the database. As known from Konqueror directories with subdirectories can be expanded and collapsed. There are some very handy operations which are accessible through the directory tree context menu:

Beside Folders:

Include All | Includes all source directories which are in the database to the preview
Exclude All | Excludes all source directories from the preview
Invert All | All folders which were included to the preview will be excluded and vice versa
Expand all Source Directories | The folder Tree will be expanded. All source directories are visible
Collapse all Source Directories | The folder tree will be collapsed. Only the top level directories are shown
Add Source Directory | Prompts the dialog to add a source directory (recursively or single)

On Folders:

Include Whole Folder | Includes the directory to the preview. Subdirectories will be included as well
Exclude Whole Folder | Excludes the directory from the preview. Subdirectories will be excluded as well
Invert Folder Selection | All subdirectories of the current folder which were included to the preview will be excluded and vice versa
Expand Source Directory | Expands the current folder
Collapse Source Directory | Collapses the current folder

#### Adding Source Directories

The &kmyapplication; database contains all images of one ore more source folders. Source folders can be added recursively or single. Adding them recursively makes &kmyapplication; add the selected directory and all directories below it. When adding a folder recursively, hard- and soft-links are followed by default. To prevent endless loops &kmyapplication; tries to detect and suppress loops in the file system directory structure.

- non-recursive: only the files in the selected folder will be added to the database.

- recursive: all files in the selected folder and all sub-folders will be added to the database.

When restarting &kmyapplication; every source folder will be rescanned and new found sub-folders and files will be added to the database. This function can also be executed manually. Missed directories of files will not automatically be removed from the database to prevent loss of the association between files and tags.

#### Removing Source Directories

Removing source directories will only remove the directory and all it's files from the &kmyapplication;. No files will be deleted, however, you will lose all tags associated with those files.

#### Rescan Source Directories

Rescanning the source directory will check the source directories for new and deleted sub directories and files. New files and directories will automatically be added to the database. &kmyapplication; will ask for user input when directories and files are deleted.

### Thumbnail Window

text text text

#### Refresh the Thumbnail Window

text text text

### Tags

text text text

#### Tag Tree

text text text

#### Adding, Deleting and Editinig Tags

text text text

##### Tagging Images

text text text

#### Tag Types

text text text

##### Title Tags

text text text

##### Boolean Tags

text text text

##### Enumeration Tags

text text text

##### String Tags

text text text

##### Numeric Tags

text text text

### Image Comments

text text text

#### Adding, Editing and Removing Comments

text text text

### Filtering the Photo Database

text text text

#### Filtering using the Tag Tree

text text text

#### Filtering using the Source Directory Tree

text text text

## Configuring &kmyapplication;

text text text

### The Configure Dialog

text text text

#### General

text text text

## Command Reference

### The main &kphotobook; window

#### The File Menu

&Ctrl;N File New

- Creates a new &kmyapplication; database

&Ctrl;O File Open

- Opens an existing &kmyapplication; database

&Ctrl;S File Save

- Saves the current &kmyapplication; database

File Save As

- Saves the current &kmyapplication; database in a new location

File Rescan Filesystem

- Rescans the source directories which are added to the database for new files and - if added recursively - for sub-folders

&Ctrl;S File Save

- Saves the document

&Ctrl;Q; &Ctrl;W File Close

- Quits &kphotobook;

#### The View Menu

F5; &Ctrl;R View Refresh View

- Refreshes the thumbnail view. This may - for example - be necessary after having changed the tag or source directory filter.

&Ctrl;+ View Increase Preview Size

- increases the thumbnail preview size.

&Ctrl;- View Decrease Preview Size

- decreases the thumbnail preview size.

View Expand All Tags

- Expands the whole tag tree with all its sub-tags so that the whole tree is visible.

View Collapse All Tags

- Collapses the whole tag tree with all its sub-tags so that only the main tags are visible.

View Expand All Source Directories

- Expands the whole source directory tree with all its sub-trees so that the whole tree is visible.

View Collapse All Source Directories

- Collapses the whole source directory tree with all its sub-trees so that only the main directories are visible.

#### The Manage Menu

Manage Add Source Directory

- Adds a new source directory to the database. This can happen to a single directory or recursively.

Manage Add Main Tag

- Adds a new main tag to the database. A main tag is a top level tag which can contain sub-tags

Manage Tag Filter Operator = AND

- Sets the tag filter operator to "AND". After refreshing, only the images which contain all the selected tags will be shown.

Manage Tag Filter Operator = OR

- Sets the tag filter operator to "OR". After refreshing, all the images which contain any of the selected tags will be shown.

#### The Settings Menu

Settings Toolbars Show Main Toolbar

- Toggles the Main Toolbar.

Settings Toolbars Show Manage

- Toggles the Manage Toolbar.

Settings Toolbars Show Preview

- Toggles the Preview Toolbar.

Manage Show Toolbar

- Toggles the Statusbar.

Manage Configure Shortcuts

- Opens the shortcut configure dialog.

Manage Configure Toolbars

- Opens the toolbar configure dialog.

Manage Configure &kmyapplication;

- Opens the &kmyapplication; configure dialog.

&Shift;F5 View Autorefresh View

- Refreshes the thumbnail view automatically after changes.

#### The Help Menu

&help.menu.documentation;

## Questions and Answers

&reporting.bugs; &updating.documentation;

How can I report bugs in &kmyapplication;?

Please visit the project homepage at sourceforge.net. Please do not send an email concerning bugs to the developer directly.

How can I report issues within this homepage?

Please send an email to the maintainer of the homepage.

Is the &kmyapplication; database compatible with the KimDaBA or Fotoon database?

No, it is not. Maybe there will be an import function.

Will there be a function to draw into the picture?

We will see...

When will the next version be released?

It's done when it's done :-)

## Credits and License

&kphotobook;

Program copyright 2004 &author.name; &author.mail;

Contributors:

- Thomas Christen &author2.mail;

- Daniel Gerber

Documentation copyright 2004 &author2.name; &author2.mail;

&underFDL; &underGPL;

## Installation

### How to obtain &kphotobook;

&install.intro.documentation;

### Requirements

In order to successfully use &kphotobook;, you need &kde; 1.1. Foobar.lib is required in order to support the advanced &kphotobook; features. &kphotobook; uses about 5 megs of memory to run, but this may vary depending on your platform and configuration.

All required libraries as well as &kphotobook; itself can be found on The &kphotobook; home page.

You can find a list of changes at http://apps.kde.org/kphotobook.

### Compilation and Installation

&install.compile.documentation;

### Configuration

Don't forget to tell your system to start the `dtd` dicer-toaster daemon first, or &kphotobook; won't work !

&documentation.index;