LoadSaveInterface.hh 8.87 KB
Newer Older
1
/*===========================================================================*\
Jan Möbius's avatar
Jan Möbius committed
2 3
*                                                                            *
*                              OpenFlipper                                   *
Jan Möbius's avatar
Jan Möbius committed
4
*      Copyright (C) 2001-2011 by Computer Graphics Group, RWTH Aachen       *
Jan Möbius's avatar
Jan Möbius committed
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
*                           www.openflipper.org                              *
*                                                                            *
*--------------------------------------------------------------------------- *
*  This file is part of OpenFlipper.                                         *
*                                                                            *
*  OpenFlipper is free software: you can redistribute it and/or modify       *
*  it under the terms of the GNU Lesser General Public License as            *
*  published by the Free Software Foundation, either version 3 of            *
*  the License, or (at your option) any later version with the               *
*  following exceptions:                                                     *
*                                                                            *
*  If other files instantiate templates or use macros                        *
*  or inline functions from this file, or you compile this file and          *
*  link it with other files to produce an executable, this file does         *
*  not by itself cause the resulting executable to be covered by the         *
*  GNU Lesser General Public License. This exception does not however        *
*  invalidate any other reasons why the executable file might be             *
*  covered by the GNU Lesser General Public License.                         *
*                                                                            *
*  OpenFlipper is distributed in the hope that it will be useful,            *
*  but WITHOUT ANY WARRANTY; without even the implied warranty of            *
*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the             *
*  GNU Lesser General Public License for more details.                       *
*                                                                            *
*  You should have received a copy of the GNU LesserGeneral Public           *
*  License along with OpenFlipper. If not,                                   *
*  see <http://www.gnu.org/licenses/>.                                       *
*                                                                            *
33 34 35
\*===========================================================================*/

/*===========================================================================*\
Jan Möbius's avatar
Jan Möbius committed
36 37 38 39 40
*                                                                            *
*   $Revision$                                                       *
*   $LastChangedBy$                                                *
*   $Date$                     *
*                                                                            *
41
\*===========================================================================*/
42

43 44
#ifndef LOADSAVEINTERFACE_HH
#define LOADSAVEINTERFACE_HH
45 46 47

#include <OpenFlipper/common/Types.hh>

48 49 50 51 52 53 54 55 56
/** \file LoadSaveInterface.hh
*
* Interface for adding and removing objects.\ref loadSaveInterfacePage
*/

/** \brief Interface for all plugins which want to Load or Save files and create Objects
  *
  * \ref loadSaveInterfacePage "Detailed description"
  * \n
57
  *
58
  * Using this interface you can instruct the core to open/save objects or
59
  * to create new empty objects.
60
 */
61
class LoadSaveInterface {
62 63

   public:
64

65 66
      /// Destructor
      virtual ~LoadSaveInterface() {};
67

68
   signals :
69 70 71 72 73
      /** \brief Save object to a file
       *
       * @param _id Object to Save
       * @param _filename Filename to save it to (Leave as "" to automatically determine filename)
      */
74
      virtual void save(int _id , QString _filename ) {}
75 76

      /** \brief Load object from file with a specific DataType
77
       *
78
       * @param _filename Filename of the File to load
79
       * @param _type Type to be loaded
80 81
       * @param _id Here the id of the loaded object is returned. id its -1 something went wrong
       */
82
      virtual void load(QString _filename, DataType _type, int& _id) {};
83

84

85
      /** Add an empty object of the given type
86
       *
87 88 89
       * @param _type Type to be created
       * @param _id Here the id of the loaded object is returned. id its -1 something went wrong
       */
90
      virtual void addEmptyObject( DataType _type, int& _id) {};
91

92 93 94 95 96
      /** Create a copy of an existing object
       *
       * @param _oldId id of the object to copy
       * @param _newId id of the new object created
       */
97
      virtual void copyObject( int _oldId, int& _newId) {};
98

99

100 101 102 103
      /** \brief DEPRECATED! Emit this signal if an empty object has been created
       *
       * Deprecated! Objects are added by the Type Plugins and this is signal is in the TypeInterface now
       *
104
       * @param _id Id of the added object
105
       */
106
      virtual void emptyObjectAdded( int _id ) {};
107

108 109 110 111
      /** \brief Delete an object
       *
       * @param _id Id of the object
       */
112
      virtual void deleteObject( int _id ){};
113

114 115 116 117 118
      /** \brief Delete all Objects
       *
       */
      virtual void deleteAllObjects(){};

119
  private slots :
120

121
    /**  \brief A file has been opened
122
     *
123 124 125
     *  This slot is called if a file has been opened by the core.\n
     *  @param _id Id of the new object
     */
126
    virtual void fileOpened( int _id ) {};
Dirk Wilden's avatar
Dirk Wilden committed
127 128

