# The &kaddressbook; Handbook

Tobias Koenig

    tokoe@kde.org

Steffen Hansen

    hansen@kde.org

Don Sanders

    &Don.Sanders.mail;

Michel Boyer de la Giroday

    michel@klaralvdalens-datakonsult.se

Michael Skiba

    michael@michael-skiba.de

2008-09-20
4.1 (&kde; 4.1.2)
&FDLNotice;

&kaddressbook; is the &kde; address book.

KDE kaddressbook

## Introduction

&kaddressbook; is the main address book application for &kde;; it enables you to manage your contacts efficiently and comfortably. Since it is based on the kabc library it supports resources, which can be used to load and save your contacts to many different locations — not just the local file system, but also to LDAP servers and SQL databases.

The user interface is similar to MS Outlook and it supports different views to represent the contact data differently; it also provides an incremental search over all fields and a jump button bar to quickly access single entries. Since the underlying kabc library uses the vCard format (specified in RFC 2426) as its default storage medium, &kaddressbook; mainly reflects the supported entry fields in its graphical user interface.

## Using &kaddressbook;

### Getting Started

After you have started &kaddressbook; (either using one of the &kde; application launchers &kickoff;, the classic &kmenu; or Lancelot Launcher, or by typing `kaddressbook` at the command prompt or by using the Contacts tab in &kontact;) the &kaddressbook; main window will be displayed:

Starting &kaddressbook;
The &kaddressbook; main window.

The &kaddressbook; main window.

### Configure Resources

&kaddressbook; can use multiple resources for loading and storing its contacts. After starting &kaddressbook; for the first time you will have a default resource installed that saves all contacts in a vCard file under `$`HOME`/.kde/share/apps/kabc/std.vcf`; you can add more resources by using the Resource Configuration dialog, which is available in the &systemsettings; under Advanced-> &kde; Resources:

The Resource Configuration Dialog
The Resource Configuration Dialog.

The Resource Configuration Dialog.

Load the configuration module you want to add your resource(s) to selecting it from the drop down box at the top of the Resources section. The module for configuring &kaddressbook;'s resources is Contacts.

Launch the Resource Configuration dialog by pushing the Add... button. Choose the resource you want to add to your Contacts module and click OK to confirm your choice.

Akonadi

  To be written

Directory

  Each contact will be stored in its own file;

File

  All contacts will be stored in one file;

GroupDAV Server (e.g. Open Groupware)

  To be written

Novell GroupWise Server

  To be written

Addressbook on IMAP Server via &kmail;

  This resource stores contacts as messages on an IMAP server. &kmail; is used to access the IMAP server, therefore, if you use this type of resource, &kmail; will open whenever you access the address book, if it (or &kontact;) are not already running.

LDAP

  All contacts will be stored on a LDAP server;

Network

  All contacts will be stored in one file, which can be located on a remote server (for example, through &HTTP;, WebDAV, &FTP; or Fish).

OpenXchange Server

  This resource stores contacts on an OpenExchange server.

Addressbook on Scalix Server via &kmail;

  To be written

Suse Linux Openexchange Server

  This resource stores contacts on an OpenExchange or SUSE &Linux; OpenExchange groupware server.

eGroupware Server (via XML-RPC)

  To be written

After selecting the type of resource another dialog appears where you can configure the resource-specific settings.

The File and Directory resources support different formats for storing the contacts:

vCard

  the contacts will be stored in the vCard format, as specified in RFC 2426;

Binary

  the contacts will be stored in a binary format — this increases performance during loading and saving, but it is not portable like the vCard format;

KDE Repository Accounts

  To be written

&kaddressbook; needs a standard resource, where all contacts should be saved if no other resource is specified; for this reason, after starting &kaddressbook; the first time, there is already a resource available. If you want to use another resource as the standard resource, use the Use as Standard button to select it. You must have both read and write access to the new standard resource, otherwise you won't be able to select it.

### Managing Contacts

