Changes

Jump to: navigation, search

Signals and Callbacks

3,003 bytes added, 22:07, 19 June 2017
no edit summary
Signals from the db can indicate the types of db changes, such as an add, update or delete of one of the primary objects. Examples of these signals are 'person-add', 'media-update', 'note-delete'. This type of signal is emitted with a list of handles of the primary objects affected as arguments.
 
Some of the other db or related signals are a rebuild; 'person-rebuild', 'place-rebuild', 'home-person-changed', 'database-changed' (with the new db), 'no-database' etc.
 
Currently, the primary objects are 'person', 'family', 'event', 'place', 'media', 'source', 'citation', 'repository', 'note', and 'tag'. The types of db signal that apply to these are 'add', 'delete', 'update', and 'rebuild'. The signals are formed by appending the signal type to the primary object type with a '-' as in 'person-add'.
The GUI also emits signals when some user action changes the state; on a given view the 'active-changed' signal indicates that the selected object has changed. In addition, Gtk provides a rich set of signals for their widgets that use the separate (but similar) Gtk signal system.
unregister_handles(ahandledict) # remove specific handles from registration.
unregister_all() # allows removing all the registered handles from registration.
 
=== Connecting directly to db with the CallbackManager ===
add_db_signal(signal_name, callback)
This does a custom db connect signal outside of the primary object ones managed automatically. It has the same arguments and function as the <code>Callback.connect</code> method. Its purpose in the CallbackManager is to allow the <code>disconnect_all</code> method manage this callback, so the user doesn't have to store a key and disconnect it individually.
 
== Db signals ==
The most commonly used signals from the db indicate the types of db changes, such as an add, update or delete of one of the primary objects. Currently, the primary objects are 'person', 'family', 'event', 'place', 'media', 'source', 'citation', 'repository', 'note', and 'tag'. The types of db signal that apply to these are 'add', 'delete', and 'update'. The signals are formed by appending the signal type to the primary object type with a '-' as in 'person-add'.
Examples of these signals are 'person-add', 'media-update', 'note-delete'. This type of signal is emitted with a list of handles of the primary objects affected as arguments.
 
Note: the following only applies to normal transactions, 'batch' transactions do not produce signals.
 
These signals are emitted when one or more commits occur at the end of a transaction. The signals are delayed until the end of the transaction so that they are not emitted if the transaction fails. Because the signals are delayed until after the all the transaction commits are actually complete, it is important for programmers to understand possible side effects.
 
For example, if a UI element made connections to both 'family-delete', and 'person-delete' and was trying to maintain a display of family related information, and further tried to be too smart about what it updated, it could 'see' apparent problems with the db. In the case of a family merge, it is possible that both the merged-in family and parents are deleted. If, when the 'person-delete' arrived, the UI element decided to update its family display, it might get an exception when it tried to access the family again. This was a real bug we had to correct.
 
To minimize likely side-effects, it was found that signals should be emitted by the db in a particular order; first are deletes, then adds, and finally updates. Within each type of commit, the various object types are also emitted in order according to the object keys (persons, families, sources, events, media, places, repositories, notes, tags and citations). By doing this we maintain consistent ordering of signals, regardless of commit order, db type or other circumstances. This emit order is maintained during undo and redo as well.
 
In the family merge example above, it would be much better for the UI element to make connection to 'family-delete', 'family-update', and 'person-update'. If a parent (or child) was removed, the 'family-update' signal would allow a correct update. If either was changed, the 'person-update' signal would allow a correct update.
 
One other class of db signals are object rebuilds; 'person-rebuild', 'place-rebuild', etc. These are emitted without parameters when a significant change has occurred to the db state, typically after a batch operation like an import, db repair, or other mass modification of the db. Usually, only views need to connect to these, Gramplets and editors will get 'active-changed' from the view code. The <code>self.db.request_rebuild()</code> call can be used by tools which make mass changes to update the UI.
 
There are a few other signal from the db;
*'home-person-changed', with no parameters
*'person-groupname-rebuild', with the name and group as parameters
and some db related signals from '''dbstate'''
*'no-database'
*'database-changed' (with the new db)
For example <code>self.dbstate.connect('database-changed', self.db_changed)</code>
 
== Other sources of signals ==
The Config manager can emit changes to the config settings; it emits the config setting as the signal name. It has its own 'connect', 'disconnect' and 'emit' methods.
*'update-available' with addon_update_list as a parameter
The '''displaystate''' passes the following signals:
*'mru-changed' with new mru when the user selects a new line in a view*'active-changed' with new handlewhen the user selects a new line in a view
The Plugin manager passes the following signals:
*'plugins-reloaded'
266
edits

Navigation menu