Breaking changes on settings between 0.9.7 and 0.9.8
With the version 0.9.8 alphaTab moved from the C# codebase to a TypeScript codebase. In preparation of the 1.0.0 release a lot of cleanups
happened and many things on the API were reviewed and changed. Goal of this (again) breaking changes is to have a future proof API surface
that can survive a few releases without the need of again some reworks.
While this version comes with a lot of new benefits this guide only focuses on the breaking changes and how to upgrade your application.
In most cases developers weren't in the need to use all the exposed classes of alphaTab and rather could stick to the main API surface
and just access the properties. Property names did not change on this version. The main changes can be summarized as:
The main API class was moved from alphaTab.AlphaTabApi to alphaTab.alphaTabApi
Enums have now clean names like alphaTab.LayoutMode
Interfaces have been removed
The AlphaTexExporter was fully removed.
Check for changed event names that were used.
Check for new settings on hiding notation elements.
Use the new on/off event subscription if you used API object events.
In case you used various classes from the alphaTab module directly, you can find fhe full changes can be found below for migration.
One of the bigger changes on this version is the event system. There are 3 ways to subscribe to events in alphaTab and each event might
be affected in a way:
Some events have been renamed and need update.
Direct API events:
The registration system for the events was completely changed and some events have been renamed.
Before events were registered via addEventName(handler) and unregistered via removeEventName(handler).
Now events are registered via eventName.on(handler) and unregistered via eventName.off(handler).
The error event previously included 2 parameters. One for the error type another for the error details.
The error type was now moved into the error details itself. Internally the errors are extending the default
Error type but due to serialization this information might get lost. The error.type property contains
one of the values of alphaTab.AlphaTabErrorType specifying some details about which kind of error was raised.
alert('The input file has an invalid format: '+ error.message);
For .net the change on the code is way bigger than it is for the Web version. The .net version is now auto generated
available data types are reduced. Due to this alphaTab is now heavily based on double values where earlier float and int values
might have been used. This can result in a higher memory consumption and major breaking changes.
Just like the Web version the .net version is affected from the event system rework. The .net version does not use the C# built-in event system anymore.
Subscribe to events via the .On(handler) and unsubscribe via the .Off(handler) method on the event object.
At many places where you would likely expect an int value you will now find double values. This does not necessarily mean that
decimal values should be filled or are supported but it is rather a side effect that we do not know from the TypeScript codebase whether
a property, parameter or variable would be an integer. We plan to improve the situation on the types in future but for now we
advise developers to be careful when passing in values to alphaTab and report potential errors that are not handled.
Internally alphaTab will try to cut off decimal parts of values where they are not needed but there might be places where this is missed.
The new error reporting system is fully based on Exceptions and you should use the corresponding exception types to determine the type of error.
For a higher level categorization also the AlphaTabError.Type property can be checked. The previous string value identifying the category has been removed.