diff options
Diffstat (limited to 'docs/reference/xml/evolution-data-server-cursor-example.sgml.in')
| -rw-r--r-- | docs/reference/xml/evolution-data-server-cursor-example.sgml.in | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/docs/reference/xml/evolution-data-server-cursor-example.sgml.in b/docs/reference/xml/evolution-data-server-cursor-example.sgml.in new file mode 100644 index 000000000..be999ae2d --- /dev/null +++ b/docs/reference/xml/evolution-data-server-cursor-example.sgml.in @@ -0,0 +1,147 @@ +<refentry id="eds-cursor-example" revision="30 Nov 2013"> + <refmeta> + <refentrytitle>Contacts Browser Example</refentrytitle> + <refmiscinfo>Contacts Browser Example</refmiscinfo> + </refmeta> + <refnamediv> + <refname>Contacts Browser Example</refname> + <refpurpose> + Explanation of how to create a scrolling window listing contacts in + alphabetical order. + </refpurpose> + </refnamediv> + + <refsect1> + <title>Introduction</title> + <para> + This is a fully functional reference application for implementing scrolling contact + browsers using the #EBookClientCursor. With the cursor, the following features are + possible. + </para> + + <itemizedlist> + <listitem> + <para>Display contacts in a configurable sort order</para> + <para> + Sort by any #EContactField which conforms to #G_TYPE_STRING, this can be checked + with e_contact_field_type() + </para> + </listitem> + <listitem> + <para>Minimal memory constraints</para> + <para> + Only load into memory the contacts which are currently visible in the list + </para> + </listitem> + <listitem> + <para>Filter search results on the fly</para> + <para> + Set new search expressions generated with #EBookQuery on the fly. Refresh + the contact list at the current position without losing the current cursor + position. + </para> + </listitem> + <listitem> + <para>Display the the user's alphabet</para> + <para> + Using interesting features from ICU libraries allow us to display + the user's alphabet, and implement features such as jumping to + a given letter in the user's alphabet. + </para> + </listitem> + </itemizedlist> + + <para> + The actual example code is built into the 'example' subdirectory of the Evolution Data Server + sources. In order to run the example, just launch the program and give it a path to a directory + full of vcards, bearing the .vcf filename extention. + </para> + + </refsect1> + + <refsect1> + <title>Contact Browser</title> + <para> + Below is an example of the contact browser code itself, the example program is + broken down into a couple of object classes which are also listed below. + </para> + + <informalexample> + <programlisting> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="text" + href="@CMAKE_SOURCE_DIR@/src/examples/cursor/cursor-example.c"/> + </programlisting> + </informalexample> + </refsect1> + + <refsect1> + <title>The alphabetic navigator</title> + <para> + This is a simple class which implements a vertical scroller and displays + various letters according to the currently active alphabet. The actual + interaction with #EBookClientCursor is done in the main contact browser + and this class is simply configured with the active alphabet. + </para> + + <informalexample> + <programlisting> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="text" + href="@CMAKE_SOURCE_DIR@/src/examples/cursor/cursor-navigator.c"/> + </programlisting> + </informalexample> + </refsect1> + + <refsect1> + <title>The search entry</title> + <para> + The search entry is placed at the top of the contacts browser, + this class simply implements a drop down box choosing the appropriate + search expression which should be used to filter the contacts + in the browser display window. + </para> + + <informalexample> + <programlisting> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="text" + href="@CMAKE_SOURCE_DIR@/src/examples/cursor/cursor-search.c"/> + </programlisting> + </informalexample> + </refsect1> + + <refsect1> + <title>The contact slot</title> + <para> + This is a very simple class who's only purpose is to display + contact related data, each entry in the list is a 'slot' + </para> + + <informalexample> + <programlisting> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="text" + href="@CMAKE_SOURCE_DIR@/src/examples/cursor/cursor-slot.c"/> + </programlisting> + </informalexample> + </refsect1> + + <refsect1> + <title>Creating addressbooks and loading vcards</title> + <para> + This is the messy part of the example, here we take care + of creating a custom addressbook and populating it with + the contacts found in the directory given to the example. + </para> + + <informalexample> + <programlisting> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + parse="text" + href="@CMAKE_SOURCE_DIR@/src/examples/cursor/cursor-data.c"/> + </programlisting> + </informalexample> + </refsect1> + +</refentry> |