#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

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)

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 TulipProject *	newProject ()

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

static TulipProject *	restoreProject (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 paths 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

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

Copies a file from the local filesystem into the project.

Parameters

source	The absolute path of the file to copy
destination	The 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

path	The 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

path	The 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

path	The 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

path	The path to open.

See Also: TulipProject

Parameters

mode	The 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

path	The path to check.

See Also: TulipProject

Returns: true/false wether the path is a directory.

bool tlp::TulipProject::isValid ( ) const

inline

Check if the object is a valid TulipProject.

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

Definition at line 253 of file TulipProject.h.

QString tlp::TulipProject::lastError ( ) const

inline

Returns the last error raised.

Note: The returned string is null if no error was raised.

Definition at line 244 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

file	The file to open.
progress	A 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 will unpack a tulip project file into some directory and allow the user to manipulate the files.

See Also: TulipProject::save()

Parameters

file	The file to open.
progress	A 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

Return 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 263 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

path	The 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

path	The 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

path	The 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

path	The 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

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

path	The 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 a 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

file	the 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 versions will always by 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

file	Absolute path where files should be packed.
progress	A progress handler

Returns: False if method failed

Property Documentation

QString tlp::TulipProject::author

readwrite

Name of the author.

Definition at line 297 of file TulipProject.h.

QString tlp::TulipProject::description

readwrite

User-written description of the project.

Definition at line 288 of file TulipProject.h.

QString tlp::TulipProject::name

readwrite

the name of the project

Definition at line 279 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 311 of file TulipProject.h.

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Member Function Documentation

Property Documentation