To create or edit contacts, &kaddressbook; offers a dialog where you can input all the data that can be stored in a vCard.

The Contact Dialog
The Contact Dialog.

The Contact Dialog.

#### General Settings tab

In the General tab you can enter the basic information about a contact, for example, addresses, phone numbers, and email addresses.

##### Automatic Name Parsing

&kaddressbook; tries to provide an easy name input by automatic name parsing; for this to work properly it is sometimes necessary to add custom name prefixes, suffixes or inclusions in the configure dialog. However, no algorithm is perfect, and rarely, a name may be parsed incorrectly; in this case, you can disable the automatic name parsing in the name edit dialog, which is available by clicking the Edit Name... button in the contact dialog. If you wish to disable the name parsing for all new contacts you can disable automatic name parsing globally in the configure dialog.

##### Formatted Name

The formatted name of a contact is used by other programs to represent it. &kaddressbook; offers three predefined types of formatted names:

Custom

  <see below>

Simple Name

  <given name> <family name>

Full Name

  <prefix> <given name> <additional name> <family name> <suffix>

Reverse Name with Comma

  <family name>, <given name>

Reverse Name

  <family name> <given name>

Organisation

  <Organisation Name>

If none of the above types fit your needs you can select the Custom name type, where you can add your own formatted name — this configuration can be done in the name edit dialog. To specify a default formatted name type for new contacts, use the configure dialog.

##### Phone Numbers

Here you can enter your contact's phone numbers. As well as land-lines and mobile/cell number, Fax, ISDN and many other types are possible. The number can contain almost any character, so it is possible to format the number in any way you need, including adding letters.

If three numbers aren't enough, simply press the Add button to get additional fields to enter a number.

If the type of the number is either a Phone, Mobile phone or Fax number you can select a script to be executed when clicking on it. (under Configuration → General)

##### Addresses

Here you can enter your contact's addresses. You can do so by pressing the Edit Addresses... Button and simply enter the Street, Post Office Box, Locality, Postal Code, and Country. After you do so you can look up the address on the map by simply clicking on the address (you can change the map-service/string used by &kaddressbook; in its settings).

You can also create a label, which will be shown instead of the real address (however, the map lookup, will use the real address).

You can also have set different addresses (i.e. one for work and one for home). It's also possible to set two different Home addresses.

##### Emails

You can enter email addresses for your contact here. You can set one address as standard.

If you set a photo for your contact on the Misc tab, &kmail; will show it when viewing these addresses.

These addresses will be used in &kmail; if you type the name of the person in either the To, CC or BCC field of a new message.

##### Instant Messaging

The IM Address text box holds the preferred Instant Messaging Address for this contact. To add, view and edit additional IM Addresses, click the Edit IM Addresses... button. The Edit Instant Messaging Address dialog appears.

The Edit IM Addresses Dialog
The Edit IM Addresses Dialog.

The Edit IM Addresses Dialog.

A contact can have multiple instant messaging addresses associated with it. Other applications, which are using the Kimproxy system, such as &kopete; or &konversation; can interact using this information. So in example you can associate a contact in IRC with a contact in your address book. This cannot be done automatically, you have to make this association manually in the specific program.

If you are not interest in whether they are picked up in another application, and just want to store the instant messaging addresses with the contact, then it's fine to add and edit them here. Otherwise it's recommended that you let the applications do the changes and not yourself, to not interfere with them.

For more information on adding new Instant Messaging Addresses, see &kopete;'s handbook and &konversation;'s handbook.

##### Categories

Categories help you to sort and group your contacts. You can simply add a contact to one or more groups by pressing the Select Categories... button.

To add your own category or remove an unused category you can click on Edit Categories.... Here you can edit, add and remove categories. Please notice that it is automatically started in Edit mode.

##### Public, Private and Confidental

The three modes Public, Private and Confidental are part of the vCard standard and implemented as such. These allow you another way to group your contacts.

#### Details tab

This is the place where you can store additional details on your contacts.

