Development/AkonadiPorting/AddressBook - Revision history

AnneW at 15:55, 19 July 2012

2012-07-19T15:55:43Z

Neverendingo: /* Buildsystem Adjustments */

2011-06-30T10:16:35Z

‎Buildsystem Adjustments

Neverendingo: Text replace - "`" to ""`


2011-06-29T18:25:59Z
Text replace - "<code>" to "<syntaxhighlight lang="make">"

				
				
				
				
			
			← Older revision
			Revision as of 18:25, 29 June 2011
			
Line 119:
Line 119:
    
  Since the application is already linking against KDE PIM Libs classes, its CMakeList.txt already has the necessary   Since the application is already linking against KDE PIM Libs classes, its CMakeList.txt already has the necessary
− <code> + <syntaxhighlight lang="make">
  find_package( KdepimLibs 4.5 REQUIRED )   find_package( KdepimLibs 4.5 REQUIRED )
  </syntaxhighlight>   </syntaxhighlight>
    
  However, "target_link_libraries" need to be extended to contain   However, "target_link_libraries" need to be extended to contain
− <code> + <syntaxhighlight lang="make">
  ${KDEPIMLIBS_AKONADI_LIBS}   ${KDEPIMLIBS_AKONADI_LIBS}
  </syntaxhighlight>   </syntaxhighlight>
  for code classes like Akonadi::Item and   for code classes like Akonadi::Item and
− <code> + <syntaxhighlight lang="make">
  ${KDEPIMLIBS_AKONADI_CONTACT_LIBS}   ${KDEPIMLIBS_AKONADI_CONTACT_LIBS}
  </syntaxhighlight>   </syntaxhighlight>

`Neverendingo: Text replace - "`" to ""

2011-06-29T18:23:51Z

Text replace - "</code>" to "</syntaxhighlight>"

