Appendix A

Script Compatibility

This Appendix summarizes aspects about different types of compatibility issues and concepts for Lua scripts inside the TI-Nspire™ platform. It supports authoring documents for a mixed environment of TI-Nspire™ software releases and different platforms. Authoring scripts for a higher API level than supported inside a current script development environment is detailed in section A.2 .

Related Topics

A.1 Backward and Forward Compatibility

There are two compatibility concepts implemented in the TI-Nspire™ platform. The following sections describe these concepts and their interaction. Understanding both is essential to author documents able to run in environments with mixed TI-Nspire™ software releases. If this is not desired, you can skip section A.1 and continue reading section A.2 .

A.1.1 Document Compatibility

This is an old concept of the TI-Nspire™ platform. For every document there are two different TI-Nspire™ release values — the release where the document was “last saved” and a “minimum requested” release. Any TI-Nspire™ release with a lower release number than the “minimum requested” release, blocks opening the document. If the TI-Nspire™ release is at least the “last saved” release level, the document will open without warning.

This concept has been recently enhanced. The “minimum requested” release is now determined dynamically based on the content. This allows a lower minimum release; however, changing the document content may raise the “minimum requested” release dynamically.

Script authors interested in backwards compatibility of scripts need to understand that changing non-scripting content inside the same document as the script might modify the “minimum release.” Currently, there is no better support for the script writer to understand what the “minimum requested” releases is other than opening the document manually with multiple releases of the TI-Nspire™ software.

If the document contains only scripts, the rule is simple. Documents will open, but scripts may fail if the used API level is not supported. The earliest software able to open documents containing scripts is TI-Nspire™ software version 3.1. As an exception, the 3.1 software release only opens documents if all contained scripts are of platform.apiLevel = '1.0'

A.1.2 Scripting Compatibility

Scripts written for the TI-Nspire™ platform are by default forward compatible on the particular platforms the script was designed and tested for (platform compatibility will be discussed in section A.3 ). The key component to ensure forward compatibility is the API level concept. The API level specifies the scripting interface of a particular TI-Nspire™ software release. The mapping between the software release and its highest supported API level is shown in Table A.1 . The highest supported, or current API level of a software release used to create a script, is the default API level for scripts when initially authored. The API level can be changed manually by the author at any time.

Backwards compatibility of scripts can be reached by requesting the API level of the oldest
TI-Nspire™ software release that is targeted to run the script. To support software release 3.1, the script would request platform.apiLevel = '1.0'.

The requested API level of the script is not guaranteed, as an older TI-Nspire™ software version running the script may not support this API level. In addition, requesting an API level that does not exist or is not supported in the used TI-Nspire™ software version will result to the highest supported API level, but not higher than the requested API level. If the script requires a minimum API level to run successful, it might be the simplest solution to prevent the script from executing. This can be archived via the File Menu in the Script Editor.

As an exception to the outlined API level behavior, requesting an API level below 1.0 will result in the current API level of the software release. Please see Table A.1 for more details. Please see section A.2 for a useful example of requesting an API level that is not supported.

A.2 Creating Scripts for a Future Software Release

There might be times when a new version of TI-Nspire™ software with a higher API Level is released, but it does not contain a development environment. In this case, the new functions of the higher API level must be used conditionally at run time. In addition, the authoring process might become a two-step approach. After first authoring the script and saving the document on the authoring platform, it might be that TI-Nspire™ software marks the document dirty when opened first on the target API level platform. When this happens please save the script on the target platform. Saving the document in such a case will be the second step of the authoring process. Once this second step is completed for a specific document it will be usually not be requested again.

An example of how this can be accomplished for the touch library when developing with OS version 3.2 is shown in Listing A.1 . This Lua snippet should be the first section in the script. The touch library is not defined in platform.apiLevel = '2.0' but in all future releases.

Table A.1: Mapping between API level and TI-Nspire™ software version

Listing A.1: Authoring for a Future Software Release for the Example of Touch

platform.apiLevel = '2.2'
iftouch  then
    if not  touch.enabled then 
        functiontouch.enabled() return true end
        functiontouch.isKeyboardAvailable() return true end 
    end
else
    touch  = {}
    functiontouch.enable() returnfalseend
end

A.3 Platform Compatibility

A script author usually prefers to write scripts that are platform independent. Unfortunately this is not true for every feature supported by all platforms. Table A.2 shows the major differences. It is the script authors choice to avoid them, use them on selected platforms only, or try to achieve a seamless user experience across all platforms. In the latter case, authors should test scripts on all platforms.

Table A.2: Overview about platform incompatibilities