EBook.BookClientCursor

g EBook.BookClientCursor EBook.BookClientCursor GObject.GInterface GObject.GInterface Gio.Initable Gio.Initable GObject.GInterface->Gio.Initable GObject.Object GObject.Object GObject.Object->EBook.BookClientCursor Gio.Initable->EBook.BookClientCursor

Subclasses:

None

Methods

Inherited:

GObject.Object (37), Gio.Initable (2)

Structs:

GObject.ObjectClass (5)

get_alphabet ()

get_contact_alphabetic_index (contact)

get_position ()

get_total ()

ref_client ()

set_alphabetic_index (index, cancellable, callback, *user_data)

set_alphabetic_index_finish (result)

set_alphabetic_index_sync (index, cancellable)

set_sexp (sexp, cancellable, callback, *user_data)

set_sexp_finish (result)

set_sexp_sync (sexp, cancellable)

step (flags, origin, count, cancellable, callback, *user_data)

step_finish (result)

step_sync (flags, origin, count, cancellable)

Virtual Methods

Inherited:

GObject.Object (7), Gio.Initable (1)

do_refresh ()

Properties

Name

Type

Flags

Short Description

alphabet

[str]

r

The active alphabet

client

EBook.BookClient

r/w/co

The EBook.BookClient for the cursor

connection

Gio.DBusConnection

w/co

The Gio.DBusConnection used to create the D-Bus proxy

context

GLib.MainContext

w/co

The GLib.MainContext in which this cursor was created

object-path

str

w/co

The object path used to create the D-Bus proxy

position

int

r

The current cursor position

sort-fields

[str]

w/co

The EBookContacts.ContactField names to sort this cursor with

total

int

r

The total contacts for this cursor’s query

Signals

Inherited:

GObject.Object (1)

Name

Short Description

refresh

Indicates that the addressbook has been modified and that any content currently being displayed from the current cursor position should be reloaded.

Fields

Inherited:

GObject.Object (1)

Name

Type

Access

Description

parent

GObject.Object

r

Class Details

class EBook.BookClientCursor(**kwargs)
Bases:

GObject.Object, Gio.Initable

Abstract:

No

Structure:

EBook.BookClientCursorClass

Contains only private data.

New in version 3.12.

get_alphabet()
Returns:

The array of displayable labels for each index in the active alphabet.

n_labels:

The number of labels in the active alphabet

underflow:

The underflow index, for any words which sort below the active alphabet

inflow:

The inflow index, for any words which sort between the active alphabets (if there is more than one)

overflow:

The overflow index, for any words which sort above the active alphabet

Return type:

([str], n_labels: int, underflow: int, inflow: int, overflow: int)

Fetches the array of displayable labels for the ‘active alphabet [cursor-alphabet]’.

The active alphabet is based on the current locale configuration of the addressbook, and can be a different alphabet for locales requiring non-Latin language scripts. These UTF-8 labels are appropriate to display in a user interface to represent the alphabetic position of the cursor in the user’s native alphabet.

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.

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.

New in version 3.12.

get_contact_alphabetic_index(contact)
Parameters:

contact (EBookContacts.Contact) – the EBookContacts.Contact to check

Returns:

The alphabetic index of contact in self.

Return type:

int

Checks which alphabetic index contact would be sorted into according to self.

So long as the active EBook.BookClientCursor :alphabet does not change, the returned index will be a valid position in the array of labels returned by EBook.BookClientCursor.get_alphabet().

If the index returned by this function is needed for any extended period of time, it should be recalculated whenever the EBook.BookClientCursor :alphabet changes.

New in version 3.12.

get_position()
Returns:

The current cursor position

Return type:

int

Fetches the number of contacts leading up to the current cursor position, inclusive of the current cursor position.

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 EBookContacts.BookCursorOrigin.BEGIN state. If the position is greater than the total, as returned by EBook.BookClientCursor.get_total(), then the cursor is positioned after the last contact in the symbolic EBookContacts.BookCursorOrigin.END position.

New in version 3.12.

get_total()
Returns:

The total number of contacts matching self's query

Return type:

int

Fetches the total number of contacts in the addressbook which match self's query

New in version 3.12.

ref_client()
Returns:

an EBook.BookClient

Return type:

EBook.BookClient

Returns the EBook.BookClientCursor :client associated with self.

The returned EBook.BookClient is referenced because the cursor does not keep a strong reference to the client.

