dtDAL::Project Class Reference

Represents the project directory structure. More...

#include <project.h>

List of all members.

Public Member Functions
void	CreateContext (const std::string &path)
	Creates a new project context if it doesn't exist.
bool	IsContextValid () const
	Returns: true if the context is valid.
void	SetContext (const std::string &path, bool openReadOnly=false)
	Assigns the context for the project.
const std::string &	GetContext () const
	Returns: the current context.
void	Refresh ()
	In the process of opening and using a project, lists of resources, maps, etc, are created This will clear or otherwise reload these cached lists so that any changes made to the project by hand will be picked up.
const std::set< std::string > &	GetMapNames ()
	Returns: a vector with the names of the maps currently in the project.
Map &	GetMap (const std::string &name)
	returns the map with the given name.
Map &	OpenMapBackup (const std::string &name)
	returns the last backup save of the map with the given name.
Map &	LoadMapIntoScene (const std::string &name, dtCore::Scene &scene, bool addBillBoards=false, bool enablePaging=true)
	Loads a map by name into an application.
void	LoadMapIntoScene (Map &map, dtCore::Scene &scene, bool addBillBoards=false, bool enablePaging=true)
	Loads a map into a scene.
Map &	CreateMap (const std::string &name, const std::string &fileName)
	Creates a new map and saves it.
void	CloseMap (Map &map, bool unloadLibraries=false)
	Closes the map passed in.
void	CloseAllMaps (bool unloadLibraries=false)
	Closes all open maps.
void	DeleteMap (Map &map, bool unloadLibraries=false)
	Deletes the given map.
void	DeleteMap (const std::string &mapName, bool unloadLibraries=false)
	Deletes the given map.
void	SaveMap (Map &map, dtCore::Scene *pScene=NULL)
	Saves the given map whether it has changed or not.
void	SaveMapAs (Map &map, const std::string &newName, const std::string &newFileName, dtCore::Scene *pScene=NULL)
	Saves the given map to a new file name and alters the open map object to point to the new file.
void	SaveMapAs (const std::string &mapName, const std::string &newName, const std::string &newFileNam, dtCore::Scene *pScene=NULL)
	Saves the given map to a new file name and alters the open map object to point to the new file.
void	SaveMap (const std::string &mapName, dtCore::Scene *pScene=NULL)
	Saves the given map whether it has changed or not.
void	SaveMapBackup (Map &map)
	Saves a new backup of the map.
bool	HasBackup (Map &map) const
	Parameters: map  the map to get the backups count for.
bool	HasBackup (const std::string &mapName) const
	Parameters: mapName  the name map to get the backups count for.
void	ClearBackup (Map &map)
	Clears the backup save for a give map.
void	ClearBackup (const std::string &mapName)
	Clears the backup save for a given map.
Map *	GetMapForActorProxy (const ActorProxy &proxy)
	This will search all open maps until is finds the one that contains the given proxy.
const Map *	GetMapForActorProxy (const ActorProxy &proxy) const
	This will search all open maps until is finds the one that contains the given proxy.
void	GetHandlersForDataType (const DataType &resourceType, std::vector< const ResourceTypeHandler * > &toFill) const
	Parameters: resourceType  the type of resource.
void	RegisterResourceTypeHander (ResourceTypeHandler &handler)
	Registers a new type handler.
const std::string	GetResourcePath (const ResourceDescriptor &resource) const
	This will take the resource descriptor object and return a path to the resource within the project.
const ResourceDescriptor	AddResource (const std::string &newName, const std::string &pathToFile, const std::string &category, const DataType &type)
	Adds a resource to the project by copying it into the project.
void	RemoveResource (const ResourceDescriptor &resource)
	Removes a resource from a project.
void	CreateResourceCategory (const std::string &category, const DataType &type)
	Creates a new resource category.
bool	RemoveResourceCategory (const std::string &category, const DataType &type, bool recursive)
	Removes a category.
const dtUtil::tree < ResourceTreeNode > &	GetAllResources () const
	Note: This tree will likely be cached.
void	GetResourcesOfType (const DataType &type, dtUtil::tree< ResourceTreeNode > &toFill) const
	Note: The data will likely be cached.
bool	IsArchive () const
	Returns: true if the current project context is stored in an archive.
bool	IsReadOnly () const
	Returns: true if the current project is opened readonly.
