Expansion

The Expansion object can be used to query the properties of a given expansion and modify it. The creation of this object is usually done by the ExpansionHandler and its various calls.

Be aware that you don't need this class in order to load content from an expansion as it's already resolved through the Expansion wildcard

Class methods

getAudioFileList

Returns a list of all available audio files in the expansion.

Expansion.getAudioFileList()

This returns a list of all audio files that are included in the given Expansion. Also it will load all audio files into the pool so they are available in the list.

getDataFileList

Returns a list of all available data files in the expansion. Edit on GitHub

Expansion.getDataFileList()

getExpansionType

returns the expansion type. Use the constants of ExpansionHandler to resolve the integer number. Edit on GitHub

Expansion.getExpansionType()

getImageList

Returns a list of all available images in the expansion. Edit on GitHub

Expansion.getImageList()

getMidiFileList

Returns a list of all available MIDI files in the expansion. Edit on GitHub

Expansion.getMidiFileList()

getProperties

Returns an object containing all properties of the expansion.

Expansion.getProperties()

This returns a JSON object with the properties of the Expansion pack. Be aware that this might be subject to change, but the current properties are:

• Name : the name of the expansion pack
• Version : the version number of the expansion pack
• Blowfish-Key : the key that is used to encode the expansion pack data.

Protip: You might not want to display the blowfish key somewhere on your interface...

getRootFolder

Returns the root folder for this expansion. Edit on GitHub

Expansion.getRootFolder()

getSampleFolder

Returns the folder where this expansion looks for samples.

Expansion.getSampleFolder()

This will return either the local Samples subfolder of the expansion folder or another one that was set with either Expansion.setSampleFolder() or ExpansionHandler.installFromPackage()

getSampleMapList

Returns a list of all available sample maps in the expansion. Edit on GitHub

Expansion.getSampleMapList()

getUserPresetList

Returns a list of all available user presets in the expansion. Edit on GitHub

Expansion.getUserPresetList()

getWildcardReference

Returns a valid wildcard reference (({EXP::Name}relativePath ) for the expansion. Edit on GitHub

Expansion.getWildcardReference(var relativePath)

loadDataFile

Attempts to parse a JSON file in the AdditionalSourceCode directory of the expansion.

Expansion.loadDataFile(var relativePath)

The AdditionalSourceCode directory in the project folder of a HISE project is reserved for C++ files which will be compiled on plugin export.
In an expansion pack, this directory can be used for any arbtitrary kind of text content, however the most useful recommended format to use for this is JSON.

This method (and it's friend Expansion.writeDataFile() can be used to fetch (and write) data to this directory.

rebuildUserPresets

Reextracts (and overrides) the user presets from the given expansion. Only works with intermediate / encrypted expansions.

Expansion.rebuildUserPresets()

If the expansion contains User Presets , they will be extracted automatically when you install the expansion the first time.
However if you update an existing expansion, the installation procedure will not override the user presets by default. If you want to ship new / modified user presets with your expansion update, you will need to call this manually after the installation of the expansion is finished.

The most convenient place for calling this method is the install callback that can be defined with Expansionhandler.setInstallCallback()

setAllowDuplicateSamples

Sets whether the samples are allowed to be duplicated for this expansion. Set this to false if you operate on the same samples differently. Edit on GitHub

Expansion.setAllowDuplicateSamples(bool shouldAllowDuplicates)

setSampleFolder

Changes the sample folder of that particular expansion.

Expansion.setSampleFolder(var newSampleFolder)

Be aware that this function will not move any samples to the new location, so the user has to do this step manually.
The most recommended way to choose a sample folder is during the installation from a package using the ExpansionHandler.installFromPackage() call.
However this function let's you offer the user a way to fix a false sample path without having to hack around with a text editor.

It's also recommended to hint to the user that he might want to restart the plugin after changing this location in order to remove any chances that the old sample path is still being cached somewhere.

unloadExpansion

Unloads this expansion so it will not show up in the list of expansions until the next restart. Edit on GitHub

Expansion.unloadExpansion()

writeDataFile

Writes the given data into the file in the AdditionalSourceCode directory of the expansion. Edit on GitHub

Expansion.writeDataFile(var relativePath, var dataToWrite)