LoadSaveInterface.hh 9.04 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-2014 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
\*===========================================================================*/
Jan Möbius's avatar
 
Jan Möbius committed
42

43 44
#ifndef LOADSAVEINTERFACE_HH
#define LOADSAVEINTERFACE_HH
Jan Möbius's avatar
 
Jan Möbius committed
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
  *
Jan Möbius's avatar
 
Jan Möbius committed
58
  * Using this interface you can instruct the core to open/save objects or
59
  * to create new empty objects.
60
 */
Jan Möbius's avatar
 
Jan Möbius committed
61
class LoadSaveInterface {
62 63

   public:
64

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

Jan Möbius's avatar
 
Jan Möbius committed
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
       *
Jan Möbius's avatar
 
Jan Möbius committed
78
       * @param _filename Filename of the File to load
79
       * @param _type Type to be loaded
Jan Möbius's avatar
Jan Möbius committed
80
       * @param _id Here the id of the loaded object is returned. id is -1 something went wrong
Jan Möbius's avatar
 
Jan Möbius committed
81
       */
82
      virtual void load(QString _filename, DataType _type, int& _id) {};
83

84

Jan Möbius's avatar
 
Jan Möbius committed
85
      /** Add an empty object of the given type
86
       *
Jan Möbius's avatar
 
Jan Möbius committed
87
       * @param _type Type to be created
Jan Möbius's avatar
Jan Möbius committed
88
       * @param _id Here the id of the loaded object is returned. id is -1 something went wrong
Jan Möbius's avatar
 
Jan Möbius committed
89
       */
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
      /** \brief DEPRECATED HERE (Moved to Type Interface)! Emit this signal if an empty object has been created
101 102 103
       *
       * Deprecated! Objects are added by the Type Plugins and this is signal is in the TypeInterface now
       *
Jan Möbius's avatar
 
Jan Möbius committed
104
       * @param _id Id of the added object
105
       */
106
      virtual void emptyObjectAdded( int _id ) {};
Jan Möbius's avatar
 
Jan Möbius committed
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
      /** \brief Delete all Objects
       *
       */
117 118 119 120 121 122
      virtual void deleteAllObjects() {};

      /** \brief Get all file filters that are registered
       *
       */
      virtual void getAllFileFilters(QStringList& _filters) {};
123

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

Jan Möbius's avatar
 
Jan Möbius committed
126
    /**  \brief A file has been opened
127
     *
Jan Möbius's avatar
 
Jan Möbius committed
128 129 130
     *  This slot is called if a file has been opened by the core.\n
     *  @param _id Id of the new object
     */
131
    virtual void fileOpened( int _id ) {};
Dirk Wilden's avatar
Dirk Wilden committed
132 133

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

140 141
    /** \brief An object was deleted
      *
142
      * This function is called by the core if an object gets deleted. It is called immediately
143 144 145 146 147 148 149
      * 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.
150
      */
151
    virtual void objectDeleted( int _id ){};
152

Jan Möbius's avatar
 
Jan Möbius committed
153 154
};

155
/** \page loadSaveInterfacePage Load/Save Interface
156 157 158 159
 * \n
\image html loadSaveInterface.png
\n

160 161 162
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.

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 195 196 197 198 199

\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
200 201
Additionally the interface informs plugins if new objects have been added to the scenes or if previous objects
have been removed.
202 203 204 205 206 207
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( ).
208

Jan Möbius's avatar
Jan Möbius committed
209
\section loadSaveInterface_usage Usage
210 211
To use the LoadSaveInterface:
<ul>
Jan Möbius's avatar
Jan Möbius committed
212
<li> include LoadSaveInterface.hh in your plugins header file
213 214 215 216 217 218 219 220
<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>

*/


221
Q_DECLARE_INTERFACE(LoadSaveInterface,"OpenFlipper.LoadSaveInterface/1.1")
222

Jan Möbius's avatar
 
Jan Möbius committed
223
#endif // LOADSAVEINTERFACE_HH