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