ExpansionHandler
The ExansionHandler
class will offer functions to manage expansions. In order to use it, create one with the function Engine.createExpansionHandler()
.
In earlier versions of HISE, this class was globally available (like the Message
or Server
class). However for stability reasons the lifetime had to be limited so it's required to create an object in the onInit
callback.
Class methods
encodeWithCredentials
Encrypts the given hxi file.
ExpansionHandler.encodeWithCredentials(var hxiFile)
This method takes the credentials object that was passed into Expansionhandler.setCredentials()
and embeds it into the given .hxi file, then copies this file as info.hxp
to the expansion folder.
The most basic example for how to use it would be to show a browser to the user,let it select a downloaded hxi file and then call this function in the file callback:
// Create a wrapper object around the expansion handler
const var expHandler = Engine.createExpansionHandler();
function installExp(hxiFile)
{
expHandler.encodeWithCredentials(hxiFile);
};
FileSystem.browse(FileSystem.Documents,
false, // read
"*.hxi", // hxi
installExp); // callback
But you can of course implement a more complex system using the Server download API.
getCurrentExpansion
Returns the currently active expansion (if there is one).
ExpansionHandler.getCurrentExpansion()
getExpansion
Returns the expansion with the given name
ExpansionHandler.getExpansion(var name)
getExpansionForInstallPackage
Checks if the expansion is already installed and returns a reference to the expansion if it exists.
ExpansionHandler.getExpansionForInstallPackage(var packageFile)
getExpansionList
Returns a list of all available expansions.
ExpansionHandler.getExpansionList()
getUninitialisedExpansions
Returns a list of all expansions that aren't loaded properly yet.
ExpansionHandler.getUninitialisedExpansions()
installExpansionFromPackage
Decompresses the samples and installs the .hxi / .hxp file.
ExpansionHandler.installExpansionFromPackage(var packageFile, var sampleDirectory)
If you have included the .hxi as metadata during the Sample export
, you can use this function to automatically extract the samples, copy the expansion file (and encrypt it if you have user credentials available) and refresh the list.
This operation will be asynchronously executed on the sample loading thread, which means you can use the ScriptPanel.setLoadingCallback function which will notify the user about the progress (extracting large sample sets might take a while so you most likely want some indication about the process).
If you want to do more specific tasks at the start and / or end of the installation routine, you can use the Expansionhandler.setInstallCallback() function.
The function expects two parameters, the first must be a file object that points to the .hr1 file you want to install and the second parameter must be either a constant from the FileSystem class or a file object pointing to an (existing) folder:
2nd Parameter | Effect |
FileSystem.Expansions
|
The samples will be copied to the expansion folder. This means they end up in the AppData directory of your system drive which is not the best idea if you have lots of samples |
FileSystem.Samples
|
The samples will be copied to the global sample folder that you can specified with the CustomSettingsPanel(!LINK). It will create an symlink file in the Expansion's Sample folder to redirect anything to the global sample folder. |
Custom folder object | This will create a symlink file in the Expansion's sample folder to point to any arbitrary location. You can use this to setup your own sample management system and allow the user to spread the samples across multiple locations. |
You can change / query the folder you specify later on using the Expansion.setSampleFolder() and Expansion.getSampleFolder() methods.
refreshExpansions
Call this to refresh the expansion list.
ExpansionHandler.refreshExpansions()
If the user has installed a new expansion, you will need to call this function in order to refresh the list of expansions and initialise new expansions.
The function will go through all the folders in the expansion root folder and tries to initialise any expansion that isn't loaded yet (either because it is new or because it couldn't been initialised yet because of missing encryption information
).
This step is only necessary when you implement a manual installation routine, but it will be called automatically at these events:
- User enters license credentials (causes a reload of all encrypted expansions with the new user credentials)
- User encodes a new Expansion with Expansionhandler.encodeWithCredentials() (will be called automatically afterwards).
- User installs an expansion from a package with Expansionhandler.installExpansionFromPackage()
setAllowedExpansionTypes
Sets a list of allowed expansion types that can be loaded.
ExpansionHandler.setAllowedExpansionTypes(var typeList)
If you encrypt Expansions for your project, you most likely want to avoid that the user can just load in unencrypted expansions. In order to prevent this, you can specify the types that can be loaded using this method.
During development / debugging you will need to have all types enabled, but don't forget to change that before release.
The argument must be an array with numbers for the type that are available as constants of the ExpansionHandler class:
ExpansionHandler.FileBased
ExpansionHandler.Intermediate
ExpansionHandler.Encrypted
setCredentials
Set a credentials object that can be embedded into each expansion.
ExpansionHandler.setCredentials(var newCredentials)
If you have a licensing scheme that offers a unique identification for each user, you can use this object to pass it to the ExpansionHandler so it can encode this data into the expansions
setCurrentExpansion
Sets the current expansion as active expansion.
ExpansionHandler.setCurrentExpansion(var expansionName)
Be aware that while there is only one expansion that can be active at the same time, it does not mean that you can't load content from multiple expansions at once (and you don't need to call this function before you want to load some data from an expansion).
It is more an additional feature that allows you to eg. adapt the UI to the most recently loaded expansion.
Whenever you call this method, the function that was specified at Expansionhandler.setExpansionCallback()
is being executed with a reference to the active Expansion
object as parameter.
setEncryptionKey
Set a encryption key that will be used to encrypt the content (deprecated).
ExpansionHandler.setEncryptionKey(String newKey)
Call this function if you want to use the encrypted Expansion type in order to protect your expansions against unauthorized usage. The key you pass in must be a valid Blowfish key, so any String up to 72 characters is fine.
Be aware that you need to pass in the exact same key you specified in the Project Settings' Expansion Key property.
As soon as you call this method, the expansion handler will reinitialise the expansions that are encrypted and try to decrypt them with the new key.
setErrorFunction
Sets a error function that will be executed.
ExpansionHandler.setErrorFunction(var newErrorFunction)
If something goes wrong with the initialisation of an expansion, you can specify a function that is called with an error message that you can show to the user somehow.
The function you pass as newErrorFunction
must have two parameters:
- the error message
- a flag indicating a critical error (a critical error will stop the plugin).
This function will be called by the expansion logic inside HISE, however you can also call it manually using the
Expansionhandler.setErrorMessage()
function
Be aware that the error function is owned by the wrapper object not the global expansion manager (so it goes out of scope as soon as the wrapper object is destructed).
setErrorMessage
Calls the error function specified with setErrorFunction.
ExpansionHandler.setErrorMessage(String errorMessage)
setExpansionCallback
Set a function that will be called whenever a expansion is being loaded.
ExpansionHandler.setExpansionCallback(var expansionLoadedCallback)
Whenever an expansion is switched, this function will be called so you can react on the event. This happens at these opportunities:
- A preset from an expansion is loaded
- Expansionhandler.setCurrentExpansion() was called
- An expansion was selected in the dropdown list in the HISE Expansion Edit bar
Be aware that the expansion callback is owned by the wrapper object not the global expansion manager (so it goes out of scope as soon as the wrapper object is destructed).
setInstallCallback
Set a function that will be called during installation of a new expansion.
ExpansionHandler.setInstallCallback(var installationCallback)
This callback expects one argument that will contain an object with some information about the installation status.
Property | Description |
obj.Status
|
A status code indicating the state of the installation: 0
before the extraction starts, 1
during the extraction and 2
if the extraction is finished. The callback is guaranteed to be executed with 2
at least once. |
obj.Expansion
|
If the installation (and optional initialisation using the authentication credentials) suceeded, this will contain a reference to the expansion so you can do some post-installation tasks. |
obj.Progress
|
This contains the extraction progress. It's basically the same as Engine.getPreloadProgress
. |
obj.SourceFile
|
The package file that is being extracted. |
obj.TargetFolder
|
The directory where the expansion is being installed to. |
obj.SampleFolder
|
The sample folder that is being used for the samples. |
You can use this callback for different tasks that might suit your handling of expansions:
- deleting the .hr1 file after a sucessful installation
- rebuilding user presets after an expansion update
- automatically switching to the installed expansion using
ExpansionHandler.setCurrentExpansion()
const var t = FileSystem.getFolder(FileSystem.Desktop).getChildFile("test.hr1");
const var e = Engine.createExpansionHandler();
function installCallback(obj)
{
if(obj.Status == 2 && isDefined(obj.Expansion))
{
// make sure the user presets are updated
obj.Expansion.rebuildUserPresets();
// ask the user if he wants to delete the archive file...
Engine.showYesNoWindow("Installation sucessful",
"Do you want to delete the archive file",
function(ok)
{
if(ok)
t.deleteFileOrDirectory();
});
}
};
e.setInstallCallback(installCallback);
e.installExpansionFromPackage(t, FileSystem.Expansions);
setInstallFullDynamics
Sets whether the installExpansionFromPackage function should install full dynamics.
ExpansionHandler.setInstallFullDynamics(bool shouldInstallFullDynamics)