Docs

File

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

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.

File.copy(var target)



createDirectory

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

File.createDirectory(String directoryName)



deleteFileOrDirectory

Deletes the file or directory WITHOUT confirmation.

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.

File.getBytesFreeOnVolume()



getChildFile

Returns a child file if this is a directory.

File.getChildFile(String childFileName)



getHash

Reads a file and generates the hash of its contents.

File.getHash()



getNonExistentSibling

Returns a sibling file that doesn't exist.

File.getNonExistentSibling()



getNumZippedItems

Returns the number of items in the zip file.

File.getNumZippedItems()



getParentDirectory

Returns the parent directory as File.

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.

File.getRedirectedFolder()



getRelativePathFrom

Returns a relative path from the given other file.

File.getRelativePathFrom(var otherFile)



getSize

Returns the size of the file in bytes.

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.

File.hasWriteAccess()



isDirectory

Checks if this file exists and is a directory.

File.isDirectory()



isFile

Checks if this file exists and is a file.

File.isFile()



loadAsAudioFile

Loads the given file as audio file.

File.loadAsAudioFile()



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.

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.

File.loadAsString()



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.

File.loadFromXmlFile()



move

Moves the file.

File.move(var target)



rename

Renames the file.

File.rename(String newName)



setExecutePermission

Changes the execute-permissions of a file.

File.setExecutePermission(bool shouldBeExecutable)



setReadOnly

Changes the read/write permission for the given file.

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.

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).

File.writeAsXmlFile(var jsonDataToBeXmled, String tagName)



writeAudioFile

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

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.

File.writeMidiFile(var eventList, var metadataObject)



writeObject

Replaces the file content with the JSON data.

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.