BackupInterface.hh 12.7 KB
Newer Older
1
/*===========================================================================*\
Jan Möbius's avatar
Jan Möbius committed
2 3
*                                                                            *
*                              OpenFlipper                                   *
Martin Schultz's avatar
Martin Schultz committed
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
 *           Copyright (c) 2001-2015, RWTH-Aachen University                 *
 *           Department of Computer Graphics and Multimedia                  *
 *                          All rights reserved.                             *
 *                            www.openflipper.org                            *
 *                                                                           *
 *---------------------------------------------------------------------------*
 * This file is part of OpenFlipper.                                         *
 *---------------------------------------------------------------------------*
 *                                                                           *
 * Redistribution and use in source and binary forms, with or without        *
 * modification, are permitted provided that the following conditions        *
 * are met:                                                                  *
 *                                                                           *
 * 1. Redistributions of source code must retain the above copyright notice, *
 *    this list of conditions and the following disclaimer.                  *
 *                                                                           *
 * 2. Redistributions in binary form must reproduce the above copyright      *
 *    notice, this list of conditions and the following disclaimer in the    *
 *    documentation and/or other materials provided with the distribution.   *
 *                                                                           *
 * 3. Neither the name of the copyright holder nor the names of its          *
 *    contributors may be used to endorse or promote products derived from   *
 *    this software without specific prior written permission.               *
 *                                                                           *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS       *
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED *
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A           *
 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER *
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,  *
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,       *
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR        *
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    *
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING      *
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS        *
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.              *
Jan Möbius's avatar
Jan Möbius committed
39
*                                                                            *
40 41
\*===========================================================================*/

42
#pragma once
Matthias Möller's avatar
Matthias Möller committed
43

Matthias Möller's avatar
Matthias Möller committed
44
#include <OpenFlipper/common/Types.hh>
Jan Möbius's avatar
 
Jan Möbius committed
45
 
46 47 48 49 50 51 52 53 54
 /** \file BackupInterface.hh
*
* Interface class for backup handling.\ref backupInterfacePage
*/

/** \brief Interface class for backup handling.
  *
  * \ref backupInterfacePage "Detailed description"
  * \n
55
  *
56 57
  * This interface defines functions to implement backup and restore
  * for objects or object groups.
Jan Möbius's avatar
 
Jan Möbius committed
58 59
 */
class BackupInterface {
Jan Möbius's avatar
Jan Möbius committed
60 61 62 63 64 65 66
  
  //===========================================================================
  /** @name Interface definition for general Plugins
  * @{ */
  //===========================================================================
  
  signals:
Dirk Wilden's avatar
Dirk Wilden committed
67

68
    /** \brief Tell Backup Plugin to create a backup
Dirk Wilden's avatar
Dirk Wilden committed
69
    *
70 71
    * Plugins which supports backups can call this function if they want to create backups.\n
    * A Backup control Plugin will do the rest.
72
    *
73 74
    * @param _objectid Identifier of the object to create the backup
    * @param _name     Name of the Backup, to show the user what can be recovered
75
    * @param _type     The type of the backup (e.g. UPDATE_SELECTION)
Dirk Wilden's avatar
Dirk Wilden committed
76
    */
77
    virtual void createBackup( int _objectid, QString _name, UpdateType _type = UPDATE_ALL){};
78

79 80 81 82
    /** \brief Tell Backup Plugin to create a group backup
    *
    * Plugins which supports backups can call this function if they want to create group backups.\n
    * The backups specified here will be grouped together. They can only be reverted as one block and
Matthias Möller's avatar
Matthias Möller committed
83
    * not one by one. They combine backups on multiple objects to a single backup set.
Jan Möbius's avatar
Jan Möbius committed
84 85
    *
    * A Backup control Plugin will do the rest.
86
    *
87 88
    * @param _objectids Identifier of the object to create the backup
    * @param _name      Name of the Backup, to show the user what can be recovered
89
    * @param _types     The types of the backups (e.g. UPDATE_SELECTION)
Jan Möbius's avatar
Jan Möbius committed
90
    */
91
    virtual void createBackup( IdList _objectids, QString _name, std::vector<UpdateType> _types){};
Jan Möbius's avatar
Jan Möbius committed
92

93
    /** \brief Tell Backup Plugin to undo the last action of an object
Jan Möbius's avatar
Jan Möbius committed
94
    *
95
    * Plugins which supports backups can call this function if they want to restore backups.\n
Jan Möbius's avatar
Jan Möbius committed
96
    * A Backup control Plugin will do the rest.
97
    * @param _objectid   Identifier of the object to restore
Jan Möbius's avatar
Jan Möbius committed
98
    */
99
    virtual void undo(int _objectid) {};
100 101