The fields are mostly self-explanatory. You will notice that the Anniversary and Birthday dates are listed in the Special Dates list in the &kontact; summary.

#### Crypto Settings tab

In this tab, you can define preferences with regards to cryptography for a contact. At the time of this writing, only &kmail; and &kontact; will make use of these preferences when composing messages. This mechanism replaces the barely editable per-recipient crypto preferences of earlier &kmail; releases.

Allowed Protocols

  Here, you can restrict the cryptographic message formats that can be used for this contact. See the section on Cryptographic Message Formats in &kmail;'s handbook for a discussion of the different available formats.

Preferred OpenPGP encryption key, Preferred &smime; encryption certificate

  Here, you can assign a preferred OpenPGP key and/or &smime; certificate to be used when encrypting to this contact. Otherwise, the local keyring and local certificate box are searched for matching keys and certificates.

Message Preference

  Here, you can select from a set of directives for user interaction both when signing and when encrypting.

  <none>

    No preference, use whatever mode &kmail; defaults to.

  Never Sign, Never Encrypt

    Never sign (encrypt) messages to this contact. Don't ask for confirmation (except in the case of conflicts with preferences of other contacts).

  Always Sign, Always Encrypt

    Always sign (encrypt) messages to the contact. Don't ask for confirmation (except in the case of conflicts with preferences of other contacts).

  Always Sign If Possible, Always Encrypt If Possible

    Always sign (encrypt) messages to this contact when it would be possible to do so. Don't ask if it isn't possible. Situations in which signing might not be possible include other recipients having signing preferences of "Never". Situations in which encryption might not be possible include missing keys/certificates for this or other receivers.

  Ask

    Always ask whether to sign (encrypt).

#### Misc tab

This describes the Misc settings tab

##### Geo Data

Here you can enter the contact's geographical location, with Latitude and Longitude. To "enable" them simply click on the check box Use geo data. After that you can either enter the coordinates by hand or click on Edit Geo Data... to select them on a world map.

##### Sound

You can store a spoken version of the name here. It is helpful for foreign names.

However this is part of the vCard 2.1 standard and only supports the three formats: WAVE, PCM, AIFF.

Select Store as URL if the sound lies on a remote machine.

##### Photo and Logo

By clicking on the buddy icon you can select and scale a picture of your contact.

The Photo will be shown in the contact preview and in the Icon view mode. However the Logo picture will only be shown in Icon view and only if there's no photo available.

To reset a photo or logo simply click on it with the &RMB; and select Reset.

##### Location of Free/Busy information

Here you can select a path to a contact's Free/Busy information, which are used when you add him to an event in &korganizer; or &kontact;'s calendar view.

#### Custom Fields Tab

In the Custom Fields Tab you can add your own fields, either for just the current contact or for all. The following types of fields are possible:

Text

  Here you can enter every alphanumeric symbol

Numeric Value

  You can only enter numbers here.

Boolean

  Boolean is only yes or no (true or false, or however you want to call it). In &kaddressbook; it's a simply check box you can check or uncheck it.

Date

  Here you can enter a date.

Time

  Here you can enter a time value.

Date & Time

  Here you can enter both, a date and a time.

### Using Views

In this version, &kaddressbook; offers different views, which can represent the contacts in three different ways:

Table View

  All contacts are listed in a table; they can be sorted by clicking at the column header of the table. The columns of the table depend on the fields which were selected in the view configuration dialog.

Icon View

  The contacts are listed as icons in a view. If the contact contains a photo or logo, then it is used in the view; otherwise, an default icon is used.

Card View

  All contacts are presented in form of cards. The titles of these cards are the formatted names; the body of each card depends on what fields were selected in the view configuration dialog.

The View Configuration Dialog
The View Configuration Dialog.

The View Configuration Dialog.

The Fields page offers you the possibility of selecting which of the stored details of a contact should be shown in the view. In the Default Filter page you can setup what filter should be used by the view.

### Using Filters

