File

The File object refers to a file or directory on disk and can be used to navigate / access the file system.

In order to use it, call the Filesystem API class to get a folder from where you navigate to the file you want to modify / load.

Be aware that there is no possibility of writing / loading files using absolute paths (eg. C:\MyFolder ) because it is not portable across operating systems (and even computers).

Class methods

copy

Copies the file. Edit on GitHub

File.copy(var target)

createDirectory

Returns the new directory created at the file location, if directory doesn't already exist Edit on GitHub

File.createDirectory(String directoryName)

deleteFileOrDirectory

Deletes the file or directory WITHOUT confirmation. Edit on GitHub

File.deleteFileOrDirectory()

extractZipFile

Extracts the ZIP archive if this file is a .zip file.

File.extractZipFile(var targetDirectory, bool overwriteFiles, var callback)

This method will extract a standard ZIP file (without password protection) to the given target directory (which can be either a file path String or a File object).

In order to extract to privileged locations on Windows, for example the user's VST3 folder, it is neccessary to add an extra linker flag /MANIFESTUAC:level='requireAdministrator' to your project's .jucer file.

The extraction process will be executed on the sample loading thread and you can assign a callback that is executed to track the extraction progress.

The callback expects a single parameter that will contain a JSON object with the following properties:

Property	Type	Description
Cancel	bool	Set to false . If you want to abort the extraction process, just set this flag to true.
Target	String	The target directory as file path.
Error	String	A error message if something went wrong during extracting.
Progress	double	the progress from 0.0 to 1.0. Be aware that this tracks only the number of files extracted vs. the total number of files, so if you have one big file inside the archive, it will not work.
NumBytesWritten	int	the number of bytes that have been extracted.
CurrentFile	String	the relative path of the file that is currently being extracted.
Status	int	a status flag indicating the state of the extraction: 0 at the beginning, 1 while extracting and 2 at the end.

The callback will be executed at the beginning of the extraction (with the Status flag 0 ) and at the end (with the Status flag 2 ) as well as when an error occurs.

If you extract a small archive (less than ~400 files), the callback will also be executed for each file (this limit prevents the scripting queue to be clogged with huge archives).

getBytesFreeOnVolume

Returns the number of bytes free on the drive that this file lives on. Edit on GitHub

File.getBytesFreeOnVolume()

getChildFile

Returns a child file if this is a directory. Edit on GitHub

File.getChildFile(String childFileName)

getHash

Reads a file and generates the hash of its contents. Edit on GitHub

File.getHash()

getNonExistentSibling

Returns a sibling file that doesn't exist. Edit on GitHub

File.getNonExistentSibling()

getNumZippedItems

Returns the number of items in the zip file. Edit on GitHub

File.getNumZippedItems()

getParentDirectory

Returns the parent directory as File. Edit on GitHub

File.getParentDirectory()

getRedirectedFolder

If this file is a folder that contains a HISE redirection file (LinkWindows / LinkOSX file), then it will return the redirection target, otherwise it will return itself. Edit on GitHub

File.getRedirectedFolder()

getRelativePathFrom

Returns a relative path from the given other file. Edit on GitHub

File.getRelativePathFrom(var otherFile)

getSize

Returns the size of the file in bytes. Edit on GitHub

File.getSize()

hasWriteAccess

true if it's possible to create and write to this file. If the file doesn't already exist, this will check its parent directory to see if writing is allowed. Edit on GitHub

File.hasWriteAccess()

isChildOf

Checks if this file is a child file of the other file. Edit on GitHub

File.isChildOf(var otherFile, bool checkSubdirectories)

isDirectory

Checks if this file exists and is a directory. Edit on GitHub

File.isDirectory()

isFile

Checks if this file exists and is a file. Edit on GitHub

File.isFile()

isSameFileAs

Checks if the file matches the other file (the object comparison might not work reliably). Edit on GitHub

File.isSameFileAs(var otherFile)

loadAsAudioFile

Loads the given file as audio file. Edit on GitHub

File.loadAsAudioFile()

loadAsBase64String

Loads the binary file, compresses it with zstd and returns a Base64 string. Edit on GitHub

File.loadAsBase64String()