    /** \brief Tell Backup Plugin to redo the last action on an object
Jan Möbius's avatar
Jan Möbius committed
102
    *
103 104 105
    * Plugins which supports backups can call this function if they want to restore backups.\n
    * A Backup control Plugin will do the rest.
    * @param _objectid   Identifier of the object to restore
Jan Möbius's avatar
Jan Möbius committed
106
    */
107
    virtual void redo(int _objectid) {};
108 109

    /** \brief Tell Backup Plugin to undo the last action
Jan Möbius's avatar
Jan Möbius committed
110
    *
111
    * Plugins which supports backups can call this function if they want to restore backups.\n
Jan Möbius's avatar
Jan Möbius committed
112 113
    * A Backup control Plugin will do the rest.
    */
114
    virtual void undo(){};
Dirk Wilden's avatar
Dirk Wilden committed
115

116
    /** \brief Tell Backup Plugin to redo the last action
Dirk Wilden's avatar
Dirk Wilden committed
117
    *
118
    * Plugins which supports backups can call this function if they want to restore backups.\n
Dirk Wilden's avatar
Dirk Wilden committed
119 120
    * A Backup control Plugin will do the rest.
    */
121 122
    virtual void redo(){};

Jan Möbius's avatar
Jan Möbius committed
123
  private slots:
124

Jan Möbius's avatar
Jan Möbius committed
125 126 127 128
    /** \brief Backup for an object requested
    * 
    * This function will be called if a plugin requests a backup. You can
    * also react on this event if you reimplement this function in your plugin.
129
    *
Jan Möbius's avatar
Jan Möbius committed
130
    * @param _objectid Identifier of the object to create the backup
Jan Möbius's avatar
Jan Möbius committed
131
    * @param _name Name of the Backup, to show the user what can be recovered
Jan Möbius's avatar
Jan Möbius committed
132
    * @param _type What has been updated (This can be used to restrict the backup to certain parts of the object)
Jan Möbius's avatar
Jan Möbius committed
133
    */
134
    virtual void slotCreateBackup( int _objectid , QString _name , UpdateType _type = UPDATE_ALL) {};
Dirk Wilden's avatar
Dirk Wilden committed
135

136
    /** \brief Backup for an object requested
Dirk Wilden's avatar
Dirk Wilden committed
137
    * 
138
    * This function will be called if a plugin requests a backup. You can
Dirk Wilden's avatar
Dirk Wilden committed
139
    * also react on this event if you reimplement this function in your plugin.
140
    *
Jan Möbius's avatar
Jan Möbius committed
141
    * @param _objectids Identifiers of the object to create the backup
142
    * @param _name Name of the Backup, to show the user what can be recovered
Jan Möbius's avatar
Jan Möbius committed
143
    * @param _types What has been updated (This can be used to restrict the backup to certain parts of the objects)
Dirk Wilden's avatar
Dirk Wilden committed
144
    */
145
    virtual void slotCreateBackup( IdList _objectids , QString _name , std::vector<UpdateType> _types) {};
146

Jan Möbius's avatar
Jan Möbius committed
147 148 149 150 151
    /** \brief A given object will be restored.
    *
    * This function is called before an object is restored from a backup.
    * perObjectDatas and the object will be reset to the backup state
    * after this function is called for all plugins.
152
    *
Jan Möbius's avatar
Jan Möbius committed
153 154 155
    * If you have any pointers or references to the given object you have to
    * clean them up here.
    *
Jan Möbius's avatar
Jan Möbius committed
156
    * @param _objectid         Identifier of the object which is about to be restored
Jan Möbius's avatar
Jan Möbius committed
157
    */
158
    virtual void slotAboutToRestore( int _objectid ) {};
159

Jan Möbius's avatar
Jan Möbius committed
160 161 162 163
    /** \brief Object fully restored
    *
    * This function is called after an object and all data from other plugins
    * is restored from a backup.
164 165 166
    *
    * perObjectDatas and the object have been reset to the backup state.
    *
Jan Möbius's avatar
Jan Möbius committed
167 168
    * @param _objectid   Identifier of the object which is about to be restored
    */
169
    virtual void slotRestored( int _objectid ) {};
170 171 172 173 174 175

   public:

    /// Destructor
    virtual ~BackupInterface() {};

176 177
  /** @} */

Jan Möbius's avatar
Jan Möbius committed
178 179 180 181 182 183 184 185 186 187 188 189 190
  //===========================================================================
  /** @name Interface definition for Backup Plugins
  *
  *  These signals and slots have to be implemented if you create a plugin managing 
  *  Backups ( A Backup plugin is already provided by OpenFlipper so you don't need
  *  to use these funcions).
  * @{ */
  //===========================================================================     
  