You can setup filters in &kaddressbook; which depend on the categories a contact belongs to. For example, you can create a filter that matches all contacts which belong to the categories Family and Friends; you can also create a filter that matches all contacts which do not these categories. To manage filters, use the filter configuration dialog:

The Filter Configuration Dialog
The Filter Configuration Dialog.

The Filter Configuration Dialog.

Filters can be used in views to reduce the number of contacts shown. In the view configuration dialog you can specify what filter should be used by a view by default.

### Using Extensions

Extensions are implemented as plugins in &kaddressbook;, so 3rd-party developers can provide more of them. At the moment we already have three extensions:

None

  This selection shows no extension. This is a good default selection, if you're not using any of the other extensions because it saves space.

Contact Editor

  Similar to the contact editing dialog, but designed to allow contacts to be edited quickly.

Address Books

  This extension shows you a list of available address book resources. You can check/uncheck them to show/hide the entries of a specific address book.

  It is also possible to Add, Edit or Remove an resource, for more information about this see how to configure resources.

Distribution List Manager

  This extension provides easy management of email distribution lists: just create a new list and select a contact in the view; then, after clicking Add contact, the selected contact is part of the distribution list. A simpler way is to drag a contact from the view and drop it over the distribution list manager. See Settings Menu about how to add an extension.

The main window with distribution list extension.
The main window with distribution list extension.

The main window with distribution list extension.

### Import and Export

With the new import/export framework &kaddressbook; offers a dialog where you can select which contacts are to be exported.

The export selection dialog.
The export selection dialog.

The export selection dialog.

#### Import

&kaddressbook; is able to import the following formats:

vCard

  With this entry you can import your contacts from the vCard format (RFC 2426).

MS Exchange Personal Address Book (.PAB)

  With this entry you can import your contacts from your Address book on a MS Exchange personal address book, which is used by MS Outlook and MS Outlook Express to store their contact data.

Eudora Addressbook

  With this plugin you can import your contacts from the Eudora mail client.

CSV List

  CSV (comma separated value) is a format that is used by many (address book) applications.

Opera Addressbook

  With this entry you can import your contacts from the Opera web browser.

KDE 2 Addressbook

  With this entry you can import your old contacts from a &kde; 2.x installation.

LDIF Addressbook

  LDIF is a plain-text representation of LDAP data, used by &Netscape; and Mozilla to store their address book data.

GMX Address Book

  To be written.

#### Export

&kaddressbook; is able to export into the following formats:

vCard 2.1 & 3.0

  With this entry you can export your contacts to the vCard format (RFC 2426). You can either export it into the 2.1 or in the 3.0 compatible version of the vCard standard.

CSV List

  CSV (comma separated value) is a format that is used by many (address book) applications, it stores the contact information in a plaintext field separated by commas. This makes CSV very flexible and good for interaction with scripts.

LDIF Addressbook

  LDIF is a plain-text representation of LDAP data, used by &Netscape; and Mozilla to store their address book data.

GMX Address Book

  To be written.

Bookmarks Menu

  This exports the stored URLs of your contacts into the &konqueror; bookmarks system.

Geo Data

  To be written.

### LDAP queries

Address information from LDAP servers can be imported into &kaddressbook;'s local address book by using the LDAP search dialog.

To configure (a number of) LDAP servers, use the configuration dialog.

On the main toolbar in &kaddressbook; a button with a picture of a magnifying glass over a book is available: use this button to open the LDAP search dialog. The dialog itself is pretty straight forward; just type in parts of a name, email address or phone number and press the Search button.

When the results display in the listbox it is possible to select one or more address(es); you can then use the Add Selected to import the selected address(es) to the local address book, or click the Send email to Contact to invoke a mail program to write an email to the selected recipients.

The Recursive search check box is enabled by default; this will make the LDAP query consider all objects below the base DN of each server. If you only want to consider objects one level below the base uncheck this check box; if in doubt, leave it checked.

### Preferences

