Expansionhandler

This 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:

1. User enters license credentials (causes a reload of all encrypted expansions with the new user credentials)
2. User encodes a new Expansion with Expansionhandler.encodeWithCredentials() (will be called automatically afterwards).
3. 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:

1. the error message
2. 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:

1. A preset from an expansion is loaded
2. Expansionhandler.setCurrentExpansion() was called
3. 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)