Tulip  5.0.0
Large graphs analysis and drawing
tlp::TulipProject Class Reference

#include <TulipProject.h>

Inherits QObject.

Public Slots

void setAuthor (const QString &)
 
void setDescription (const QString &)
 
void setName (const QString &)
 
void setPerspective (const QString &)
 

Signals

void projectFileChanged (const QString &projectFile)
 

Public Member Functions

QString absoluteRootPath () const
 
QString author () const
 
void clearProject ()
 
bool copy (const QString &source, const QString &destination)
 
QString description () const
 
QStringList entryList (const QString &path, QDir::Filters filters=QDir::NoFilter, QDir::SortFlags sort=QDir::NoSort)
 
QStringList entryList (const QString &path, const QStringList &nameFilters, QDir::Filters filters=QDir::NoFilter, QDir::SortFlags sort=QDir::NoSort)
 
bool exists (const QString &path)
 
QIODevice * fileStream (const QString &path, QIODevice::OpenMode mode=QIODevice::ReadWrite)
 
bool isDir (const QString &path)
 
bool isValid () const
 
QString lastError () const
 
bool mkpath (const QString &path)
 
QString name () const
 
bool openProjectFile (const QString &file, tlp::PluginProgress *progress=NULL)
 
QString perspective () const
 
QString projectFile () const
 
bool removeAllDir (const QString &path)
 
bool removeDir (const QString &path)
 
bool removeFile (const QString &path)
 
void setProjectFile (const QString &projectFile)
 
std::fstream * stdFileStream (const QString &path, std::ios_base::openmode=std::fstream::in|std::fstream::out|std::fstream::app)
 
QString toAbsolutePath (const QString &relativePath)
 
bool touch (const QString &path)
 
QString version () const
 
bool write (const QString &file, tlp::PluginProgress *progress=NULL)
 

Static Public Member Functions

static TulipProjectnewProject ()
 
static TulipProjectopenProject (const QString &file, tlp::PluginProgress *progress=NULL)
 
static TulipProjectrestoreProject (const QString &path)
 

Properties

QString author
 
QString description
 
QString name
 
QString perspective
 

Detailed Description

The TulipProject object handles the content of a Tulip project.

All tulip projects contain a set of defined static meta-information:

  • name (QString): the name of the project
  • description (QString): Comments about the project
  • author (QString): the author of the project
  • perspective (QString): the name of the perspective plugin associated to the project
  • date (QDate): the date of project's last modification
  • version (QString): the version of the Tulip project format

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 is left to the perspective.

A TulipProject DOES NOT automatically save to disk. One will have to call the write() method to serialize data.

Warning
Precise implementation of the TulipProject object should NOT be known or used by the user since it could be subject to changes.

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.

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. Files can be opened using the stdFileStram and fileStream methods. They will always be opened in Read/Write mode.

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. The root directory is identified by "/".

Warning
TulipProject path ALWAYS use the "/" character as a directory separator. This is OS-independant.
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".

Definition at line 71 of file TulipProject.h.

Member Function Documentation

QString tlp::TulipProject::absoluteRootPath ( ) const

This method returns the real absolute path corresponding to / in the TulipProject.

This can be used to create a TulipProject directly from a path.

Warning
Using several TulipProject instances at the same time on the same path may result in undefined behavior.
QString tlp::TulipProject::author ( ) const
See also
author
void tlp::TulipProject::clearProject ( )

Removes all files in the project and unset project file if any.

Since
Tulip 5.0
bool tlp::TulipProject::copy ( const QString &  source,
const QString &  destination 
)

Copies a file from the local filesystem into the project.

Parameters
sourceThe absolute path of the file to copy
destinationThe project path where to copy the file
Returns
false if copy failed
QString tlp::TulipProject::description ( ) const
See also
description
QStringList tlp::TulipProject::entryList ( const QString &  path,
QDir::Filters  filters = QDir::NoFilter,
QDir::SortFlags  sort = QDir::NoSort 
)

Lists entries in a directory.

See also
QDir documentation for a complete description of filtering arguments
Parameters
pathThe path to scan.
See also
TulipProject
Returns
The list of files and directories present in the given directory
QStringList tlp::TulipProject::entryList ( const QString &  path,
const QStringList &  nameFilters,
QDir::Filters  filters = QDir::NoFilter,
QDir::SortFlags  sort = QDir::NoSort 
)

Lists entries in a directory.

See also
QDir documentation for a complete description of filtering arguments
Parameters
pathThe path to scan.
See also
TulipProject
Returns
The list of files and directories present in the given directory
bool tlp::TulipProject::exists ( const QString &  path)

Checks if the specified file/folder exists.

Parameters
pathThe path to check.
Returns
true if the path exists.
QIODevice* tlp::TulipProject::fileStream ( const QString &  path,
QIODevice::OpenMode  mode = QIODevice::ReadWrite 
)

Gets a Qt I/O device (default to R/W access mode) to the given path.

Warning
This method does not check if the given path is a directory or a file. User might get an invalid filestream.
User SHOULD NOT cast the QIODevice returned by this method into any of its subclass since the implementation might change in future versions.
It is up to the user to delete the QIODevice returned.
Parameters
pathThe path to open.
See also
TulipProject
Parameters
modeThe opening mode as described in the Qt documentation.
Returns
an opened Qt device on the given path.
bool tlp::TulipProject::isDir ( const QString &  path)

Checks if the given path is a directory.