You can modify many aspects of &kaddressbook;'s behavior in the preferences dialog; the dialog can be opened via Settings Configure &kaddressbook;... or using the toolbar icon.

Configuring &kaddressbook;
The preferences dialog.

The preferences dialog.

#### The General Page

##### The General Tab

Honor &kde; single click

  If checked, &kaddressbook; pays attention to the &kde; single-click option.

Automatic Name Parsing for new addresses

  If checked, the automatic name parsing feature is used for new addresses.

Limit unfiltered display to 100 contacts

  If checked, &kaddressbook; will only display 100 contacts in the contact list, when no filter is applied.

Addressee editor type

  You can either select the "Simple Editor" or the "Full Editor".

  The Simple editor mode only lets you enter the name (which will be automatically parsed, if enabled) and an email address.

Script Hooks

  Here you can specify commands which are to be executed whenever you click at a (mobile) phone number or fax number or SMS link in the details page.

##### The Contact Tab

&kaddressbook; can automatically parse a name into its parts; to make sure this works in many cases you can add, here, additional name parts, like prefixes, suffixes and inclusions.

Prefixes

  Here you can manage name prefixes, like 'Prof.' or 'Dr.'.

Inclusions

  Here you can manage name inclusions, like 'van' or 'von', which are often part of Dutch or German names.

Suffixes

  Here you can manage name suffixes like 'Sr.' or 'Jr.'.

Default Formatted Name

  Here you can select the default type of formatted names to be used for new contacts.

#### The LDAP Lookup Page

On this page you can configure the LDAP servers that should be used for ldap queries in &kaddressbook;.

Use Add Host... to add and setup a new server.

Configuring LDAP Lookup
Example of LDAP Lookup configuration.

The Add Host dialog - Example of LDAP Lookup configuration.

Please notice that some of the fields might be disabled, depending on your selections.

You can include and exclude servers from the search by selecting or deselecting their check boxes in the server list. Press OK to close the dialog.

You may configure the search order by moving the servers up or down in the list. This can be done using the arrows on the right side of the dialog.

#### The Custom Pages Page

This section allows you to add your own &GUI; elements ('Widgets') to store your own values into &kaddressbook;. Proceed as described below:

- 1. Click on Edit with QT Designer.(note: &Qt; Designer has to be installed, otherwise the button is disabled)
- 2. In the dialog, select Widget, then click OK.
- 3. Add your widgets to the form.
- 4. Save the file in the folder proposed by &Qt; Designer
- 5. Close &Qt; Designer

In case you already have a designer file (*.ui) located somewhere on your hard disk, simply choose Import Page...

IMPORTANT: The name of each input widget you place within the form must start with 'X_'; so if you want the widget to correspond to your custom entry 'X-Foo', set the widget's name property to 'X_Foo'.

IMPORTANT: The widget will edit custom fields with an application name of &kaddressbook;. To change the application name to be edited, set the widget name in &Qt; Designer.

## Command References

### The File Menu

File New New Contact...

  Opens the contact editor for adding a new contact.

File New New Distribution List...

  Opens the distribution list editor for adding a new list.

&Ctrl;S File Save

  Saves the changed contacts.

File Import

  Lists all available import modules.

File Export

  Lists all available export modules.

&Ctrl;P File Print...

  Prints the currently selected contacts.

File Send Email to Contact...

  Opens the preferred mail program with the currently selected contacts as recipients.

File Send Contact...

  Opens the preferred mail program with the currently selected contact details attached as vCard.

File Chat With...

  If a Instant Messenger application (like &kopete;) is started and online, and has an association for this contact, this entry appears. It will open a new chat window to your contact.

&Ctrl;Q File Quit

  Quits &kaddressbook;.

### The Edit Menu

&Ctrl;Z Edit Undo

  Undos the last change.

&Ctrl;&Shift;Z Edit Redo

  Redos the last change.

&Ctrl;X Edit Cut

  Cuts the currently-selected contacts.

&Ctrl;C Edit Copy

  Copies the currently-selected contacts to the clipboard.