Unreference the EBook.BookClient with GObject.Object.unref() when finished with it.

New in version 3.12.

set_alphabetic_index(index, cancellable, callback, *user_data)
Parameters:

Sets the current cursor position to point to an ‘Alphabetic Index [cursor-alphabet]’.

See: EBook.BookClientCursor.set_alphabetic_index_sync().

This asynchronous call is completed with a call to EBook.BookClientCursor.set_alphabetic_index_finish() from the specified callback.

New in version 3.12.

set_alphabetic_index_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set.

Return type:

bool

Completes an asynchronous call initiated by EBook.BookClientCursor.set_alphabetic_index().

New in version 3.12.

set_alphabetic_index_sync(index, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set.

Return type:

bool

Sets the cursor to point to an ‘Alphabetic Index [cursor-alphabet]’.

After setting the alphabetic index, for example the index for letter ‘E’, then further calls to EBook.BookClientCursor.step() will return results starting with the letter ‘E’ (or results starting with the last result in ‘D’ when navigating through cursor results in reverse).

The passed index must be a valid index into the alphabet parameters returned by EBook.BookClientCursor.get_alphabet().

If this method is called from the same thread context in which the cursor was created, then the updates to the EBook.BookClientCursor :position property are guaranteed to be delivered synchronously upon successful completion of moving the cursor. Otherwise, notifications will be delivered asynchronously in the cursor’s original thread context.

If this method completes with an EDataServer.ClientError.OUT_OF_SYNC error, it is an indication that the addressbook has been set into a new locale and it would be unsafe to set the alphabetic index at this time. If you receive an out of sync error from this method, then you should wait until an EBook.BookClientCursor :alphabet property change notification is delivered and then proceed to load the new alphabet before trying to set any alphabetic index.

New in version 3.12.

set_sexp(sexp, cancellable, callback, *user_data)
Parameters:

Sets the ‘Search Expression [cursor-search]’ for the cursor.

See: EBook.BookClientCursor.set_sexp_sync().

This asynchronous call is completed with a call to EBook.BookClientCursor.set_sexp_finish() from the specified callback.

New in version 3.12.

set_sexp_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set.

Return type:

bool

Completes an asynchronous call initiated by EBook.BookClientCursor.set_sexp(), reporting whether the new search expression was accepted.

New in version 3.12.

set_sexp_sync(sexp, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set.

Return type:

bool

Sets the ‘Search Expression [cursor-search]’ for the cursor.

A side effect of setting the search expression is that the

‘position and total [cursor-pos-total]’ properties will be updated.

If this method is called from the same thread context in which the cursor was created, then the updates to the EBook.BookClientCursor :position and EBook.BookClientCursor :total properties are guaranteed to be delivered synchronously upon successful completion of setting the search expression. Otherwise, notifications will be delivered asynchronously in the cursor’s original thread context.

If the backend does not support the given search expression, an EDataServer.ClientError.INVALID_QUERY error will be set.

New in version 3.12.

step(flags, origin, count, cancellable, callback, *user_data)
Parameters:

‘Steps the cursor through the results [cursor-iteration]’ by a maximum of count and fetch the results traversed.

See: EBook.BookClientCursor.step_sync().

This asynchronous call is completed with a call to EBook.BookClientCursor.step_finish() from the specified callback.

New in version 3.12.

step_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

The number of contacts traversed if successful, otherwise -1 is returned and error is set.

out_contacts:

return location for a GLib.SList of EBookContacts.Contact

Return type:

(int, out_contacts: [EBookContacts.Contact])

Completes an asynchronous call initiated by EBook.BookClientCursor.step(), fetching any contacts which might have been returned by the call.

New in version 3.12.

step_sync(flags, origin, count, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

The number of contacts traversed if successful, otherwise -1 is returned and error is set.

out_contacts:

return location for a GLib.SList of EBookContacts.Contact

Return type:

(int, out_contacts: [EBookContacts.Contact])

‘Steps the cursor through the results [cursor-iteration]’ by a maximum of count and fetch the results traversed.

If count is negative, then the cursor will move backwards.

If self reaches the beginning or end of the query results, then the returned list might not contain the amount of desired contacts, or might return no results if the cursor currently points to the last contact. Reaching the end of the list is not considered an error condition. Attempts to step beyond the end of the list after having reached the end of the list will however trigger an EDataServer.ClientError.QUERY_REFUSED error.

If EBookContacts.BookCursorStepFlags.FETCH is specified in flags, a pointer to a None GLib.SList pointer should be provided for the results parameter.

If EBookContacts.BookCursorStepFlags.MOVE is specified in flags, then the cursor’s state will be modified and the ‘position [cursor-pos-total]’ 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 EBook.BookClientCursor :position property are guaranteed to be delivered synchronously upon successful completion of moving the cursor. Otherwise, notifications will be delivered asynchronously in the cursor’s original thread context.

If this method completes with an EDataServer.ClientError.OUT_OF_SYNC error, it is an indication that the addressbook has been modified and it would be unsafe to move the cursor at this time. Any EDataServer.ClientError.OUT_OF_SYNC error is guaranteed to be followed by an EBook.BookClientCursor ::refresh signal at which point any content should be reloaded.

New in version 3.12.

do_refresh() virtual

Signal Details

EBook.BookClientCursor.signals.refresh(book_client_cursor)
Signal Name:

refresh

Flags:

RUN_LAST

Parameters:

book_client_cursor (EBook.BookClientCursor) – The object which received the signal

Indicates that the addressbook has been modified and that any content currently being displayed from the current cursor position should be reloaded.

This signal is guaranteed to be delivered in the GLib.MainContext which was the thread default context at cursor creation time.

New in version 3.12.

Property Details

EBook.BookClientCursor.props.alphabet
Name:

alphabet

Type:

[str]

Default Value:

[]

Flags:

READABLE

The currently ‘active alphabet [cursor-alphabet]’.

The value is a None terminated array of strings, each string is suitable to display a specific letter in the active alphabet.

Indexes from this array can later be used with EBook.BookClientCursor.set_alphabetic_index().

This property will automatically change if the active locale of the addressbook server changes.

Property change notifications are guaranteed to be delivered in the GLib.MainContext which was the thread default context at cursor creation time.

New in version 3.12.

EBook.BookClientCursor.props.client
Name:

client

Type:

EBook.BookClient

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

The EBook.BookClient which this cursor was created for

New in version 3.12.

EBook.BookClientCursor.props.connection
Name:

connection

Type:

Gio.DBusConnection

Default Value:

None

Flags:

WRITABLE, CONSTRUCT_ONLY

The Gio.DBusConnection to the addressbook server.

This is an internal parameter for constructing the cursor, to construct the cursor use EBook.BookClient.get_cursor().

New in version 3.12.

EBook.BookClientCursor.props.context
Name:

context

Type:

GLib.MainContext

Default Value:

None

Flags:

WRITABLE, CONSTRUCT_ONLY

The GLib.MainContext in which the EBook.BookClient created this cursor.

This is an internal parameter for constructing the cursor, to construct the cursor use EBook.BookClient.get_cursor().

New in version 3.12.

EBook.BookClientCursor.props.object_path
Name:

object-path

Type:

str

Default Value:

None

Flags:

WRITABLE, CONSTRUCT_ONLY

The D-Bus object path to find the server side cursor object.

This is an internal parameter for constructing the cursor, to construct the cursor use EBook.BookClient.get_cursor().

New in version 3.12.

EBook.BookClientCursor.props.position
Name:

position

Type:

int

Default Value:

0

Flags:

READABLE

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 in the symbolic EBookContacts.BookCursorOrigin.BEGIN position. If the position value is greater than EBook.BookClientCursor :total, this indicates that the cursor is positioned after the contact list in the symbolic EBookContacts.BookCursorOrigin.END position.

Property change notifications are guaranteed to be delivered in the GLib.MainContext which was the thread default context at cursor creation time.

New in version 3.12.

EBook.BookClientCursor.props.sort_fields
Name:

sort-fields

Type:

[str]

Default Value:

[]

Flags:

WRITABLE, CONSTRUCT_ONLY

The EBookContacts.ContactField names to sort this cursor with

This is an internal parameter for constructing the cursor, to construct the cursor use EBook.BookClient.get_cursor().

New in version 3.12.

EBook.BookClientCursor.props.total
Name:

total

Type:

int

Default Value:

0

Flags:

READABLE

The total number of contacts which satisfy the cursor’s query.

Property change notifications are guaranteed to be delivered in the GLib.MainContext which was the thread default context at cursor creation time.

New in version 3.12.