void	SetEditMode (bool pInStage)
	This flag will alert actors whether or not there proxy is being loaded into STAGE as a note this should only be set from dtEditQt namespace potential refactor would be to ensure only dtEditQt could set it another implementation would be to have a project state which could control whether we are editing or not if need be we can add a getter for this.
const bool	GetEditMode () const
	Returns if Project is being executed from STAGE.
Static Public Member Functions
static Project &	GetInstance ()
	Returns: the single instance of this class.
Protected Member Functions
virtual	~Project ()

---

Detailed Description

Represents the project directory structure.

This represents the project directory structure and implements the methods to access and modify a project including the maps and resource content. This class is a singleton. Call the getInstance method for the single instance.

---

Constructor & Destructor Documentation

dtDAL::Project::~Project

(

)

[protected, virtual]

---

Member Function Documentation

static Project& dtDAL::Project::GetInstance

(

void

)

[inline, static]

Returns:

the single instance of this class.

void dtDAL::Project::CreateContext

(

const std::string &

path

)

Creates a new project context if it doesn't exist.

Parameters:

path

the full path to the new context directory

Exceptions:

dtUtil::Exception

with ExceptionEnum::ProjectInvalidContext if the path specified is invalid.

bool dtDAL::Project::IsContextValid

(

)

const [inline]

Returns:

true if the context is valid.

void dtDAL::Project::SetContext	(	const std::string &	path,
		bool	openReadOnly = false
	)

Assigns the context for the project.

If it is not opened read only, the code will attempt to make the path into a project. It no longer creates a context if it does not exist.

See also:

CreateContext

Parameters:

	path	the file path of to the project
	openReadOnly	optional parameter that defaults to false. If true, the class will not attempt to modify the project directory.

Exceptions:

ExceptionEnum::ProjectInvalidContext

if the path specified is invalid.

const std::string& dtDAL::Project::GetContext

(

)

const [inline]

Returns:

the current context.

This will be empty if no valid context is set.

void dtDAL::Project::Refresh

(

)

In the process of opening and using a project, lists of resources, maps, etc, are created This will clear or otherwise reload these cached lists so that any changes made to the project by hand will be picked up.

const std::set< std::string > & dtDAL::Project::GetMapNames

(

)

Returns:

a vector with the names of the maps currently in the project.

Exceptions:

ExceptionEnum::ProjectInvalidContext

if the context is not set.

Map & dtDAL::Project::GetMap

(

const std::string &

name

)

returns the map with the given name.

Parameters:

name

the name of the map as specified by the getMapNames() vector.

Returns:

the opened map

Exceptions:

	ExceptionEnum::MapLoadParsingError	if an error occurs reading the map file.
	FileExceptionEnum::FileNotFound	if the map does not exist.
	ExceptionEnum::ProjectInvalidContext	if the context is not set.

Map & dtDAL::Project::OpenMapBackup

(

const std::string &

name

)

returns the last backup save of the map with the given name.

Note:

if no backup is found, this call will NOT open the saved map, it will throw a file not found exception.

Parameters:

name

the name of the map as specified by the getMapNames() vector.

Returns:

the opened map

Exceptions:

	ExceptionEnum::MapLoadParsingError	if an error occurs reading the map file.
	FileExceptionEnum::FileNotFound	if a backup does not exist.
	ExceptionEnum::ProjectInvalidContext	if the context is not set.

Map & dtDAL::Project::LoadMapIntoScene	(	const std::string &	name,
		dtCore::Scene &	scene,
		bool	addBillBoards = false,
		bool	enablePaging = true
	)

Loads a map by name into an application.

If the map is already opened, the currently loaded map will be reused.

Parameters:

	name	The name of the map to load.
	scene	The application to add the proxy objects to.
	addBillBoards	pass true to add the billboards for any proxies that have the drawmode set to add the billboards.
	enablePaging	pass true to enable paging in the scene

Returns:

the map that was loaded into the scene.

Exceptions:

	ExceptionEnum::MapLoadParsingError	if an error occurs reading the map file.
	FileExceptionEnum::FileNotFound	if the map does not exist.
	ExceptionEnum::ProjectInvalidContext	if the context is not set.

void dtDAL::Project::LoadMapIntoScene	(	Map &	map,
		dtCore::Scene &	scene,
		bool	addBillBoards = false,
		bool	enablePaging = true
	)

Loads a map into a scene.

Parameters:

	map	The map to load into the scene
	scene	the scene to load the map into
	addBillBoards	pass true to add the billboards for any proxies that have the drawmode set to add the billboards.
	enablePaging	pass true to enable paging in the scene

