Signals and Callbacks - Revision history

Bamaustin: /* See also */

2025-02-16T22:41:05Z

‎See also

Daleathan at 00:13, 10 September 2024

2024-09-10T00:13:31Z

Bamaustin: /* Gtk */ link to Sphinx docs for callbacks

2024-07-28T01:08:36Z

‎Gtk: link to Sphinx docs for callbacks

Bamaustin at 00:59, 30 January 2024

2024-01-30T00:59:25Z

Bamaustin at 02:38, 1 December 2023

2023-12-01T02:38:47Z

Gioto at 03:32, 12 June 2020

2020-06-12T03:32:16Z

Sam888: /* Callback */

2017-07-02T00:14:46Z

‎Callback

Sam888: /* uistate */

2017-07-02T00:11:48Z

‎uistate

Sam888: /* Other sources of signals */

2017-07-02T00:10:57Z

‎Other sources of signals

Sam888: thanks paul very handy

2017-07-02T00:09:58Z

thanks paul very handy

@@ Line 140: / Line 140: @@
 The Gtk system has its own callback and signal system with very similar underlying concepts.  Please see the https://developer.gnome.org/gnome-devel-demos/stable/signals-callbacks.py.html.en for more information.
 === See also ===
-* Gramps developer docs (Sphinx) : [https://gramps-project.org/docs/gen/gen_utils.html#module-gramps.gen.utils.callback gramps/gen/utils/callback]
+* Gramps developer docs (Sphinx)
+** [https://gramps-project.org/docs/gen/gen_utils.html#module-gramps.gen.utils.callback gramps/gen/utils/callback]
 [[Category:Developers/Tutorials]]
 [[Category:Developers/General]]
 [[Category:GEPS]]

@@ Line 107: / Line 107: @@
 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.
+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 development|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;

@@ Line 139: / Line 139: @@
 ===Gtk===
 The Gtk system has its own callback and signal system with very similar underlying concepts.  Please see the https://developer.gnome.org/gnome-devel-demos/stable/signals-callbacks.py.html.en for more information.
 [[Category:Developers/Tutorials]]
 [[Category:Developers/General]]
 [[Category:GEPS]]

@@ Line 1: / Line 1: @@
 {{man tip|Information on developing for Gramps}}
-The Gramps signaling system is used to pass changes in the db, GUI, or other sources to various elements (usually the GUI) that need to be updated when changes occur.
+The Gramps signaling system is used to pass changes in the db, GUI, or other sources to various elements (usually, the GUI) that need to be updated when changes occur.
 Signals are emitted by the source, processed by the callback system and managers and result in callbacks to the GUI (or other) elements that have done a 'connect' to the callback manager for the signal of interest.
-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.
+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', 'citation-delete', 'note-rebuild'.  This type of signal is emitted with a list of handles of the primary objects affected as arguments.
 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.

@@ Line 65: / Line 65: @@
 The CallbackManager actually makes the connections to the db when the following is executed, so this MUST follow the <code>register_callbacks</code> method in your code.  The handles can be registered later on if desired.
      connect_all(keys)
-This connects all database signals related to the primary objects given in 'keys' to the already registered callbacks.  Note that only those callbacks registered with <code>register_callbacks</code> will effectively result in an action, so it is safe to connect to all keys even if not all keys have a registered callback.  The parameter 'keys'  is a list of keys of primary objects for which to connect the signals, with the default that no connects are done. One can enable signal activity to needed objects by passing a list, e.g. <code>keys=['source', 'place]</code>, or to all with <code>keys=callman.KEYS</code> (which is a list of all the keys)
+This connects all database signals related to the primary objects given in 'keys' to the already registered callbacks.  Note that only those callbacks registered with <code>register_callbacks</code> will effectively result in an action, so it is safe to connect to all keys even if not all keys have a registered callback.  The parameter 'keys'  is a list of keys of primary objects for which to connect the signals, with the default that no connects are done. One can enable signal activity to needed objects by passing a list, <abbr title="exempli gratia - Latin phrase meaning 'for example'">e.g.</abbr> <code>keys=['source', 'place]</code>, or to all with <code>keys=callman.KEYS</code> (which is a list of all the keys)
 === Removing connections with the CallbackManager ===

← Older revision		Revision as of 03:32, 12 June 2020
Line 1:		Line 1:
		+	{{man tip\|Information on developing for Gramps}}
	The Gramps signaling system is used to pass changes in the db, GUI, or other sources to various elements (usually the GUI) that need to be updated when changes occur.		The Gramps signaling system is used to pass changes in the db, GUI, or other sources to various elements (usually the GUI) that need to be updated when changes occur.

@@ Line 8: / Line 8: @@
 == Callback ==
-For the db and most of the GUI, the callback.py module with its Callback class provides much of the functionality.  The Callback class is usually a base class for modules that emit and allow connection to callbacks, so its methods become part of the main class.  An example is the class DbBsddbRead, or the displaystate.py History class.  When emitting or connecting to a callback it is important to use the correct object in calling the method.  If your code needs to see a 'databased-changed' and 'person-update' signals, for instance, you might use:
+For the db and most of the GUI, the [https://github.com/gramps-project/gramps/blob/master/gramps/gen/utils/callback.py callback.py] module with its Callback class provides much of the functionality.  The Callback class is usually a base class for modules that emit and allow connection to callbacks, so its methods become part of the main class.  An example is the class DbBsddbRead, or the displaystate.py History class.  When emitting or connecting to a callback it is important to use the correct object in calling the method.  If your code needs to see a 'databased-changed' and 'person-update' signals, for instance, you might use:
          self.dbstate.connect('database-changed', self.db_changed)
          self.db.connect('person-update', self.update)

@@ Line 126: / Line 126: @@
 *'filters-changed' with class of objects as a parameter
 *'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 handle when the user selects a new line in a view
 The Plugin manager passes the following signals:
 *'plugins-reloaded'
 ===Gtk===

@@ Line 119: / Line 119: @@
 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.
 The user interface '''uistate''' has the following signals available:
 *'nameformat-changed'
@@ Line 130: / Line 131: @@
 The Plugin manager passes the following signals:
 *'plugins-reloaded'
 The Gtk system has its own callback and signal system with very similar underlying concepts.  Please see the https://developer.gnome.org/gnome-devel-demos/stable/signals-callbacks.py.html.en for more information.

@@ Line 1: / Line 1: @@
 The Gramps signaling system is used to pass changes in the db, GUI, or other sources to various elements (usually the GUI) that need to be updated when changes occur.
@@ Line 7: / Line 6: @@
 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.
 == Callback ==
 For the db and most of the GUI, the callback.py module with its Callback class provides much of the functionality.  The Callback class is usually a base class for modules that emit and allow connection to callbacks, so its methods become part of the main class.  An example is the class DbBsddbRead, or the displaystate.py History class.  When emitting or connecting to a callback it is important to use the correct object in calling the method.  If your code needs to see a 'databased-changed' and 'person-update' signals, for instance, you might use:
@@ Line 15: / Line 15: @@
          history = self.uistate.get_history(nav_type, self.nav_group) # get history for current view
          history.connect("active-changed", method)
 === Callback methods ===
      emit(signal_name, args=tuple())
@@ Line 27: / Line 28: @@
 There are additional methods in this module (read the code) to enable or disable logging of signals and a few lesser used functions.
 === Callback example ===
 An example usage of the Callback methods is to get an update of a person object, the db code will at some point do:
@@ Line 40: / Line 42: @@
   # in close or cleanup code make sure to disconnect from db
          self.db.disconnect(self.key)
 == Callman ==
 There is also the callman.py which implements the CallbackManager class.  This class serves to assist a signal user (typically a GUI element) in registering for callbacks on primary objects (Person, Place etc.) from the db.  The CallbackManager acts as a filter, in that it will only pass on a signal to the GUI element if the element has registered for one or more handles it is interested in.  This reduces the overhead of signals when there are a lot of GUI elements 'listening', they don't all have to update on every signal.  It also assists in keeping track of callbacks so the cleanup process is a bit easier.
 === Instantiating the CallbackManager ===
 The Callback class is unique to a db and some GUI element. When instantiating the class, the current db is passed in:
          self.callman = CallbackManager(database)
 When a db is changed, one should destroy the CallbackManager and set up a new one (or delete the GUI element as it shows info from a previous db).
 === Registering callbacks with the CallbackManager ===
 The CallbackManager allows the programmer to 'register' several callbacks at once:
@@ Line 55: / Line 60: @@
 If the key is only one of the primary object types ('person', 'family', 'tag' etc.), then the function is registered for all of the available db transaction types ('add', 'delete', 'update', 'rebuild').
 === Making connections with the CallbackManager ===
 The CallbackManager actually makes the connections to the db when the following is executed, so this MUST follow the <code>register_callbacks</code> method in your code.  The handles can be registered later on if desired.
      connect_all(keys)
 This connects all database signals related to the primary objects given in 'keys' to the already registered callbacks.  Note that only those callbacks registered with <code>register_callbacks</code> will effectively result in an action, so it is safe to connect to all keys even if not all keys have a registered callback.  The parameter 'keys'  is a list of keys of primary objects for which to connect the signals, with the default that no connects are done. One can enable signal activity to needed objects by passing a list, e.g. <code>keys=['source', 'place]</code>, or to all with <code>keys=callman.KEYS</code> (which is a list of all the keys)
 === Removing connections with the CallbackManager ===
      disconnect_all()
 This disconnects the GUI element from all signals from the database.   This method should always be called before the callback methods become invalid, that is, before closing the GUI element.
 === Registering handles for callbacks ===
 The CallbackManager allows the programmer to 'register' handles to be monitored in mass, according to the basic object class of each handle.
@@ Line 74: / Line 82: @@
 When directonly is True, this method, will register all directly primary objects (their handles) connected to baseobj with the CallbackManager.  So a person objects media, notes, attributes etc. will have their handles returned.  If directonly is False, a recursive search is done through the primary objects that have references, and all other referenced handles will also be registered.
 Note that the handle for baseobj is not registered itself.  Also note that objects that go through a reference object (like Event through EventRef) are not registered.
 === Unregister handles with the CallbackManager ===
 The following allows the programmer to stop monitoring handles.  It uses the same ahandledict as <code>register_handles</code>:
@@ Line 87: / Line 96: @@
 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.
+{{man note|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.
@@ Line 127: / Line 136: @@
 [[Category:Developers/Tutorials]]
 [[Category:Developers/General]]