EDataBook.DataBookView¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37), Gio.Initable (2)
Structs:: GObject.ObjectClass (5)

class	`new` (backend, sexp, connection, object_path)
	`claim_contact_uid` (uid)
	`dup_contacts` (range_start, range_length)
	`dup_indices` ()
	`get_connection` ()
	`get_fields_of_interest` ()
	`get_flags` ()
	`get_force_initial_notifications` ()
	`get_id` ()
	`get_n_total` ()
	`get_object_path` ()
	`get_sexp` ()
	`is_completed` ()
	`notify_complete` (error)
	`notify_content_changed` ()
	`notify_progress` (percent, message)
	`notify_remove` (id)
	`notify_update` (contact)
	`notify_update_prefiltered_vcard` (id, vcard)
	`notify_update_vcard` (id, vcard)
	`ref_backend` ()
	`set_force_initial_notifications` (value)
	`set_indices` (indices)
	`set_n_total` (n_total)
	`set_sort_fields` (fields)

Virtual Methods¶

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

Properties¶

Name	Type	Flags	Short Description
`backend`	`EDataBook.BookBackend`	r/w/co	The backend being monitored
`connection`	`Gio.DBusConnection`	r/w/co	The `Gio.DBusConnection` on which to export the view interface
`indices`	`int`	r/w
`n-total`	`int`	r/w
`object-path`	`str`	r/w/co	The object path at which to export the view interface
`sexp`	`EDataBook.BookBackendSExp`	r/w/co	The query expression for this view

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`objects-added`	Emitted when new objects are added into the view.
`objects-modified`	Emitted when the objects in the view are modified.
`objects-removed`	Emitted when the objects are removed from the view.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class EDataBook.DataBookView(**kwargs)¶

Bases:: GObject.Object, Gio.Initable
Abstract:: No
Structure:: EDataBook.DataBookViewClass

classmethod new(backend, sexp, connection, object_path)¶

Parameters:

backend (EDataBook.BookBackend) – an EDataBook.BookBackend
sexp (EDataBook.BookBackendSExp) – an EDataBook.BookBackendSExp
connection (Gio.DBusConnection) – a Gio.DBusConnection
object_path (str) – an object path for the view

Raises:

GLib.Error

Returns:

an EDataBook.DataBookView or None on error

Return type:

EDataBook.DataBookView

Creates a new EDataBook.DataBookView and exports its D-Bus interface on connection at object_path. If an error occurs while exporting, the function sets error and returns None.

claim_contact_uid(uid)¶

Parameters:: uid (str) – a contact UID

Tells the self, that it contains a contact with UID uid. This is useful for “manual query” view, which do not do initial notifications. It helps to not send “objects-added” signal for contacts, which are already Camel.part of the self, because for them the “objects-modified” should be emitted instead.

New in version 3.50.

dup_contacts(range_start, range_length)¶

Parameters:

range_start (int) – 0-based range start to retrieve the contacts for
range_length (int) – how many contacts to retrieve

Returns:

array of the read contacts, or None, when not applicable or when the range_start it out of bounds.

Return type:

[EBookContacts.Contact] or None

Reads range_length contacts from index range_start. When there are asked more than EDataBook.DataBookView.get_n_total() contacts only those up to the total number of contacts are read.

Free the returned GLib.PtrArray with g_ptr_array_unref(), when no longer needed.

Note: This function can be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY.

New in version 3.50.

dup_indices()¶

Returns:: list of indices for the view, or None when cannot determine
Return type:: EBookContacts.BookIndices or None

Returns a list of EBookContacts.BookIndices holding indices of the contacts in the view. These are received from the first sort field set by EDataBook.DataBookView.set_sort_fields(). The last item of the returned array is the one with chr member being None.

Free the returned array with e_book_indices_free(), when no longer needed.

Note: This function can be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY.

New in version 3.50.

get_connection()¶

Returns:: the Gio.DBusConnection
Return type:: Gio.DBusConnection

Returns the Gio.DBusConnection on which the AddressBookView D-Bus interface is exported.

New in version 3.8.

get_fields_of_interest()¶

Returns:

Hash table of field names which the listener is interested in. Backends can return fully populated objects, but the listener advertised that it will use only these. Returns None for all available fields.

Note: The data pointer in the hash table has no special meaning, it’s only GINT_TO_POINTER(1) for easier checking. Also, field names are compared case insensitively.

Return type:

{str: int} or None

get_flags()¶

Returns:: the flags for self.
Return type:: EBookContacts.BookClientViewFlags

Gets the EBookContacts.BookClientViewFlags that control the behaviour of self.

New in version 3.4.

get_force_initial_notifications()¶

Returns:: value set by EDataBook.DataBookView.set_force_initial_notifications()
Return type:: bool

Returns whether the self should do initial notifications even when the flags do not contain EBookContacts.BookClientViewFlags.NOTIFY_INITIAL. The default is False.

New in version 3.50.

get_id()¶

Returns:: an identifier of the view
Return type:: int

Returns an identifier of the self. It does not change for the whole life time of the self.

Note: This function can be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY.

New in version 3.50.

get_n_total()¶

Returns:: how many contacts are available in the view
Return type:: int

Returns how many contacts are available in the view.

Note: This function can be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY.

New in version 3.50.

get_object_path()¶

Returns:: the object path
Return type:: str

Returns the object path at which the AddressBookView D-Bus interface is exported.

New in version 3.8.

get_sexp()¶

Returns:: The EDataBook.BookBackendSExp used.
Return type:: EDataBook.BookBackendSExp

Gets the s-expression used for matching contacts to self.

New in version 3.8.

is_completed()¶

Returns:: whether the self had been completed; that is, whether EDataBook.DataBookView.notify_complete() had been called since the self had been started.
Return type:: bool