Parameters
pathThe path to check.
See also
TulipProject
Returns
true/false wether the path is a directory.
bool tlp::TulipProject::isValid ( ) const
inline

Checks if the object is a valid TulipProject.

Warning
Calling methods on invalid TulipProject instances may result in undefined behavior.

Definition at line 268 of file TulipProject.h.

QString tlp::TulipProject::lastError ( ) const
inline

Returns the last error raised.

Note
The returned string is empty if no error was raised.

Definition at line 259 of file TulipProject.h.

bool tlp::TulipProject::mkpath ( const QString &  path)

Recursively creates the specified path.

Created folders will be empty

Returns
true if path was successfully created.
QString tlp::TulipProject::name ( ) const
See also
name
static TulipProject* tlp::TulipProject::newProject ( )
static

Starts a new TulipProject from scratch.

This method builds up a new TulipProject file without taking any input.

See also
openProject()
static TulipProject* tlp::TulipProject::openProject ( const QString &  file,
tlp::PluginProgress progress = NULL 
)
static

Opens a previously saved tulip project file and returns the corresponding project.

This method will unpack a tulip project file into some directory and allow the user to manipulate the files.

See also
TulipProject::save()
Parameters
fileThe file to open.
progressA progress handler.
Returns
a pointer to a TulipProject object.
bool tlp::TulipProject::openProjectFile ( const QString &  file,
tlp::PluginProgress progress = NULL 
)

Opens a previously saved tulip project file.

This method unpacks a tulip project file into some directory and allow the user to manipulate the files.

See also
TulipProject::save()
Parameters
fileThe file to open.
progressA progress handler.
Returns
true if the file has been successfully opened
QString tlp::TulipProject::perspective ( ) const
See also
perspective
QString tlp::TulipProject::projectFile ( ) const
inline

Returns the archive file associated with this project.

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. In other cases, this method will return an empty string.

Definition at line 278 of file TulipProject.h.

bool tlp::TulipProject::removeAllDir ( const QString &  path)

Removes a directory and all its content from the project.

If the given file points to a file, or if the directory does not exist, this method will fail and return false.

Warning
This will remove every file stored in the specified directory.
Parameters
pathThe path to delete.
See also
TulipProject
bool tlp::TulipProject::removeDir ( const QString &  path)

Removes a directory from the project.

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.

See also
removeAllDir to remove a non-empty directory.
Parameters
pathThe path to delete.
See also
TulipProject
bool tlp::TulipProject::removeFile ( const QString &  path)

Removes a file from the project.

If the given path points to a directory, or if the file does not exist, this method will fail and return false

Parameters
pathThe path to delete.
See also
TulipProject
static TulipProject* tlp::TulipProject::restoreProject ( const QString &  path)
static

Restores a project which has already been extracted into path.

Warning
Using several TulipProject instances on the same directory may result in undefined behavior. This method should only be used for crash handling purposes.
Parameters
pathThe path where the archive was previously extracted
Returns
a pointer to a TulipProject object.
void tlp::TulipProject::setAuthor ( const QString &  )
slot
See also
author
void tlp::TulipProject::setDescription ( const QString &  )
slot
See also
description
void tlp::TulipProject::setName ( const QString &  )
slot
See also
name
void tlp::TulipProject::setPerspective ( const QString &  )
slot
See also
perspective
void tlp::TulipProject::setProjectFile ( const QString &  projectFile)

Sets the file where to save the project.

Parameters
projectFileabsolute path to a .tlpx file
Since
Tulip 5.0
std::fstream* tlp::TulipProject::stdFileStream ( const QString &  path,
std::ios_base::openmode  = std::fstream::in|std::fstream::out|std::fstream::app 
)

Gets a STL file stream (default to R/W access mode) to the given path.

Warning
This method does not check if the given path is a directory or a file. User might get an invalid filestream.
It is up to the user to delete the std::fstream returned.
Parameters
pathThe path to open.
See also
TulipProject
Returns
an opened filestream on the given path.
QString tlp::TulipProject::toAbsolutePath ( const QString &  relativePath)

Returns the absolute filesystem path used to store the file.

Warning
Be cautious though since directly modifying project files without using TulipProject methods could result in undefined behavior.
bool tlp::TulipProject::touch ( const QString &  path)

Creates an empty file.

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.

Parameters
filethe file to create
Returns
true if file creation was sucessful.
QString tlp::TulipProject::version ( ) const

The version of the Tulip project format with which the file was created. Project from older format version will be always saved into the newest version available.

bool tlp::TulipProject::write ( const QString &  file,
tlp::PluginProgress progress = NULL 
)

Writes files in the TulipProject into a packed archive.

This method packs every file in the project into a single archive.

Note
This method DOES NOT close the project. It only commits changes to the specified file. A TulipProject is only closed when destroyed.
Parameters
fileAbsolute path where files should be packed.
progressA progress handler
Returns
False if method failed

Property Documentation

QString tlp::TulipProject::author
readwrite

Name of the author.

Definition at line 312 of file TulipProject.h.

QString tlp::TulipProject::description
readwrite

User-written description of the project.

Definition at line 303 of file TulipProject.h.

QString tlp::TulipProject::name
readwrite

the name of the project

Definition at line 294 of file TulipProject.h.

QString tlp::TulipProject::perspective
readwrite

Name of the perspective associated to the project.

When the user open a project from Tulip, this porperty is first read to identify find kind of perspective plugin should be launched to open the project

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.

Definition at line 326 of file TulipProject.h.