[evolution-data-server/openismus-work-3-8] EBookClientCursor documentation improvements.
- From: Tristan Van Berkom <tvb src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [evolution-data-server/openismus-work-3-8] EBookClientCursor documentation improvements.
- Date: Thu, 24 Oct 2013 20:42:05 +0000 (UTC)
commit cf8081cccc1ea622e95e5825c23b90c015ef3593
Author: Tristan Van Berkom <tristanvb openismus com>
Date: Tue Oct 22 00:27:38 2013 +0200
EBookClientCursor documentation improvements.
Added/reviewed/adapted much cursor documentation in e-book-client-cursor.c
addressbook/libebook/e-book-client-cursor.c | 388 +++++++++++++++++++++------
1 files changed, 304 insertions(+), 84 deletions(-)
---
diff --git a/addressbook/libebook/e-book-client-cursor.c b/addressbook/libebook/e-book-client-cursor.c
index a5460a2..bc053f7 100644
--- a/addressbook/libebook/e-book-client-cursor.c
+++ b/addressbook/libebook/e-book-client-cursor.c
@@ -31,16 +31,48 @@
* <title>Sort Keys</title>
* <para>
* When creating the cursor initially with e_book_client_get_cursor(),
- * a list of sort keys must be provided to define the behavior
- * of the newly created cursor. Only summary #EContactFields are
- * supported for usage as sort keys. Whether a sort key is valid in
- * your addressbook can be verified by checking with
+ * a list of #EContactFields must be provided to define the sort order for
+ * the newly created cursor. Only contact fields of type %G_TYPE_STRING
+ * can potentially be used to define a cursor's sort order.
+ * </para>
+ * <para>
+ * Backends which support cursors may refuse to create a cursor based
+ * on the fields specified as sort keys, if this happens then an
+ * %E_CLIENT_ERROR_INVALID_QUERY error will be reported by
+ * e_book_client_get_cursor().
+ * </para>
+ * <para>
+ * The default SQLite backend provided with Evolution Data Server
+ * only supports #EContactFields that are specified as summary information
+ * to be used as sort keys. Whether a contact field is configured to
+ * be part of the summary for your addressbook can be verified with
* e_source_backend_summary_setup_get_summary_fields().
* </para>
* <para>
- * Any string type #EContactField in the summary can be used as a sort key,
- * the keys are provided in order of precedence, the primary sort
- * key is first followed by any secondary or tertiary sort keys.
+ * The order of sort keys given to e_book_client_get_cursor() defines
+ * which sort key will be the primary sort key and which keys will
+ * serve as tie breakers where the previous sort keys are exact matches.
+ * In the following example we create a typical cursor sorted with
+ * %E_CONTACT_FAMILY_NAME as the primary sort key and %E_CONTACT_GIVEN_NAME
+ * as a tie breaker.
+ * <informalexample>
+ * <programlisting>
+ * <![CDATA[EBookClientCursor *cursor = NULL;
+ * EContactField sort_fields[] = { E_CONTACT_FAMILY_NAME, E_CONTACT_GIVEN_NAME };
+ * EBookCursorSortType sort_types[] = { E_BOOK_CURSOR_SORT_ASCENDING, E_BOOK_CURSOR_SORT_ASCENDING };
+ * GError *error = NULL;
+ *
+ * if (e_book_client_get_cursor_sync (book_client, // EBookClient
+ * NULL, // Search Expression
+ * sort_fields, // Sort Keys
+ * sort_types, // Ascending / Descending
+ * 2, // Number of keys
+ * &cursor, // Return location for cursor
+ * NULL, // GCancellable
+ * &error)) {
+ * // Now we have a cursor ...
+ * }]]></programlisting>
+ * </informalexample>
* </para>
* <para>
* Sort order is immutable, if you need to browse content in a different
@@ -48,23 +80,145 @@
* </para>
* </refsect2>
*
+ * <refsect2 id="cursor-state">
+ * <title>Understanding cursor state</title>
+ * <para>
+ * At any given time in a cursor's life cycle, a cursor's internal state will refer to a
+ * relative position in a sorted list.
+ * </para>
+ * <para>
+ * There are three basic varieties of cursor states:
+ * <itemizedlist>
+ * <listitem>
+ * <para>
+ * Virtual states referring to the beginnng and end of the list.
+ * </para>
+ * <para>
+ * The beginning state is positioned before any contact in the addressbook.
+ * When the cursor is in this state, a call to e_book_client_cursor_step()
+ * will always start reporting contacts from the beginning of the list.
+ * Similarly when in the end state, stepping in reverse will start
+ * reporting contacts from the end of the list.
+ * </para>
+ * <para>
+ * The beginning and end states can be reached by stepping off the
+ * end of the list, or by specifying the %E_BOOK_CURSOR_ORIGIN_BEGIN or
+ * %E_BOOK_CURSOR_ORIGIN_END origins to e_book_client_cursor_step(). The
+ * cursor is also initially positioned before the contact list.
+ * </para>
+ * </listitem>
+ * <listitem>
+ * <para>
+ * States referring to a specific contact.
+ * </para>
+ * <para>
+ * A state which refers to a specific contact in the list of
+ * contacts associated with a given cursor. At the end of any
+ * successful call to e_book_client_cursor_step() with
+ * the %E_BOOK_CURSOR_STEP_MOVE flag specified; the cursor
+ * state is updated with the value of the last result.
+ * </para>
+ * </listitem>
+ * <listitem>
+ * <para>
+ * States referring to an alphabetic position.
+ * </para>
+ * <para>
+ * When a state refers to an
+ * <link linkend="cursor-alphabet">Alphabetic Index</link>,
+ * it refers to a position which is in between contacts.
+ * For instance the alphabetic position "E" refers to a
+ * position after contacts starting with "D" and before contacts
+ * starting with "E".
+ * </para>
+ * </listitem>
+ * </itemizedlist>
+ * </para>
+ * </refsect2>
+ *
+ * <refsect2 id="cursor-pos-total">
+ * <title>Cursor position and total</title>
+ * <para>
+ * The #EBookClientCursor:position and #EBookClientCursor:total attributes
+ * provide feedback about a cursor's position in relation to the addressbook
+ * provided the cursor's sort order.
+ * </para>
+ * <para>
+ * The total reflects that total amount of contacts in the addressbook given
+ * the cursor's <link linkend="cursor-search">Search Expression</link>. The position
+ * is defined as the number of contacts leading up to the cursor position inclusive
+ * of the cursor position.
+ * </para>
+ * <para>
+ * To help illustrate how the total and position attributes relate to a sorted list
+ * of contacts, we've provided the diagram below.
+ * </para>
+ * <inlinegraphic fileref="cursor-positions.png" format="PNG" align="center"></inlinegraphic>
+ * <para>
+ * The above diagram shows two representations of a sorted contact list, using
+ * %E_CONTACT_FAMILY_NAME as the primary sort key and %E_CONTACT_GIVEN_NAME as
+ * a secondary sort key. On either side we can see the symbolic positions
+ * %E_BOOK_CURSOR_ORIGIN_BEGIN and %E_BOOK_CURSOR_ORIGIN_END.
+ * </para>
+ * <para>
+ * For a given cursor state, the position value will be equal to the total
+ * number of contacts leading up to the current cursor state inclusive of the
+ * cursor state itself. In the left hand side of the above diagram the cursor
+ * points to the fourth contact and the cursor position is also 4. An exception
+ * to this is when the cursor state refers to the %E_BOOK_CURSOR_ORIGIN_END position.
+ * When the cursor state refers to the end of list, the position property
+ * will have a value of (total + 1).
+ * </para>
+ * <para>
+ * Another thing the above diagram illustrates is the effect that an
+ * asynchronous addressbook modification has on the cursor. The right
+ * hand side of the diagram portrays the result of deleting "Mickey Mouse"
+ * from the original list on the left.
+ * </para>
+ * <para>
+ * The cursor state at this time still litteraly refers to "Mickey Mouse",
+ * however the number of contacts leading up to "Mickey Mouse" is now 3
+ * instead of 4. As one might have guessed, any addition of a contact
+ * which is considered to be less than or equal to "Mickey Mouse" at this point,
+ * will cause the position to increase again. In this way, asynchronous
+ * addressbook modification might cause the cursor's position and total
+ * values to change, but never effect the cursor's state and it's
+ * actual position in relation to other contacts in the sorted list.
+ * </para>
+ * <para>
+ * These total and position values are guaranteed to always be coherent, they are
+ * updated synchronously upon successful completion of any of the asynchronous
+ * cursor API calls, and also updated asynchronously whenever the addressbook
+ * changes and a #EBookClientCursor::refresh signal is delivered.
+ * </para>
+ * <para>
+ * Change notifications are guaranteed to only ever be delivered in the #GMainContext which
+ * was the thread default main context at cursor creation time.
+ * </para>
+ * </refsect2>
+ *
* <refsect2 id="cursor-search">
* <title>Search Expressions</title>
* <para>
* The list of contacts associated to a given cursor can be filtered
- * with a search expression generated by e_book_query_to_string(). This
- * however comes with the same limitation as sort keys, only #EContactFields
- * which are stored in the addressbook summary can be referred to in
- * search expressions provided to e_book_client_cursor_set_sexp().
+ * with a search expression generated by e_book_query_to_string(). Since
+ * this effects how the data will be traversed in the backend, seach
+ * expressions come with the same limitation as sort keys. Backends
+ * will report %E_CLIENT_ERROR_INVALID_QUERY for contact fields which
+ * are not supported. For the default local addressbook, any fields
+ * which are configured in the summary can be used to filter cursor
+ * results.
* </para>
* <para>
* Changing the search expression can be done at any time using
- * e_book_client_cursor_set_sexp() The <link linkend="cursor-stats">cursor status</link>
- * will be updated synchronously after successfully setting the
+ * e_book_client_cursor_set_sexp().
+ * The cursor <link linkend="cursor-pos-total">position and total</link>
+ * values will be updated synchronously after successfully setting the
* search expression at which time you might refresh the current
* view, displaying the new filtered list of contacts at the same
* cursor position.
* </para>
+ * <inlinegraphic fileref="cursor-positions-filtered.png" format="PNG" align="center"></inlinegraphic>
* </refsect2>
*
* <refsect2 id="cursor-iteration">
@@ -84,6 +238,8 @@
* GSList *results;
*
* if (!e_book_client_cursor_step_sync (cursor,
+ * E_BOOK_CURSOR_STEP_MOVE |
+ * E_BOOK_CURSOR_STEP_FETCH,
* E_BOOK_CURSOR_ORIGIN_CURRENT,
* 10,
* &results,
@@ -93,22 +249,39 @@
* if (g_error_matches (error,
* E_CLIENT_ERROR,
* E_CLIENT_ERROR_OUT_OF_SYNC))
+ * // The addressbook has been modified at the same time as
+ * // we asked to step. The appropriate thing to do is wait
+ * // for the "refresh" signal before trying again.
* handle_out_of_sync_condition (cursor);
+ * else if (g_error_matches (error,
+ * E_CLIENT_ERROR,
+ * E_CLIENT_ERROR_END_OF_LIST))
+ * // We asked for 10 contacts but were already positioned
+ * // at the end of the list (or we asked for -10 contacts
+ * // and were positioned at the beginning).
+ * handle_end_of_list_condition (cursor);
* else
+ * // Some error actually occurred
* handle_error_condition (cursor, error);
*
* g_clear_error (&error);
* }]]></programlisting>
* </informalexample>
* In the above example we chose %E_BOOK_CURSOR_ORIGIN_CURRENT as our #EBookCursorOrigin so the above
- * call will fetch 10 contacts after the cursor's current position and reposition the current cursor
- * location 10 contacts further into the results. We could have chosen the %E_BOOK_CURSOR_ORIGIN_RESET
- * origin to start at the beginning of the results or the %E_BOOK_CURSOR_ORIGIN_PREVIOUS
- * origin to start the query from the previous position. The cursor keeps a record of the last
- * known cursor position for the purpose of repeating queries when the addressbook is modified.
+ * call will traverse 10 contacts following the cursor's current position. One can also choose the
+ * %E_BOOK_CURSOR_ORIGIN_BEGIN or %E_BOOK_CURSOR_ORIGIN_END origin to start at the beginning or end
+ * of the results at any time.
+ * </para>
+ * <para>
+ * We also specified both of the flags %E_BOOK_CURSOR_STEP_MOVE and %E_BOOK_CURSOR_STEP_FETCH,
+ * this means we want to receive results from the addressbook and we also want to modify
+ * the current cursor state (move the cursor), these operations can however be done
+ * completely independantly of eachother, which is often what is desired for a contact
+ * browsing user interface. It is however recommended to move and fetch
+ * results in a single pass wherever that makes sense in your application.
* </para>
* <para>
- * Because Evolution's addressbook might be modified at any time by another application,
+ * Because the addressbook might be modified at any time by another application,
* it's important to handle the %E_CLIENT_ERROR_OUT_OF_SYNC error. This error will occur
* at any time that the cursor detects an addressbook change while trying to move.
* Whenever an out of sync condition arises, the cursor should be left alone until the
@@ -117,42 +290,40 @@
* loaded content, it is also guaranteed to be triggered after any %E_CLIENT_ERROR_OUT_OF_SYNC
* error.
* </para>
- * </refsect2>
- *
- * <refsect2 id="cursor-stats">
- * <title>Cursor Status</title>
* <para>
- * The cursor's current status is available through the #EBookClientCursor:total and
- * #EBookClientCursor:position properties. These values are guaranteed to always
- * be coherent, they are updated synchronously upon successful completion of any
- * of the asynchronous cursor API calls, and also updated asynchronously whenever
- * the addressbook changes and a #EBookClientCursor::refresh signal is delivered.
- * </para>
- * <para>
- * Change notifications are guaranteed to only ever be delivered in the #GMainContext which
- * was the thread default main context at cursor creation time.
+ * The diagram below illustrates some scenarios of how the cursor state is updated
+ * in calls to e_book_client_cursor_step().
* </para>
+ * <inlinegraphic fileref="cursor-positions-step.png" format="PNG" align="center"></inlinegraphic>
* </refsect2>
- *
+ *
* <refsect2 id="cursor-alphabet">
* <title>Alphabetic Indexes</title>
* <para>
- * The cursor implementation uses ICU libraries to provide a rich locale sensitive
- * featureset, this ensures that results are always sorted in the expected addressbook
- * sort order (as opposed to dictionary order or phonetic order) and in the expected
- * order according to the user's locale.
+ * The cursor permits navigation of the sorted contact list in terms of alphabetic
+ * positions in the list, allowing one to jump from one letter to the next in
+ * the active alphabet.
+ * </para>
+ * <para>
+ * The active alphabet itself is represented as an array of UTF-8 strings which are
+ * suitable to display a given glyph or alphabetic position in the user's active alphabet.
+ * This array of alphabetic position labels is exposed via the #EBookClientCursor:alphabet
+ * property and can always be fetched with e_book_client_cursor_get_alphabet().
* </para>
* <para>
- * One of the more interesting features this allows for, is support for locale
- * specific language scripts, i.e. Alphabetic Indexes.
+ * As shown below, each index in the active alphabet array is a potential cursor state
+ * which refers to a position before, after or in between contacts in the sorted contact list.
+ * Most of the positions in the active alphabet array refer to alphabetic glyhps or positions,
+ * however the the 'underflow', 'inflow' and 'overflow' positions represent positions for
+ * contacts which sort outside the bounderies of the active alphabet.
* </para>
+ * <inlinegraphic fileref="cursor-alphabetic-indexes.png" format="PNG" align="center"></inlinegraphic>
* <para>
- * The cursor exposes the active alphabet via the #EBookClientCursor:alphabet property.
- * which is a null terminated array of strings. The strings are appropriate to display
- * to represent positions (letters / characters) in the active alphabet, for instance
- * for a Latin alphabet the array will contain <emphasis>"A", "B", "C", ...</emphasis>.
- * The full information on the active alphabet can always be fetched with
- * e_book_client_cursor_get_alphabet().
+ * The active alphabet is dynamically resolved from the system locale at startup time and
+ * whenever a system locale change notification is delivered to Evolution Data Server. If
+ * ever the system locale changes at runtime then a change notification will be delivered
+ * for the #EBookClientCursor:alphabet property, this is a good time to refresh the list
+ * of alphabetic positions available in a user interface.
* </para>
* <para>
* Using the active alphabet, one can build a user interface which allows the user
@@ -164,6 +335,9 @@
* <![CDATA[GError *error = NULL;
* gint index = currently_selected_index (user_interface);
*
+ * // At this point 'index' must be a numeric value corresponding
+ * // to one of the positions in the array returned by
+ * // e_book_client_cursor_get_alphabet().
* if (!e_book_client_cursor_set_alphabetic_index_sync (cursor,
* index,
* NULL,
@@ -172,6 +346,8 @@
* if (g_error_matches (error,
* E_CLIENT_ERROR,
* E_CLIENT_ERROR_OUT_OF_SYNC))
+ * // The system locale has changed at the same time
+ * // as we were setting an alphabetic cursor position.
* handle_out_of_sync_condition (cursor);
* else
* handle_error_condition (cursor, error);
@@ -184,7 +360,7 @@
* beginning of the given letter.
* </para>
* <para>
- * This API can also result in an %E_CLIENT_ERROR_OUT_OF_SYNC error. This error will
+ * This API can result in an %E_CLIENT_ERROR_OUT_OF_SYNC error. This error will
* occur at any time that the cursor tries to set the alphabetic index whilst the
* addressbook is changing its active locale setting. In the case of a dynamic locale
* change, a change notification will be delivered for the #EBookClientCursor:alphabet
@@ -209,6 +385,24 @@
* <example id="example-contact-browser"><title>Example Contact Browser</title><programlisting><xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../../tests/cursor-example/cursor-example.c"><xi:fallback>FIXME: MISSING XINCLUDE
CONTENT</xi:fallback></xi:include></programlisting></example>
* </para>
* </refsect2>
+ *
+ * <refsect2 id="cursor-example-program">
+ * <title>Example Contact Browser</title>
+ * <para>
+ * Evolution Data Server comes with an example implementation of a
+ * contact browser using the cursor features, the main portion of
+ * this example is included here below.
+ * </para>
+ * <informalexample>
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
+ * parse="text"
+ * href="../../../../../tests/cursor-example/cursor-example.c">
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * </xi:include>
+ * </programlisting>
+ * </informalexample>
+ * </refsect2>
*/
#ifdef HAVE_CONFIG_H
#include <config.h>
@@ -451,6 +645,10 @@ e_book_client_cursor_class_init (EBookClientCursorClass *class)
*
* The #EContactField names to sort this cursor with
*
+ * <note><para>This is an internal parameter for constructing the
+ * cursor, to construct the cursor use e_book_client_get_cursor().
+ * </para></note>
+ *
* Since: 3.12
*/
g_object_class_install_property (
@@ -487,6 +685,10 @@ e_book_client_cursor_class_init (EBookClientCursorClass *class)
*
* The #GMainContext in which the #EBookClient created this cursor.
*
+ * <note><para>This is an internal parameter for constructing the
+ * cursor, to construct the cursor use e_book_client_get_cursor().
+ * </para></note>
+ *
* Since: 3.12
*/
g_object_class_install_property (
@@ -505,6 +707,10 @@ e_book_client_cursor_class_init (EBookClientCursorClass *class)
*
* The #GDBusConnection to the addressbook server.
*
+ * <note><para>This is an internal parameter for constructing the
+ * cursor, to construct the cursor use e_book_client_get_cursor().
+ * </para></note>
+ *
* Since: 3.12
*/
g_object_class_install_property (
@@ -524,6 +730,10 @@ e_book_client_cursor_class_init (EBookClientCursorClass *class)
*
* The D-Bus object path to find the server side cursor object.
*
+ * <note><para>This is an internal parameter for constructing the
+ * cursor, to construct the cursor use e_book_client_get_cursor().
+ * </para></note>
+ *
* Since: 3.12
*/
g_object_class_install_property (
@@ -544,6 +754,10 @@ e_book_client_cursor_class_init (EBookClientCursorClass *class)
*
* The direct handle to the #EDataBookCursor for direct read access mode.
*
+ * <note><para>This is an internal parameter for constructing the
+ * cursor, to construct the cursor use e_book_client_get_cursor().
+ * </para></note>
+ *
* Since: 3.12
*/
g_object_class_install_property (
@@ -560,8 +774,8 @@ e_book_client_cursor_class_init (EBookClientCursorClass *class)
/**
* EBookClientCursor:alphabet:
*
- * The active alphabet.
- *
+ * The currently <link linkend="cursor-alphabet">active alphabet</link>.
+ *
* The value is a %NULL terminated array of strings,
* each string is suitable to display a specific letter
* in the active alphabet.
@@ -615,6 +829,16 @@ e_book_client_cursor_class_init (EBookClientCursorClass *class)
*
* The current cursor position in the cursor's result list.
*
+ * More specifically, the cursor position is defined as
+ * the number of contacts leading up to the current
+ * cursor position, inclusive of the current cursor
+ * position.
+ *
+ * If the position value is %0, then the cursor is positioned
+ * before the contact list. Conversely, if the position value
+ * is greater than #EBookClientCursor:total, this indicates
+ * that the cursor is positioned after the contact list.
+ *
* Property change notifications are guaranteed to be
* delivered in the #GMainContext which was the thread
* default context at cursor creation time.
@@ -636,10 +860,8 @@ e_book_client_cursor_class_init (EBookClientCursorClass *class)
* @cursor: The #EBookClientCursor which needs to be refreshed
*
* Indicates that the addressbook has been modified and
- * that the cursor results should be refreshed.
- *
- * This is normally done by calling e_book_client_cursor_step()
- * with an %E_BOOK_CURSOR_ORIGIN_PREVIOUS origin.
+ * that any content currently being displayed from the current
+ * cursor position should be reloaded.
*
* This signal is guaranteed to be delivered in the #GMainContext
* which was the thread default context at cursor creation time.
@@ -1868,7 +2090,7 @@ e_book_client_cursor_ref_client (EBookClientCursor *cursor)
* @inflow: (allow-none) (out): The inflow index, for any words which sort between the active alphabets (if
there is more than one)
* @overflow: (allow-none) (out): The overflow index, for any words which sort above the active alphabet
*
- * Fetches the array of displayable labels for the active alphabet.
+ * Fetches the array of displayable labels for the <link linkend="cursor-alphabet">active alphabet</link>.
*
* The active alphabet is based on the current locale configuration of the
* addressbook, and can be a different alphabet for locales requiring non-Latin
@@ -1876,23 +2098,17 @@ e_book_client_cursor_ref_client (EBookClientCursor *cursor)
* interface to represent the alphabetic position of the cursor in the user's
* native alphabet.
*
- * The positions of these labels in the returned array can later be used
- * with e_book_client_cursor_set_alphabetic_index() to explicitly set the
- * cursor position to a given index in the active alphabet. This allows
- * one to construct a user interface which allows the user to jump to
- * a given letter in the ordered cursor results.
- *
- * The alphabet can periodically change when the system locale changes, change
- * notifications will be delivered asynchronously to the #EBookClientCursor:alphabet
- * property at any time the system locale changes and the active alphabet is updated.
- *
* The @underflow, @inflow and @overflow parameters allow one to observe which
* indexes Evolution Data Server is using to store words which sort outside
* of the alphabet, for instance words from foreign language scripts and
- * words which start with numeric characters, or other types of character
- * (the @inflow index is currently unused, but can be used for words which
- * sort between the active alphabets, if more than one alphabet is displayed
- * for a given locale).
+ * words which start with numeric characters, or other types of character.
+ *
+ * While the @underflow and @overflow are for words which sort below or
+ * above the active alphabets, the @inflow index is for words which sort
+ * in between multiple concurrently active alphabets. The active alphabet
+ * array might contain more than one alphabet for locales where it is
+ * very common or expected to have names in Latin script as well as names
+ * in another script.
*
* Returns: (array zero-terminated=1) (element-type utf8) (transfer none):
* The array of displayable labels for each index in the active alphabet.
@@ -1942,15 +2158,16 @@ e_book_client_cursor_get_total (EBookClientCursor *cursor)
* e_book_client_cursor_get_position:
* @cursor: an #EBookClientCursor
*
- * Fetches the current cursor position within @cursor's
- * query results.
+ * Fetches the number of contacts leading up to the current
+ * cursor position, inclusive of the current cursor position.
*
- * The position value can be any where from 0 to the total
- * number of contacts at any given time, a value of 0 indicates
- * that the cursor is positioned before the contact list, if
- * the position is equal to the total, as returned by
- * e_book_client_cursor_get_total(), then the cursor points
- * to the last contact in @cursor's query results.
+ * The position value can be anywhere from 0 to the total
+ * number of contacts plus one. A value of 0 indicates
+ * that the cursor is positioned before the contact list in
+ * the symbolic %E_BOOK_CURSOR_ORIGIN_BEGIN state. If
+ * the position is greater than the total, as returned by
+ * e_book_client_cursor_get_total(), then the cursor is positioned
+ * after the last contact in the symbolic %E_BOOK_CURSOR_ORIGIN_END position.
*
* Returns: The current cursor position
*
@@ -2067,7 +2284,7 @@ e_book_client_cursor_set_sexp_finish (EBookClientCursor *cursor,
* Sets the <link linkend="cursor-search">Search Expression</link> for the cursor.
*
* A side effect of setting the search expression is that the
- * #EBookClientCursor:position and #EBookClientCursor:total
+ * <link linkend="cursor-pos-total">position and total</link>
* properties will be updated.
*
* If this method is called from the same thread context in which
@@ -2177,8 +2394,8 @@ e_book_client_cursor_step (EBookClientCursor *cursor,
* Completes an asynchronous call initiated by e_book_client_cursor_step(), fetching
* any contacts which might have been returned by the call.
*
- * Returns: The number of contacts which the cursor has moved by if successfull.
- * Otherwise -1 is returned and @error is set.
+ * Returns: The number of contacts traversed if successfull, otherwise -1 is
+ * returned and @error is set.
*
* Since: 3.12
*/
@@ -2245,8 +2462,9 @@ e_book_client_cursor_step_finish (EBookClientCursor *cursor,
* If %E_BOOK_CURSOR_STEP_FETCH is specified in %flags, a pointer to
* a %NULL #GSList pointer should be provided for the @results parameter.
*
- * A side effect of moving the cursor is that the #EBookClientCursor:position
- * property will be updated.
+ * If %E_BOOK_CURSOR_STEP_MOVE is specified in %flags, then the cursor's
+ * state will be modified and the <link linkend="cursor-pos-total">position</link>
+ * property will be updated as a result.
*
* If this method is called from the same thread context in which
* the cursor was created, then the updates to the #EBookClientCursor:position
@@ -2260,8 +2478,8 @@ e_book_client_cursor_step_finish (EBookClientCursor *cursor,
* to be followed by an #EBookClientCursor::refresh signal at which point any content
* should be reloaded.
*
- * Returns: The number of contacts which the cursor has moved by if successfull.
- * Otherwise -1 is returned and @error is set.
+ * Returns: The number of contacts traversed if successfull, otherwise -1 is
+ * returned and @error is set.
*
* Since: 3.12
*/
@@ -2359,6 +2577,8 @@ e_book_client_cursor_set_alphabetic_index (EBookClientCursor *cursor,
* Completes an asynchronous call initiated by e_book_client_cursor_set_alphabetic_index().
*
* Returns: %TRUE on success, otherwise %FALSE is returned and @error is set.
+ *
+ * Since: 3.12
*/
gboolean
e_book_client_cursor_set_alphabetic_index_finish (EBookClientCursor *cursor,
@@ -2399,9 +2619,9 @@ e_book_client_cursor_set_alphabetic_index_finish (EBookClientCursor *cursor,
* @cancellable: (allow-none): a #GCancellable to optionally cancel this operation while in progress
* @error: (out) (allow-none): return location for a #GError, or %NULL
*
- * Sets the current cursor position to point to an <link linkend="cursor-alphabet">Alphabetic Index</link>.
+ * Sets the cursor to point to an <link linkend="cursor-alphabet">Alphabetic Index</link>.
*
- * After setting the target alphabetic index, for example the
+ * After setting the alphabetic index, for example the
* index for letter 'E', then further calls to e_book_client_cursor_step()
* will return results starting with the letter 'E' (or results starting
* with the last result in 'D' when navigating through cursor results
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