    /**  \brief An empty object has been added
129
     *
Dirk Wilden's avatar
Dirk Wilden committed
130 131 132
     *  This slot is called if an empty object has been added by the core.\n
     *  @param _id Id of the new object
     */
133
    virtual void addedEmptyObject( int _id ) {};
Dirk Wilden's avatar
Dirk Wilden committed
134

135 136
    /** \brief An object was deleted
      *
137
      * This function is called by the core if an object gets deleted. It is called immediately
138 139 140 141 142 143 144
      * before the object is removed from the scenegraph. So if this function is invoked, the object still
      * exists. All plugins get informed via this slot.\
      *
      * After this function got called for all plugins, the object is removed from the scene with all
      * nodes attached to it and all PerObjectData attached to it.
      *
      * @param _id Id of the object that is deleted.
145
      */
146
    virtual void objectDeleted( int _id ){};
147

148 149
};

150
/** \page loadSaveInterfacePage Load/Save Interface
151 152 153 154
 * \n
\image html loadSaveInterface.png
\n

155 156 157
The LoadSaveInterface can be used by plugins to add new objects to the scene either by creating empty objects
or by loading them from files. The interface also triggers saving of existing objects to files.

158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194

\section loadSaveInterface_load_save Load/Save Files
You can load a file from within your plugin via
\code
  emit LoadSaveInterface::load(QString _filename, DataType _type, int& _id);
\endcode
and to save an object to a file, call LoadSaveInterface::
\code
  emit LoadSaveInterface::save(int _id , QString _filename );
\endcode

The corresponding File Plugin will than be activated and load or save the object. for load, the id of the new object
is returned.

\section loadSaveInterface_createObjects Creating/Copying Objects
To add objects to the scene you can use the following two functions:
\code
  emit LoadSaveInterface::addEmptyObject( DataType _type, int& _id);
\endcode
This will create a new object of the given DataType and return the id of it, while
\code
  emit LoadSaveInterface::copyObject( int _oldId, int& _newId);
\endcode
will copy the given object and return the new object id.

\section loadSaveInterface_deleteObjects Deleting Objects

You can delete a specific object via
\code
  emit LoadSaveInterface::deleteObject( int _id );
\endcode
or clear the whole scene with:
\code
  emit LoadSaveInterface::deleteAllObjects();
\endcode

\section loadSaveInterface_callbacks Object Information
195 196
Additionally the interface informs plugins if new objects have been added to the scenes or if previous objects
have been removed.
197 198 199 200 201 202
LoadSaveInterface::fileOpened( int _id ) will be triggered each time an object is loaded from a file. If simply an
empty object has been added, the slot LoadSaveInterface::addedEmptyObject( int _id ) will be called. If an object
gets deleted, the LoadSaveInterface::objectDeleted( int _id ) will be called immediately before the object is removed
from the scenegraph. So if this function is invoked, the object still exists. All plugins get informed via this slot.

If you want to know if the whole scene got cleared, use BaseInterface::slotAllCleared( ).
203

Jan Möbius's avatar
Jan Möbius committed
204
\section loadSaveInterface_usage Usage
205 206
To use the LoadSaveInterface:
<ul>
Jan Möbius's avatar
Jan Möbius committed
207
<li> include LoadSaveInterface.hh in your plugins header file
208 209 210 211 212 213 214 215
<li> derive your plugin from the class LoadSaveInterface
<li> add Q_INTERFACES(LoadSaveInterface) to your plugin class
<li> And add the signals or slots you want to use to your plugin class (You don't need to implement all of them)
</ul>

*/


216
Q_DECLARE_INTERFACE(LoadSaveInterface,"OpenFlipper.LoadSaveInterface/1.1")
217

218
#endif // LOADSAVEINTERFACE_HH