Exceptions:

ExceptionEnum::ProjectInvalidContext

if the context is not set.

Map & dtDAL::Project::CreateMap	(	const std::string &	name,
		const std::string &	fileName
	)

Creates a new map and saves it.

Parameters:

	name	The name of the map.
	fileName	the name of the map file.

Returns:

The new map.

Exceptions:

	ExceptionEnum::ProjectInvalidContext	if the context is not set.
	ExceptionEnum::ProjectReadOnly	if the project is read only.
	ExceptionEnum::ProjectException	if a map by that name or fileName already exists.
	ExceptionEnum::MapSaveError	if the new map could not be saved.

void dtDAL::Project::CloseMap	(	Map &	map,
		bool	unloadLibraries = false
	)

Closes the map passed in.

The map will likely be freed when this method exits.

Note:

if you tell this call to unloadLibraries, be certain you have cleared all of the proxies in this map from your scene and deleted any memory that may have been allocated by the map or you can end up in a bad state.

Parameters:

	map	the map the close.
	unloadLibraries	unload all libraries not used by other open maps. This is dangerous.

Exceptions:

ExceptionEnum::ProjectInvalidContext

if the context is not set.

void dtDAL::Project::CloseAllMaps

(

bool

unloadLibraries = false

)

Closes all open maps.

Note:

if you tell this call to unloadLibraries, be certain you have cleared all of the proxies in these maps from your scene and deleted any memory that may have been allocated by the maps or you can end up in a bad state.

Parameters:

unloadLibraries

unload all libraries not used by other open maps. This is dangerous.

Exceptions:

ExceptionEnum::ProjectInvalidContext

if the context is not set.

void dtDAL::Project::DeleteMap	(	Map &	map,
		bool	unloadLibraries = false
	)

Deletes the given map.

Note:

if you tell this call to unloadLibraries, be certain you have cleared all of the proxies in this map from your scene and deleted any memory that may may have been allocated by the map or you can end up in a bad state.

Parameters:

	map	the map the delete.
	unloadLibraries	unload all libraries not used by other open maps. This is dangerous.

Exceptions:

	ExceptionEnum::ProjectInvalidContext	if the context is not set.
	ExceptionEnum::ProjectReadOnly	if the context is read only.

void dtDAL::Project::DeleteMap	(	const std::string &	mapName,
		bool	unloadLibraries = false
	)

Deletes the given map.

Note:

if you tell this call to unloadLibraries, be certain you have cleared all of the proxies in this map from your scene and deleted any memory that may may have been allocated by the map or you can end up in a bad state.

Parameters:

	mapName	the name of the map to delete.
	unloadLibraries	unload all libraries not used by other open maps. This is dangerous.

Exceptions:

	ExceptionEnum::ProjectInvalidContext	if the context is not set.
	ExceptionEnum::ProjectReadOnly	if the context is read only.

void dtDAL::Project::SaveMap	(	Map &	map,
		dtCore::Scene *	pScene = NULL
	)

Saves the given map whether it has changed or not.

Parameters:

	map	the map to save.
	scene	map is being saved as, if no scene is present use NULL

Exceptions:

	ExceptionEnum::ProjectException	if you change the name to match another map.
	ExceptionEnum::ProjectInvalidContext	if the context is not set or the Map is not part of the project.
	ExceptionEnum::ProjectReadOnly	if the context is read only.
	ExceptionEnum::MapSaveError	if the new map could not be saved.

void dtDAL::Project::SaveMapAs	(	Map &	map,
		const std::string &	newName,
		const std::string &	newFileName,
		dtCore::Scene *	pScene = NULL
	)

Saves the given map to a new file name and alters the open map object to point to the new file.

There will then be no open copy of the old map file name.

Parameters:

	map	the map to save.
	scene	map is being saved as, if no scene is present use NULL
	newName	the new name of the map to save.
	newFileName	the new file name of the map to save.

Exceptions:

	ExceptionEnum::ProjectException	if a map by that name or fileName already exists.
	ExceptionEnum::ProjectInvalidContext	if the context is not set or the Map is not part of the project.
	ExceptionEnum::ProjectReadOnly	if the context is read only.
	ExceptionEnum::MapSaveError	if the new map could not be saved.

void dtDAL::Project::SaveMapAs	(	const std::string &	mapName,
		const std::string &	newName,
		const std::string &	newFileNam,
		dtCore::Scene *	pScene = NULL
	)

Saves the given map to a new file name and alters the open map object to point to the new file.

