Tulip  5.0.0
Large graphs analysis and drawing
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
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 <QDir>
24 #include <QString>
25 #include <QStringList>
26 #include <QDate>
27 #include <QObject>
28 #include <QIODevice>
29 
30 #include <tulip/tulipconf.h>
31 
32 #include <fstream>
33 
34 namespace tlp {
35 
36 class PluginProgress;
37 
38 /**
39  @ingroup Plugins
40 
41  @brief The TulipProject object handles the content of a Tulip project.
42 
43  All tulip projects contain a set of defined static meta-information:
44  @list
45  @li name (QString): the name of the project
46  @li description (QString): Comments about the project
47  @li author (QString): the author of the project
48  @li perspective (QString): the name of the perspective plugin associated to the project
49  @li date (QDate): the date of project's last modification
50  @li version (QString): the version of the Tulip project format
51  @endlist
52 
53  Alongside this information, 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
54  is left to the perspective.
55 
56  A TulipProject DOES NOT automatically save to disk. One will have to call the write() method to serialize data.
57  @warning Precise implementation of the TulipProject object should NOT be known or used by the user since it could be subject to changes.
58 
59  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.
60 
61  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.
62  Files can be opened using the stdFileStram and fileStream methods. They will always be opened in Read/Write mode.
63 
64  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.
65  The root directory is identified by "/".
66 
67  @warning TulipProject path ALWAYS use the "/" character as a directory separator. This is OS-independant.
68 
69  @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".
70  */
71 class TLP_QT_SCOPE TulipProject: public QObject {
72  Q_OBJECT
73 
74  TulipProject();
75  TulipProject(const QString &);
76 public:
77 
78  virtual ~TulipProject();
79 
80  /**
81  @brief Starts a new TulipProject from scratch
82 
83  This method builds up a new TulipProject file without taking any input.
84  @see openProject()
85  */
86  static TulipProject *newProject();
87 
88  /**
89  @brief Opens a previously saved tulip project file and returns the corresponding project
90 
91  This method will unpack a tulip project file into some directory and allow the user to manipulate the files.
92  @see TulipProject::save()
93  @param file The file to open.
94  @param progress A progress handler.
95  @return a pointer to a TulipProject object.
96  */
97  static TulipProject *openProject(const QString &file, tlp::PluginProgress *progress=NULL);
98 
99  /**
100  @brief Opens a previously saved tulip project file
101 
102  This method unpacks a tulip project file into some directory and allow the user to manipulate the files.
103  @see TulipProject::save()
104  @param file The file to open.
105  @param progress A progress handler.
106  @return true if the file has been successfully opened
107  */
108  bool openProjectFile(const QString &file, tlp::PluginProgress *progress=NULL);
109 
110  /**
111  @brief Restores a project which has already been extracted into path
112 
113  @warning Using several TulipProject instances on the same directory may result in undefined behavior. This method should only be used for crash handling purposes.
114  @param path The path where the archive was previously extracted
115  @return a pointer to a TulipProject object.
116  */
117  static TulipProject *restoreProject(const QString &path);
118 
119 
120  /**
121  * @brief Removes all files in the project and unset project file if any
122  *
123  * @since Tulip 5.0
124  */
125  void clearProject();
126 
127  /**
128  * @brief Sets the file where to save the project
129  * @param projectFile absolute path to a .tlpx file
130  *
131  * @since Tulip 5.0
132  */
133  void setProjectFile(const QString &projectFile);
134 
135  /**
136  @brief Writes files in the TulipProject into a packed archive.
137 
138  This method packs every file in the project into a single archive.
139  @note This method DOES NOT close the project. It only commits changes to the specified file. A TulipProject is only closed when destroyed.
140  @param file Absolute path where files should be packed.
141  @param progress A progress handler
142  @return False if method failed
143  */
144  bool write(const QString &file,tlp::PluginProgress *progress=NULL);
145 
146  /**
147  @brief Lists entries in a directory
148 
149  @see QDir documentation for a complete description of filtering arguments
150  @param path The path to scan. @see TulipProject
151  @return The list of files and directories present in the given directory
152  */
153  QStringList entryList(const QString &path, QDir::Filters filters = QDir::NoFilter, QDir::SortFlags sort = QDir::NoSort);
154 
155  /**
156  @brief Lists entries in a directory
157 
158  @see QDir documentation for a complete description of filtering arguments
159  @param path The path to scan. @see TulipProject
160  @return The list of files and directories present in the given directory
161  */
162  QStringList entryList(const QString &path, const QStringList &nameFilters, QDir::Filters filters = QDir::NoFilter, QDir::SortFlags sort = QDir::NoSort);
163 
164  /**
165  @brief Checks if the specified file/folder exists
166 
167  @param path The path to check.
168  @return true if the path exists.
169  */
170  bool exists(const QString &path);
171 
172  /**
173  @brief Recursively creates the specified path.
174 
175  Created folders will be empty
176  @return true if path was successfully created.
177  */
178  bool mkpath(const QString &path);
179 
180  /**
181  @brief Checks if the given path is a directory.
182 
183  @param path The path to check. @see TulipProject
184  @return true/false wether the path is a directory.
185  */
186  bool isDir(const QString &path);
187 
188  /**
189  @brief Removes a file from the project.
190 
191  If the given path points to a directory, or if the file does not exist, this method will fail and return false
192  @param path The path to delete. @see TulipProject
193  */
194  bool removeFile(const QString &path);
195 
196  /**
197  @brief Removes a directory from the project.
198 
199  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.
200  @see removeAllDir to remove a non-empty directory.
201  @param path The path to delete. @see TulipProject
202  */
203  bool removeDir(const QString &path);
204 
205  /**
206  @brief Removes a directory and all its content from the project.
207 
208  If the given file points to a file, or if the directory does not exist, this method will fail and return false.
209  @warning This will remove every file stored in the specified directory.
210  @param path The path to delete. @see TulipProject
211  */
212  bool removeAllDir(const QString &path);
213 
214  /**
215  @brief Copies a file from the local filesystem into the project
216 
217  @param source The absolute path of the file to copy
218  @param destination The project path where to copy the file
219  @return false if copy failed
220  */
221  bool copy(const QString& source, const QString& destination);
222 
223  /**
224  @brief Creates an empty file
225 
226  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.
227  @param file the file to create
228  @return true if file creation was sucessful.
229  */
230  bool touch(const QString& path);
231 
232  /**
233  @brief Gets a STL file stream (default to R/W access mode) to the given path.
234 
235  @warning This method does not check if the given path is a directory or a file. User might get an invalid filestream.
236  @warning It is up to the user to delete the std::fstream returned.
237  @param path The path to open. @see TulipProject
238  @return an opened filestream on the given path.
239  */
240  std::fstream *stdFileStream(const QString &path, std::ios_base::openmode=std::fstream::in | std::fstream::out | std::fstream::app);
241 
242  /**
243  @brief Gets a Qt I/O device (default to R/W access mode) to the given path.
244 
245  @warning This method does not check if the given path is a directory or a file. User might get an invalid filestream.
246  @warning User SHOULD NOT cast the QIODevice returned by this method into any of its subclass since the implementation might change in future versions.
247  @warning It is up to the user to delete the QIODevice returned.
248  @param path The path to open. @see TulipProject
249  @param mode The opening mode as described in the Qt documentation.
250  @return an opened Qt device on the given path.
251  */
252  QIODevice *fileStream(const QString &path, QIODevice::OpenMode mode=QIODevice::ReadWrite);
253 
254  /**
255  @brief Returns the last error raised.
256 
257  @note The returned string is empty if no error was raised.
258  */
259  QString lastError() const {
260  return _lastError;
261  }
262 
263  /**
264  @brief Checks if the object is a valid TulipProject.
265 
266  @warning Calling methods on invalid TulipProject instances may result in undefined behavior.
267  */
268  bool isValid() const {
269  return _isValid;
270  }
271 
272  /**
273  @brief Returns the archive file associated with this project.
274 
275  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.
276  In other cases, this method will return an empty string.
277  */
278  QString projectFile() const {
279  return _projectFile;
280  }
281 
282  /**
283  @brief This method returns the real absolute path corresponding to / in the TulipProject.
284 
285  This can be used to create a TulipProject directly from a path.
286  @warning Using several TulipProject instances at the same time on the same path may result in undefined behavior.
287  */
288  QString absoluteRootPath() const;
289 
290  // Developer note: Every field in the TulipProject tagged as a Q_PROPERTY will automaticaly be serialized in the project.xml file
291  /**
292  @brief the name of the project
293  */
294  Q_PROPERTY(QString name READ name WRITE setName)
295  /**
296  * @see name
297  */
298  QString name() const;
299 
300  /**
301  @brief User-written description of the project
302  */
303  Q_PROPERTY(QString description READ description WRITE setDescription)
304  /**
305  * @see description
306  */
307  QString description() const;
308 
309  /**
310  @brief Name of the author
311  */
312  Q_PROPERTY(QString author READ author WRITE setAuthor)
313  /**
314  * @see author
315  */
316  QString author() const;
317 
318  /**
319  @brief Name of the perspective associated to the project.
320 
321  When the user open a project from Tulip, this porperty is first read to identify find kind of perspective plugin should be launched to
322  open the project
323 
324  @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.
325  */
326  Q_PROPERTY(QString perspective READ perspective WRITE setPerspective)
327  /**
328  * @see perspective
329  */
330  QString perspective() const;
331 
332  /**
333  @brief The version of the Tulip project format with which the file was created.
334  Project from older format version will be always saved into the newest version available.
335  */
336  QString version() const;
337 
338  /**
339  @brief Returns the absolute filesystem path used to store the file
340  @warning Be cautious though since directly modifying project files without using TulipProject methods could result in undefined behavior.
341  */
342  QString toAbsolutePath(const QString &relativePath);
343 
344 signals:
345  void projectFileChanged(const QString& projectFile);
346 
347 public slots:
348  /**
349  * @see name
350  */
351  void setName(const QString &);
352  /**
353  * @see description
354  */
355  void setDescription(const QString &);
356  /**
357  * @see author
358  */
359  void setAuthor(const QString &);
360  /**
361  * @see perspective
362  */
363  void setPerspective(const QString &);
364 
365 private:
366  static QString temporaryPath();
367 
368  bool writeMetaInfo();
369  bool readMetaInfo();
370 
371  bool removeAllDirPrivate(const QString &path, bool removeRootDir = true);
372 
373  // Core fileset
374  QDir _rootDir;
375  QDir _dataDir;
376  QString _projectFile;
377 
378  // Meta information
379  QString _author;
380  QString _name;
381  QString _description;
382  QString _perspective;
383 
384  // Error handling
385  QString _lastError;
386  bool _isValid;
387 };
388 
389 }
390 #endif // TULIPPROJECT_H
The TulipProject object handles the content of a Tulip project.
Definition: TulipProject.h:71
QString lastError() const
Returns the last error raised.
Definition: TulipProject.h:259
PluginProcess subclasses are meant to notify about the progress state of some process (typically a pl...
QString projectFile() const
Returns the archive file associated with this project.
Definition: TulipProject.h:278
bool isValid() const
Checks if the object is a valid TulipProject.
Definition: TulipProject.h:268