loadAsMidiFile

Loads the track (zero-based) of the MIDI file. If successful, it returns an object containing the time signature and a list of all events. Edit on GitHub

File.loadAsMidiFile(int trackIndex)

loadAsObject

Loads the given file as object.

File.loadAsObject()

This tries to parse the given file as JSON object and return it. If you are storing complex data, this will be the most convenient option.

loadAsString

Loads the given file as text. Edit on GitHub

File.loadAsString()

loadAudioMetadata

Tries to parse the metadata from the audio file (channel amount, length, samplerate, etc) and returns a JSON object if sucessful. Edit on GitHub

File.loadAudioMetadata()

loadEncryptedObject

Loads the encrypted object using the supplied RSA key pair.

File.loadEncryptedObject(String key)

This function will load a JSON object from a file that has been written with File.writeEncryptedObject()

The encryption uses Blowfish encryption, so it should be able to encrypt / decrypt pretty fast.

You can use these functions to create an authentification scheme that stores the license key in a file in order to bypass online activation.

loadFromXmlFile

Loads the XML file and tries to parse it as JSON object. Edit on GitHub

File.loadFromXmlFile()

loadMidiMetadata

Tries to parse the metadata of the MIDI file and returns a JSON object if successful. Edit on GitHub

File.loadMidiMetadata()

move

Moves the file. Edit on GitHub

File.move(var target)

rename

Renames the file. Edit on GitHub

File.rename(String newName)

setExecutePermission

Changes the execute-permissions of a file. Edit on GitHub

File.setExecutePermission(bool shouldBeExecutable)

setReadOnly

Changes the read/write permission for the given file. Edit on GitHub

File.setReadOnly(bool shouldBeReadOnly, bool applyRecursively)

show

Opens a Explorer / Finder window that points to the file.

File.show()

This opens a OS specific file browser that will reveal the file to the user.

startAsProcess

Launches the file as a process. Edit on GitHub

File.startAsProcess(String parameters)

toReferenceString

Returns a reference string with a wildcard.

File.toReferenceString(String folderType)

This function tries to parse this file as relative path string depending on the folder type. If you want to import a custom sample into a samplemap and want to make sure that it is as portable as possible you can use this:

inline function dropCallback(f)
{
	local samplePath = f.getReferenceString("Samples");
	
	Sampler.loadSampleMapFromJSON([
	{
		"FileName": samplePath
	}]);
};

If the file that was dropped was in the sample folder of the plugin, samplePath will be {PROJECT_FOLDER}MySample.wav (otherwise it will just be the absolute path). Having it as project reference will allow the user to port the data across systems which might be a bit more convenient.

toString

Returns a String representation of that file.

File.toString(int formatType)

You can use this to display the filename on your UI.

The formatType argument is expected to be one of the constants supplied in the File object:

The following table will show the formatting for the file C:\MyFolder\Textfile.txt

Name	Example
FullPath	C:\MyFolder\Textfile.txt
NoExtension	Textfile
OnlyExtension	.txt
Filename	Textfile.txt

writeAsXmlFile

Replaces the XML file with the JSON content (needs to be convertible). Edit on GitHub

File.writeAsXmlFile(var jsonDataToBeXmled, String tagName)

writeAudioFile

Writes the given data (either a Buffer or Array of Buffers) to a audio file. Edit on GitHub

File.writeAudioFile(var audioData, double sampleRate, int bitDepth)

writeEncryptedObject

Encrypts an JSON object using the supplied key.

File.writeEncryptedObject(var jsonData, String key)

This function will encrypt the JSON object with the given key and write it to the specified file. The key can be up to 72 characters long.

In order to read the encrypted file, use File.loadEncryptedObject() with the same key.

writeMidiFile

Writes the array of MessageHolders as MIDI file using the metadataObject to determine time signature, tempo, etc. Edit on GitHub

File.writeMidiFile(var eventList, var metadataObject)

writeObject

Replaces the file content with the JSON data. Edit on GitHub

File.writeObject(var jsonData)

writeString

Replaces the file content with the given text.

File.writeString(String text)

It will return true if the file operation was completed successfully or false if there was an error during the operation.