# Using &appname;

## Quick Start

By default, &appname; starts with an empty book collection. To work with some other type of collection, create it using the File New menu item, or the button on the toolbar. Collections are populated with some of the more common fields, but you can add, modify, or delete them to suit your needs.

New entries can be added by using the &entry-editor;. The Collection New Entry menu item will open the &entry-editor; with an empty entry ready for editing. The &entry-editor; can also be opened by using the Settings Show &entry-editor; menu item. Once you've entered the values for the entry, you can save it to the collection by using the Save Entry button in the &entry-editor; dialog, which remains open in case you want to continue adding new entries. Once you've saved an entry in the collection, you can modify it by clicking on it in the main window. If the &entry-editor; is not already open, you can double click an entry to open the editor and start editing.

If you want to include an image in the entry, you can use the standard &kde; File Selector by clicking the Select Image... button in the &entry-editor;, or you can drag an image from the file manager or web browser into the &entry-editor;.

When you select an entry, the &entry-view; shows a formatted view of the entry's contents. You can change the template used for showing the entry in the &config-dialog;.

The entries in the collection are grouped together when they share the same values for certain fields, such as the author or director. You can change the field used for grouping by using the combo box in the toolbar or the Settings Group Selection menu item.

You can use the &quick-filter; in the toolbar to quickly limit the visible entries to ones which contain the word you type. The filter is also useful when you want to quickly find an entry. You can type in the title or some other unique word that identifies the entry and the &detailed-view; will only show the entries that match the filter. The statusbar shows you how many entries are in the collection, and how many are currently being filtered.

## General Usage

The main window has three distinct areas, all of which show information about the collection in a different manner. The primary view is the &detailed-view; in the upper right area, where the value of every field for each entry may be shown. On the left side, the &group-view; can be used to sort the entries into groups in a tree-structure. Finally, the &entry-view; shows a formatted view of the data for a single entry, or an icon view of a group of entries, in the lower right.

The &appname; Main Window
The &appname; Main Window

The &appname; Main Window

### &detailed-view;

Any of the fields in the collections may be shown in the &detailed-view;, although Paragraph and Table fields will probably not be useful. Right-clicking on the header of the view opens a menu for selecting the visible fields. The columns may be resized and reordered in any way, and the settings will be saved between sessions.

### &group-view;

The &group-view; groups the entries in a tree-view by any field which allows grouping. The number of entries in each group may be shown next to the group name by achanging an option in the &config-dialog;. Groups may be expanded or collapsed by clicking the plus sign, or by double-clicking the item. Expanding and contracting all the groups are options in the right-click context menu. The tree may be sorted either by the group name, or by the count, by right-clicking on a group item. The group may also be used as a filter for the &detailed-view;

When more than one field in the collection has Format as name turned on, an additional group is added to combine all those fields into one single People pseudo-group.

If an entry does not contain a value for the field being used to form the groups, it is placed in the (Empty) group.

### &entry-view;

A formatted representation of the entry's values is shown in the &entry-view;. Templates are used for the layout and any additional graphics. Separate templates for each type of collection may be specified in the &config-dialog;. The default templates make &URL; fields active, which will open up with the default &kde; file association. When exporting to &html;, the current template is used for exporting the individual entry files.

In addition, when the collection or a group item is selected in the &group-view;, an icon view of the entries is shown, using the first Image field in the collection. Entries may be selected as in the &detailed-view;.

### Statusbar

The statusbar is used to show you what &appname; is currently doing. It also includes a total count of the entries in the collection, and if a filter is being used, how many are currently visible.

## Editing Entries

The &entry-editor; is used to add and modify entries in the collection. Double-clicking on an entry in either the &group-view; or the &detailed-view; opens the &entry-editor; with that entry. New entries may be created using the Collection menu, the toolbar icon, or the button in the &entry-editor; itself.

Closing the &entry-editor; when changes have been made but not saved will cause a warning message to appear. The fields are grouped by category and appear in the order that they appear in the &fields-dialog;. They may also be reordered.

The &entry-editor;
The &entry-editor;

The &entry-editor;

Clicking the field title for a &URL; field will open the link using the default &kde; file association. The &URL; selector button beside the text entry will open the default &kde; File Open Dialog, but the field is not limited to local files. Any &URL; may be entered. Relative &URL;s are not currently supported, as the value is interpreted relative to the location of the template stylesheet.

For Image fields, the Select Image... button opens up the &kde; image file selection dialog. The image is saved in the collection in the original format, and a scaled version is shown in the &entry-editor;. The image may be cleared by using the Clear button. Cleared images are removed from the collection.

The &entry-editor; for Image fields
The &entry-editor; for Image fields

The &entry-editor; for Image fields

The edit widget also supports drag-and-drop. Dragging an image file from a &konqueror; window does the same thing as selecting the image in the File Selector. Dragging an image from the edit widget into a &konqueror; file manager window will save the image in that folder.

Since the images are stored in the collection data file, too many images will cause &appname; to slow down significantly as well as generate a very large data file. The problem may be alleviated by limiting stored images to small thumbnails, or linking images using URL fields.

Table fields begin with five rows, but moving the cursor to the last row automatically adds another. For 2-column tables, only the first column is used for grouping or formatting.

