Updated restore and about to restore signals and slots

backup Interface documentation


git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@12693 383ad7c9-94d9-4d36-a494-682f7c89f535

BasePlugin/BackupInterface.hh

@@ -46,12 +46,18 @@
 #include <QtGui>
 #include <OpenFlipper/common/Types.hh>
  
- /** \brief Create or restore backups 
-  * 
-  * Interface Class for Backup Plugins. The Backup Interface can be used to communicate with or write a backup plugin.
+ /** \file BackupInterface.hh
+*
+* Interface class for backup handling.\ref backupInterfacePage
+*/
+
+/** \brief Interface class for backup handling.
+  *
+  * \ref backupInterfacePage "Detailed description"
+  * \n
   *
-  * See tutorial \ref ex6 for detailed information on how to use this plugin interface.
-  * 
+  * This interface defines functions to implement backup and restore
+  * for objects or object groups.
  */
 class BackupInterface {
   
@@ -66,19 +72,26 @@ class BackupInterface {
     *
     * Plugins which supports backups can call this function if they want to create backups.\n
     * A Backup control Plugin will do the rest.
+    *
     * @param _objectid Identifier of the object to create the backup
     * @param _name     Name of the Backup, to show the user what can be recovered
+    * @param _type     The type of the backup (e.g. UPDATE_SELECTION)
     */
-    virtual void createBackup( int /*_objectid*/, QString /*_name*/, UpdateType /*_type*/ = UPDATE_ALL){};
+    virtual void createBackup( int _objectid, QString _name, UpdateType _type = UPDATE_ALL){};
 
-    /** \brief Tell Backup Plugin to create a backup
+    /** \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
+    * not one by one. they combine backups on multiple objects to a singe backup set.
     *
-    * Plugins which supports backups can call this function if they want to create backups.\n
     * A Backup control Plugin will do the rest.
+    *
     * @param _objectids Identifier of the object to create the backup
     * @param _name      Name of the Backup, to show the user what can be recovered
+    * @param _types     The types of the backups (e.g. UPDATE_SELECTION)
     */
-    virtual void createBackup( IdList /*_objectids*/, QString /*_name*/, std::vector<UpdateType> /*_types*/){};
+    virtual void createBackup( IdList _objectids, QString _name, std::vector<UpdateType> _types){};
 
     /** \brief Tell Backup Plugin to undo the last action of an object
     *
@@ -86,7 +99,7 @@ class BackupInterface {
     * A Backup control Plugin will do the rest.
     * @param _objectid   Identifier of the object to restore
     */
-    virtual void undo(int /*_objectid*/) {};
+    virtual void undo(int _objectid) {};
 
     /** \brief Tell Backup Plugin to redo the last action on an object
     *
@@ -94,7 +107,7 @@ class BackupInterface {
     * A Backup control Plugin will do the rest.
     * @param _objectid   Identifier of the object to restore
     */
-    virtual void redo(int /*_objectid*/) {};
+    virtual void redo(int _objectid) {};
 
     /** \brief Tell Backup Plugin to undo the last action
     *
@@ -116,59 +129,55 @@ class BackupInterface {
     * 
     * 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.
+    *
     * @param _id Identifier of the object to create the backup
     * @param _name Name of the Backup, to show the user what can be recovered
     * @param _internalId Unique identifier of the backup. This number is generated by the core and returned by the original signal. 
     */
-    virtual void slotCreateBackup( int /*_objectid*/ , QString /*_name*/ , UpdateType /*_type*/ = UPDATE_ALL) {};
+    virtual void slotCreateBackup( int _objectid , QString _name , UpdateType _type = UPDATE_ALL) {};
 
     /** \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.
+    *
     * @param _id Identifier of the object to create the backup
     * @param _name Name of the Backup, to show the user what can be recovered
     * @param _internalId Unique identifier of the backup. This number is generated by the core and returned by the original signal. 
     */
-    virtual void slotCreateBackup( IdList /*_objectids*/ , QString /*_name*/ , std::vector<UpdateType> /*_types*/) {};
+    virtual void slotCreateBackup( IdList _objectids , QString _name , std::vector<UpdateType> _types) {};
 
     /** \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.
+    *
     * If you have any pointers or references to the given object you have to
     * clean them up here.
-    * @param _id         Identifier of the object which is about to be restored
-    */
-    virtual void slotAboutToRestore( int /*_objectid*/, UpdateType /*_type*/ ) {};
-
-    /** \brief Restore Object
-    *
-    * This function is called after the main object is restored from a backup.
-    * perObjectDatas and the object have been reset to the backup state.\n
-    *
-    * Here you can restore additional data which is not managed in perObjectDatas but
-    * in your local plugin.\n
     *
-    * @param _objectid   Identifier of the object which is about to be restored
+    * @param _id         Identifier of the object which is about to be restored
     */
-    virtual void slotRestore( int /*_objectid*/, UpdateType /*_type*/ ) {};
+    virtual void slotAboutToRestore( int _objectid ) {};
 
     /** \brief Object fully restored
     *
     * This function is called after an object and all data from other plugins
     * is restored from a backup.
-    * perObjectDatas and the object have been reset to the backup state.    
+    *
+    * perObjectDatas and the object have been reset to the backup state.
+    *
     * @param _objectid   Identifier of the object which is about to be restored
     */
-    virtual void slotRestored( int /*_objectid*/, UpdateType /*_type*/ ) {};
+    virtual void slotRestored( int _objectid ) {};
 
    public:
 
     /// Destructor
     virtual ~BackupInterface() {};
 
+  /** @} */
+
   //===========================================================================
   /** @name Interface definition for Backup Plugins
   *
@@ -182,17 +191,12 @@ class BackupInterface {
     /** \brief Backup Plugin tells other Plugins that a restore will happen
     *
     */
-    virtual void aboutToRestore(int /*_objectid*/ , UpdateType /*_type*/ ) {};
-  
-    /** \brief Backup Plugin tells other Plugins that they should restore their own data
-    *
-    */
-    virtual void restore(int /*_objectid*/ , UpdateType /*_type*/ ) {};
-    
+    virtual void aboutToRestore(int _objectid ) {};
+
     /** \brief Backup Plugin tells other Plugins that a restore has happened
     *
     */
-    virtual void restored( int /*_objectid*/ , UpdateType /*_type*/ ) {};
+    virtual void restored( int _objectid ) {};
     
     
   private slots:
@@ -206,7 +210,7 @@ class BackupInterface {
     *
     * @param _objectid   Identifier of the object to restore
     */
-    virtual void slotUndo(int /*_objectid*/) {};
+    virtual void slotUndo(int _objectid) {};
 
     /** \brief Redo the last action on an object
     *
@@ -216,7 +220,7 @@ class BackupInterface {
     *
     * @param _objectid   Identifier of the object to restore
     */
-    virtual void slotRedo(int /*_objectid*/) {};
+    virtual void slotRedo(int _objectid) {};
 
     /** \brief Undo the last action
     *
@@ -237,15 +241,62 @@ class BackupInterface {
     virtual void slotRedo(){};
 
   signals:
+
     /** \brief This signal is emitted by a BackupPlugin and tells a TypePlugin to generate a backup
      *
-     * @param _id Id of the added object
+     * @param _id   Id of the added object
+     * @param _name Name of the backup to generate
      * @param _type the type of backup that needs to be done
      */
     virtual void generateBackup( int _id, QString _name, UpdateType _type ) {};
 
+  /** @} */
+
 };
 
-Q_DECLARE_INTERFACE(BackupInterface,"GUI.BackupInterface/1.0")
+/** \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
+createBackup() signal. a simple example looks like this:
+
+\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
+Backups can be restored and re-applied. You can simply emit the undo() signal and the last backup will be
+restored. redo() will re apply the last operation stored. It is also possible to restore backups of a specific
+object via undo(int) and redo(int), if they are not blocked by a group backup which can only be reverted as one
+operation.
+
+
+
+\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")
       
 #endif // BACKUPPLUGININTERFACE_HH

Core/Core.hh

@@ -363,14 +363,10 @@ signals:
    void redo();
 
    /// Backup Plugin tells other Plugins that a restore will happen
-   void aboutToRestore(int _objectId, UpdateType _type);
-   
-   /// Backup Plugin tells other Plugins that they should restore their own data
-   void restore(int _objectId, UpdateType _type);
+   void aboutToRestore(int _objectId);
    
    /// Backup Plugin tells other Plugins that a restore has happened
-   void restored( int _objectId, UpdateType _type);
-
+   void restored( int _objectId);
 
    /// Tell the plugins that a file has been opened ( -> Database)
    void openedFile( int _id );

Core/PluginLoader.cc

@@ -1692,21 +1692,15 @@ void Core::loadPlugin(QString filename, bool silent, QString& _licenseErrors, QO
     //====================================================================================
     
     // Stage one : restore will happen soon
-    if ( checkSignal( plugin , "aboutToRestore(int,UpdateType)" ) ) {
-      connect(plugin  , SIGNAL( aboutToRestore(int,UpdateType)) ,
-              this    , SIGNAL( aboutToRestore(int,UpdateType) ),Qt::DirectConnection);
+    if ( checkSignal( plugin , "aboutToRestore(int)" ) ) {
+      connect(plugin  , SIGNAL( aboutToRestore(int)) ,
+              this    , SIGNAL( aboutToRestore(int) ),Qt::DirectConnection);
     }
     
-    // Stage two: Core restore done, plugins should restore
-    if ( checkSignal( plugin , "restore(int,UpdateType)" ) ) {
-      connect(plugin  , SIGNAL(restore(int,UpdateType)) ,
-              this    , SIGNAL( restore(int,UpdateType) ),Qt::DirectConnection);
-    }
-    
-    // Stage three: Restore complete
-    if ( checkSignal( plugin , "restored(int,UpdateType)" ) ) {
-      connect(plugin  , SIGNAL(restored(int,UpdateType)) ,
-              this    , SIGNAL( restored(int,UpdateType) ),Qt::DirectConnection);
+    // Stage two: Restore complete
+    if ( checkSignal( plugin , "restored(int)" ) ) {
+      connect(plugin  , SIGNAL(restored(int)) ,
+              this    , SIGNAL( restored(int) ),Qt::DirectConnection);
     }
     
     //====================================================================================
@@ -1714,21 +1708,15 @@ void Core::loadPlugin(QString filename, bool silent, QString& _licenseErrors, QO
     //====================================================================================
      
      // Stage one : restore will happen soon
-     if ( checkSlot( plugin , "slotAboutToRestore(int,UpdateType)" ) ) {
-       connect(this   , SIGNAL( aboutToRestore(int,UpdateType)) ,
-               plugin , SLOT( slotAboutToRestore(int,UpdateType) ),Qt::DirectConnection);
-     }
-     
-     // Stage one : restore will happen soon
-     if ( checkSlot( plugin , "slotRestore(int,UpdateType)" ) ) {
-       connect(this   , SIGNAL( restore(int,UpdateType)) ,
-               plugin , SLOT( slotRestore(int,UpdateType) ),Qt::DirectConnection);
+     if ( checkSlot( plugin , "slotAboutToRestore(int)" ) ) {
+       connect(this   , SIGNAL( aboutToRestore(int)) ,
+               plugin , SLOT( slotAboutToRestore(int) ),Qt::DirectConnection);
      }
      
-     // Stage one : restore will happen soon
-     if ( checkSlot( plugin , "slotRestored(int,UpdateType)" ) ) {
-       connect(this   , SIGNAL( restored(int,UpdateType)) ,
-               plugin , SLOT( slotRestored(int,UpdateType) ),Qt::DirectConnection);
+     // Stage two : restore will happen soon
+     if ( checkSlot( plugin , "slotRestored(int)" ) ) {
+       connect(this   , SIGNAL( restored(int)) ,
+               plugin , SLOT( slotRestored(int) ),Qt::DirectConnection);
      }
      
      // Signal from plugin to restore a group with the given id