Neverendingo: Text replace - "`" to ""`


2011-06-29T18:22:27Z
Text replace - "<code cppqt>" to "<syntaxhighlight lang="cpp-qt">"

				
				
				
				
			
			← Older revision
			Revision as of 18:22, 29 June 2011
			
Line 21:
Line 21:
  A common use case is to look for a contact object by its identifier, e.g. acquired by user selection somewhen in the past.   A common use case is to look for a contact object by its identifier, e.g. acquired by user selection somewhen in the past.
  The code to do that usually looks like this:   The code to do that usually looks like this:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  KABC::AddressBook *addressBook = KABC::StdAddressBook::self();   KABC::AddressBook *addressBook = KABC::StdAddressBook::self();
    
Line 28:
Line 28:
    
  The equivalent using Akonadi API looks like this   The equivalent using Akonadi API looks like this
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob( this );   Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob( this );
  job->setQuery( Akonadi::ContactSearchJob::ContactUid, uidString );   job->setQuery( Akonadi::ContactSearchJob::ContactUid, uidString );
Line 35:
Line 35:
  </code>   </code>
  and   and
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  void contactSearchResult( KJob *job )   void contactSearchResult( KJob *job )
  {   {
Line 54:
Line 54:
    
  Another common use case is searching for matching contacts by email address. The code for that with KABC classes is almost identical:   Another common use case is searching for matching contacts by email address. The code for that with KABC classes is almost identical:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  KABC::AddressBook *addressBook = KABC::StdAddressBook::self();   KABC::AddressBook *addressBook = KABC::StdAddressBook::self();
    
Line 61:
Line 61:
    
  Unsurprisingly, the Akonadi code looks also quite similar to the previous use case:   Unsurprisingly, the Akonadi code looks also quite similar to the previous use case:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob( this );   Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob( this );
  job->setQuery( Akonadi::ContactSearchJob::Email, emailString );   job->setQuery( Akonadi::ContactSearchJob::Email, emailString );
Line 73:
Line 73:
    
  Another use case for KABC::AddressBook is not directly available in Akonadi:   Another use case for KABC::AddressBook is not directly available in Akonadi:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  KABC::AddressBook *addressBook = KABC::StdAddressBook::self();   KABC::AddressBook *addressBook = KABC::StdAddressBook::self();
    
Line 88:
Line 88:
    
  When using KABC::StdAddressBook, modifying a contact (for example one retrieved by findByUid()) worked like this:   When using KABC::StdAddressBook, modifying a contact (for example one retrieved by findByUid()) worked like this:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  addressBook->insertAddressee( contact );   addressBook->insertAddressee( contact );
    
Line 105:
Line 105:
    
  Lets say there is just the item's identifier:   Lets say there is just the item's identifier:
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  Akonadi::Item item( itemId );   Akonadi::Item item( itemId );
  item.setPayload<KABC::Addressee>( contact );   item.setPayload<KABC::Addressee>( contact );
Line 134:
Line 134:
    
  Includes for Akonadi core classes are like   Includes for Akonadi core classes are like
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  #include <Akonadi/Item>   #include <Akonadi/Item>
  </code>   </code>
    
  for contact related specializations they are like   for contact related specializations they are like
− <code cppqt> + <syntaxhighlight lang="cpp-qt">
  #include <Akonadi/Contact/ContactSearchJob>   #include <Akonadi/Contact/ContactSearchJob>
  </code>   </code>



Krake: Adding buildsystem section
2010-06-20T13:17:59Z
Adding buildsystem section

				
				
				
				
			
			← Older revision
			Revision as of 13:17, 20 June 2010
			
Line 115:
Line 115:
    
  The code for the result slot is similar to the one for search.   The code for the result slot is similar to the one for search.
  + 
  + == Buildsystem Adjustments ==
  + 
  + Since the application is already linking against KDE PIM Libs classes, its CMakeList.txt already has the necessary
  + <code>
  + find_package( KdepimLibs 4.5 REQUIRED )
  + </code>
  + 
  + However, "target_link_libraries" need to be extended to contain
  + <code>
  + ${KDEPIMLIBS_AKONADI_LIBS}
  + </code>
  + for code classes like Akonadi::Item and
  + <code>
  + ${KDEPIMLIBS_AKONADI_CONTACT_LIBS}
  + </code>
  + for contact related classes like Akonadi::ContactSearchJob.
  + 
  + Includes for Akonadi core classes are like
  + <code cppqt>
  + #include <Akonadi/Item>
  + </code>
  + 
  + for contact related specializations they are like
  + <code cppqt>
  + #include <Akonadi/Contact/ContactSearchJob>
  + </code>
  + 
  + In both cases also available in lowercase variants with ".h" suffix.
    
  == Further Reading ==   == Further Reading ==



Krake: /* Further Reading */
2010-06-20T13:14:47Z
‎Further Reading

				
				
				
				
			
			← Older revision
			Revision as of 13:14, 20 June 2010
			
Line 117:
Line 117:
    
  == Further Reading ==   == Further Reading ==
  + 
  + Akonadi porting efforts have resulted in a couple of useful classes for various aspects of dealing with PIM data.
  + 
  + For contacts such classes would be:
  + * [http://api.kde.org/4.x-api/kdepimlibs/akonadi/contact/classAkonadi_1_1ContactEditor.html Akonadi::ContactEditor] (also available as a dialog)
  + * [http://api.kde.org/4.x-api/kdepimlibs/akonadi/contact/classAkonadi_1_1ContactViewer.html Akonadi::ContactViewer] (again also available as a dialog)
  + * [http://api.kde.org/4.x-api/kdepimlibs/akonadi/contact/classAkonadi_1_1ContactsTreeModel.html Akonadi::ContactsTreeModel]



Krake: /* Modifying A Contact */
2010-06-20T13:12:41Z
‎Modifying A Contact

				
				
				
				
			
			← Older revision
			Revision as of 13:12, 20 June 2010
			
Line 86:
Line 86:
    
  === Modifying A Contact ===   === Modifying A Contact ===
  + 
  + When using KABC::StdAddressBook, modifying a contact (for example one retrieved by findByUid()) worked like this:
  + <code cppqt>
  + addressBook->insertAddressee( contact );
  + 
  + KABC::Ticket *ticket = addressBook->requestSaveTicket();
  + if ( !ticket ) {
  +   // error
  + } else if ( !addressBook->save( ticket ) ) {
  +     // error
  +     addressBook->releaseSaveTicket( ticket );
  +   }
  + }
  + </code>
  + 
  + With Akonadi, the application will need the [http://api.kde.org/4.x-api/kdepimlibs/akonadi/classAkonadi_1_1Item.html Akonadi::Item] or at least the item's identifier.
  + Assuming the contact got retrieved using ContactSearchJob, consider keeping the item or Item::id() around, see [http://api.kde.org/4.x-api/kdepimlibs/akonadi/classAkonadi_1_1ItemSearchJob.html#bf8f7a6037f632d3384637e08c99c77a ContactSearchJob::items()].
  + 
  + Lets say there is just the item's identifier:
  + <code cppqt>
  + Akonadi::Item item( itemId );
  + item.setPayload<KABC::Addressee>( contact );
  + item.setMimeType( KABC::Addressee::mimeType() );
  + 
  + Akonadi::ItemModifyJob *job = new Akonadi::ItemModifyJob( item );
  + connect( job, SIGNAL( result( KJob* ) ), SLOT( contactModifyResult( KJob* ) ) );
  + </code>
  + 
  + The code for the result slot is similar to the one for search.
    
  == Further Reading ==   == Further Reading ==



Krake: /* Who Am I */
2010-06-20T13:07:34Z
‎Who Am I

				
				
				
				
			
			← Older revision
			Revision as of 13:07, 20 June 2010
			
Line 71:
Line 71:
    
  === Who Am I ===   === Who Am I ===
  + 
  + Another use case for KABC::AddressBook is not directly available in Akonadi:
  + <code cppqt>
  + KABC::AddressBook *addressBook = KABC::StdAddressBook::self();
  + 
  + KABC::Addressee contact = addressBook->whoAmI();
  + </code>
  + 
  + {{Note|Even this had its shortcomings, because this depends on the users adding themselves to the address book and marking the respective entry as "this is me".}}
  + 
  + Concrete use cases this has been deployed for are getting the user's full name and/or their email address, which might be better served by using KDE's identity management instead, see [http://api.kde.org/4.x-api/kdepimlibs/kpimidentities/classKPIMIdentities_1_1IdentityManager.html KPIMIdentities::IdentityManager].
  + 
  + It contains the identity users can configure in the Systemsettings module for personal information, so if there is data yet, the application can just embed the respective KCM in a dialog and let the user configure this centrally for all of KDE.
    
  === Modifying A Contact ===   === Modifying A Contact ===
    
  == Further Reading ==   == Further Reading ==



Krake: /* Find By Email */
2010-06-20T13:03:39Z
‎Find By Email

				
				
				
				
			
			← Older revision
			Revision as of 13:03, 20 June 2010
			
Line 52:
Line 52:
    
  === Find By Email ===   === Find By Email ===
  + 
  + Another common use case is searching for matching contacts by email address. The code for that with KABC classes is almost identical:
  + <code cppqt>
  + KABC::AddressBook *addressBook = KABC::StdAddressBook::self();
  + 
  + KABC::Addressee contact = addressBook->findByEmail( emailString );
  + </code>
  + 
  + Unsurprisingly, the Akonadi code looks also quite similar to the previous use case:
  + <code cppqt>
  + Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob( this );
  + job->setQuery( Akonadi::ContactSearchJob::Email, emailString );
  + 
  + connect( job, SIGNAL( result( KJob* ) ), SLOT( contactSearchResult( KJob* ) ) );
  + </code>
  + 
  + The code for the result slot is the same as above.
    
  === Who Am I ===   === Who Am I ===

← Older revision		Revision as of 15:55, 19 July 2012
Line 1:		Line 1:
−	~~{{Template:I18n/Language Navigation Bar\|Development/AkonadiPorting/AddressBook}}~~	+

	== Introduction ==		== Introduction ==

← Older revision		Revision as of 13:17, 20 June 2010
Line 115:		Line 115:

	The code for the result slot is similar to the one for search.		The code for the result slot is similar to the one for search.
		+
		+	== Buildsystem Adjustments ==
		+
		+	Since the application is already linking against KDE PIM Libs classes, its CMakeList.txt already has the necessary
		+	<code>
		+	find_package( KdepimLibs 4.5 REQUIRED )
		+	</code>
		+
		+	However, "target_link_libraries" need to be extended to contain
		+	<code>
		+	${KDEPIMLIBS_AKONADI_LIBS}
		+	</code>
		+	for code classes like Akonadi::Item and
		+	<code>
		+	${KDEPIMLIBS_AKONADI_CONTACT_LIBS}
		+	</code>
		+	for contact related classes like Akonadi::ContactSearchJob.
		+
		+	Includes for Akonadi core classes are like
		+	<code cppqt>
		+	#include <Akonadi/Item>
		+	</code>
		+
		+	for contact related specializations they are like
		+	<code cppqt>
		+	#include <Akonadi/Contact/ContactSearchJob>
		+	</code>
		+
		+	In both cases also available in lowercase variants with ".h" suffix.

	== Further Reading ==		== Further Reading ==

← Older revision		Revision as of 13:14, 20 June 2010
Line 117:		Line 117:

	== Further Reading ==		== Further Reading ==
		+
		+	Akonadi porting efforts have resulted in a couple of useful classes for various aspects of dealing with PIM data.
		+
		+	For contacts such classes would be:
		+	* [http://api.kde.org/4.x-api/kdepimlibs/akonadi/contact/classAkonadi_1_1ContactEditor.html Akonadi::ContactEditor] (also available as a dialog)
		+	* [http://api.kde.org/4.x-api/kdepimlibs/akonadi/contact/classAkonadi_1_1ContactViewer.html Akonadi::ContactViewer] (again also available as a dialog)
		+	* [http://api.kde.org/4.x-api/kdepimlibs/akonadi/contact/classAkonadi_1_1ContactsTreeModel.html Akonadi::ContactsTreeModel]

← Older revision		Revision as of 13:12, 20 June 2010
Line 86:		Line 86:

	=== Modifying A Contact ===		=== Modifying A Contact ===
		+
		+	When using KABC::StdAddressBook, modifying a contact (for example one retrieved by findByUid()) worked like this:
		+	<code cppqt>
		+	addressBook->insertAddressee( contact );
		+
		+	KABC::Ticket *ticket = addressBook->requestSaveTicket();
		+	if ( !ticket ) {
		+	// error
		+	} else if ( !addressBook->save( ticket ) ) {
		+	// error
		+	addressBook->releaseSaveTicket( ticket );
		+	}
		+	}
		+	</code>
		+
		+	With Akonadi, the application will need the [http://api.kde.org/4.x-api/kdepimlibs/akonadi/classAkonadi_1_1Item.html Akonadi::Item] or at least the item's identifier.
		+	Assuming the contact got retrieved using ContactSearchJob, consider keeping the item or Item::id() around, see [http://api.kde.org/4.x-api/kdepimlibs/akonadi/classAkonadi_1_1ItemSearchJob.html#bf8f7a6037f632d3384637e08c99c77a ContactSearchJob::items()].
		+
		+	Lets say there is just the item's identifier:
		+	<code cppqt>
		+	Akonadi::Item item( itemId );
		+	item.setPayload<KABC::Addressee>( contact );
		+	item.setMimeType( KABC::Addressee::mimeType() );
		+
		+	Akonadi::ItemModifyJob *job = new Akonadi::ItemModifyJob( item );
		+	connect( job, SIGNAL( result( KJob* ) ), SLOT( contactModifyResult( KJob* ) ) );
		+	</code>
		+
		+	The code for the result slot is similar to the one for search.

	== Further Reading ==		== Further Reading ==

← Older revision		Revision as of 13:03, 20 June 2010
Line 52:		Line 52:

	=== Find By Email ===		=== Find By Email ===
		+
		+	Another common use case is searching for matching contacts by email address. The code for that with KABC classes is almost identical:
		+	<code cppqt>
		+	KABC::AddressBook *addressBook = KABC::StdAddressBook::self();
		+
		+	KABC::Addressee contact = addressBook->findByEmail( emailString );
		+	</code>
		+
		+	Unsurprisingly, the Akonadi code looks also quite similar to the previous use case:
		+	<code cppqt>
		+	Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob( this );
		+	job->setQuery( Akonadi::ContactSearchJob::Email, emailString );
		+
		+	connect( job, SIGNAL( result( KJob* ) ), SLOT( contactSearchResult( KJob* ) ) );
		+	</code>
		+
		+	The code for the result slot is the same as above.

	=== Who Am I ===		=== Who Am I ===

Development/AkonadiPorting/AddressBook - Revision history

AnneW at 15:55, 19 July 2012

Neverendingo: /* Buildsystem Adjustments */

Neverendingo: Text replace - "" to ""

Neverendingo: Text replace - "" to ""

Neverendingo: Text replace - "" to ""

Krake: Adding buildsystem section

Krake: /* Further Reading */

Krake: /* Modifying A Contact */

Krake: /* Who Am I */

Krake: /* Find By Email */

Neverendingo: Text replace - "`" to ""`

`Neverendingo: Text replace - "`" to ""

Neverendingo: Text replace - "`" to ""`