A tracktion project. More...

#include <tracktion_Project.h>

Inheritance diagram for engine::Project:

Public Types
enum	NagMode { nagAsk , nagAutoYes , nagAutoNo }
	General enum for requests that have a project setting and so can return true without asking the user. More...

enum	ProjectSortType { SortByName , SortByDesc , SortByType , SortByLength , SortBySize , SortByModified , SortByCreated }

using	ReloadMode = ProjectBase::ReloadMode
	Controls when reload() actually re-reads the backing store.

using	Ptr = juce::ReferenceCountedObjectPtr< Project >

Public Types inherited from engine::Selectable
using	WeakRef = juce::WeakReference< Selectable >

Public Member Functions
	~Project () override

bool	save ()
	Saves the project if changes have been made since the last save.

void	handleAsyncUpdate () override

bool	isValid () const
	Returns true if the project is valid.

bool	isReadOnly () const
	Returns true if the project file or folder is read-only.

bool	isTemporary () const
	Returns true if this is a temporary project (won't appear in recent projects).

void	setTemporary (bool)
	Marks this project as temporary (won't appear in recent projects).

ProjectID	getProjectID () const
	Returns the project ID.

juce::String	getName () const
	Returns the project name.

juce::String	getDescription () const
	Returns the project description string.

bool	isFolderBased () const
	Returns true if this is a folder-based project (as opposed to file-based).

const juce::File &	getProjectFile () const noexcept
	Returns the project file (.tracktion) or, for folder-based projects, the folder itself.

juce::File	getDefaultDirectory () const
	Returns the default directory for storing project media.

juce::File	getDirectoryForMedia (ProjectItem::Category category) const
	Returns the subdirectory for media of the given category (e.g.

juce::String	getSourcePathForFile (const juce::File &file) const
	Returns the appropriate source path string for referencing the given file.

void	setName (const juce::String &newName)
	Renames the project.

void	setDescription (const juce::String &newDesc)
	Sets the project description.

void	createNewProjectId ()
	Generates and assigns a new random project ID.

juce::String	getProjectProperty (const juce::String &name) const
	Returns a named project property.

void	setProjectProperty (const juce::String &name, const juce::String &value)
	Sets a named project property.

void	refreshProjectPropertiesFromFile ()
	Reloads project properties from the project file (or project_info.json).

bool	isLibraryProject () const
	Returns true if this project is flagged as a library project (a shared sound/media library).

juce::Array< ProjectItemRef >	findOrphanItemRefs ()
	Returns refs to items whose source files are not referenced by any edit.

juce::Array< ProjectItem::Ptr >	findOrphanItems ()

int	getNumProjectItems ()
	Returns the number of items in this project.

ProjectItemRef	getProjectItemRef (int index)
	Returns a ProjectItemRef at the given index.

juce::Array< ProjectItemRef >	getAllProjectItemRefs () const
	Returns all ProjectItemRefs in this project.

ProjectItem::Ptr	getProjectItemAt (int index)
	Returns the ProjectItem at the given index, or nullptr if out of range.

juce::Array< ProjectItem::Ptr >	getAllProjectItems ()
	Returns all ProjectItems in this project.

int	getIndexOf (const ProjectItemRef &) const
	Returns the index of the item with the given ref, or -1 if not found.

ProjectItem::Ptr	getProjectItemFor (const ProjectItemRef &)
	Returns the ProjectItem for the given ref, or nullptr if not found.

ProjectItem::Ptr	getProjectItemForFile (const juce::File &file)
	Returns the ProjectItem that references the given file, or nullptr if not found.

ProjectItem::Ptr	createNewItem (const juce::File &fileToReference, const juce::String &type, const juce::String &name, const juce::String &description, const ProjectItem::Category cat, bool atTopOfList)
	Returns an existing ProjectItem for the file if one exists, otherwise creates a new one with the given name, type, description, and category.

bool	removeProjectItem (const ProjectItemRef &, bool deleteSourceMaterial)
	Removes the item matching the given ref.

void	moveProjectItem (int indexToMoveFrom, int indexToMoveTo)
	Moves a project item from one index to another.

ProjectItem::Ptr	createNewEdit ()
	Creates a new empty .tracktionedit file and adds it as a ProjectItem.

void	redirectIDsFromProject (ProjectID oldProjId, ProjectID newProjId)
	Tells all exportables in all edits to remap references from oldProjId to newProjId.

void	mergeArchiveContents (const juce::File &archiveFile)
	Imports items from a .tracktion archive file into this project.

void	mergeOtherProjectIntoThis (const juce::File &otherProject)
	Merges all items from another project file into this project.

void	refreshFolderStructure ()
	Makes sure all media files are in the correct category subfolders.

void	createDefaultFolders ()
	Creates the default media subdirectories (e.g.

juce::String	getSelectableDescription () override
	Subclasses must return a description of what they are.

void	lockFile ()
	Locks the project file to prevent writes or moves.

void	unlockFile ()
	Unlocks the project file.

void	sourceFileMoved (const juce::File &oldFile, const juce::File &newFile)
	Updates all edit source references after a file has been moved/renamed.

void	reload (ReloadMode=ReloadMode::lazy)
	Invalidates any cached project item list so the next call to getAllProjectItems() re-reads the backing store.

void	setNewProjectId (ProjectID)

Public Member Functions inherited from engine::Selectable
	Selectable ()

virtual	~Selectable ()

virtual void	selectionStatusChanged (bool isNowSelected)
	Can be overridden to tell this object that it has just been selected or deselected.

virtual void	selectableAboutToBeDeleted ()
	Called just before the selectable is about to be deleted so any subclasses should still be valid at this point.

void	addListener (SelectableListener *)

void	removeListener (SelectableListener *)

void	addSelectableListener (SelectableListener *)

void	removeSelectableListener (SelectableListener *)

void	cancelAnyPendingUpdates ()
	If changed() has been called, this will cancel any pending async change notificaions.

void	deselect ()

void	propertiesChanged ()

void	notifyListenersOfDeletion ()

WeakRef	getWeakRef ()

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

ProjectManager &	projectManager
	The ProjectManager that owns this project.

Public Attributes inherited from engine::Selectable
WeakRef::Master	masterReference

Additional Inherited Members
Static Public Member Functions inherited from engine::Selectable
static void	initialise ()

static bool	isSelectableValid (const Selectable *) noexcept
	checks whether this object has been deleted.

Detailed Description

A tracktion project.

A Project wraps either a .tracktion project file (FileBasedProject) or a project folder (FolderBasedProject). The backend is chosen automatically based on whether the path passed to ProjectManager is a file or directory.

File-based projects** persist their state in a binary .tracktion file. Items have valid ProjectItemIDs and support full ID-based lookup, search, reordering, and merging.

Folder-based projects** discover items by lazily scanning the folder on disk. Items have invalid (zero) ProjectItemIDs, so ID-based lookup always returns nullptr. Operations that rely on IDs or binary state (merge, reorder) are no-ops for folder-based projects; properties and descriptions are stored in a project_info.json file inside the folder.

The per-method docs below note where behaviour differs between backends.

Source references in edits:** Clips in an Edit reference their audio source via a string stored in the source property. For file-based projects this is a ProjectItemID string (e.g. "1234_5678"). For folder-based projects this is a file path – relative to the project folder if the file lives inside it, or absolute otherwise. Use getSourcePathForFile() to obtain the correct string for a given file.

See also: ProjectManager, ProjectItem

Member Typedef Documentation

◆ ReloadMode

using engine::Project::ReloadMode = ProjectBase::ReloadMode

Controls when reload() actually re-reads the backing store.

See also: ProjectBase::ReloadMode

◆ Ptr

using engine::Project::Ptr = juce::ReferenceCountedObjectPtr<Project>

Member Enumeration Documentation

◆ NagMode

enum engine::Project::NagMode

General enum for requests that have a project setting and so can return true without asking the user.

Enumerator
nagAsk	Should ask user.
nagAutoYes	Should do task automatically.
nagAutoNo	Should not do task automatically.

◆ ProjectSortType

enum engine::Project::ProjectSortType

Enumerator
SortByName
SortByDesc
SortByType
SortByLength
SortBySize
SortByModified
SortByCreated

Constructor & Destructor Documentation

◆ ~Project()

engine::Project::~Project ( )

override

Member Function Documentation

◆ save()

bool engine::Project::save ( )

Saves the project if changes have been made since the last save.

Folder-based projects have no persistent state file, so this always returns true.

◆ handleAsyncUpdate()

void engine::Project::handleAsyncUpdate ( )

override

◆ isValid()

bool engine::Project::isValid ( ) const

Returns true if the project is valid.

File-based: checks that the project ID is non-zero. Folder-based: checks that the folder exists on disk.

◆ isReadOnly()

bool engine::Project::isReadOnly ( ) const

Returns true if the project file or folder is read-only.

◆ isTemporary()

bool engine::Project::isTemporary ( ) const

Returns true if this is a temporary project (won't appear in recent projects).

◆ setTemporary()

void engine::Project::setTemporary ( bool )

Marks this project as temporary (won't appear in recent projects).

◆ getProjectID()

ProjectID engine::Project::getProjectID ( ) const

Returns the project ID.

File-based: the persisted random ID. Folder-based: a hash of the folder path.

◆ getName()

juce::String engine::Project::getName ( ) const

Returns the project name.

Folder-based projects return the folder name.

◆ getDescription()

juce::String engine::Project::getDescription ( ) const

Returns the project description string.

Stored as a project property and works for both file-based and folder-based projects.

◆ isFolderBased()

bool engine::Project::isFolderBased ( ) const

Returns true if this is a folder-based project (as opposed to file-based).

◆ getProjectFile()

const juce::File & engine::Project::getProjectFile ( ) const

noexcept

Returns the project file (.tracktion) or, for folder-based projects, the folder itself.

◆ getDefaultDirectory()

juce::File engine::Project::getDefaultDirectory ( ) const

Returns the default directory for storing project media.

For folder-based projects this is the project folder itself.

◆ getDirectoryForMedia()

juce::File engine::Project::getDirectoryForMedia ( ProjectItem::Category category ) const

Returns the subdirectory for media of the given category (e.g.

"recorded", "rendered").

◆ getSourcePathForFile()

juce::String engine::Project::getSourcePathForFile ( const juce::File & file ) const

Returns the appropriate source path string for referencing the given file.

For folder-based projects, this returns a path relative to the project folder if the file is a child of it, or an absolute path otherwise. File-based projects should not use this method — they use ProjectItemIDs.

◆ setName()

void engine::Project::setName ( const juce::String & newName )

Renames the project.

This renames the underlying file or folder on disk.

◆ setDescription()

void engine::Project::setDescription ( const juce::String & newDesc )

Sets the project description.

Works for both file-based and folder-based projects.

◆ createNewProjectId()

void engine::Project::createNewProjectId ( )

Generates and assigns a new random project ID.

No-op for folder-based projects.

◆ getProjectProperty()

juce::String engine::Project::getProjectProperty ( const juce::String & name ) const

Returns a named project property.

Folder-based projects store properties in project_info.json.

◆ setProjectProperty()

void engine::Project::setProjectProperty	(	const juce::String &	name,
		const juce::String &	value
	)

Sets a named project property.

Folder-based projects store properties in project_info.json.

◆ refreshProjectPropertiesFromFile()

void engine::Project::refreshProjectPropertiesFromFile ( )

Reloads project properties from the project file (or project_info.json).

◆ isLibraryProject()

bool engine::Project::isLibraryProject ( ) const

Returns true if this project is flagged as a library project (a shared sound/media library).

◆ findOrphanItemRefs()

juce::Array< ProjectItemRef > engine::Project::findOrphanItemRefs ( )

Returns refs to items whose source files are not referenced by any edit.

Works for both file-based and folder-based projects.

◆ findOrphanItems()

juce::Array< ProjectItem::Ptr > engine::Project::findOrphanItems ( )

Deprecated:: Use findOrphanItemRefs() instead.

◆ getNumProjectItems()

int engine::Project::getNumProjectItems ( )

Returns the number of items in this project.

Folder-based projects lazily scan the folder on the first call.

◆ getProjectItemRef()

ProjectItemRef engine::Project::getProjectItemRef ( int index )

Returns a ProjectItemRef at the given index.

File-based projects return an ID-based ref, folder-based return a path-based ref.

◆ getAllProjectItemRefs()

juce::Array< ProjectItemRef > engine::Project::getAllProjectItemRefs ( ) const

Returns all ProjectItemRefs in this project.

Folder-based projects trigger the lazy folder scan and return path-based refs.

◆ getProjectItemAt()

ProjectItem::Ptr engine::Project::getProjectItemAt ( int index )

Returns the ProjectItem at the given index, or nullptr if out of range.

◆ getAllProjectItems()

juce::Array< ProjectItem::Ptr > engine::Project::getAllProjectItems ( )

Returns all ProjectItems in this project.

◆ getIndexOf()

int engine::Project::getIndexOf ( const ProjectItemRef & ) const

Returns the index of the item with the given ref, or -1 if not found.

◆ getProjectItemFor()

ProjectItem::Ptr engine::Project::getProjectItemFor ( const ProjectItemRef & )

Returns the ProjectItem for the given ref, or nullptr if not found.

For file-based projects, looks up by ID. For folder-based, resolves the path and looks up by file.

◆ getProjectItemForFile()

ProjectItem::Ptr engine::Project::getProjectItemForFile ( const juce::File & file )

Returns the ProjectItem that references the given file, or nullptr if not found.

Works for both file-based and folder-based projects.

◆ createNewItem()

ProjectItem::Ptr engine::Project::createNewItem	(	const juce::File &	fileToReference,
		const juce::String &	type,
		const juce::String &	name,
		const juce::String &	description,
		const ProjectItem::Category	cat,
		bool	atTopOfList
	)

Returns an existing ProjectItem for the file if one exists, otherwise creates a new one with the given name, type, description, and category.

Folder-based items are created with invalid ProjectItemIDs.

◆ removeProjectItem()

bool engine::Project::removeProjectItem	(	const ProjectItemRef &	,
		bool	deleteSourceMaterial
	)

Removes the item matching the given ref.

If deleteSourceMaterial is true, deletes the source file on disk. Works for both file-based and folder-based projects.

◆ moveProjectItem()

void engine::Project::moveProjectItem	(	int	indexToMoveFrom,
		int	indexToMoveTo
	)

Moves a project item from one index to another.

No-op for folder-based projects.

◆ createNewEdit()

ProjectItem::Ptr engine::Project::createNewEdit ( )

Creates a new empty .tracktionedit file and adds it as a ProjectItem.

Folder-based items are created with invalid ProjectItemIDs.

◆ redirectIDsFromProject()

void engine::Project::redirectIDsFromProject	(	ProjectID	oldProjId,
		ProjectID	newProjId
	)

Tells all exportables in all edits to remap references from oldProjId to newProjId.

No-op for folder-based projects.

◆ mergeArchiveContents()

void engine::Project::mergeArchiveContents ( const juce::File & archiveFile )

Imports items from a .tracktion archive file into this project.

No-op for folder-based projects.

◆ mergeOtherProjectIntoThis()

void engine::Project::mergeOtherProjectIntoThis ( const juce::File & otherProject )

Merges all items from another project file into this project.

No-op for folder-based projects.

◆ refreshFolderStructure()

void engine::Project::refreshFolderStructure ( )

Makes sure all media files are in the correct category subfolders.

No-op for folder-based projects.

◆ createDefaultFolders()

void engine::Project::createDefaultFolders ( )

Creates the default media subdirectories (e.g.

"recorded", "rendered") if they don't exist.

◆ getSelectableDescription()

juce::String engine::Project::getSelectableDescription ( )

overridevirtual

Subclasses must return a description of what they are.

Implements engine::Selectable.

◆ lockFile()

void engine::Project::lockFile ( )

Locks the project file to prevent writes or moves.

No-op for folder-based projects.

◆ unlockFile()

void engine::Project::unlockFile ( )

Unlocks the project file.

No-op for folder-based projects.

◆ sourceFileMoved()

void engine::Project::sourceFileMoved	(	const juce::File &	oldFile,
		const juce::File &	newFile
	)

Updates all edit source references after a file has been moved/renamed.

For folder-based projects, this walks all edits and calls reassignReferencedItem to update path-based source references. File-based projects are a no-op (IDs are stable).

◆ reload()

void engine::Project::reload ( ReloadMode = ReloadMode::lazy )

Invalidates any cached project item list so the next call to getAllProjectItems() re-reads the backing store.

For folder-based projects this clears the directory scan cache; for file-based projects this is a no-op.

◆ setNewProjectId()

void engine::Project::setNewProjectId ( ProjectID )

Member Data Documentation

◆ engine

Engine& engine::Project::engine

The Engine instance this project belongs to.

◆ projectManager

ProjectManager& engine::Project::projectManager

The ProjectManager that owns this project.

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

tracktion_Project.h

Public Types

Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ReloadMode

◆ Ptr

Member Enumeration Documentation

◆ NagMode

◆ ProjectSortType

Constructor & Destructor Documentation

◆ ~Project()

Member Function Documentation

◆ save()

◆ handleAsyncUpdate()

◆ isValid()

◆ isReadOnly()

◆ isTemporary()

◆ setTemporary()

◆ getProjectID()

◆ getName()

◆ getDescription()

◆ isFolderBased()

◆ getProjectFile()

◆ getDefaultDirectory()

◆ getDirectoryForMedia()

◆ getSourcePathForFile()

◆ setName()

◆ setDescription()

◆ createNewProjectId()

◆ getProjectProperty()

◆ setProjectProperty()

◆ refreshProjectPropertiesFromFile()

◆ isLibraryProject()

◆ findOrphanItemRefs()

◆ findOrphanItems()

◆ getNumProjectItems()

◆ getProjectItemRef()

◆ getAllProjectItemRefs()

◆ getProjectItemAt()

◆ getAllProjectItems()

◆ getIndexOf()

◆ getProjectItemFor()

◆ getProjectItemForFile()

◆ createNewItem()

◆ removeProjectItem()

◆ moveProjectItem()

◆ createNewEdit()

◆ redirectIDsFromProject()

◆ mergeArchiveContents()

◆ mergeOtherProjectIntoThis()

◆ refreshFolderStructure()

◆ createDefaultFolders()

◆ getSelectableDescription()

◆ lockFile()

◆ unlockFile()

◆ sourceFileMoved()

◆ reload()

◆ setNewProjectId()

Member Data Documentation

◆ engine

◆ projectManager