Difference between revisions of "Changes in OS 3.2"

From Inspired-Lua Wiki
Jump to navigation Jump to search
 
(25 intermediate revisions by the same user not shown)
Line 1: Line 1:
__NOTOC__
 
 
 
In its TI-Nspire OS 3.2, TI updated the Lua scripting API.
 
In its TI-Nspire OS 3.2, TI updated the Lua scripting API.
  
 
Here are the changes made.
 
Here are the changes made.
  
* [[platform.apiLevel]] is now '2.0'. You can manually set it to '1.0' again in order to have some retro-compatibility.
+
==Compatibility mode==
* [[platform.gc]] has been deleted.
+
TI has 2 "[[platform.apilevel|apilevel]]s" in 3.2. apilevel 1.0 provides backwards compatibility for &lt; 3.2 OSes by keeping the old API structure.<br />
* [[on.construction]] replaces [[on.create]]
+
'''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.<br /> 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.<br />
* [[D2Editor|D2Editor]] improved.
+
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:
* [[Physics Engine]]
+
:''platform.apilevel = "1.0"'' ( or ''platform.apilevel = "2.0"'' depending on what you plan to use)
  
 +
==Events==
 +
* [[on.create]] is removed in apilevel 2.0 and replaced with [[on.construction]]. This event handler is guaranteed to run before all others.<br />
 +
* New : [[on.getFocus]] is called when the script receives user input focus.
 +
* New : [[on.loseFocus]] is called when the script loses user input focus.
 +
* New : [[on.getSymbolList]] is called when the script app symbol list is being serialized to the clipboard.
 +
* Changed : if the mouse ([[cursor]]) is not shown whenever the user presses the center button of the clickpad/touchpad, [[on.mouseDown]] is now fired, with its parameters x and y being both 0.
  
(todo)
+
==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)
 +
* [[gc:clipRect]] doesn't have the ''intersect'' option anymore.
 +
* In [[platform.apilevel|apilevel]] 2.0, [[platform.gc]]() is removed and replaced with [[platform.withGC]](). Usage example:<br />
  
==Compatibility mode==
+
<syntaxhighlight>function getHeightWidth(str, gc)
Let me first begin with the compatibility mode. TI has 2 "apiLevel's" in 3.2. apiLevel 1.0 provides backwards compatibility for &lt;3.2 OS's by keeping the old API structure.<br />
+
    local width = gc:getStringWidth(str) -- Gets the pixel length of str
'''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.<br /> 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. I have given the details of the changes to ExtendeD so he will probably update Luna soon.<br />
+
    local height = gc:getStringHeight(str) -- Gets the pixel height of str
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:
+
    return height, width
:''platform.apiLevel = '1.0'''
+
end
<br />
+
height, width = platform.withGC(getHeightWidth, 'Hello World')</syntaxhighlight>
or :<br />
+
What it does is calling the function you give as first argument, and additionally passing a dummy [[gc|GC]] (Graphics Context) to it.
:''platform.apiLevel = '2.0'''
+
 
<br />
+
==D2Editor==
Please note that using apiLevel 2.0 with the current Luna will result in an error.<br />
+
[[D2Editor|D2Editor]] has been greatly improved ; Here are the new functions :<br />
 +