There will then be no open copy of the old map file name. Keep in mind that if the map name given is not loaded, this call will actually open the map before saving it.

Parameters:

	map	the current map name.
	scene	map is being saved as, if no scene is present use NULL
	newName	the new name of the map to save.
	newFileName	the new file name of the map to save.

Exceptions:

	ExceptionEnum::ProjectException	if a map by that name or fileName already exists.
	ExceptionEnum::ProjectInvalidContext	if the context is not set or the Map is not part of the project.
	ExceptionEnum::ProjectReadOnly	if the context is read only.
	ExceptionEnum::MapSaveError	if the new map could not be saved.

void dtDAL::Project::SaveMap	(	const std::string &	mapName,
		dtCore::Scene *	pScene = NULL
	)

Saves the given map whether it has changed or not.

If the map has not been loaded, but exists, this call is a NOOP.

Parameters:

	map	the map to save.
	scene	map is being saved as, if no scene is present use NULL

Exceptions:

	ExceptionEnum::ProjectInvalidContext	if the context is not set.
	ExceptionEnum::ProjectReadOnly	if the context is read only.
	ExceptionEnum::MapSaveError	if the new map could not be saved.

void dtDAL::Project::SaveMapBackup

(

Map &

map

)

Saves a new backup of the map.

Parameters:

map

the map to save a backup of.

Exceptions:

	ExceptionEnum::ProjectInvalidContext	if the context is not set.
	ExceptionEnum::ProjectReadOnly	if the context is read only.
	ExceptionEnum::MapSaveError	if the new map could not be saved.

bool dtDAL::Project::HasBackup

(

Map &

map

)

const

Parameters:

map

the map to get the backups count for.

Returns:

the number of backup files this map has currently

bool dtDAL::Project::HasBackup

(

const std::string &

mapName

)

const

Parameters:

mapName

the name map to get the backups count for.

Returns:

the number of backup files this map has currently

void dtDAL::Project::ClearBackup

(

Map &

map

)

Clears the backup save for a give map.

Parameters:

map

the map to clear the backups for.

void dtDAL::Project::ClearBackup

(

const std::string &

mapName

)

Clears the backup save for a given map.

Parameters:

mapName

the name of the map to clear the backups for.

Map * dtDAL::Project::GetMapForActorProxy

(

const ActorProxy &

proxy

)

This will search all open maps until is finds the one that contains the given proxy.

Returns:

the map that contains a given actor proxy or NULL if it's not found.

Parameters:

proxy

the proxy to search for.

const Map * dtDAL::Project::GetMapForActorProxy

(

const ActorProxy &

proxy

)

const

This will search all open maps until is finds the one that contains the given proxy.

Returns:

the map that contains a given actor proxy or NULL if it's not found.

Parameters:

proxy

the proxy to search for.

void dtDAL::Project::GetHandlersForDataType	(	const DataType &	resourceType,
		std::vector< const ResourceTypeHandler * > &	toFill
	)			const

Parameters:

resourceType

the type of resource.

The datatype passed in MUST be a resource type.

Parameters:

toFill

the vector to fill with the handlers.

Returns:

The resource types that are available for the given handler.

Exceptions:

ExceptionEnum::ProjectResourceError

if the datatype is a primitive type, not a resource type.

void dtDAL::Project::RegisterResourceTypeHander

(

ResourceTypeHandler &

handler

)

Registers a new type handler.

The method will get the datatype and applicable filters from the handler itself.

Parameters:

handler

The resource type handler to register.

Exceptions:

ExceptionEnum::ProjectResourceError

if the datatype of the handler is a primitive type, not a resource type.

const std::string dtDAL::Project::GetResourcePath

(

const ResourceDescriptor &

resource

)

const

This will take the resource descriptor object and return a path to the resource within the project.

The first time this is called, an index of the resources may need to be created internally to validate the string, so it may take some time to return.

Parameters:

resource

The representation of a resource.

Returns:

The path to load a resource.

Exceptions:

	ExceptionEnum::ProjectInvalidContext	if the context is not set.
	ExceptionEnum::ProjectResourceError	if the string representation is invalid.
	FileExceptionEnum::FileNotFound	if the file was not found.

const ResourceDescriptor dtDAL::Project::AddResource	(	const std::string &	newName,
		const std::string &	pathToFile,
		const std::string &	category,
		const DataType &	type
	)

Adds a resource to the project by copying it into the project.

