Warning, /frameworks/kpeople/README.md is written in an unsupported language. File is not indexed.

0001 # KPeople
0002 
0003 Provides access to all contacts and aggregates them by person.
0004 
0005 ## Introduction
0006 
0007 KPeople offers unified access to our contacts from different sources, grouping
0008 them by person while still exposing all the data.
0009 
0010 Furthermore, KPeople will also provide facilities to integrate the data provided
0011 in user interfaces by providing QML and Qt Widgets components.
0012 
0013 The sources are plugin-based, allowing to easily extend the contacts collection.
0014 
0015 ## Usage
0016 
0017 ### Components
0018 
0019 To use KPeople, you'll want to look for it using
0020 
0021 ```cmake
0022 find_package(KF6People)
0023 ```
0024 
0025 Or its qmake counterpart. Then you'll have available 3 different libraries to
0026 depend on:
0027 
0028 * KPeople which is the most basic one and will mainly provide PersonsModel
0029 and PersonData. You will use them respectively in case you need information
0030 about the full set of contacts on your system or just the one.
0031 
0032 * KPeopleWidgets will be required in case we want to integrate it into your
0033 QtWidgets-based application. We will mainly find the PersonDetailsView and
0034 the MergeDialog.
0035 
0036 * KPeopleBackend is the library used to make it possible to create backends
0037 for KPeople. You should _only_ use it in case you are providing support for
0038 a new backend type.
0039 
0040 \warning KPeopleBackend ABI interfaces are not yet stable.
0041 
0042 * Also KPeople also bundles a qml import module that can be pulled using:
0043 
0044 ```qml
0045 import org.kde.people 1.0
0046 ```
0047 
0048 This will allow access to the KPeople data from QML code-bases.
0049 
0050 ### Models
0051 
0052 KPeople provides Qt models for accessing different person related data.
0053 KPeople::PersonsModel lists all available contacts. Actions for each contact can be
0054 accessed by providing KPeople::PersonActions with a KPeople::PersonsModel::personUri.
0055 
0056 ### Person Data
0057 
0058 KPeople::PersonsModel and KPeople::PersonData also provide raw access to the VCard of a contact.
0059 
0060 VCard is a standard that is supported on many platforms and supports storing all kind
0061 of information about a person, including instant messenger contacts, phone number, names etc.
0062 It can be processed using a KContacts::VCardConverter.
0063 
0064 ### Editing contacts
0065 
0066 To make changes to a contact, its vcard can be edited by setting the custom property vcard of
0067 KPeople::PersonData to the new raw vcard data. New vcard data can be created using the
0068 KPeople::Addressee class, from which the KPeople::VCardConverter can create a vcard.
0069 
0070 ### Adding / Removing
0071 
0072 KPeople::PersonPluginManager provides static functions for adding and removing contacts.
0073 
0074 KPeople::PersonPluginManager::addContact() can be fed with a QVariantMap, which has to contain
0075 the key “vcard” with vcard data.
0076 
0077 KPeople::PersonPluginManager::deleteContact() deletes the contact with the specified uri.