* [[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.<br />
 +
The physics module is the chipmunk physics engine.<br />  
 +
color is just a table containing colors. (color.red (or color["red"]) will return the color code for red.)<br />
 +
'strict' is a module (not tested) which, apparently, makes it so Lua checks uses of undeclared global variables. All global variables must be 'declared' through a regular assignment (even assigning nil will do) in a main chunk before being used anywhere or assigned to inside a function.<br />
 +
Usage: [[require]] 'modulename'<br />
 +
 
 +
==Physics==
 +
Maybe the best part of it : OS 3.2 now includes the Open Source Chipmunk [[Physics_Engine|Physics engine]], and you can use it right from Lua!<br /> This will allow some great games and applications <br /> Find all the functions/categories [[:Category:Physics_Engine|here]] (WIP !).Tutorials about it coming soon.<br />
 +
 
 +
==Image==
 +
[[image.rotate]]. Performs images rotation. (Warning : The image changes size when you rotate it. So you need to figure where to draw it based on the middle of its rotated size.)
 +
 
 +
==Math==
 +
* [[math.eval]] was revised to remove the optional argument exact and use current document settings, approximate mode, and full precision
 +
* New : [[math.evalStr]], [[math.getEvalSettings]] and  [[math.setEvalSettings]].<br />
 +
 
 +
==Platform==
 +
* The already mentioned [[platform.withGC]]<br />
 +
* [[platform.registerErrorHandler]], this allows you to take actions when an error occurs in your document.  
 +
* [[platform.window:setFocus]], regain focus in your script.<br />
 +
* [[platform.hw]](), returns a number corresponding to the device the scripts is running on.
  
=='''on.create'''==
+
==Toolpalette==
<tt>on.create</tt> is removed in apiLevel 2.0 and replaced with <tt>on.construction</tt>.<br />
+
If the [[platform.apilevel|APILevel]] is set to '2.0', the names of toolpalette items may be changed dynamically while the program is running.
This event handler is guaranteed to run before all others.<br />
+
Calling toolpalette.register(nil) deactivates the toolpalette.
  
==Graphical==
+
==Variable==
operations <nowiki>* Most graphical operations are now anti-aliased. This makes that applications look more pretty </nowiki><br /> <nowiki>* </nowiki><tt>gc:setColorRGB</tt> now supports one number as input (as well as the old style). For example, you can do <tt>gc:setColorRGB(0xFF00CC)</tt> or <tt>gc:setColorRGB(0)</tt><br /> <nowiki>* You can not use coordinates for drawing to the screen above/under (-) 32 000. Normally this shouldn't affect anyone, but because of this Cubefield refuses to run. </nowiki><br /> <br /> <nowiki>* In apiLevel 2.0 </nowiki><tt>platform.gc()</tt> is removed and replaced with <tt>platform.withGC()</tt>. An example of it:<br /> <div class="codeheader">Code: [javascript:void(0) Select All] | [javascript:void(0) Copy To Clipboard]</div><div id="code_a2" class="code">  {| |  | <div id="code_tda2"><font face="monospace"><br /> function getStringWidth(gc, str)<br />   return gc:getStringWidth(str)<br /> end<br /> <br /> function on.construction()<br />   local strw = platform.withGC(getStringWidth, "The game")<br /> end<br /> </font></div> |}  </div><br /> So what it does it call the function you give as first argument and pass a dummy GC to it. <br /> '''D2Editor''' D2Editor is greatly improved, and it finally useful <br /> <br /> '''require''' There are three modules that you can 'require': physics, color, and strict.<br /> The physics module is the chipmunk physics engine.<br /> color is just a table containing colors. color.red (or color["red"]) will return the color code for red.<br /> I have no idea what strict is or does [[Image:tongue.gif|Tongue]]<br /> <br /> Usage: <tt>require 'modulename'</tt><br /> <br /> '''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!<br /> This will allow some great games and applications <br /> However it's is far to complex to detail in this post, so I will probably write a tutorial about it soon <br /> <br /> '''Image''' Normally 3.2 would have many updates to the image, but sadly enough they did not make 3.2 and are pushed for the next OS.<br /> However, there is one function that made it, and that is <tt>image.rotate</tt>. This allows you to rotate images in anyway.<br /> But beware, it is not the fastest function out there.<br /> '''Math''' <tt>math.eval</tt> has got some friends: <tt>math.evalStr</tt>, <tt>math.getEvalSettings</tt> and  <tt>math.setEvalSettings</tt>.<br /> '''Platform''' I already mentioned <tt>platform.withGC</tt>, but there are still two other newcomers:<br /> <nowiki>* </nowiki><tt>platform.registerErrorHandler</tt>, this allows you to take actions when an error occurs in your document. Pretty nice <br /> <nowiki>* </nowiki><tt>platform.window:setFocus</tt>, regain focus in your script.<br /> '''Variable''' <nowiki>* </nowiki><tt>var.recallAt</tt>, fetch data from a certain spot in a list or matrix<br /> <nowiki>* </nowiki><tt>var.makeNumericList</tt>, create a list in the symbol table. The create list will work much more efficient with other var functions.<br /> <br /> <br /> <br /> Well, that's about it. I'm sure there are some stuff I forgot, but you can find them all in the API documentation here -- Link to doc --.<br /> Good luck and may the coding force be with you!</div>
+
* [[var.recallAt]] : fetches data from a certain spot in a list or matrix<br />
 +
* [[var.storeAt]] : Stores a numeric value into an element of a math list or matrix with the given name.<br />
 +
* [[var.makeNumericList]] : creates a list in the symbol table with the given name. The list is optimized to hold numeric values.

Latest revision as of 02:14, 7 May 2014

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.
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" depending on what you plan to use)

Events

  • on.create is removed in apilevel 2.0 and replaced with on.construction. This event handler is guaranteed to run before all others.
  • New : on.getFocus is called when the script receives user input focus.
  • New : on.loseFocus is called when the script loses user input focus.
  • New : on.getSymbolList is called when the script app symbol list is being serialized to the clipboard.
  • Changed : if the mouse (cursor) is not shown whenever the user presses the center button of the clickpad/touchpad, on.mouseDown is now fired, with its parameters x and y being both 0.

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)
  • gc:clipRect doesn't have the intersect option anymore.
  • In apilevel 2.0, platform.gc() is removed and replaced with platform.withGC(). Usage example:
function getHeightWidth(str, gc)
    local width = gc:getStringWidth(str) -- Gets the pixel length of str
    local height = gc:getStringHeight(str) -- Gets the pixel height of str
    return height, width
end
height, width = platform.withGC(getHeightWidth, 'Hello World')

What it does is calling the function you give as first argument, and additionally passing a dummy GC (Graphics Context) to it.

D2Editor

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

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.)
'strict' is a module (not tested) which, apparently, makes it so Lua checks uses of undeclared global variables. All global variables must be 'declared' through a regular assignment (even assigning nil will do) in a main chunk before being used anywhere or assigned to inside a function.
Usage: require 'modulename'

Physics

Maybe the best part of it : 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
Find all the functions/categories here (WIP !).Tutorials about it coming soon.

Image

image.rotate. Performs images rotation. (Warning : The image changes size when you rotate it. So you need to figure where to draw it based on the middle of its rotated size.)

Math

Platform

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 : fetches data from a certain spot in a list or matrix
  • var.storeAt : Stores a numeric value into an element of a math list or matrix with the given name.
  • var.makeNumericList : creates a list in the symbol table with the given name. The list is optimized to hold numeric values.