The &entry-editor; for Table fields
The &entry-editor; for Table fields

The &entry-editor; for Table fields

### Editing Multiple Entries

Multiple entries may be edited at the same time by selecting more than one in either the &group-view; or the &detailed-view;. If multiple entries are selected, the fields which contain the same value in every entry are enabled. If entries have different values, then the fields are disabled. Checkboxes are added to the extreme right for each field entry which control whether the field is enabled or not, as shown in the screenshot below.

Only enabled fields will be modified when the entries are saved, which makes large-scale editing much easier. For example, to set the Medium of all the video entries in the collection, and make sure the Medium field is enabled. Change it to DVD, then save the entries. Only the Medium field will be modified, preserving all the other field values for the entries.

The &entry-editor; for multiple entries
The &entry-editor; for multiple entries

The &entry-editor; for multiple entries

## Editing Fields

The &fields-dialog; allows you to add new fields to the collection, to modify the existing ones, or to delete fields altogether.

The &appname; &fields-dialog;
The &appname; &fields-dialog;

The &appname; &fields-dialog;

### Field List

On the left side of the dialog is the list of the current fields. Modified fields are shown in bold italics. The buttons below the list will add or delete a field, and the arrows can be used to change their order. The order of the fields in the list is important because the &entry-editor; uses the order for its layout. For each category, the fields will be laid out from left to right, according to the top-to-bottom order of the fields in the list.

### Field Properties

A field is defined by its title, type, category, description, and possibly some allowed values. The title is used everywhere to refer to the field in the user interface. The &entry-editor; uses it to prompt for values. The &detailed-view; uses it as a column header. The different types of fields are explained in the Field Types section. The description is used as a tooltip in the &entry-editor;, perhaps to provide an explanation of the field's contents. In addition, for Dependent fields, the description is used to format the field's value. The list of allowed values for Choice fields should be separated by a semi-colon.

New fields may be any type, but changing the type of existing fields is restricted to compatible types, as shown in the table below:

#### Allowable Field Type Changes

Current Type | New Type Allowed
--- | ---
Simple Text | Simple Text, Paragraph, Number, URL, Table
Paragraph | Simple Text, Paragraph
Choice | Simple Text, Paragraph, Choice, Number, URL, Table
Checkbox | Simple Text, Paragraph, Checkbox, Number, URL, Table
Number | Simple Text, Paragraph, Number, URL, Table
URL | Simple Text, Paragraph, Number, URL, Table
Table | Simple Text, Paragraph, Table, Table (2 Columns)
Table (2 Columns) | Simple Text, Paragraph, Table, Table (2 Columns)
Image | Image
Date | Simple Text, Date
Dependent | Dependent

### Field Formatting

&appname; provides some capability for automatic formatting of field values. The simplest is auto-capitalization, which capitalizes every word except the articles. Title formatting moves certain articles from the beginning to the end of the field, for example, changing "The Return of the King" to "Return of the King, The". The title articles are configurable. Finally, name formatting tries to break up the string so that the last, or family, name of the person is shown first. Name prefixes and suffixes are configurable. Also, the special People group uses all fields with name formatting, even if the global setting is turned off.

All automatic formatting can be disabled by changing the global options in the &config-dialog;. Globally, capitalization is a distinct option from formatting, so a title can be auto-formatted without being capitalized. Not all field types allow auto-formatting.

#### Formatting Examples

Format Type | Field Value | Auto-Capitalized | Auto-Formatted | Auto-Capitalized & Auto-Formatted
--- | --- | --- | --- | ---
Title | the return of the king | The Return of the King | return of the king, the | Return of the King, The
Name | tom swift, jr. | Tom Swift, Jr. | swift, jr., tom | Swift, Jr., Tom

### Field Options

Fields also have three general options. If auto-completion is enabled, &appname; caches the values for each field, and the &entry-editor; offers automatic completion, using the standard &kde; settings. Not all field types allow auto-completion. &appname; also needs to know if a field may have multiple values or may be used to group the entries. A semi-colon is used to separate multiple values when editing an entry;

For efficiency, do not enable auto-completion unless you need it for the fields. The more fields with auto-completion in the collection, the slower it takes &appname; to load the file.

## Filtering Entries

The &filter-dialog; allows you to limit the entries visible in the &detailed-view; to those that match one or more filter rules. The filter may be used to find the entries that meet all of the rules in the dialog, or just to find those that meet any of them.

The &appname; &filter-dialog;
The &appname; &filter-dialog;

The &appname; &filter-dialog;

Each row contains a single filter rule. Select the field to match in the first box in the row, then select a matching rule in the center. Rules may match values that contain a certain word, or are exactly equal. A regular expression may also be used to match entries, in which case the Edit... button becomes active for editing the expression. Finally, the word or string to match should be entered in the text box.

Up to eight (8) rules may be used in the filter. The More and Fewer buttons may be used to add or remove rules.

To find the science fiction books you've not read, check the Match all of the following button, set the first rule to Genre contains Science Fiction and the second to Read does not contain true. (For Checkbox fields, the internal value is true).

To find the books by Bujold or Weber, check the Match any of the following button, set the first rule to Author contains Bujold and the second to Author contains Weber.