&Ctrl;V Edit Paste

  Paste the clipboard contents into the address book (if it is in a valid format).

Edit Copy Contact To...

  To be written .

Edit Move Contact To...

  To be written .

Delete Edit Delete Contact

  Deletes the currently selected contacts.

Edit Store Contact In...

  If two or more resources are available you can move a contact into another resource.

  Please notice: This dialog will only work if two or more resources are available, if only one resource is present nothing will happen (this is a known bug).

&Ctrl;A Edit Select All

  Selects all contacts.

Edit Merge Contacts

  To merge contacts, simply select two or more and press the Merge Contacts entry. The last contact selected will be the merged contact, which now contains all information from both.

Edit Select Categories...

  Opens a dialog where you can set the categories for the currently selected contacts; when the selected categories differ from the categories of the contacts the dialog will ask you if you want to merge these differences or if the categories should be overwritten .

Edit Set as Personal Contact Data

  Marks the currently selected contact as the 'Who Am I' contact, which represents the user's data. You should have such a contact, because other applications, like &kmail; and &kword;, can make use of these data: this way you don't have to input it separately in every application .

### The View Menu

View Select View

  Lists all available views.

View Add View...

  Opens a dialog for creating a new view.

View Modify View...

  Opens a dialog where you can modify the settings of the current view.

View Delete View

  Deletes the current view.

View Contact Editor

  Display or hide the contact editor window.

View Distribution List Editor

  Display or hide the distribution list editor window.

View Address Books

  Display or hide the adressbook window.

View Refresh View

  Refreshes the current view.

### The Tools Menu

This menu provides tools for acting on the contact database.

Tools LDAP Lookup

  Opens the search dialog for addresses located on LDAP servers. You can configure the server settings in the configure dialog.

### The Settings Menu

This menu provides options for configuring &kaddressbook;, changing its appearance, shortcuts and standard behavior.

Settings Show Toolbar

  Toggles the toolbars on/off.

Settings Show Jump Bar

  Toggles the Jump Bar on/off.

Settings Show/Hide Details

  Toggles the Details Page on/off.

Settings Edit Filters...

  Opens a dialog where you can edit the filters.

Settings Configure Shortcuts...

  Opens a dialog for changing the key bindings. Using this option you can change the standard keyboard shortcuts for &kaddressbook;'s commands or create new ones.

Settings Configure Toolbars...

  Opens a dialog for configuring the toolbar. You can add and remove toolbuttons for &kaddressbook;'s commands with this option.

Settings Configure &kaddressbook;...

  Opens the preferences dialog.

### The Help Menu

&help.menu.documentation;

## Command Line Options

&kaddressbook; supports some command-line arguments, which can be used to influence its starting behavior:

`kaddressbook` `-a, --addr <email>`

  Shows the contact editor with the given email address.

`kaddressbook` `--uid <uid>`

  Shows the contact editor with the given uid.

`kaddressbook` `--editor-only`

  Launches in editor only mode.

`kaddressbook` `--new-contact`

  Launches an editor for a new contact.

&kaddressbook; also supports all other command-line options common to &kde; and &Qt; programs; you can get a list of these options with ``--help``, ``--help-kde``, and ``--help-qt``.

## Options Without a User Interface Representation

Apart from the options presented in the configuration dialog, some options can only be set directly in the configuration file ($KDEHOME/share/config/kaddressbookrc) or through KIOSK.

ContactListAboveExtensions

  If enabled, extensions (e.g. the distribution list editor) are shown below the contact list, not in an separate column. By default, this option is disabled. To enable this option, add a line reading (under [MainWindow] section):

      ContactListAboveExtensions=true

## Credits and License

&kaddressbook; - The &kde; Address Book

Copyright (c) 1997-2007, The &kde;-PIM Team

&kaddressbook; was originally written in 1997 by &Don.Sanders; &Don.Sanders.mail;. Currently it is maintained by &Tobias.Koenig; tokoe@kde.org.

&underFDL;