1# 2# Gramps - a GTK+/GNOME based genealogy program 3# 4# Copyright (C) 2009 Benny Malengier 5# 6# This program is free software; you can redistribute it and/or modify 7# it under the terms of the GNU General Public License as published by 8# the Free Software Foundation; either version 2 of the License, or 9# (at your option) any later version. 10# 11# This program is distributed in the hope that it will be useful, 12# but WITHOUT ANY WARRANTY; without even the implied warranty of 13# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14# GNU General Public License for more details. 15# 16# You should have received a copy of the GNU General Public License 17# along with this program; if not, write to the Free Software 18# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 19# 20 21""" 22Group common stuff Gramps GUI elements must be able to do when tracking a DB: 23 24 * connect to db signals 25 * listen to db changes to update themself on relevant changes 26 * determine if the GUI has become out of sync with the db 27""" 28 29#------------------------------------------------------------------------- 30# 31# Gramps modules 32# 33#------------------------------------------------------------------------- 34from gramps.gen.utils.callman import CallbackManager 35 36#------------------------------------------------------------------------- 37# 38# DbGUIElement class 39# 40#------------------------------------------------------------------------- 41class DbGUIElement: 42 """ 43 Most interaction with the DB should be done via the callman attribute. 44 On initialization, the method :meth:`_connect_db_signals` is called. 45 Inheriting objects are advised to group the setup of the callman attribute 46 here. 47 48 .. attribute callman: a :class:`.CallbackManager` object, to be used to 49 track specific changes in the db and set up callbacks 50 """ 51 def __init__(self, database): 52 self.callman = CallbackManager(database) 53 self._connect_db_signals() 54 55 def _add_db_signal(self, name, callback): 56 """ 57 Convenience function to add a custom db signal. The attributes are just 58 passed to the callman object. 59 For primary objects, use the register method of the callman attribute. 60 61 :param name: name of the signal to connect to 62 :type name: string 63 :param callback: function to call when signal is emitted 64 :type callback: a funtion or method with the correct signature for the 65 signal 66 """ 67 self.callman.add_db_signal(name, callback) 68 69 def _connect_db_signals(self): 70 """ 71 Convenience method that is called on initialization of DbGUIElement. 72 Use this to group setup of the callman attribute. 73 Also called in _change_db method 74 """ 75 pass 76 77 def _cleanup_callbacks(self): 78 """ 79 Remove all db callbacks. 80 This is done automatically on destruction of the object, but is 81 normally needed earlier, calling this method does so. 82 Use _change_db method if you need to remove the callbacks because the 83 database has changed 84 """ 85 database = self.callman.database 86 if database.is_open(): 87 #a closed database has disconnected all signals 88 self.callman.disconnect_all() 89 #set a new callback manager 90 self.callman = CallbackManager(database) 91 92 def _change_db(self, database): 93 """ 94 Change the database the GUI element works on to database. 95 This removes all callbacks and all registered handles. 96 97 :param database: the new database to connect to 98 """ 99 dbold = self.callman.database 100 if dbold.is_open(): 101 #a closed database has disconnected all signals 102 self.callman.disconnect_all() 103 #set a new callback manager on new database 104 self.callman = CallbackManager(database) 105 self._connect_db_signals() 106