Tulip  4.1.0
Better Visualization Through Research
 All Classes Files Functions Variables Enumerations Enumerator Properties Groups Pages
TulipProject.h
1 /*
2  *
3  * This file is part of Tulip (www.tulip-software.org)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux 1 and Inria Bordeaux - Sud Ouest
7  *
8  * Tulip is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *
13  * Tulip is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  * See the GNU General Public License for more details.
17  *
18  */
19 
20 #ifndef TULIPPROJECT_H
21 #define TULIPPROJECT_H
22 
23 #include <fstream>
24 
25 #include <QtCore/QDir>
26 #include <QtCore/QString>
27 #include <QtCore/QStringList>
28 #include <QtCore/QDate>
29 #include <QtCore/QObject>
30 #include <QtCore/QIODevice>
31 
32 #include <tulip/tulipconf.h>
33 #include <tulip/PluginProgress.h>
34 
35 namespace tlp {
36 
37 /**
38  @ingroup Plugins
39 
40  @brief The TulipProject object handles the content of a Tulip project.
41 
42  All tulip projects contain a set of defined static meta-informations:
43  @list
44  @li name (QString): the name of the project
45  @li description (QString): Comments about the project
46  @li author (QString): the author of the project
47  @li perspective (QString): the name of the perspective plugin associated to the project
48  @li date (QDate): the date of project's last modification
49  @li version (QString): the version of the Tulip project format
50  @endlist
51 
52  Alongside those informations, one can store any kind of file into a Tulip project. Since a project is meant to be associated to a specific perspective, the responisbility of those file
53  is left to the perspective.
54 
55  A TulipProject DOES NOT automatically save to disk. One will have to call the write() method to serialize data.
56  @warning Precise implementation of the TulipProject object should NOT be known or used by the user since it could be subject to changes.
57 
58  If something wrong happens when calling a method from TulipProject, this method will return either false or a invalid result (see specific method documentation). The last error message can be retrieved with the lastError() method.
59 
60  After opening and before saving a project, user will be able to list/delete files and directories available in the project and open them using std filestreams or Qt's QIODevice.
61  Files can be opened using the stdFileStram and fileStream methods. They will always be opened in Read/Write mode.
62 
63  Files in a tulip project are identified by their path. Those path ar similar to the path of a standard file system and use the "/" character as a separator.
64  The root directory is identified by "/".
65 
66  @warning TulipProject paths ALWAYS use the "/" character as a directory separator. This is OS-independant.
67 
68  @note A file called graph.tlp located at the top-level directory will be identified by the "/graph.tlp" path while the file "graph.tlp" located in the "data" directory will be identified by "/data/graph.tlp".
69  */
70 class TLP_QT_SCOPE TulipProject: public QObject {
71  Q_OBJECT
72 
73  TulipProject();
74  TulipProject(const QString &);
75 public:
76 
77  virtual ~TulipProject();
78 
79  /**
80  @brief Starts a new TulipProject from scratch
81 
82  This method builds up a new TulipProject file without taking any input.
83  @see openProject()
84  */
85  static TulipProject *newProject();
86 
87  /**
88  @brief Opens a previously saved tulip project file
89 
90  This method will unpack a tulip project file into some directory and allow the user to manipulate the files.
91  @see TulipProject::save()
92  @param file The file to open.
93  @param progress A progress handler.
94  @return a pointer to a TulipProject object.
95  */
96  static TulipProject *openProject(const QString &file, tlp::PluginProgress *progress=NULL);
97 
98  /**
99  @brief Restores a project which has already been extracted into path
100 
101  @warning Using several TulipProject instances on the same directory may result in undefined behavior. This method should only be used for crash handling purposes.
102  @param path The path where the archive was previously extracted
103  @return a pointer to a TulipProject object.
104  */
105  static TulipProject *restoreProject(const QString &path);
106 
107 
108  /**
109  @brief Writes files in the TulipProject into a packed archive.
110 
111  This method packs every file in the project into a single archive.
112  @note This method DOES NOT close the project. It only commits changes to the specified file. A TulipProject is only closed when destroyed.
113  @param file Absolute path where files should be packed.
114  @param progress A progress handler
115  @return False if method failed
116  */
117  bool write(const QString &file,tlp::PluginProgress *progress=NULL);
118 
119  /**
120  @brief Lists entries in a directory
121 
122  @see QDir documentation for a complete description of filtering arguments
123  @param path The path to scan. @see TulipProject
124  @return The list of files and directories present in the given directory
125  */
126  QStringList entryList(const QString &path, QDir::Filters filters = QDir::NoFilter, QDir::SortFlags sort = QDir::NoSort);
127 
128  /**
129  @brief Lists entries in a directory
130 
131  @see QDir documentation for a complete description of filtering arguments
132  @param path The path to scan. @see TulipProject
133  @return The list of files and directories present in the given directory
134  */
135  QStringList entryList(const QString &path, const QStringList &nameFilters, QDir::Filters filters = QDir::NoFilter, QDir::SortFlags sort = QDir::NoSort);
136 
137  /**
138  @brief Checks if the specified file/folder exists
139 
140  @param path The path to check.
141  @return true if the path exists.
142  */
143  bool exists(const QString &path);
144 
145  /**
146  @brief Recursively creates the specified path.
147 
148  Created folders will be empty
149  @return true if path was successfully created.
150  */
151  bool mkpath(const QString &path);
152 
153  /**
154  @brief Checks if the given path is a directory.
155 
156  @param path The path to check. @see TulipProject
157  @return true/false wether the path is a directory.
158  */
159  bool isDir(const QString &path);
160 
161  /**
162  @brief Removes a file from the project.
163 
164  If the given path points to a directory, or if the file does not exist, this method will fail and return false
165  @param path The path to delete. @see TulipProject
166  */
167  bool removeFile(const QString &path);
168 
169  /**
170  @brief Removes a directory from the project.
171 
172  If the given file points to a file, or if the directory does not exist, or if the directory is not empty, this method will fail and return false.
173  @see removeAllDir to remove a non-empty directory.
174  @param path The path to delete. @see TulipProject
175  */
176  bool removeDir(const QString &path);
177 
178  /**
179  @brief Removes a directory and all its content from the project.
180 
181  If the given file points to a file, or if the directory does not exist, this method will fail and return false.
182  @warning This will remove every file stored in the specified directory.
183  @param path The path to delete. @see TulipProject
184  */
185  bool removeAllDir(const QString &path);
186 
187  /**
188  @brief Copies a file from the local filesystem into the project
189 
190  @param source The absolute path of the file to copy
191  @param destination The project path where to copy the file
192  @return false if copy failed
193  */
194  bool copy(const QString& source, const QString& destination);
195 
196  /**
197  @brief Creates a empty file
198 
199  This method is similar to the UNIX's touch shell command. Except it won't renew the file's creation date if the file already exists.
200  @param file the file to create
201  @return true if file creation was sucessful.
202  */
203  bool touch(const QString& path);
204 
205  /**
206  @brief Gets a STL file stream (R/W access mode) to the given path.
207 
208  @warning This method does not check if the given path is a directory or a file. User might get an invalid filestream.
209  @param path The path to open. @see TulipProject
210  @return an opened filestream on the given path.
211  */
212  std::fstream *stdFileStream(const QString &path);
213 
214  /**
215  @brief Gets a Qt I/O device (R/W access mode) to the given path.
216 
217  @warning This method does not check if the given path is a directory or a file. User might get an invalid filestream.
218  @warning User SHOULD NOT cast the QIODevice returned by this method into any of its subclass since the implementation might change in future versions.
219  @param path The path to open. @see TulipProject
220  @return an opened Qt device on the given path.
221  */
222  QIODevice *fileStream(const QString &path);
223 
224  /**
225  @brief Returns the last error raised.
226 
227  @note The returned string is null if no error was raised.
228  */
229  QString lastError() const {
230  return _lastError;
231  }
232 
233  /**
234  @brief Check if the object is a valid TulipProject.
235 
236  @warning Calling methods on invalid TulipProject instances may result in undefined behavior.
237  */
238  bool isValid() const {
239  return _isValid;
240  }
241 
242  /**
243  @brief Return the archive file associated with this project.
244 
245  If the project has been opened from an existing file or if the write method has already been called, this method will return the last file path specified.
246  In other cases, this method will return an empty string.
247  */
248  QString projectFile() const {
249  return _projectFile;
250  }
251 
252  /**
253  @brief This method returns the real absolute path corresponding to / in the TulipProject.
254 
255  This can be used to create a TulipProject directly from a path.
256  @warning Using several TulipProject instances at the same time on the same path may result in undefined behavior.
257  */
258  QString absoluteRootPath() const;
259 
260  // Developer note: Every field in the TulipProject tagged as a Q_PROPERTY will automaticaly be serialized in the project.xml file
261  /**
262  @brief the name of the project
263  */
264  Q_PROPERTY(QString name READ name WRITE setName)
265  /**
266  * @see name
267  */
268  QString name() const;
269 
270  /**
271  @brief User-written description of the project
272  */
273  Q_PROPERTY(QString description READ description WRITE setDescription)
274  /**
275  * @see description
276  */
277  QString description() const;
278 
279  /**
280  @brief Name of the author
281  */
282  Q_PROPERTY(QString author READ author WRITE setAuthor)
283  /**
284  * @see author
285  */
286  QString author() const;
287 
288  /**
289  @brief Name of the perspective associated to the project.
290 
291  When the user open a project from Tulip, this porperty is first read to identify find kind of perspective plugin should be launched to
292  open the project
293 
294  @warning If the perspective name associated to the project is invalid or correspond to a missing plugin, tulip may not be able to open the file.
295  */
296  Q_PROPERTY(QString perspective READ perspective WRITE setPerspective)
297  /**
298  * @see perspective
299  */
300  QString perspective() const;
301 
302  /**
303  @brief The version of the Tulip project format with which the file was created.
304  Project from older format versions will always by saved into the newest version available.
305  */
306  QString version() const;
307 
308  /**
309  @brief Returns the absolute filesystem path used to store the file
310  @warning Be cautious though since directly modifying project files without using TulipProject methods could result in undefined behavior.
311  */
312  QString toAbsolutePath(const QString &relativePath);
313 
314 public slots:
315  /**
316  * @see name
317  */
318  void setName(const QString &);
319  /**
320  * @see description
321  */
322  void setDescription(const QString &);
323  /**
324  * @see author
325  */
326  void setAuthor(const QString &);
327  /**
328  * @see perspective
329  */
330  void setPerspective(const QString &);
331 
332 private:
333  static QString temporaryPath();
334 
335  bool writeMetaInfos();
336  bool readMetaInfos();
337 
338  bool removeAllDirPrivate(const QString &path);
339 
340  // Core fileset
341  QDir _rootDir;
342  QDir _dataDir;
343  QString _projectFile;
344 
345  // Meta informations
346  QString _author;
347  QString _name;
348  QString _description;
349  QString _perspective;
350 
351  // Error handling
352  QString _lastError;
353  bool _isValid;
354 };
355 
356 }
357 #endif // TULIPPROJECT_H