[Evolution-hackers] Keeping your contacts in order

[Tristan Van Berkom <tristanvb openismus com>]

Hi,
    I'm pleased to announce that today we've finally landed the
addressbook cursor API in EDS master, a project which has been
months in the making.

What is the cursor API ?
~~~~~~~~~~~~~~~~~~~~~~~~
The EBookClientCursor is an API which allows iteration over a
sorted contact list. 

The cursor could be used for a variety of things, but was primarily
designed with sorted contact browsing user interfaces in mind.

The cursor API provides rich i18n support, allowing and aiding 
one to design contact browsers which can be used, and are suitable,
for virtually any locale.

I'm proud of the documented[0] so please go ahead and read it :)

Really there are a lot of details so I wont go over all of the
features and show case the API in this email.

A word on ICU & localization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ICU libraries (International Components for Unicode)
are now a hard dependency for Evolution Data Server.

The ICU libraries are very available and in common usage.
EDS already consumes ICU optionally through libphonenumber,
and pango consumes ICU through harfbuzz.

Another thing of note is that now the addressbook is locale
aware and has a locale setting, this setting will automatically
adapt to dynamic system locale changes.

In the user facing APIs, the locale configuration of the
addressbook can be obtained at any time with
e_book_client_get_locale().

The locale configuration is driven by the system locale
configuration D-Bus interface provided/defined by systemd[1],
"org.freedesktop.locale1".

On Backends
~~~~~~~~~~~
Currently the cursor is only implemented by the local file
backend, and the grunt work is done by the EBookBackendSqliteDB
object (this object is also shared with other backends, making
it easier at least for those backends to adapt and support the
cursor API).

For backends which use an EBookBackendSqliteDB object, one can
implement cursors with very little effort using the
EDataBookCursorSqlite cursor implementation. If other backends
want to implement cursors, they need to create their own
implementation of the abstract EDataBookCursor class.

Some documentation on implementing the cursor class can
be found here[2].

Example Code
~~~~~~~~~~~~
This branch comes with a sort of reference implementation for
a sorted contact browser which leverages most of the cursor's
features.

This example code uses the template features from the new GTK+
releases, so I've added some lines to configure.ac to declare
a completely separate set of dependencies to build the example
code.

The reasons I did it this way are:

  o Because we want the example code to be
    shown in documentation, so we would rather
    really show the newest, most recommended
    example for newly written code.

  o Because we don't want EDS to be bound
    to the same GTK+ version requirements
    (EDS depends on GTK+ for an authorization
    prompt dialog).

This example code can be found here[3].

Enjoy,
    -Tristan

[0]:https://people.gnome.org/~tvb/libebook/EBookClientCursor.html
[1]:http://www.freedesktop.org/wiki/Software/systemd/localed/
[2]:https://people.gnome.org/~tvb/libedata-book/EDataBookCursor.html
[3]:https://git.gnome.org/browse/evolution-data-server/tree/tests/cursor-example/