EDataBook.DataBookView

g EDataBook.DataBookView EDataBook.DataBookView GObject.GInterface GObject.GInterface Gio.Initable Gio.Initable GObject.GInterface->Gio.Initable GObject.Object GObject.Object GObject.Object->EDataBook.DataBookView Gio.Initable->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:
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:

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