Parameters:

	newName	the new name of the resource.
	pathToFile	The path to the file to copy into the project.
	category	The category of the resource file as a dot-notation string.
	type	the resounce datatype of the resource. This must be one of the enums that define a resource.

Returns:

the resource's unique identifier string.

Exceptions:

	ExceptionEnum::ProjectInvalidContext	if the context is not set.
	FileExceptionEnum::IOException	if the could not complete because of some sort of IO exception.
	ExceptionEnum::ProjectReadOnly	if the project is read only.
	FileExceptionEnum::FileNotFound	if the file to import does not exist.
	ExceptionEnum::ProjectResourceError	if the file could not be imported if the Datatype is not a resource type.

void dtDAL::Project::RemoveResource

(

const ResourceDescriptor &

resource

)

Removes a resource from a project.

This will delete the file if it exists. If no such resource exists, the call will be a noop. This call is not guaranteed to check all actors to make sure the resource is not in use.

Parameters:

resource

The resource descriptor object.

Exceptions:

	ExceptionEnum::ProjectInvalidContext	if the context is not set.
	ExceptionEnum::ProjectReadOnly	if the project is read only.
	FileExceptionEnum::IOException	if the could not complete because of some sort of IO exception.
	ExceptionEnum::ProjectResourceError	if the resource could not be removed for reasons other than file io.

void dtDAL::Project::CreateResourceCategory	(	const std::string &	category,
		const DataType &	type
	)

Creates a new resource category.

Note:

if the category already exists, this will be a no-op.

Parameters:

	category	the category to create.
	type	the data type to add the category into.

Exceptions:

	ExceptionEnum::ProjectInvalidContext	if the context is not set.
	ExceptionEnum::ProjectReadOnly	if the project is read only.
	FileExceptionEnum::IOException	if the operation could not complete because of some sort of IO exception.
	ExceptionEnum::ProjectResourceError	if type is not a resource type.

bool dtDAL::Project::RemoveResourceCategory	(	const std::string &	category,
		const DataType &	type,
		bool	recursive
	)

Removes a category.

Parameters:

	category	The category to remove.
	type	The datatype the category is in.
	recursive	true to recursively delete the category and all subcategories and resources.

Returns:

true if the category was removed, or didn't exist. false if the category could not be removed because recursive was false and the category was not empty.

Exceptions:

	ExceptionEnum::ProjectInvalidContext	if the context is not set.
	ExceptionEnum::ProjectReadOnly	if the project is read only.
	FileExceptionEnum::IOException	if the operation could not complete because of some sort of IO exception.
	ExceptionEnum::ProjectResourceError	if the resource could not be removed for reasons other than file io.
	FileExceptionEnum::FileNotFound	on rare occasion, this could possibly be thrown if the file contents are changed while the recusive delete is occuring.

const dtUtil::tree<ResourceTreeNode>& dtDAL::Project::GetAllResources

(

)

const [inline]

Note:

This tree will likely be cached.

See the Project::refresh() method.

See also:

Project::refresh

Returns:

all of the resources known to the project.

void dtDAL::Project::GetResourcesOfType	(	const DataType &	type,
		dtUtil::tree< ResourceTreeNode > &	toFill
	)			const

Note:

The data will likely be cached.

See the Project::refresh() method.

See also:

Project::refresh

Parameters:

toFill

The tree to fill with the results.

Returns:

all of the resources known to the project of the given type.

bool dtDAL::Project::IsArchive

(

)

const

Returns:

true if the current project context is stored in an archive.

Exceptions:

ExceptionEnum::ProjectInvalidContext

if the context is not set.

bool dtDAL::Project::IsReadOnly

(

)

const

Returns:

true if the current project is opened readonly.

Exceptions:

ExceptionEnum::ProjectInvalidContext

if the context is not set.

void dtDAL::Project::SetEditMode

(

bool

pInStage

)

This flag will alert actors whether or not there proxy is being loaded into STAGE as a note this should only be set from dtEditQt namespace potential refactor would be to ensure only dtEditQt could set it another implementation would be to have a project state which could control whether we are editing or not if need be we can add a getter for this.

const bool dtDAL::Project::GetEditMode

(

)

const [inline]

Returns if Project is being executed from STAGE.

Returns:

mIsInSTAGE

Note:

NO USER SHOULD CALL THIS FUNCTION, EVER. If you want to find out if you are running from STAGE, please use dtDAL::ActorProxy::IsInSTAGE();

See also:

class dtDAL::ActorProxy

---