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:

index (int) – the alphabetic index
cancellable (Gio.Cancellable or None) – a Gio.Cancellable to optionally cancel this operation while in progress
callback (Gio.AsyncReadyCallback or None) – callback to call when a result is ready
user_data (object or None) – user data for the callback

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:

index (int) – the alphabetic index
cancellable (Gio.Cancellable or None) – a Gio.Cancellable to optionally cancel this operation while in progress

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:

sexp (str) – the new search expression for self
cancellable (Gio.Cancellable or None) – a Gio.Cancellable to optionally cancel this operation while in progress
callback (Gio.AsyncReadyCallback or None) – callback to call when a result is ready
user_data (object or None) – user data for the callback

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:

sexp (str) – the new search expression for self
cancellable (Gio.Cancellable or None) – a Gio.Cancellable to optionally cancel this operation while in progress

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:

flags (EBookContacts.BookCursorStepFlags) – The EBookContacts.BookCursorStepFlags for this step
origin (EBookContacts.BookCursorOrigin) – The EBookContacts.BookCursorOrigin from whence to step
count (int) – a positive or negative amount of contacts to try and fetch
cancellable (Gio.Cancellable or None) – a Gio.Cancellable to optionally cancel this operation while in progress
callback (Gio.AsyncReadyCallback or None) – callback to call when a result is ready
user_data (object or None) – user data for the callback

‘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:

flags (EBookContacts.BookCursorStepFlags) – The EBookContacts.BookCursorStepFlags for this step
origin (EBookContacts.BookCursorOrigin) – The EBookContacts.BookCursorOrigin from whence to step
count (int) – a positive or negative amount of contacts to try and fetch
cancellable (Gio.Cancellable or None) – a Gio.Cancellable to optionally cancel this operation while in progress

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¶: The class handler for the EBook.BookClientCursor ::refresh signal

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.