Manages the master list of projects known to the engine. More...

#include <tracktion_ProjectManager.h>

Classes
struct	TempProject
	Helper struct that creates a temporary project (won't be persisted in the list). More...

Public Member Functions
	ProjectManager (Engine &)
	Constructor — takes the Engine instance this manager belongs to.

	~ProjectManager ()
	Destructor — clears the folder tree and asserts that no projects remain open.

void	initialise ()
	Loads the persisted project list and imports example projects on first run.

Project::Ptr	addProjectToList (const juce::File &projectFile, bool shouldSaveList, juce::ValueTree folderToAddTo, int insertIndex=-1)
	Adds a project file or folder to the list under the given folder node.

void	removeProjectFromList (const juce::File &)
	Removes the project for the given file from the list.

void	clearProjects ()
	Removes all projects from the list and clears the open-project array.

juce::ValueTree	getActiveProjectsFolder ()
	Returns the "Active Projects" ValueTree folder.

juce::ValueTree	getLibraryProjectsFolder ()
	Returns the "Library Projects" ValueTree folder.

Project::Ptr	getProjectFrom (const juce::ValueTree &, bool createIfNotFound=true)
	Returns the Project object cached in a PROJECT ValueTree node.

Project::Ptr	getProject (ProjectID projectID)
	Looks up a project by its ID.

Project::Ptr	getProject (const juce::File &)
	Looks up a project by its file or folder path.

juce::ReferenceCountedArray< Project >	getAllProjects ()
	Returns every project in the entire folder tree.

juce::ReferenceCountedArray< Project >	getAllProjects (const juce::ValueTree &folder)
	Returns every project under the given folder subtree.

void	unpackArchiveAndAddToList (const juce::File &archiveFile, const juce::File &destDir, juce::ValueTree folder)
	Extracts a .trkx archive into destDir and adds any contained projects to the list.

ProjectItem::Ptr	getProjectItem (const ProjectItemRef &)
	Finds the project containing the given ref and returns the matching ProjectItem.

ProjectItem::Ptr	getProjectItem (ProjectItemID)
	Finds the project containing the given item ID and returns the matching ProjectItem.

ProjectItem::Ptr	getProjectItem (const Edit &)
	Returns the ProjectItem for the given Edit's project item ID.

Project::Ptr	getProject (const Edit &)
	Returns the Project that owns the given Edit (may return nullptr).

juce::File	findSourceFile (const ProjectItemRef &)
	Returns the source file for the given project item ref.

juce::File	findSourceFile (ProjectItemID)
	Returns the source file for the given project item ID.

ProjectItem::Ptr	getProjectItem (juce::File)
	Returns the ProjectItem for the a given file.

void	saveAllProjects ()
	Saves every project in the folder tree.

juce::StringArray	getRecentProjects (bool printableFormat)
	Returns a list of recently-opened project files not currently in the list.

void	addFileToRecentProjectsList (const juce::File &)
	Adds a file to the recent-projects list if it isn't already tracked.

juce::ValueTree	findFolderContaining (const Project &) const
	Returns the parent ValueTree folder node containing the given project.

juce::ValueTree	findFolderContaining (ProjectID projectId) const
	Returns the parent ValueTree folder node containing the project with the given ID.

juce::ValueTree	getFolderItemFor (const Project &) const
	Returns the PROJECT ValueTree node for the given project.

int	getFolderIndexFor (const Project &) const
	Returns the index of the project within its parent folder, or -1 if not found.

void	createNewProjectFolder (juce::ValueTree parent, const juce::String &name)
	Creates a new organisational sub-folder inside the given parent and saves the list.

void	deleteProjectFolder (juce::ValueTree folder)
	Removes a folder node from the tree.

void	updateProjectFile (Project &p, const juce::File &)
	Updates the file path stored in the ValueTree for the given project.

Project::Ptr	createNewProject (const juce::File &projectFile)
	Creates a new Project object for the given file or folder.

Project::Ptr	createNewProject (const juce::File &projectFile, juce::ValueTree folderToAddTo, ProjectType projectType)
	Creates a project with a new ID, a default edit, and adds it to the list.

void	createNewProjectInteractively (const juce::String &suggestedName, const juce::File &lastPath, juce::ValueTree folderToAddTo, ProjectType projectType, std::function< void(Project::Ptr)> callback)
	Shows UI dialogs to let the user create a project in a chosen location.

Project::Ptr	createNewProjectFromTemplate (const juce::String &suggestedName, const juce::File &lastPath, const juce::File &templateArchiveFile, juce::ValueTree folderToAddTo, ProjectType projectType)
	Extracts a template archive, remaps IDs, and adds the resulting project to the list.

Project::Ptr	findProjectWithId (const juce::ValueTree &folder, ProjectID pid)
	Recursively searches a folder subtree for a project matching the given ID.

Project::Ptr	findProjectWithFile (const juce::ValueTree &folder, const juce::File &)
	Recursively searches a folder subtree for a project matching the given file path.

void	loadList ()
	Loads the project list from persistent storage.

void	saveList ()
	Saves the project list to persistent storage.

Public Attributes
Engine &	engine
	The Engine instance this manager belongs to.

juce::ValueTree	folders
	The root ValueTree holding the entire project folder hierarchy.

Detailed Description

Manages the master list of projects known to the engine.

ProjectManager owns a ValueTree folder hierarchy that organises projects into "Active Projects" and "Library Projects" folders (plus user-created sub-folders). It provides APIs for looking up, creating, adding, removing, and persisting projects, as well as archive import/export.

The folder hierarchy is saved to persistent storage via the Engine's PropertyStorage.

See also: Project, ProjectItem

Constructor & Destructor Documentation

◆ ProjectManager()

engine::ProjectManager::ProjectManager ( Engine & )

Constructor — takes the Engine instance this manager belongs to.

◆ ~ProjectManager()

engine::ProjectManager::~ProjectManager ( )

Destructor — clears the folder tree and asserts that no projects remain open.

Member Function Documentation

◆ initialise()

void engine::ProjectManager::initialise ( )

Loads the persisted project list and imports example projects on first run.

◆ addProjectToList()

Project::Ptr engine::ProjectManager::addProjectToList	(	const juce::File &	projectFile,
		bool	shouldSaveList,
		juce::ValueTree	folderToAddTo,
		int	insertIndex = `-1`
	)

Adds a project file or folder to the list under the given folder node.

Deduplicates by file path and (for non-zero IDs) by project ID. Returns the Project, or nullptr if the file is not a valid project.

Parameters

projectFile	The .tracktion file or project folder to add.
shouldSaveList	If true, saves the project list after adding.
folderToAddTo	The ValueTree folder node to insert into.
insertIndex	Position within the folder (-1 to append).

◆ removeProjectFromList()

void engine::ProjectManager::removeProjectFromList ( const juce::File & )

Removes the project for the given file from the list.

Closes any edits belonging to the project and adds the file to the recent-projects list.

◆ clearProjects()

void engine::ProjectManager::clearProjects ( )

Removes all projects from the list and clears the open-project array.

◆ getActiveProjectsFolder()

juce::ValueTree engine::ProjectManager::getActiveProjectsFolder ( )

Returns the "Active Projects" ValueTree folder.

◆ getLibraryProjectsFolder()

juce::ValueTree engine::ProjectManager::getLibraryProjectsFolder ( )

Returns the "Library Projects" ValueTree folder.

◆ getProjectFrom()

Project::Ptr engine::ProjectManager::getProjectFrom	(	const juce::ValueTree &	,
		bool	createIfNotFound = `true`
	)

Returns the Project object cached in a PROJECT ValueTree node.

If createIfNotFound is true and the node represents a valid project file on disk, the project is opened and cached in the tree.

◆ getProject() [1/3]

Project::Ptr engine::ProjectManager::getProject ( ProjectID projectID )

Looks up a project by its ID.

Checks open projects first, then searches the entire folder tree.

◆ getProject() [2/3]

Project::Ptr engine::ProjectManager::getProject ( const juce::File & )

Looks up a project by its file or folder path.

Checks open projects first, then searches the entire folder tree.

◆ getAllProjects() [1/2]

juce::ReferenceCountedArray< Project > engine::ProjectManager::getAllProjects ( )

Returns every project in the entire folder tree.

◆ getAllProjects() [2/2]

juce::ReferenceCountedArray< Project > engine::ProjectManager::getAllProjects ( const juce::ValueTree & folder )

Returns every project under the given folder subtree.

◆ unpackArchiveAndAddToList()

void engine::ProjectManager::unpackArchiveAndAddToList	(	const juce::File &	archiveFile,
		const juce::File &	destDir,
		juce::ValueTree	folder
	)

Extracts a .trkx archive into destDir and adds any contained projects to the list.

◆ getProjectItem() [1/4]

ProjectItem::Ptr engine::ProjectManager::getProjectItem ( const ProjectItemRef & )

Finds the project containing the given ref and returns the matching ProjectItem.

◆ getProjectItem() [2/4]

ProjectItem::Ptr engine::ProjectManager::getProjectItem ( ProjectItemID )

Finds the project containing the given item ID and returns the matching ProjectItem.

Prefer the ProjectItemRef overload for new code.

◆ getProjectItem() [3/4]

ProjectItem::Ptr engine::ProjectManager::getProjectItem ( const Edit & )

Returns the ProjectItem for the given Edit's project item ID.

◆ getProject() [3/3]

Project::Ptr engine::ProjectManager::getProject ( const Edit & )

Returns the Project that owns the given Edit (may return nullptr).

◆ findSourceFile() [1/2]

juce::File engine::ProjectManager::findSourceFile ( const ProjectItemRef & )

Returns the source file for the given project item ref.

◆ findSourceFile() [2/2]

juce::File engine::ProjectManager::findSourceFile ( ProjectItemID )

Returns the source file for the given project item ID.

Prefer the ProjectItemRef overload for new code.

◆ getProjectItem() [4/4]

ProjectItem::Ptr engine::ProjectManager::getProjectItem ( juce::File )

Returns the ProjectItem for the a given file.

◆ saveAllProjects()

void engine::ProjectManager::saveAllProjects ( )

Saves every project in the folder tree.

◆ getRecentProjects()

juce::StringArray engine::ProjectManager::getRecentProjects ( bool printableFormat )

Returns a list of recently-opened project files not currently in the list.

Parameters

printableFormat If true, returns display names instead of full paths.

◆ addFileToRecentProjectsList()

void engine::ProjectManager::addFileToRecentProjectsList ( const juce::File & )

Adds a file to the recent-projects list if it isn't already tracked.

◆ findFolderContaining() [1/2]

juce::ValueTree engine::ProjectManager::findFolderContaining ( const Project & ) const

Returns the parent ValueTree folder node containing the given project.

◆ findFolderContaining() [2/2]

juce::ValueTree engine::ProjectManager::findFolderContaining ( ProjectID projectId ) const

Returns the parent ValueTree folder node containing the project with the given ID.

◆ getFolderItemFor()

juce::ValueTree engine::ProjectManager::getFolderItemFor ( const Project & ) const

Returns the PROJECT ValueTree node for the given project.

◆ getFolderIndexFor()

int engine::ProjectManager::getFolderIndexFor ( const Project & ) const

Returns the index of the project within its parent folder, or -1 if not found.

◆ createNewProjectFolder()

void engine::ProjectManager::createNewProjectFolder	(	juce::ValueTree	parent,
		const juce::String &	name
	)

Creates a new organisational sub-folder inside the given parent and saves the list.

◆ deleteProjectFolder()

void engine::ProjectManager::deleteProjectFolder ( juce::ValueTree folder )

Removes a folder node from the tree.

◆ updateProjectFile()

void engine::ProjectManager::updateProjectFile	(	Project &	p,
		const juce::File &
	)

Updates the file path stored in the ValueTree for the given project.

◆ createNewProject() [1/2]

Project::Ptr engine::ProjectManager::createNewProject ( const juce::File & projectFile )

Creates a new Project object for the given file or folder.

This is a low-level method — the project is not added to the list.

Referenced by engine::ProjectManager::TempProject::TempProject().

◆ createNewProject() [2/2]

Project::Ptr engine::ProjectManager::createNewProject	(	const juce::File &	projectFile,
		juce::ValueTree	folderToAddTo,
		ProjectType	projectType
	)

Creates a project with a new ID, a default edit, and adds it to the list.

Also creates default media folders and refreshes the folder structure. N.B. the backend is determined by whether projectFile is a directory on disk, so for ProjectType::folderBased the caller must create the directory first. projectFile is asserted to match the given ProjectType.

◆ createNewProjectInteractively()

void engine::ProjectManager::createNewProjectInteractively	(	const juce::String &	suggestedName,
		const juce::File &	lastPath,
		juce::ValueTree	folderToAddTo,
		ProjectType	projectType,
		std::function< void(Project::Ptr)>	callback
	)

Shows UI dialogs to let the user create a project in a chosen location.

Handles directory creation, non-empty directory warnings, and naming.

◆ createNewProjectFromTemplate()

Project::Ptr engine::ProjectManager::createNewProjectFromTemplate	(	const juce::String &	suggestedName,
		const juce::File &	lastPath,
		const juce::File &	templateArchiveFile,
		juce::ValueTree	folderToAddTo,
		ProjectType	projectType
	)

Extracts a template archive, remaps IDs, and adds the resulting project to the list.

◆ findProjectWithId()

Project::Ptr engine::ProjectManager::findProjectWithId	(	const juce::ValueTree &	folder,
		ProjectID	pid
	)

Recursively searches a folder subtree for a project matching the given ID.

◆ findProjectWithFile()

Project::Ptr engine::ProjectManager::findProjectWithFile	(	const juce::ValueTree &	folder,
		const juce::File &
	)

Recursively searches a folder subtree for a project matching the given file path.

◆ loadList()

void engine::ProjectManager::loadList ( )

Loads the project list from persistent storage.

◆ saveList()

void engine::ProjectManager::saveList ( )

Saves the project list to persistent storage.

Member Data Documentation

◆ engine

Engine& engine::ProjectManager::engine

The Engine instance this manager belongs to.

◆ folders

juce::ValueTree engine::ProjectManager::folders

The root ValueTree holding the entire project folder hierarchy.

The documentation for this class was generated from the following file:

tracktion_ProjectManager.h

Classes

Public Member Functions

Public Attributes