  signals: 
    /** \brief Backup Plugin tells other Plugins that a restore will happen
    *
    */
191 192
    virtual void aboutToRestore(int _objectid ) {};

Jan Möbius's avatar
Jan Möbius committed
193 194 195
    /** \brief Backup Plugin tells other Plugins that a restore has happened
    *
    */
196
    virtual void restored( int _objectid ) {};
Jan Möbius's avatar
Jan Möbius committed
197 198 199
    
    
  private slots:
200 201 202
    
    
    /** \brief Undo the last action of an object
Jan Möbius's avatar
Jan Möbius committed
203 204 205 206 207
    *
    * This function has to be implemented in the backup management plugin. Normally
    * this function is provided by the default backup plugin and should not be used!
    * To restore data in your plugin use the slotRestore above.
    *
208
    * @param _objectid   Identifier of the object to restore
Jan Möbius's avatar
Jan Möbius committed
209
    */
210
    virtual void slotUndo(int _objectid) {};
Dirk Wilden's avatar
Dirk Wilden committed
211

212
    /** \brief Redo the last action on an object
Dirk Wilden's avatar
Dirk Wilden committed
213 214 215 216 217
    *
    * This function has to be implemented in the backup management plugin. Normally
    * this function is provided by the default backup plugin and should not be used!
    * To restore data in your plugin use the slotRestore above.
    *
218
    * @param _objectid   Identifier of the object to restore
Dirk Wilden's avatar
Dirk Wilden committed
219
    */
220
    virtual void slotRedo(int _objectid) {};
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240

    /** \brief Undo the last action
    *
    * This function has to be implemented in the backup management plugin. Normally
    * this function is provided by the default backup plugin and should not be used!
    * To restore data in your plugin use the slotRestore above.
    *
    */
    virtual void slotUndo(){};

    /** \brief Redo the last action
    *
    * This function has to be implemented in the backup management plugin. Normally
    * this function is provided by the default backup plugin and should not be used!
    * To restore data in your plugin use the slotRestore above.
    *
    */
    virtual void slotRedo(){};

  signals:
241

242 243
    /** \brief This signal is emitted by a BackupPlugin and tells a TypePlugin to generate a backup
     *
244 245
     * @param _id   Id of the added object
     * @param _name Name of the backup to generate
246 247 248
     * @param _type the type of backup that needs to be done
     */
    virtual void generateBackup( int _id, QString _name, UpdateType _type ) {};
Jan Möbius's avatar
Jan Möbius committed
249

250 251
  /** @} */

Jan Möbius's avatar
 
Jan Möbius committed
252 253
};

254 255 256 257 258 259 260 261 262 263 264
/** \page backupInterfacePage Backup Interface
 * \n
\image html BackupInterface.png
\n

\section BackupInterfacePage_Overview Overview
The Backup interface can be used to manage backups within OpenFlipper. It provides abstractions for backup and
redo operations which get managed by the backup plugin.

\section backupInterfacePage_generatingBackups Generating Backups
To generate a backup of a specific object, you just have to derive from the BackupInterface and emit the
Jan Möbius's avatar
Jan Möbius committed
265
BackupInterface::createBackup() signal. A simple example looks like this:
266 267 268 269 270 271 272 273 274 275 276 277

\code
emit createBackup(object->id(),"Smoothing", UPDATE_GEOMETRY );
\endcode

We create a backup of the object with the given id. The Backup will be named "Smoothing" and the backup
system is informed that only the geometry has changed.

It is also possible to create backup groups. This is required, if you change several objects at once and
they should be restored only together.

\section backupInterfacePage_restoringBackups Restoring Backups
Jan Möbius's avatar
Jan Möbius committed
278 279 280 281 282 283 284 285
Backups can be restored and re-applied. You can simply emit the BackupInterface::undo() signal and the
last backup will be restored. BackupInterface::redo() will re apply the last operation stored. It is
also possible to restore backups of a specific object via BackupInterface::undo(int) and
BackupInterface::redo(int), if they are not blocked by a group backup which can only be reverted as one
operation.\n

The other plugins will be informed about a restore operation by BackupInterface::slotAboutToRestore(int)
and BackupInterface::slotRestored(int) which will be emitted directly before and after the restore operation.
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300


\section backupInterfacePage_usage Usage
To use the BackupInterface:
<ul>
<li> include BackupInterface.hh in your plugins header file
<li> derive your plugin from the class BackupInterface
<li> add Q_INTERFACES(BackupInterface) to your plugin class
<li> And implement the required slots and functions
</ul>

*/


Q_DECLARE_INTERFACE(BackupInterface,"GUI.BackupInterface/1.1")