Changes in OS 3.2

In its TI-Nspire OS 3.2, TI updated the Lua scripting API.

Here are the changes made.

Compatibility mode

TI has 2 "apilevels" in 3.2. apilevel 1.0 provides backwards compatibility for < 3.2 OSes by keeping the old API structure.
All documents created for 3.1 and previous will run in that apilevel by default. This is because some changes in the XML structure of the document. So most programs and games should run fine by default.
Then there is apilevel 2.0. This apilevel has some big changes to the API structure, so you will have to update some of your code in order to have some of they new 3.2 stuff. However, it is currently not possible to create apilevel 2.0 documents with Luna due to changes in the XML structure (Luna crash). Lua may get updated soon.
For the best support and guarantee that you are using the correct apilevel, you should add the following to the top of new Lua documents you create:

platform.apilevel = "1.0" or platform.apilevel = "2.0"

Events

• on.create is removed in apilevel 2.0 and replaced with on.construction. This event handler is guaranteed to run before all others.
  
• on.getFocus is called when the script receives user input focus.
• on.loseFocus is called when the script loses user input focus.
• on.getSymbolList is called when the script app symbol list is being serialized to the clipboard.

Graphical operations

• Most graphical operations are now anti-aliased.
• gc:setColorRGB now supports one number as input (as well as the old style). For example, you can do gc:setColorRGB(0xFF00CC) or gc:setColorRGB(0)
• You can not use coordinates for drawing to the screen above/under (-) 32 000. (Be careful, some scripts might need to take that into account now, or they may crash)
• In apilevel 2.0, platform.gc() is removed and replaced with platform.withGC(). An example of it:
  

function getStringWidth(gc, str)
   return gc:getStringWidth(str)
end
function on.construction() -- was on.create before
   local strw = platform.withGC(getStringWidth, "The game") -- was platform.gc() before
end

So what it does it call the function you give as first argument and pass a dummy GC (Graphics Context) to it.

D2Editor

D2Editor has been greatly improved ; Here are the new functions :

• D2Editor:createChemBox()
• D2Editor:createMathBox()
• D2Editor:getExpressionSelection()
• D2Editor:hasFocus()
• D2Editor:isVisible()
• D2Editor:registerFilter(handlerTable)
• D2Editor:setDisable2DinRT
• D2Editor:setBorder
• D2Editor:setBorderColor
• D2Editor:setColorable
• D2Editor:setTextColor(color)
• D2Editor:setTextChangeListener
• D2Editor:setSizeChangeListener(function(editor, w, h))
• D2Editor:setSelectable(true or false)
• D2Editor:setReadOnly(true or false)
• D2Editor:setVisible(true or false)
• D2Editor:setMainFont(family, style)
• D2Editor:setWordWrapWidth(width)

Require

There are three modules that you can 'require': physics, color, and strict.
The physics module is the chipmunk physics engine.
color is just a table containing colors. (color.red (or color["red"]) will return the color code for red.)
We don't know what strict is or does.
Usage: require 'modulename'

Physics

Maybe the best part of it of. OS 3.2 now includes the Open Source Chipmunk Physics engine, and you can use it right from Lua!
This will allow some great games and applications
Tutorials about it coming soon.

Image

image.rotate. Performs images rotation.

Math

• math.eval was revised to remove the optional argument exact and use current document settings, approximate mode, and full precision in platform.apilevel = '2.0'
• New : math.evalStr, math.getEvalSettings and math.setEvalSettings.
  

Platform

• The already mentioned platform.withGC
  
• platform.registerErrorHandler, this allows you to take actions when an error occurs in your document.
• platform.window:setFocus, regain focus in your script.
  
• platform.hw(), returns a number corresponding to the device the scripts is running on.

Toolpalette

If the APILevel is set to '2.0', the names of toolpalette items may be changed dynamically while the program is running. Calling toolpalette.register(nil) deactivates the toolpalette.

Variable

• var.recallAt, fetch data from a certain spot in a list or matrix
  
• var.makeNumericList, create a list in the symbol table. The create list will work much more efficient with other var functions.