New in version 3.34.

notify_complete(error)¶

Parameters:: error (GLib.Error) – the error of the query, if any

Notifies listeners that all pending updates on self have been sent. The listener’s information should now be in sync with the backend’s.

notify_content_changed()¶

Notifies the client side that the content of the self changed, which it should use to refresh the view data.

Note: This function can be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY.

New in version 3.50.

notify_progress(percent, message)¶

Parameters:

percent (int) – percent done; use -1 when not available
message (str) – a text message

Provides listeners with a human-readable text describing the current backend operation. This can be used for progress reporting.

New in version 3.2.

notify_remove(id)¶

Parameters:: id (str) – a unique contact ID

Notify listeners that a contact specified by id was removed from self.

notify_update(contact)¶

Parameters:: contact (EBookContacts.Contact) – an EBookContacts.Contact

Notify listeners that contact has changed. This can trigger an add, change or removal event depending on whether the change causes the contact to start matching, no longer match, or stay matching the query specified by self.

notify_update_prefiltered_vcard(id, vcard)¶

Parameters:

id (str) – the UID of this contact
vcard (str) – a plain vCard

Notify listeners that vcard has changed. This can trigger an add, change or removal event depending on whether the change causes the contact to start matching, no longer match, or stay matching the query specified by self. This method should be preferred over EDataBook.DataBookView.notify_update() when the native representation of a contact is a vCard.

The important difference between this method and EDataBook.DataBookView.notify_update() and EDataBook.DataBookView.notify_update_vcard() is that it doesn’t match the contact against the book view query to see if it should be included, it assumes that this has been done and the contact is known to exist in the view.

notify_update_vcard(id, vcard)¶

Parameters:

id (str) – a unique id of the vcard
vcard (str) – a plain vCard

Notify listeners that vcard has changed. This can trigger an add, change or removal event depending on whether the change causes the contact to start matching, no longer match, or stay matching the query specified by self. This method should be preferred over EDataBook.DataBookView.notify_update() when the native representation of a contact is a vCard.

ref_backend()¶

Returns:: The associated EDataBook.BookBackend.
Return type:: EDataBook.BookBackend or None

Refs the backend that self is querying. Unref the returned backend, if not None, with GObject.Object.unref(), when no longer needed.

New in version 3.34.

set_force_initial_notifications(value)¶

Parameters:: value (bool) – value to set

Sets whether the self should do initial notifications even when the flags do not contain EBookContacts.BookClientViewFlags.NOTIFY_INITIAL.

New in version 3.50.

set_indices(indices)¶

Parameters:: indices (EBookContacts.BookIndices) – an array of EBookContacts.BookIndices

Sets indices used by the self. The array is terminated by an item with chr member being None. See EDataBook.DataBookView.dup_indices() for more information.

Note: This function can be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY.

New in version 3.50.

set_n_total(n_total)¶

Parameters:: n_total (int) – a value to set

Sets how many contacts are available in the view.

Note: This function can be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY.

New in version 3.50.

set_sort_fields(fields)¶

Parameters:: fields (EBookContacts.BookClientViewSortFields) – an array of EBookContacts.BookClientViewSortFields fields to sort by

Sets fields to sort the view by. The default is to sort by the file-as field. The contacts are always sorted in ascending order. Not every field can be used for sorting, the default available fields are EBookContacts.ContactField.FILE_AS, EBookContacts.ContactField.GIVEN_NAME and EBookContacts.ContactField.FAMILY_NAME.

The first sort field is used to populate indices, as returned by EDataBook.DataBookView.dup_indices().

Note: This function can be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY.

New in version 3.50.

Signal Details¶

EDataBook.DataBookView.signals.objects_added(data_book_view, vcards)¶

Signal Name:

objects-added

Flags:

RUN_LAST

Parameters:

data_book_view (EDataBook.DataBookView) – The object which received the signal
vcards ([str]) – array of vCards as string

Emitted when new objects are added into the view.

Note: This signal is used only when the view has set EBookContacts.BookClientViewFlags.MANUAL_QUERY flag.

New in version 3.50.

EDataBook.DataBookView.signals.objects_modified(data_book_view, vcards)¶

Signal Name:

objects-modified

Flags:

RUN_LAST

Parameters:

data_book_view (EDataBook.DataBookView) – The object which received the signal
vcards ([str]) – array of vCards as string

Emitted when the objects in the view are modified.

Note: This signal is used only when the view has set EBookContacts.BookClientViewFlags.MANUAL_QUERY flag.

New in version 3.50.

EDataBook.DataBookView.signals.objects_removed(data_book_view, uids)¶

Signal Name:

objects-removed

Flags:

RUN_LAST

Parameters:

data_book_view (EDataBook.DataBookView) – The object which received the signal
uids ([str]) – array of UIDs as string

Emitted when the objects are removed from the view.

Note: This signal is used only when the view has set EBookContacts.BookClientViewFlags.MANUAL_QUERY flag.

New in version 3.50.

Property Details¶

EDataBook.DataBookView.props.backend¶

Name:: backend
Type:: EDataBook.BookBackend
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The backend being monitored

EDataBook.DataBookView.props.connection¶

Name:: connection
Type:: Gio.DBusConnection
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The Gio.DBusConnection on which to export the view interface

EDataBook.DataBookView.props.indices¶

Name:: indices
Type:: int
Default Value:: None
Flags:: READABLE, WRITABLE

EDataBook.DataBookView.props.n_total¶

Name:: n-total
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

EDataBook.DataBookView.props.object_path¶

Name:: object-path
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The object path at which to export the view interface

EDataBook.DataBookView.props.sexp¶

Name:: sexp
Type:: EDataBook.BookBackendSExp
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The query expression for this view