Inspired-Lua Wiki - User contributions [en]

class

2013-07-15T04:37:12Z

Jonius7: tutorial link url

A complete tutorial about classes is written here: http://inspired-lua.org/index.php/2011/05/5-object-classes/

Here's how the class() function is defined, in the API :

<source lang="lua">
class = function(prototype)
local derived={}
if prototype then
function derived.__index(t,key)
return rawget(derived,key) or prototype[key]
end
else
function derived.__index(t,key)
return rawget(derived,key)
end
end
function derived.__call(proto,...)
local instance={}
setmetatable(instance,proto)
local init=instance.init
if init then
init(instance,...)
end
return instance
end
setmetatable(derived,derived)
return derived
end

</source>

TI.Image

2013-07-01T08:17:59Z

Jonius7: /* Bytes and Data sections */

The TI.Image format is a type of image used in several places in the Nspire documents, such as Lua scripts.

The format is some form of bitmap, with almost no compression at all.

The examples here, as the encoded strings visible in .lua files sometimes show letters and symbols instead of expected "\xxx" characters. This is because the "\xxx" is actually a representation of a non-printable character, and when, by chance, the character is printable the editor displays its value, which can be a letter, a symbol etc.

==Bytes and Data sections==

All the data in a Ti.image is formatted in what we call bytes.
A byte can look like this (without the quotes): "<tt>\255</tt>", "<tt>\129</tt>", "<tt>\045</tt>" or "<tt>.</tt>". The byte number ranges from \000 to \255
If the byte number is reprecentable in ascii (and the nspire supports that char), it is allowed to just use the ascii version as byte, to lower the size of the image. For example, you can change "<tt>\046</tt>" to "<tt>.</tt>".

A data section is a group of bytes used to represent some header data or a pixel.
For example, it might look like this: "<tt>\255\123</tt>".
What is very important to understand is that the data is not written logically, in fact, the position of the bytes is swapped.
For example, let's take a picture with the width 320, and you want to convert the width size to put in your header:

1. You first convert the number to binary: <tt>320 --> 101000000</tt>. 
2.Then you have to add the extra zeros to make it fit in the header (width is 4 bytes): 
<tt>00000000000000000000000101000000</tt> 
3.This is then splited in four (4 bytes): 
<tt>00000000 - 00000000 - 00000001 - 01000000</tt> 
4.Then converted back to decimal: 
<tt>000 - 000 - 001 - 064</tt> 

You would expect to put this then as "<tt>\000\000\001\064</tt>" in the header, but no, you have to swap it: "<tt>\064\001\000\000</tt>" (Little Endian) 
You can also change the "<tt>\064</tt>" in the header to "<tt>@</tt>", since that is its ASCII representation.
Finally, the data would look like this: "<tt>@\001\000\000</tt>"

==Header==
The header is 20 "bytes" long, and can be devided in the following 6 data sections: 
<tt>[IMAGE WIDTH, 4 bytes][IMAGE HEIGHT, 4 bytes][EMPTY, 4 bytes][IMAGE BUFFER SIZE, 4 bytes][IMAGE DEPTH, 2 bytes][OTHER, 2 bytes]</tt>

The header is the first data of the Ti.image format.

<tt>[IMAGE WIDTH, 4 bytes]</tt> : This is the width of your image, and is four bytes long. 
<tt>[IMAGE HEIGHT, 4 bytes]</tt> : This is the height of your image, and is four bytes long. 
<tt>[EMPTY, 4 bytes]</tt> : This space is just filled with zeroes ("\000\000\000\000"), and is four bytes long 
<tt>[IMAGE BUFFER SIZE, 4 bytes]</tt> : Amount of bytes in one buffer row , this is normally 2*width. 4 bytes long. 
<tt>[IMAGE DEPTH, 2 bytes]</tt> : This is the image, normally just 16 ,two bytes long (actaully the image is 15 bit, but if you count the alpha channel it is 16) 
<tt>[UNKNOWN, 2 bytes]</tt> : Unknown, maybe compression type? Two bytes long, and has 1 as default value.<bt>

Example header and description: 
<tt>.\000\000\000\018\000\000\000\000\000\000\000\092\000\000\000\016\000\001\000</tt>

The first four bytes ("<tt>.\000\000\000</tt>") shows that the width is 46px. 
The next four bytes ("<tt>\018\000\000\000</tt>") shows that the height 18px. 
The next four bytes is empty. 
The four bytes ("<tt>\092\000\000\000</tt>") after this is the buffer row size (2*width) 
The next two bytes ("<tt>\016\000</tt>") is the image depth.
The next two bytes ("<tt>\001\000</tt>") are unkown.

==Pixel data==
The pixel data comes directly after the header.
Pixels are arranged in rows.
Each pixel has a data section of two bytes.
It contains the rgb values, and the alpha channel.

Here is how it is structured (in binary):

<tt>A - RRRRR - GGGGG - BBBBB</tt> 
Example : <tt>1 - 11111 - 10001 - 00000</tt> 
A is the alpha channel, 1 for not transparent, 0 for fully transparent. R, G, and B or the color levels.

To convert this to valid pixel data it has to be cut in two:

ARRRRRGG - GGGBBBBB
11111110 - 00100000

|| || Converter to decimal
\/ \/

254 032

And finally, swapped:

"\032\254"

This is then added to the data buffer.

==Examples==

<tt>'''str = "\007\000\000\000\008\000\000\000\000\000\000\000\014\000\000\000\016\000\001\000'''alalalalalalalal\000\244\000\244al\000\244\000\244al\000\244\000\244\000\244\000\244\000\244\000\244\000\244\000\244\000\244\000\244\000\244\000\244\000\244\000\244al\000\244\000\244\000\244\000\244\000\244alalal\000\244\000\244\000\244alalalalal\000\244alalalalalalalalalal5"</tt>

You then need to use the function ''[[image.new]](str)''.

==External Links==

[[User:Adriweb|Adriweb]] made [http://www.youtube.com/watch?v=YQhrMHNkL3A a video] showing some direct manipulations of the TI-Image, in order to understand better the format in general.

[[User:jimbauwens|Jimbauwens]] made [http://bwns.be/jim/tiviewer.html a image previewer], [http://bwns.be/jim/sprite.html a sprite creator] and a basic [http://bwns.be/jim/convert.py python image converter] (you need PythonMagick to run this)

These tools are not official and we'll update this as soon as we can / are allowed to.

In the official Nspire Lua toolkit, TI included in their software a feature that converts an image (with a common format such as jpg, png etc.) into a TI.Image format.

==References==
http://en.wikipedia.org/wiki/Highcolor

[[Category:image]]

Overview of the API

2013-06-30T06:02:40Z

Jonius7: /* Events */

Note: Neither the ''io'' nor ''os'' libraries are present for the TI-Nspire, which seems to be running a light version of Lua 5.1.4.

== Standard Library ==

( This has been taken from [http://www.wowwiki.com/Lua_functions a WoWWiki page] - See the full, official documentation [http://www.lua.org/manual/5.1/manual.html here] )

=== Basic Library Functions ===

*'''[[G]]''' - Global Variable - A global variable (not a function) that holds the global environment (that is, _G._G = _G). Lua itself does not use this variable; changing its value does not affect any environment, nor vice-versa. (Use setfenv to change environments.) - taken from Lua docs
*'''[[assert]]'''(value[, errormsg]) - asserts a value evaluates to true. If it is, returns value, otherwise causes a Lua error to be thrown.
*'''[[collectgarbage]]'''
*'''[[error]]'''
*'''[[getfenv]]'''(function or integer) - Returns the table representing the stack frame of the given function or stack level.
*'''[[getmetatable]]'''(obj, mtable) - Returns the metatable of the given table or userdata object.
*'''[[next]]'''(table, index) - Returns the next key, value pair of the table, allowing you to walk over the table.
*'''[[newproxy]]'''(boolean or proxy) - Creates a userdata with a sharable metatable.
*'''[[print]]''' - print (···) - Receives any number of arguments, and prints their values to stdout, using the tostring function to convert them to strings. print is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use string.format. - taken from Lua Docs
*'''[[select]]'''(index, list) - Returns the number of items in list or the value of the item in list at index.
*'''[[setfenv]]'''(function or integer, table) - Sets the table representing the stack frame of the given function or stack level.
*'''[[setmetatable]]'''(obj, mtable) - Sets the metatable of the given table or userdata object.
*'''[[tostring]]''' - tostring (e) - Receives an argument of any type and converts it to a string in a reasonable format. For complete control of how numbers are converted, use string.format. If the metatable of e has a "__tostring" field, then tostring calls the corresponding value with e as argument, and uses the result of the call as its result. - taken from Lua Docs.
*'''[[tonumber]]''' - tonumber (e) - Receives an argument of the string type and converts it to a number when possible. If the metatable of e has a "__tonumber" field, then tonumber calls the corresponding value with e as argument, and uses the result of the call as its result. - taken from Lua Docs.

*'''[[type]]'''(var) - Returns the type of variable as a string, "number", "string", "table", "function" or "userdata".
*'''[[unpack]]'''(table[, start][, end]) - Returns the contents of its argument as separate values.
*'''[[xpcall]]'''(func, err) - Returns a boolean indicating successful execution of func and calls err on failure, additionally returning func's or err's results.

=== String Library ===
byte char dump find format gmatch gsub len lower match rep reverse sub upper

=== Math Library ===
abs acos asin atan atan2 ceil cos cosh deg exp oor fmod frexp huge ldexp log log10 max min modf pi pow rad random randomseed sin sinh sqrt tan tanh

More information about the other libraries can be found on the [[Extended Standard Library]] Page

== Concepts and Basics ==

This part will explain you how the Lua actually works inside the OS and help you to figure out what you're doing when you write a script for the TI-Nspire. Before reading this, you have to know all about the Lua basics.

The Lua is an interpreted script language which means that it isn't as fast as ASM/C programs, but is still better than the TI-BASIC. One good thing is that this language is in a complete harmony with the OS with basic events and a powerfull graphic context. First, we have to understand how this works. Basicly the script is launched before the executive engine. This means that we can neither evaluate expressions nor use some of the standard API (like platform, var) until the engine is launched. Here is a call summary :

*Launch string library
*Launch math library
*...
*Open and launch User's Lua script
*...
*Launch var API (store, recall, ...)
*Launch platform API (window, gc, ...)
*...
*Link events (pseudo code)
<source lang="lua">while(Exit)
------- Some OS routines here

---- Begin of Event link
buffer:captureDataFromKeyPad() -- (N) some underground routines to catch events
if buffer.charInput ~= "" then -- (N)
on.charIn(buffer.charInput)
buffer.charInput= "" -- (N)
end
if buffer.arrowKey ~= "" then -- (N)
on.arrowKey(buffer.arrowKey)
buffer.arrowKey = "" -- (N)
end
----- etc ...
if platform.window.isInvalidate then
platform.gc():purge() -- (N) Empty buffer before starting to draw
on.paint(platform.gc()) -- save all the things we have to draw
platform:paint() -- (N) draw all those things
platform.window.isInvalidate = false -- say that the window has been drawn
end
----- End of Event link
end''
Note : the (N) commented line only indicates the meaning of the routine. Those functions don't really exist.</source>

Now we can understand how everything is linked, just by a main loop. This helps you to understand that you don't have to code a loop yourself, because the screen wouldn't be refreshed. This also helps to see when the screen gets refreshed. In other words, we cannot use niether '''gc''' nor '''platform.gc()''' (which are the same) in order to draw somthing on the screen if we are outside of '''on.paint()''' (except if your outside function is called within on.paint() ). This also means that we don't need to pass '''gc''' as parameter, because we can rather use '''platform.gc()''' for any functions called within on.paint(). This is exactly what [https://github.com/adriweb/BetterLuaAPI-for-TI-Nspire/blob/master/BetterLuaAPI.lua the BetterLuaAPI library for Nspire] does.

Here is an example of a simple Lua program that displays a message only when a key is pressed (and let the screen blank otherwise).
<source lang="lua"> function on.paint(gc)
if message then
gc:setFont("sansserif", "r", 10) -- initialize font drawing
gc:drawString(message, 0, 0, "top") -- display the message at (0, 0) coordinates
message = nil -- erase the message
timer.start(1) -- start a timer to exit on.paint() but keep in mind that we have to redraw the screen
end
end

function on.timer()
timer.stop()
platform.window:invalidate()
end

function on.charIn(ch)
message = "Hello World !" -- store a message
platform.window:invalidate() -- force display
end</source>
When you open the document, the script is read once. It initializes and overwrites all the functions and globals with the ones you defined. Thus, '''message''' is nil. Once the '''on.paint()''' event is called, '''message''' is nil, thus, nothing is done. When you press a key that calls '''on.charIn()''' (see below for more information), '''message''' is now "Hello World" and we tell the '''platform''' that the screen has to be refreshed. Then, '''on.paint()''' is called again, '''message''' is not nil then we display it, erase '''message''' and launch a timer. Why is that ? Because if we call '''platform.window:invalidate()''' right there, we won't refresh the screen. Why again ? Just look at the pseudo-code above. We set the window as drawn after each call of on.paint(). Thus a timer is necessary to manually recall '''on.paint()''' and exit the '''on.paint()''' function to draw the screen. When the timer is ended, '''on.timer()''' is called and we refresh the screen. The screen is then redrawn but there is nothing to draw because '''message''' is nil. Thus, the graphic context lets the screen blank.

== gc (as in Graphics Context) ==

Note: You need to add “gc:” before each of these commands in order to use them. ex. '''gc:setAlpha(...)'''. You can also call gc like this : '''platform.gc():setAlpha(...)'''. Then you can use the gc library in a function where gc is not passed as an argument. but this function *has* to be called within '''on.paint(gc)'''

The maximum screen resolution available to Lua programs is 318 by 212 pixels.

*'''[[gc:begin]]''' -
*'''[[gc:clipRect]]''' -
*'''[[gc:drawArc]]'''(x, y, width, height, start angle, finish angle) Note, to draw a circle, use drawArc(x - diameter/2, y - diameter/2, diameter,diameter,0,360) where x and y are the coordinates of the middle.
*'''[[gc:drawImage]]'''(image,x,y) First argument in format “[[TI.Image]]”, x and y the coords.
*'''[[gc:drawLine]]'''(xstart, ystart, xend, yend) Draws a line starting at the point (xstart,ystart) and ending at the point (xend, yend)
*'''[[gc:drawPolyLine]]'''(int list1 [,int list2, .., int listN]) Draws a shape from a list contaning successively the x and y coordinates of each point the line have to draw.

*'''[[gc:drawRect]]'''(x, y, xwidth, yheight) Draws a rectangle at (x,y) with the “x” side being “xwidth” long and the “y” side being “yheight” long
*'''[[gc:drawString]]'''(string, x, y, PositionString) PositionString is the string’s anchor point and can be “bottom”, “middle”, or “top”.
*'''[[gc:fillArc]]'''(x, y, width, height, start angle, finish angle) see drawArc
*'''[[gc:fillPolygon]]'''(int list1 [,int list2, .., int listN]) see drawPolyLine
*'''[[gc:fillRect]]'''(x, y, width, height) see drawRect
*'''[[gc:finish]]''' -
*'''[[gc:getStringHeight]]'''(string)
*'''[[gc:getStringWidth]]'''(string)
*'''[[gc:isColorDisplay]]''' Bool (Read-only) Returns 1 if color, 0 if not.
*'''[[gc:setAlpha]]'''(int) - where the argument is an int between 0 and 255. Sets the transparency.
*'''[[gc:setColorRGB]]'''(red, green, blue) RGB values are integers, from 0 to 255.
*'''[[gc:setFont]]'''(font, type, size), with font : {“sansserif”, "serif", ..}, type {“b”, “r”, “i”}, size(int)
*'''[[gc:setPen]]'''(size, smooth) size {“thin”, “medium”, "thick"}, smooth {“smooth”, "dotted", "dashed"}

== platform ==

These are mainly read-only. These work by writing "'''platform.'''" in front of them. Example : "'''platform.window:invalidate()'''"

*'''[[platform.apilevel]]''' : Returns the version of the API. Currently (OS 3.0.1) returns 1.0.0.
*'''[[platform.window]]'''

:*'''[[platform.window:width]]''' - Returns the width of the window. Ex : ''platform.window:height()''
:*'''[[platform.window:height]]''' - Returns the height of the window
:*'''[[platform.window:invalidate]]''' - Repaints the window (it calls '''on.paint(gc)''')

*'''[[platform.isDeviceModeRendering]]''' Returns true or false whether the unit is "rendering" or not
*'''[[platform.gc]]''' - Other way to call '''gc'''. Use it like that : '''platform.gc():setAlpha(...)''' for example. This is useful when you're in a function outside '''on.paint(gc)''' (but this function has to be called within [[on.paint]](gc).)
*'''[[platform.isColorDisplay]]''' Returns ''true'' if the unit the code is being run on has a color display (-> Nspire CX), and ''false'' otherwise.

== cursor ==

*'''[[cursor.hide]]'''() - hides the cursor (mouse pointer)
*'''[[cursor.set]]'''(string) - string can be one of those : (interrogation, crosshair, text, pointer, link select, diag resize, wait busy, hollow pointer, rotation, pencil, zoom box, arrow, zoom out, dotted arrow, clear, animate, excel plus, mod label, writing, unavailable, resize row, resize column, drag grab, hand open, hand closed, hand pointer, zoom in, dilation, translation).
*'''[[cursor.show]]'''() - Shows the cursor on screen

== document ==

*'''[[document.markChanged]]'''() - Flag the document as "changed" so the user has to save it after using it.

== clipboard ==

*'''[[clipboard.addText]]'''()
*'''[[clipboard.getText]]'''()

== locale ==

*'''[[locale.name]]'''() - Returns the current language the calculator is set in, formatted as ISO-639 (i.e : "fr", "en", "it" ...).

== image ==

*'''[[image.copy]]'''(image, width, height) - returns a new Image which has a new scale. Width is the final width, Heigth, the final height of the image.
*'''[[image.height]]'''(image) - returns the height of the image given in parameter
*'''[[image.new]]'''(string) - Creates a new image from the string given in parameter (see TI.Image).
*'''[[image.width]]'''(image) - returns the width of the image given in parameter

== timer ==

*'''[[timer.getMilliSecCounter]]'''() - Returns the amount of milliseconds elapsed since last calculator reboot. (in TI's Computer software, returns an absolute negative time)
*'''[[timer.start]]'''(int) - Starts a timer with 1 second.
*'''[[timer.stop]]'''() - Stops a timer

== toolpalette ==

*'''[[toolpalette.enable]]'''(string)
*'''[[toolpalette.enableCopy]]'''()
*'''[[toolpalette.enableCut]]'''()
*'''[[toolpalette.enablePaste]]'''()
*'''[[toolpalette.register]]'''(table)

== var ==

*'''[[var.list]]'''() - returns a list of all the variables in the entire Activity
*'''[[var.monitor]]'''() - ?
*'''[[var.recall]]'''(string) - returns the variable value which name is given in parameter
*'''[[var.recallstr]]'''(string) - returns the variable value converted to string which name is given in parameter
*'''[[var.store]]'''(string, value) - store in the variable, which name is given in parameter, the value
*'''[[var.unmonitor]]'''() - ?

== Events ==
*'''[[on.create]]'''() function called when script application is created. Removed in OS 3.2 (API v2.0)
*'''[[on.construction]]'''() function that is guaranteed to run first before any other function. New in OS 3.2 (API v2.0)
*'''[[on.paint]]'''(gc) is called when the GUI is painted. 'gc' is the Graphics Context (see above)
*'''[[on.resize]]'''() is called when the window is rezised
*'''[[on.timer]]'''() is called when the timer has been finished. Here an example of using timer to play an animation :
<source lang="lua"> x = 1
animating = false
function on.paint(gc)
gc:setFont("sansserif", "r", 10)
gc:drawString(tostring(x), 0, 0, "top")
if animating then
x = x + 1
timer.start(0.5)
end
end

function on.charIn(ch)
animating = not animating -- switch state
platform.window:invalidate() -- recall graph engine
end

function on.timer()
timer.stop()
platform.window:invalidate() -- recall graph engine
end
</source>
----

*'''[[on.arrowKey]]'''(key) is called when an '''arrow key''' from the clickPad/TouchPad is pressed (right, left, up, down)
*'''[[on.arrowLeft]]'''() is called when the '''left''' arrow is pressed
*'''[[on.arrowRight]]'''() is called when the '''right''' arrow is pressed
*'''[[on.arrowUp]]'''() is called when the up '''arrow''' is pressed
*'''[[on.arrowDown]]'''() is called when the '''down''' arrow is pressed

----

*'''[[on.up]]'''() -- probably for the touchpad up motion
*'''[[on.down]]'''() -- probably for the touchpad down motion

----

*'''[[on.enterKey]]'''() is called when the '''enter''' key is pressed.
*'''[[on.escapeKey]]'''() is called when the '''escape''' key is pressed.
*'''[[on.tabKey]]'''() is called when the '''tab''' key is pressed.
*'''[[on.deleteKey]]'''() is called when the '''delete''' key is pressed.
*'''[[on.backspaceKey]]'''() is called when the '''clear''' key is pressed.
*'''[[on.returnKey]]'''() is called when the '''return''' key is pressed.
*'''[[on.contextMenu]]'''() is called when the combo-key '''Ctrl Menu''' is pressed.
*'''[[on.backtabKey]]'''() is called when the combo-key '''Maj Tab''' is pressed.
*'''[[on.clearKey]]'''() is called when the combo-key '''Ctrl Clear''' is pressed.
*'''[[on.help]]'''() is called when the combo-key '''Ctrl H''' is pressed.

*'''[[on.charIn]]'''(string) is called when the Nspire detects a non arrow key being pressed. ch is the character it detect. If you want to auto start an event in the file linked to key r(like a reset) put on.charIn(“r”) where you want.

*'''[[on.blink]]'''() ? is called when the focus is lost on the page (like launching the document, changing page etc...)

----

*'''[[on.deactivate]]'''() ? is called when the focus is lost on the page (like launching the document, changing page etc...)
*'''[[on.activate]]'''() ? is called when the focus is on the page (like launching the document, changing page etc...)

----

*'''[[on.mouseDown]]'''(x, y) is called when we press the left mouse button. X and Y are the pressed point coordinates.
*'''[[on.mouseUp]]'''() is called when we release the left mouse button.
*'''[[on.mouseMove]]'''() is called when the mouse moves
*'''[[on.grabDown]]'''() ? (software only ?)
*'''[[on.grabMove]]'''() ? (software only ?)
*'''[[on.grabUp]]'''() ? (software only ?)
*'''[[on.rightMouseDown]]'''() ? (software only ?)
*'''[[on.rightMouseUp]]'''() ? (software only ?)

----

*'''[[on.cutEnabled]]'''() ? (software only ?)
*'''[[on.copyEnabled]]'''() ? (software only ?)
*'''[[on.pasteEnabled]]'''() ? (software only ?)
*'''[[on.cut]]'''() ? (software only ?)
*'''[[on.copy]]'''() ? (software only ?)
*'''[[on.paste]]'''() ? (software only ?)

----

== D2Editor ==

*'''[[D2Editor.newRichText]]'''() creates a new RichText object (default values : x, y, width, height = 0)
*'''[[D2Editor.resize]]'''(width, height)
*'''[[D2Editor.move]]'''(x, y)
*'''[[D2Editor.setText]]'''(string)
*'''[[D2Editor.getText]]'''() returns the RichText value
*'''[[D2Editor.setReadOnly]]'''(bool) bool : true/false : If true, the content becomes read-only, i.e. non-editable.
*'''[[D2Editor.setFormattedText]]'''() - ?

Example of a valid function using the D2Editor
<source lang="lua">
function createRichTextBox
box = D2Editor.newRichText()
box:move(50, 50)
box:resize(50, 50)
box:setText("Hello World !")
end</source>

== External Links ==

An interesting page about LUA code optimization, that can be really useful, especially for calculators : [http://trac.caspring.org/wiki/LuaPerformance Lua Performance]

== Online Demo ==

[[Document Player]]

Overview of the API

2013-06-30T06:01:55Z

Jonius7: /* Events */

Note: Neither the ''io'' nor ''os'' libraries are present for the TI-Nspire, which seems to be running a light version of Lua 5.1.4.

== Standard Library ==

( This has been taken from [http://www.wowwiki.com/Lua_functions a WoWWiki page] - See the full, official documentation [http://www.lua.org/manual/5.1/manual.html here] )

=== Basic Library Functions ===

*'''[[G]]''' - Global Variable - A global variable (not a function) that holds the global environment (that is, _G._G = _G). Lua itself does not use this variable; changing its value does not affect any environment, nor vice-versa. (Use setfenv to change environments.) - taken from Lua docs
*'''[[assert]]'''(value[, errormsg]) - asserts a value evaluates to true. If it is, returns value, otherwise causes a Lua error to be thrown.
*'''[[collectgarbage]]'''
*'''[[error]]'''
*'''[[getfenv]]'''(function or integer) - Returns the table representing the stack frame of the given function or stack level.
*'''[[getmetatable]]'''(obj, mtable) - Returns the metatable of the given table or userdata object.
*'''[[next]]'''(table, index) - Returns the next key, value pair of the table, allowing you to walk over the table.
*'''[[newproxy]]'''(boolean or proxy) - Creates a userdata with a sharable metatable.
*'''[[print]]''' - print (···) - Receives any number of arguments, and prints their values to stdout, using the tostring function to convert them to strings. print is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use string.format. - taken from Lua Docs
*'''[[select]]'''(index, list) - Returns the number of items in list or the value of the item in list at index.
*'''[[setfenv]]'''(function or integer, table) - Sets the table representing the stack frame of the given function or stack level.
*'''[[setmetatable]]'''(obj, mtable) - Sets the metatable of the given table or userdata object.
*'''[[tostring]]''' - tostring (e) - Receives an argument of any type and converts it to a string in a reasonable format. For complete control of how numbers are converted, use string.format. If the metatable of e has a "__tostring" field, then tostring calls the corresponding value with e as argument, and uses the result of the call as its result. - taken from Lua Docs.
*'''[[tonumber]]''' - tonumber (e) - Receives an argument of the string type and converts it to a number when possible. If the metatable of e has a "__tonumber" field, then tonumber calls the corresponding value with e as argument, and uses the result of the call as its result. - taken from Lua Docs.

*'''[[type]]'''(var) - Returns the type of variable as a string, "number", "string", "table", "function" or "userdata".
*'''[[unpack]]'''(table[, start][, end]) - Returns the contents of its argument as separate values.
*'''[[xpcall]]'''(func, err) - Returns a boolean indicating successful execution of func and calls err on failure, additionally returning func's or err's results.

=== String Library ===
byte char dump find format gmatch gsub len lower match rep reverse sub upper

=== Math Library ===
abs acos asin atan atan2 ceil cos cosh deg exp oor fmod frexp huge ldexp log log10 max min modf pi pow rad random randomseed sin sinh sqrt tan tanh

More information about the other libraries can be found on the [[Extended Standard Library]] Page

== Concepts and Basics ==

This part will explain you how the Lua actually works inside the OS and help you to figure out what you're doing when you write a script for the TI-Nspire. Before reading this, you have to know all about the Lua basics.

The Lua is an interpreted script language which means that it isn't as fast as ASM/C programs, but is still better than the TI-BASIC. One good thing is that this language is in a complete harmony with the OS with basic events and a powerfull graphic context. First, we have to understand how this works. Basicly the script is launched before the executive engine. This means that we can neither evaluate expressions nor use some of the standard API (like platform, var) until the engine is launched. Here is a call summary :

*Launch string library
*Launch math library
*...
*Open and launch User's Lua script
*...
*Launch var API (store, recall, ...)
*Launch platform API (window, gc, ...)
*...
*Link events (pseudo code)
<source lang="lua">while(Exit)
------- Some OS routines here

---- Begin of Event link
buffer:captureDataFromKeyPad() -- (N) some underground routines to catch events
if buffer.charInput ~= "" then -- (N)
on.charIn(buffer.charInput)
buffer.charInput= "" -- (N)
end
if buffer.arrowKey ~= "" then -- (N)
on.arrowKey(buffer.arrowKey)
buffer.arrowKey = "" -- (N)
end
----- etc ...
if platform.window.isInvalidate then
platform.gc():purge() -- (N) Empty buffer before starting to draw
on.paint(platform.gc()) -- save all the things we have to draw
platform:paint() -- (N) draw all those things
platform.window.isInvalidate = false -- say that the window has been drawn
end
----- End of Event link
end''
Note : the (N) commented line only indicates the meaning of the routine. Those functions don't really exist.</source>

Now we can understand how everything is linked, just by a main loop. This helps you to understand that you don't have to code a loop yourself, because the screen wouldn't be refreshed. This also helps to see when the screen gets refreshed. In other words, we cannot use niether '''gc''' nor '''platform.gc()''' (which are the same) in order to draw somthing on the screen if we are outside of '''on.paint()''' (except if your outside function is called within on.paint() ). This also means that we don't need to pass '''gc''' as parameter, because we can rather use '''platform.gc()''' for any functions called within on.paint(). This is exactly what [https://github.com/adriweb/BetterLuaAPI-for-TI-Nspire/blob/master/BetterLuaAPI.lua the BetterLuaAPI library for Nspire] does.

Here is an example of a simple Lua program that displays a message only when a key is pressed (and let the screen blank otherwise).
<source lang="lua"> function on.paint(gc)
if message then
gc:setFont("sansserif", "r", 10) -- initialize font drawing
gc:drawString(message, 0, 0, "top") -- display the message at (0, 0) coordinates
message = nil -- erase the message
timer.start(1) -- start a timer to exit on.paint() but keep in mind that we have to redraw the screen
end
end

function on.timer()
timer.stop()
platform.window:invalidate()
end

function on.charIn(ch)
message = "Hello World !" -- store a message
platform.window:invalidate() -- force display
end</source>
When you open the document, the script is read once. It initializes and overwrites all the functions and globals with the ones you defined. Thus, '''message''' is nil. Once the '''on.paint()''' event is called, '''message''' is nil, thus, nothing is done. When you press a key that calls '''on.charIn()''' (see below for more information), '''message''' is now "Hello World" and we tell the '''platform''' that the screen has to be refreshed. Then, '''on.paint()''' is called again, '''message''' is not nil then we display it, erase '''message''' and launch a timer. Why is that ? Because if we call '''platform.window:invalidate()''' right there, we won't refresh the screen. Why again ? Just look at the pseudo-code above. We set the window as drawn after each call of on.paint(). Thus a timer is necessary to manually recall '''on.paint()''' and exit the '''on.paint()''' function to draw the screen. When the timer is ended, '''on.timer()''' is called and we refresh the screen. The screen is then redrawn but there is nothing to draw because '''message''' is nil. Thus, the graphic context lets the screen blank.

== gc (as in Graphics Context) ==

Note: You need to add “gc:” before each of these commands in order to use them. ex. '''gc:setAlpha(...)'''. You can also call gc like this : '''platform.gc():setAlpha(...)'''. Then you can use the gc library in a function where gc is not passed as an argument. but this function *has* to be called within '''on.paint(gc)'''

The maximum screen resolution available to Lua programs is 318 by 212 pixels.

*'''[[gc:begin]]''' -
*'''[[gc:clipRect]]''' -
*'''[[gc:drawArc]]'''(x, y, width, height, start angle, finish angle) Note, to draw a circle, use drawArc(x - diameter/2, y - diameter/2, diameter,diameter,0,360) where x and y are the coordinates of the middle.
*'''[[gc:drawImage]]'''(image,x,y) First argument in format “[[TI.Image]]”, x and y the coords.
*'''[[gc:drawLine]]'''(xstart, ystart, xend, yend) Draws a line starting at the point (xstart,ystart) and ending at the point (xend, yend)
*'''[[gc:drawPolyLine]]'''(int list1 [,int list2, .., int listN]) Draws a shape from a list contaning successively the x and y coordinates of each point the line have to draw.

*'''[[gc:drawRect]]'''(x, y, xwidth, yheight) Draws a rectangle at (x,y) with the “x” side being “xwidth” long and the “y” side being “yheight” long
*'''[[gc:drawString]]'''(string, x, y, PositionString) PositionString is the string’s anchor point and can be “bottom”, “middle”, or “top”.
*'''[[gc:fillArc]]'''(x, y, width, height, start angle, finish angle) see drawArc
*'''[[gc:fillPolygon]]'''(int list1 [,int list2, .., int listN]) see drawPolyLine
*'''[[gc:fillRect]]'''(x, y, width, height) see drawRect
*'''[[gc:finish]]''' -
*'''[[gc:getStringHeight]]'''(string)
*'''[[gc:getStringWidth]]'''(string)
*'''[[gc:isColorDisplay]]''' Bool (Read-only) Returns 1 if color, 0 if not.
*'''[[gc:setAlpha]]'''(int) - where the argument is an int between 0 and 255. Sets the transparency.
*'''[[gc:setColorRGB]]'''(red, green, blue) RGB values are integers, from 0 to 255.
*'''[[gc:setFont]]'''(font, type, size), with font : {“sansserif”, "serif", ..}, type {“b”, “r”, “i”}, size(int)
*'''[[gc:setPen]]'''(size, smooth) size {“thin”, “medium”, "thick"}, smooth {“smooth”, "dotted", "dashed"}

== platform ==

These are mainly read-only. These work by writing "'''platform.'''" in front of them. Example : "'''platform.window:invalidate()'''"

*'''[[platform.apilevel]]''' : Returns the version of the API. Currently (OS 3.0.1) returns 1.0.0.
*'''[[platform.window]]'''

:*'''[[platform.window:width]]''' - Returns the width of the window. Ex : ''platform.window:height()''
:*'''[[platform.window:height]]''' - Returns the height of the window
:*'''[[platform.window:invalidate]]''' - Repaints the window (it calls '''on.paint(gc)''')

*'''[[platform.isDeviceModeRendering]]''' Returns true or false whether the unit is "rendering" or not
*'''[[platform.gc]]''' - Other way to call '''gc'''. Use it like that : '''platform.gc():setAlpha(...)''' for example. This is useful when you're in a function outside '''on.paint(gc)''' (but this function has to be called within [[on.paint]](gc).)
*'''[[platform.isColorDisplay]]''' Returns ''true'' if the unit the code is being run on has a color display (-> Nspire CX), and ''false'' otherwise.

== cursor ==

*'''[[cursor.hide]]'''() - hides the cursor (mouse pointer)
*'''[[cursor.set]]'''(string) - string can be one of those : (interrogation, crosshair, text, pointer, link select, diag resize, wait busy, hollow pointer, rotation, pencil, zoom box, arrow, zoom out, dotted arrow, clear, animate, excel plus, mod label, writing, unavailable, resize row, resize column, drag grab, hand open, hand closed, hand pointer, zoom in, dilation, translation).
*'''[[cursor.show]]'''() - Shows the cursor on screen

== document ==

*'''[[document.markChanged]]'''() - Flag the document as "changed" so the user has to save it after using it.

== clipboard ==

*'''[[clipboard.addText]]'''()
*'''[[clipboard.getText]]'''()

== locale ==

*'''[[locale.name]]'''() - Returns the current language the calculator is set in, formatted as ISO-639 (i.e : "fr", "en", "it" ...).

== image ==

*'''[[image.copy]]'''(image, width, height) - returns a new Image which has a new scale. Width is the final width, Heigth, the final height of the image.
*'''[[image.height]]'''(image) - returns the height of the image given in parameter
*'''[[image.new]]'''(string) - Creates a new image from the string given in parameter (see TI.Image).
*'''[[image.width]]'''(image) - returns the width of the image given in parameter

== timer ==

*'''[[timer.getMilliSecCounter]]'''() - Returns the amount of milliseconds elapsed since last calculator reboot. (in TI's Computer software, returns an absolute negative time)
*'''[[timer.start]]'''(int) - Starts a timer with 1 second.
*'''[[timer.stop]]'''() - Stops a timer

== toolpalette ==

*'''[[toolpalette.enable]]'''(string)
*'''[[toolpalette.enableCopy]]'''()
*'''[[toolpalette.enableCut]]'''()
*'''[[toolpalette.enablePaste]]'''()
*'''[[toolpalette.register]]'''(table)

== var ==

*'''[[var.list]]'''() - returns a list of all the variables in the entire Activity
*'''[[var.monitor]]'''() - ?
*'''[[var.recall]]'''(string) - returns the variable value which name is given in parameter
*'''[[var.recallstr]]'''(string) - returns the variable value converted to string which name is given in parameter
*'''[[var.store]]'''(string, value) - store in the variable, which name is given in parameter, the value
*'''[[var.unmonitor]]'''() - ?

== Events ==
*'''[[on.create]]''' function called when script application is created. Removed in OS 3.2 (API v2.0)
*'''[[on.construction]]''' function that is guaranteed to run first before any other function. New in OS 3.2 (API v2.0)
*'''[[on.paint]]'''(gc) is called when the GUI is painted. 'gc' is the Graphics Context (see above)
*'''[[on.resize]]'''() is called when the window is rezised
*'''[[on.timer]]'''() is called when the timer has been finished. Here an example of using timer to play an animation :
<source lang="lua"> x = 1
animating = false
function on.paint(gc)
gc:setFont("sansserif", "r", 10)
gc:drawString(tostring(x), 0, 0, "top")
if animating then
x = x + 1
timer.start(0.5)
end
end

function on.charIn(ch)
animating = not animating -- switch state
platform.window:invalidate() -- recall graph engine
end

function on.timer()
timer.stop()
platform.window:invalidate() -- recall graph engine
end
</source>
----

*'''[[on.arrowKey]]'''(key) is called when an '''arrow key''' from the clickPad/TouchPad is pressed (right, left, up, down)
*'''[[on.arrowLeft]]'''() is called when the '''left''' arrow is pressed
*'''[[on.arrowRight]]'''() is called when the '''right''' arrow is pressed
*'''[[on.arrowUp]]'''() is called when the up '''arrow''' is pressed
*'''[[on.arrowDown]]'''() is called when the '''down''' arrow is pressed

----

*'''[[on.up]]'''() -- probably for the touchpad up motion
*'''[[on.down]]'''() -- probably for the touchpad down motion

----

*'''[[on.enterKey]]'''() is called when the '''enter''' key is pressed.
*'''[[on.escapeKey]]'''() is called when the '''escape''' key is pressed.
*'''[[on.tabKey]]'''() is called when the '''tab''' key is pressed.
*'''[[on.deleteKey]]'''() is called when the '''delete''' key is pressed.
*'''[[on.backspaceKey]]'''() is called when the '''clear''' key is pressed.
*'''[[on.returnKey]]'''() is called when the '''return''' key is pressed.
*'''[[on.contextMenu]]'''() is called when the combo-key '''Ctrl Menu''' is pressed.
*'''[[on.backtabKey]]'''() is called when the combo-key '''Maj Tab''' is pressed.
*'''[[on.clearKey]]'''() is called when the combo-key '''Ctrl Clear''' is pressed.
*'''[[on.help]]'''() is called when the combo-key '''Ctrl H''' is pressed.

*'''[[on.charIn]]'''(string) is called when the Nspire detects a non arrow key being pressed. ch is the character it detect. If you want to auto start an event in the file linked to key r(like a reset) put on.charIn(“r”) where you want.

*'''[[on.blink]]'''() ? is called when the focus is lost on the page (like launching the document, changing page etc...)

----

*'''[[on.deactivate]]'''() ? is called when the focus is lost on the page (like launching the document, changing page etc...)
*'''[[on.activate]]'''() ? is called when the focus is on the page (like launching the document, changing page etc...)

----

*'''[[on.mouseDown]]'''(x, y) is called when we press the left mouse button. X and Y are the pressed point coordinates.
*'''[[on.mouseUp]]'''() is called when we release the left mouse button.
*'''[[on.mouseMove]]'''() is called when the mouse moves
*'''[[on.grabDown]]'''() ? (software only ?)
*'''[[on.grabMove]]'''() ? (software only ?)
*'''[[on.grabUp]]'''() ? (software only ?)
*'''[[on.rightMouseDown]]'''() ? (software only ?)
*'''[[on.rightMouseUp]]'''() ? (software only ?)

----

*'''[[on.cutEnabled]]'''() ? (software only ?)
*'''[[on.copyEnabled]]'''() ? (software only ?)
*'''[[on.pasteEnabled]]'''() ? (software only ?)
*'''[[on.cut]]'''() ? (software only ?)
*'''[[on.copy]]'''() ? (software only ?)
*'''[[on.paste]]'''() ? (software only ?)

----

== D2Editor ==

*'''[[D2Editor.newRichText]]'''() creates a new RichText object (default values : x, y, width, height = 0)
*'''[[D2Editor.resize]]'''(width, height)
*'''[[D2Editor.move]]'''(x, y)
*'''[[D2Editor.setText]]'''(string)
*'''[[D2Editor.getText]]'''() returns the RichText value
*'''[[D2Editor.setReadOnly]]'''(bool) bool : true/false : If true, the content becomes read-only, i.e. non-editable.
*'''[[D2Editor.setFormattedText]]'''() - ?

Example of a valid function using the D2Editor
<source lang="lua">
function createRichTextBox
box = D2Editor.newRichText()
box:move(50, 50)
box:resize(50, 50)
box:setText("Hello World !")
end</source>

== External Links ==

An interesting page about LUA code optimization, that can be really useful, especially for calculators : [http://trac.caspring.org/wiki/LuaPerformance Lua Performance]

== Online Demo ==

[[Document Player]]

Overview of the API

2013-06-29T09:46:40Z

Jonius7: /* Standard Library */

Note: Neither the ''io'' nor ''os'' libraries are present for the TI-Nspire, which seems to be running a light version of Lua 5.1.4.

== Standard Library ==

( This has been taken from [http://www.wowwiki.com/Lua_functions a WoWWiki page] - See the full, official documentation [http://www.lua.org/manual/5.1/manual.html here] )

=== Basic Library Functions ===

*'''[[G]]''' - Global Variable - A global variable (not a function) that holds the global environment (that is, _G._G = _G). Lua itself does not use this variable; changing its value does not affect any environment, nor vice-versa. (Use setfenv to change environments.) - taken from Lua docs
*'''[[assert]]'''(value[, errormsg]) - asserts a value evaluates to true. If it is, returns value, otherwise causes a Lua error to be thrown.
*'''[[collectgarbage]]'''
*'''[[error]]'''
*'''[[getfenv]]'''(function or integer) - Returns the table representing the stack frame of the given function or stack level.
*'''[[getmetatable]]'''(obj, mtable) - Returns the metatable of the given table or userdata object.
*'''[[next]]'''(table, index) - Returns the next key, value pair of the table, allowing you to walk over the table.
*'''[[newproxy]]'''(boolean or proxy) - Creates a userdata with a sharable metatable.
*'''[[print]]''' - print (···) - Receives any number of arguments, and prints their values to stdout, using the tostring function to convert them to strings. print is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use string.format. - taken from Lua Docs
*'''[[select]]'''(index, list) - Returns the number of items in list or the value of the item in list at index.
*'''[[setfenv]]'''(function or integer, table) - Sets the table representing the stack frame of the given function or stack level.
*'''[[setmetatable]]'''(obj, mtable) - Sets the metatable of the given table or userdata object.
*'''[[tostring]]''' - tostring (e) - Receives an argument of any type and converts it to a string in a reasonable format. For complete control of how numbers are converted, use string.format. If the metatable of e has a "__tostring" field, then tostring calls the corresponding value with e as argument, and uses the result of the call as its result. - taken from Lua Docs.
*'''[[tonumber]]''' - tonumber (e) - Receives an argument of the string type and converts it to a number when possible. If the metatable of e has a "__tonumber" field, then tonumber calls the corresponding value with e as argument, and uses the result of the call as its result. - taken from Lua Docs.

*'''[[type]]'''(var) - Returns the type of variable as a string, "number", "string", "table", "function" or "userdata".
*'''[[unpack]]'''(table[, start][, end]) - Returns the contents of its argument as separate values.
*'''[[xpcall]]'''(func, err) - Returns a boolean indicating successful execution of func and calls err on failure, additionally returning func's or err's results.

=== String Library ===
byte char dump find format gmatch gsub len lower match rep reverse sub upper

=== Math Library ===
abs acos asin atan atan2 ceil cos cosh deg exp oor fmod frexp huge ldexp log log10 max min modf pi pow rad random randomseed sin sinh sqrt tan tanh

More information about the other libraries can be found on the [[Extended Standard Library]] Page

== Concepts and Basics ==

This part will explain you how the Lua actually works inside the OS and help you to figure out what you're doing when you write a script for the TI-Nspire. Before reading this, you have to know all about the Lua basics.

The Lua is an interpreted script language which means that it isn't as fast as ASM/C programs, but is still better than the TI-BASIC. One good thing is that this language is in a complete harmony with the OS with basic events and a powerfull graphic context. First, we have to understand how this works. Basicly the script is launched before the executive engine. This means that we can neither evaluate expressions nor use some of the standard API (like platform, var) until the engine is launched. Here is a call summary :

*Launch string library
*Launch math library
*...
*Open and launch User's Lua script
*...
*Launch var API (store, recall, ...)
*Launch platform API (window, gc, ...)
*...
*Link events (pseudo code)
<source lang="lua">while(Exit)
------- Some OS routines here

---- Begin of Event link
buffer:captureDataFromKeyPad() -- (N) some underground routines to catch events
if buffer.charInput ~= "" then -- (N)
on.charIn(buffer.charInput)
buffer.charInput= "" -- (N)
end
if buffer.arrowKey ~= "" then -- (N)
on.arrowKey(buffer.arrowKey)
buffer.arrowKey = "" -- (N)
end
----- etc ...
if platform.window.isInvalidate then
platform.gc():purge() -- (N) Empty buffer before starting to draw
on.paint(platform.gc()) -- save all the things we have to draw
platform:paint() -- (N) draw all those things
platform.window.isInvalidate = false -- say that the window has been drawn
end
----- End of Event link
end''
Note : the (N) commented line only indicates the meaning of the routine. Those functions don't really exist.</source>

Now we can understand how everything is linked, just by a main loop. This helps you to understand that you don't have to code a loop yourself, because the screen wouldn't be refreshed. This also helps to see when the screen gets refreshed. In other words, we cannot use niether '''gc''' nor '''platform.gc()''' (which are the same) in order to draw somthing on the screen if we are outside of '''on.paint()''' (except if your outside function is called within on.paint() ). This also means that we don't need to pass '''gc''' as parameter, because we can rather use '''platform.gc()''' for any functions called within on.paint(). This is exactly what [https://github.com/adriweb/BetterLuaAPI-for-TI-Nspire/blob/master/BetterLuaAPI.lua the BetterLuaAPI library for Nspire] does.

Here is an example of a simple Lua program that displays a message only when a key is pressed (and let the screen blank otherwise).
<source lang="lua"> function on.paint(gc)
if message then
gc:setFont("sansserif", "r", 10) -- initialize font drawing
gc:drawString(message, 0, 0, "top") -- display the message at (0, 0) coordinates
message = nil -- erase the message
timer.start(1) -- start a timer to exit on.paint() but keep in mind that we have to redraw the screen
end
end

function on.timer()
timer.stop()
platform.window:invalidate()
end

function on.charIn(ch)
message = "Hello World !" -- store a message
platform.window:invalidate() -- force display
end</source>
When you open the document, the script is read once. It initializes and overwrites all the functions and globals with the ones you defined. Thus, '''message''' is nil. Once the '''on.paint()''' event is called, '''message''' is nil, thus, nothing is done. When you press a key that calls '''on.charIn()''' (see below for more information), '''message''' is now "Hello World" and we tell the '''platform''' that the screen has to be refreshed. Then, '''on.paint()''' is called again, '''message''' is not nil then we display it, erase '''message''' and launch a timer. Why is that ? Because if we call '''platform.window:invalidate()''' right there, we won't refresh the screen. Why again ? Just look at the pseudo-code above. We set the window as drawn after each call of on.paint(). Thus a timer is necessary to manually recall '''on.paint()''' and exit the '''on.paint()''' function to draw the screen. When the timer is ended, '''on.timer()''' is called and we refresh the screen. The screen is then redrawn but there is nothing to draw because '''message''' is nil. Thus, the graphic context lets the screen blank.

== gc (as in Graphics Context) ==

Note: You need to add “gc:” before each of these commands in order to use them. ex. '''gc:setAlpha(...)'''. You can also call gc like this : '''platform.gc():setAlpha(...)'''. Then you can use the gc library in a function where gc is not passed as an argument. but this function *has* to be called within '''on.paint(gc)'''

The maximum screen resolution available to Lua programs is 318 by 212 pixels.

*'''[[gc:begin]]''' -
*'''[[gc:clipRect]]''' -
*'''[[gc:drawArc]]'''(x, y, width, height, start angle, finish angle) Note, to draw a circle, use drawArc(x - diameter/2, y - diameter/2, diameter,diameter,0,360) where x and y are the coordinates of the middle.
*'''[[gc:drawImage]]'''(image,x,y) First argument in format “[[TI.Image]]”, x and y the coords.
*'''[[gc:drawLine]]'''(xstart, ystart, xend, yend) Draws a line starting at the point (xstart,ystart) and ending at the point (xend, yend)
*'''[[gc:drawPolyLine]]'''(int list1 [,int list2, .., int listN]) Draws a shape from a list contaning successively the x and y coordinates of each point the line have to draw.

*'''[[gc:drawRect]]'''(x, y, xwidth, yheight) Draws a rectangle at (x,y) with the “x” side being “xwidth” long and the “y” side being “yheight” long
*'''[[gc:drawString]]'''(string, x, y, PositionString) PositionString is the string’s anchor point and can be “bottom”, “middle”, or “top”.
*'''[[gc:fillArc]]'''(x, y, width, height, start angle, finish angle) see drawArc
*'''[[gc:fillPolygon]]'''(int list1 [,int list2, .., int listN]) see drawPolyLine
*'''[[gc:fillRect]]'''(x, y, width, height) see drawRect
*'''[[gc:finish]]''' -
*'''[[gc:getStringHeight]]'''(string)
*'''[[gc:getStringWidth]]'''(string)
*'''[[gc:isColorDisplay]]''' Bool (Read-only) Returns 1 if color, 0 if not.
*'''[[gc:setAlpha]]'''(int) - where the argument is an int between 0 and 255. Sets the transparency.
*'''[[gc:setColorRGB]]'''(red, green, blue) RGB values are integers, from 0 to 255.
*'''[[gc:setFont]]'''(font, type, size), with font : {“sansserif”, "serif", ..}, type {“b”, “r”, “i”}, size(int)
*'''[[gc:setPen]]'''(size, smooth) size {“thin”, “medium”, "thick"}, smooth {“smooth”, "dotted", "dashed"}

== platform ==

These are mainly read-only. These work by writing "'''platform.'''" in front of them. Example : "'''platform.window:invalidate()'''"

*'''[[platform.apilevel]]''' : Returns the version of the API. Currently (OS 3.0.1) returns 1.0.0.
*'''[[platform.window]]'''

:*'''[[platform.window:width]]''' - Returns the width of the window. Ex : ''platform.window:height()''
:*'''[[platform.window:height]]''' - Returns the height of the window
:*'''[[platform.window:invalidate]]''' - Repaints the window (it calls '''on.paint(gc)''')

*'''[[platform.isDeviceModeRendering]]''' Returns true or false whether the unit is "rendering" or not
*'''[[platform.gc]]''' - Other way to call '''gc'''. Use it like that : '''platform.gc():setAlpha(...)''' for example. This is useful when you're in a function outside '''on.paint(gc)''' (but this function has to be called within [[on.paint]](gc).)
*'''[[platform.isColorDisplay]]''' Returns ''true'' if the unit the code is being run on has a color display (-> Nspire CX), and ''false'' otherwise.

== cursor ==

*'''[[cursor.hide]]'''() - hides the cursor (mouse pointer)
*'''[[cursor.set]]'''(string) - string can be one of those : (interrogation, crosshair, text, pointer, link select, diag resize, wait busy, hollow pointer, rotation, pencil, zoom box, arrow, zoom out, dotted arrow, clear, animate, excel plus, mod label, writing, unavailable, resize row, resize column, drag grab, hand open, hand closed, hand pointer, zoom in, dilation, translation).
*'''[[cursor.show]]'''() - Shows the cursor on screen

== document ==

*'''[[document.markChanged]]'''() - Flag the document as "changed" so the user has to save it after using it.

== clipboard ==

*'''[[clipboard.addText]]'''()
*'''[[clipboard.getText]]'''()

== locale ==

*'''[[locale.name]]'''() - Returns the current language the calculator is set in, formatted as ISO-639 (i.e : "fr", "en", "it" ...).

== image ==

*'''[[image.copy]]'''(image, width, height) - returns a new Image which has a new scale. Width is the final width, Heigth, the final height of the image.
*'''[[image.height]]'''(image) - returns the height of the image given in parameter
*'''[[image.new]]'''(string) - Creates a new image from the string given in parameter (see TI.Image).
*'''[[image.width]]'''(image) - returns the width of the image given in parameter

== timer ==

*'''[[timer.getMilliSecCounter]]'''() - Returns the amount of milliseconds elapsed since last calculator reboot. (in TI's Computer software, returns an absolute negative time)
*'''[[timer.start]]'''(int) - Starts a timer with 1 second.
*'''[[timer.stop]]'''() - Stops a timer

== toolpalette ==

*'''[[toolpalette.enable]]'''(string)
*'''[[toolpalette.enableCopy]]'''()
*'''[[toolpalette.enableCut]]'''()
*'''[[toolpalette.enablePaste]]'''()
*'''[[toolpalette.register]]'''(table)

== var ==

*'''[[var.list]]'''() - returns a list of all the variables in the entire Activity
*'''[[var.monitor]]'''() - ?
*'''[[var.recall]]'''(string) - returns the variable value which name is given in parameter
*'''[[var.recallstr]]'''(string) - returns the variable value converted to string which name is given in parameter
*'''[[var.store]]'''(string, value) - store in the variable, which name is given in parameter, the value
*'''[[var.unmonitor]]'''() - ?

== Events ==

*'''[[on.paint]]'''(gc) is called when the GUI is painted. 'gc' is the Graphics Context (see above)
*'''[[on.resize]]'''() is called when the window is rezised
*'''[[on.timer]]'''() is called when the timer has been finished. Here an example of using timer to play an animation :
<source lang="lua"> x = 1
animating = false
function on.paint(gc)
gc:setFont("sansserif", "r", 10)
gc:drawString(tostring(x), 0, 0, "top")
if animating then
x = x + 1
timer.start(0.5)
end
end

function on.charIn(ch)
animating = not animating -- switch state
platform.window:invalidate() -- recall graph engine
end

function on.timer()
timer.stop()
platform.window:invalidate() -- recall graph engine
end
</source>
----

*'''[[on.arrowKey]]'''(key) is called when an '''arrow key''' from the clickPad/TouchPad is pressed (right, left, up, down)
*'''[[on.arrowLeft]]'''() is called when the '''left''' arrow is pressed
*'''[[on.arrowRight]]'''() is called when the '''right''' arrow is pressed
*'''[[on.arrowUp]]'''() is called when the up '''arrow''' is pressed
*'''[[on.arrowDown]]'''() is called when the '''down''' arrow is pressed

----

*'''[[on.up]]'''() -- probably for the touchpad up motion
*'''[[on.down]]'''() -- probably for the touchpad down motion

----

*'''[[on.enterKey]]'''() is called when the '''enter''' key is pressed.
*'''[[on.escapeKey]]'''() is called when the '''escape''' key is pressed.
*'''[[on.tabKey]]'''() is called when the '''tab''' key is pressed.
*'''[[on.deleteKey]]'''() is called when the '''delete''' key is pressed.
*'''[[on.backspaceKey]]'''() is called when the '''clear''' key is pressed.
*'''[[on.returnKey]]'''() is called when the '''return''' key is pressed.
*'''[[on.contextMenu]]'''() is called when the combo-key '''Ctrl Menu''' is pressed.
*'''[[on.backtabKey]]'''() is called when the combo-key '''Maj Tab''' is pressed.
*'''[[on.clearKey]]'''() is called when the combo-key '''Ctrl Clear''' is pressed.
*'''[[on.help]]'''() is called when the combo-key '''Ctrl H''' is pressed.

*'''[[on.charIn]]'''(string) is called when the Nspire detects a non arrow key being pressed. ch is the character it detect. If you want to auto start an event in the file linked to key r(like a reset) put on.charIn(“r”) where you want.

*'''[[on.blink]]'''() ? is called when the focus is lost on the page (like launching the document, changing page etc...)

----

*'''[[on.deactivate]]'''() ? is called when the focus is lost on the page (like launching the document, changing page etc...)
*'''[[on.activate]]'''() ? is called when the focus is on the page (like launching the document, changing page etc...)

----

*'''[[on.mouseDown]]'''(x, y) is called when we press the left mouse button. X and Y are the pressed point coordinates.
*'''[[on.mouseUp]]'''() is called when we release the left mouse button.
*'''[[on.mouseMove]]'''() is called when the mouse moves
*'''[[on.grabDown]]'''() ? (software only ?)
*'''[[on.grabMove]]'''() ? (software only ?)
*'''[[on.grabUp]]'''() ? (software only ?)
*'''[[on.rightMouseDown]]'''() ? (software only ?)
*'''[[on.rightMouseUp]]'''() ? (software only ?)

----

*'''[[on.cutEnabled]]'''() ? (software only ?)
*'''[[on.copyEnabled]]'''() ? (software only ?)
*'''[[on.pasteEnabled]]'''() ? (software only ?)
*'''[[on.cut]]'''() ? (software only ?)
*'''[[on.copy]]'''() ? (software only ?)
*'''[[on.paste]]'''() ? (software only ?)

----

== D2Editor ==

*'''[[D2Editor.newRichText]]'''() creates a new RichText object (default values : x, y, width, height = 0)
*'''[[D2Editor.resize]]'''(width, height)
*'''[[D2Editor.move]]'''(x, y)
*'''[[D2Editor.setText]]'''(string)
*'''[[D2Editor.getText]]'''() returns the RichText value
*'''[[D2Editor.setReadOnly]]'''(bool) bool : true/false : If true, the content becomes read-only, i.e. non-editable.
*'''[[D2Editor.setFormattedText]]'''() - ?

Example of a valid function using the D2Editor
<source lang="lua">
function createRichTextBox
box = D2Editor.newRichText()
box:move(50, 50)
box:resize(50, 50)
box:setText("Hello World !")
end</source>

== External Links ==

An interesting page about LUA code optimization, that can be really useful, especially for calculators : [http://trac.caspring.org/wiki/LuaPerformance Lua Performance]

== Online Demo ==

[[Document Player]]

Overview of the API

2013-06-29T09:42:57Z

Jonius7: /* Standard Library */

Note: Neither the ''io'' nor ''os'' libraries are present for the TI-Nspire, which seems to be running a light version of Lua 5.1.4.

== Standard Library ==

( This has been taken from [http://www.wowwiki.com/Lua_functions a WoWWiki page] - See the full, official documentation [http://www.lua.org/manual/5.1/manual.html here] )

=== Basic Library Functions ===

*'''[[G]]''' - Global Variable - A global variable (not a function) that holds the global environment (that is, _G._G = _G). Lua itself does not use this variable; changing its value does not affect any environment, nor vice-versa. (Use setfenv to change environments.) - taken from Lua docs
*'''[[assert]]'''(value[, errormsg]) - asserts a value evaluates to true. If it is, returns value, otherwise causes a Lua error to be thrown.
*'''[[collectgarbage]]'''
*'''[[error]]'''
*'''[[getfenv]]'''(function or integer) - Returns the table representing the stack frame of the given function or stack level.
*'''[[getmetatable]]'''(obj, mtable) - Returns the metatable of the given table or userdata object.
*'''[[next]]'''(table, index) - Returns the next key, value pair of the table, allowing you to walk over the table.
*'''[[newproxy]]'''(boolean or proxy) - Creates a userdata with a sharable metatable.
*'''[[print]]''' - print (···) - Receives any number of arguments, and prints their values to stdout, using the tostring function to convert them to strings. print is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use string.format. - taken from Lua Docs
*'''[[select]]'''(index, list) - Returns the number of items in list or the value of the item in list at index.
*'''[[setfenv]]'''(function or integer, table) - Sets the table representing the stack frame of the given function or stack level.
*'''[[setmetatable]]'''(obj, mtable) - Sets the metatable of the given table or userdata object.
*'''[[tostring]]''' - tostring (e) - Receives an argument of any type and converts it to a string in a reasonable format. For complete control of how numbers are converted, use string.format. If the metatable of e has a "__tostring" field, then tostring calls the corresponding value with e as argument, and uses the result of the call as its result. - taken from Lua Docs.
*'''[[tonumber]]''' - tonumber (e) - Receives an argument of the string type and converts it to a number when possible. If the metatable of e has a "__tonumber" field, then tonumber calls the corresponding value with e as argument, and uses the result of the call as its result. - taken from Lua Docs.

*'''[[type]]'''(var) - Returns the type of variable as a string, "number", "string", "table", "function" or "userdata".
*'''[[unpack]]'''(table[, start][, end]) - Returns the contents of its argument as separate values.
*'''[[xpcall]]'''(func, err) - Returns a boolean indicating successful execution of func and calls err on failure, additionally returning func's or err's results.

=== String Library ===
byte char dump �nd format gmatch gsub len lower match rep reverse sub upper

=== Math Library ===
abs acos asin atan atan2 ceil cos cosh deg exp oor fmod frexp huge ldexp log log10 max min modf pi pow rad random randomseed sin sinh sqrt tan tanh

== Concepts and Basics ==

This part will explain you how the Lua actually works inside the OS and help you to figure out what you're doing when you write a script for the TI-Nspire. Before reading this, you have to know all about the Lua basics.

The Lua is an interpreted script language which means that it isn't as fast as ASM/C programs, but is still better than the TI-BASIC. One good thing is that this language is in a complete harmony with the OS with basic events and a powerfull graphic context. First, we have to understand how this works. Basicly the script is launched before the executive engine. This means that we can neither evaluate expressions nor use some of the standard API (like platform, var) until the engine is launched. Here is a call summary :

*Launch string library
*Launch math library
*...
*Open and launch User's Lua script
*...
*Launch var API (store, recall, ...)
*Launch platform API (window, gc, ...)
*...
*Link events (pseudo code)
<source lang="lua">while(Exit)
------- Some OS routines here

---- Begin of Event link
buffer:captureDataFromKeyPad() -- (N) some underground routines to catch events
if buffer.charInput ~= "" then -- (N)
on.charIn(buffer.charInput)
buffer.charInput= "" -- (N)
end
if buffer.arrowKey ~= "" then -- (N)
on.arrowKey(buffer.arrowKey)
buffer.arrowKey = "" -- (N)
end
----- etc ...
if platform.window.isInvalidate then
platform.gc():purge() -- (N) Empty buffer before starting to draw
on.paint(platform.gc()) -- save all the things we have to draw
platform:paint() -- (N) draw all those things
platform.window.isInvalidate = false -- say that the window has been drawn
end
----- End of Event link
end''
Note : the (N) commented line only indicates the meaning of the routine. Those functions don't really exist.</source>

Now we can understand how everything is linked, just by a main loop. This helps you to understand that you don't have to code a loop yourself, because the screen wouldn't be refreshed. This also helps to see when the screen gets refreshed. In other words, we cannot use niether '''gc''' nor '''platform.gc()''' (which are the same) in order to draw somthing on the screen if we are outside of '''on.paint()''' (except if your outside function is called within on.paint() ). This also means that we don't need to pass '''gc''' as parameter, because we can rather use '''platform.gc()''' for any functions called within on.paint(). This is exactly what [https://github.com/adriweb/BetterLuaAPI-for-TI-Nspire/blob/master/BetterLuaAPI.lua the BetterLuaAPI library for Nspire] does.

Here is an example of a simple Lua program that displays a message only when a key is pressed (and let the screen blank otherwise).
<source lang="lua"> function on.paint(gc)
if message then
gc:setFont("sansserif", "r", 10) -- initialize font drawing
gc:drawString(message, 0, 0, "top") -- display the message at (0, 0) coordinates
message = nil -- erase the message
timer.start(1) -- start a timer to exit on.paint() but keep in mind that we have to redraw the screen
end
end

function on.timer()
timer.stop()
platform.window:invalidate()
end

function on.charIn(ch)
message = "Hello World !" -- store a message
platform.window:invalidate() -- force display
end</source>
When you open the document, the script is read once. It initializes and overwrites all the functions and globals with the ones you defined. Thus, '''message''' is nil. Once the '''on.paint()''' event is called, '''message''' is nil, thus, nothing is done. When you press a key that calls '''on.charIn()''' (see below for more information), '''message''' is now "Hello World" and we tell the '''platform''' that the screen has to be refreshed. Then, '''on.paint()''' is called again, '''message''' is not nil then we display it, erase '''message''' and launch a timer. Why is that ? Because if we call '''platform.window:invalidate()''' right there, we won't refresh the screen. Why again ? Just look at the pseudo-code above. We set the window as drawn after each call of on.paint(). Thus a timer is necessary to manually recall '''on.paint()''' and exit the '''on.paint()''' function to draw the screen. When the timer is ended, '''on.timer()''' is called and we refresh the screen. The screen is then redrawn but there is nothing to draw because '''message''' is nil. Thus, the graphic context lets the screen blank.

== gc (as in Graphics Context) ==

Note: You need to add “gc:” before each of these commands in order to use them. ex. '''gc:setAlpha(...)'''. You can also call gc like this : '''platform.gc():setAlpha(...)'''. Then you can use the gc library in a function where gc is not passed as an argument. but this function *has* to be called within '''on.paint(gc)'''

The maximum screen resolution available to Lua programs is 318 by 212 pixels.

*'''[[gc:begin]]''' -
*'''[[gc:clipRect]]''' -
*'''[[gc:drawArc]]'''(x, y, width, height, start angle, finish angle) Note, to draw a circle, use drawArc(x - diameter/2, y - diameter/2, diameter,diameter,0,360) where x and y are the coordinates of the middle.
*'''[[gc:drawImage]]'''(image,x,y) First argument in format “[[TI.Image]]”, x and y the coords.
*'''[[gc:drawLine]]'''(xstart, ystart, xend, yend) Draws a line starting at the point (xstart,ystart) and ending at the point (xend, yend)
*'''[[gc:drawPolyLine]]'''(int list1 [,int list2, .., int listN]) Draws a shape from a list contaning successively the x and y coordinates of each point the line have to draw.

*'''[[gc:drawRect]]'''(x, y, xwidth, yheight) Draws a rectangle at (x,y) with the “x” side being “xwidth” long and the “y” side being “yheight” long
*'''[[gc:drawString]]'''(string, x, y, PositionString) PositionString is the string’s anchor point and can be “bottom”, “middle”, or “top”.
*'''[[gc:fillArc]]'''(x, y, width, height, start angle, finish angle) see drawArc
*'''[[gc:fillPolygon]]'''(int list1 [,int list2, .., int listN]) see drawPolyLine
*'''[[gc:fillRect]]'''(x, y, width, height) see drawRect
*'''[[gc:finish]]''' -
*'''[[gc:getStringHeight]]'''(string)
*'''[[gc:getStringWidth]]'''(string)
*'''[[gc:isColorDisplay]]''' Bool (Read-only) Returns 1 if color, 0 if not.
*'''[[gc:setAlpha]]'''(int) - where the argument is an int between 0 and 255. Sets the transparency.
*'''[[gc:setColorRGB]]'''(red, green, blue) RGB values are integers, from 0 to 255.
*'''[[gc:setFont]]'''(font, type, size), with font : {“sansserif”, "serif", ..}, type {“b”, “r”, “i”}, size(int)
*'''[[gc:setPen]]'''(size, smooth) size {“thin”, “medium”, "thick"}, smooth {“smooth”, "dotted", "dashed"}

== platform ==

These are mainly read-only. These work by writing "'''platform.'''" in front of them. Example : "'''platform.window:invalidate()'''"

*'''[[platform.apilevel]]''' : Returns the version of the API. Currently (OS 3.0.1) returns 1.0.0.
*'''[[platform.window]]'''

:*'''[[platform.window:width]]''' - Returns the width of the window. Ex : ''platform.window:height()''
:*'''[[platform.window:height]]''' - Returns the height of the window
:*'''[[platform.window:invalidate]]''' - Repaints the window (it calls '''on.paint(gc)''')

*'''[[platform.isDeviceModeRendering]]''' Returns true or false whether the unit is "rendering" or not
*'''[[platform.gc]]''' - Other way to call '''gc'''. Use it like that : '''platform.gc():setAlpha(...)''' for example. This is useful when you're in a function outside '''on.paint(gc)''' (but this function has to be called within [[on.paint]](gc).)
*'''[[platform.isColorDisplay]]''' Returns ''true'' if the unit the code is being run on has a color display (-> Nspire CX), and ''false'' otherwise.

== cursor ==

*'''[[cursor.hide]]'''() - hides the cursor (mouse pointer)
*'''[[cursor.set]]'''(string) - string can be one of those : (interrogation, crosshair, text, pointer, link select, diag resize, wait busy, hollow pointer, rotation, pencil, zoom box, arrow, zoom out, dotted arrow, clear, animate, excel plus, mod label, writing, unavailable, resize row, resize column, drag grab, hand open, hand closed, hand pointer, zoom in, dilation, translation).
*'''[[cursor.show]]'''() - Shows the cursor on screen

== document ==

*'''[[document.markChanged]]'''() - Flag the document as "changed" so the user has to save it after using it.

== clipboard ==

*'''[[clipboard.addText]]'''()
*'''[[clipboard.getText]]'''()

== locale ==

*'''[[locale.name]]'''() - Returns the current language the calculator is set in, formatted as ISO-639 (i.e : "fr", "en", "it" ...).

== image ==

*'''[[image.copy]]'''(image, width, height) - returns a new Image which has a new scale. Width is the final width, Heigth, the final height of the image.
*'''[[image.height]]'''(image) - returns the height of the image given in parameter
*'''[[image.new]]'''(string) - Creates a new image from the string given in parameter (see TI.Image).
*'''[[image.width]]'''(image) - returns the width of the image given in parameter

== timer ==

*'''[[timer.getMilliSecCounter]]'''() - Returns the amount of milliseconds elapsed since last calculator reboot. (in TI's Computer software, returns an absolute negative time)
*'''[[timer.start]]'''(int) - Starts a timer with 1 second.
*'''[[timer.stop]]'''() - Stops a timer

== toolpalette ==

*'''[[toolpalette.enable]]'''(string)
*'''[[toolpalette.enableCopy]]'''()
*'''[[toolpalette.enableCut]]'''()
*'''[[toolpalette.enablePaste]]'''()
*'''[[toolpalette.register]]'''(table)

== var ==

*'''[[var.list]]'''() - returns a list of all the variables in the entire Activity
*'''[[var.monitor]]'''() - ?
*'''[[var.recall]]'''(string) - returns the variable value which name is given in parameter
*'''[[var.recallstr]]'''(string) - returns the variable value converted to string which name is given in parameter
*'''[[var.store]]'''(string, value) - store in the variable, which name is given in parameter, the value
*'''[[var.unmonitor]]'''() - ?

== Events ==

*'''[[on.paint]]'''(gc) is called when the GUI is painted. 'gc' is the Graphics Context (see above)
*'''[[on.resize]]'''() is called when the window is rezised
*'''[[on.timer]]'''() is called when the timer has been finished. Here an example of using timer to play an animation :
<source lang="lua"> x = 1
animating = false
function on.paint(gc)
gc:setFont("sansserif", "r", 10)
gc:drawString(tostring(x), 0, 0, "top")
if animating then
x = x + 1
timer.start(0.5)
end
end

function on.charIn(ch)
animating = not animating -- switch state
platform.window:invalidate() -- recall graph engine
end

function on.timer()
timer.stop()
platform.window:invalidate() -- recall graph engine
end
</source>
----

*'''[[on.arrowKey]]'''(key) is called when an '''arrow key''' from the clickPad/TouchPad is pressed (right, left, up, down)
*'''[[on.arrowLeft]]'''() is called when the '''left''' arrow is pressed
*'''[[on.arrowRight]]'''() is called when the '''right''' arrow is pressed
*'''[[on.arrowUp]]'''() is called when the up '''arrow''' is pressed
*'''[[on.arrowDown]]'''() is called when the '''down''' arrow is pressed

----

*'''[[on.up]]'''() -- probably for the touchpad up motion
*'''[[on.down]]'''() -- probably for the touchpad down motion

----

*'''[[on.enterKey]]'''() is called when the '''enter''' key is pressed.
*'''[[on.escapeKey]]'''() is called when the '''escape''' key is pressed.
*'''[[on.tabKey]]'''() is called when the '''tab''' key is pressed.
*'''[[on.deleteKey]]'''() is called when the '''delete''' key is pressed.
*'''[[on.backspaceKey]]'''() is called when the '''clear''' key is pressed.
*'''[[on.returnKey]]'''() is called when the '''return''' key is pressed.
*'''[[on.contextMenu]]'''() is called when the combo-key '''Ctrl Menu''' is pressed.
*'''[[on.backtabKey]]'''() is called when the combo-key '''Maj Tab''' is pressed.
*'''[[on.clearKey]]'''() is called when the combo-key '''Ctrl Clear''' is pressed.
*'''[[on.help]]'''() is called when the combo-key '''Ctrl H''' is pressed.

*'''[[on.charIn]]'''(string) is called when the Nspire detects a non arrow key being pressed. ch is the character it detect. If you want to auto start an event in the file linked to key r(like a reset) put on.charIn(“r”) where you want.

*'''[[on.blink]]'''() ? is called when the focus is lost on the page (like launching the document, changing page etc...)

----

*'''[[on.deactivate]]'''() ? is called when the focus is lost on the page (like launching the document, changing page etc...)
*'''[[on.activate]]'''() ? is called when the focus is on the page (like launching the document, changing page etc...)

----

*'''[[on.mouseDown]]'''(x, y) is called when we press the left mouse button. X and Y are the pressed point coordinates.
*'''[[on.mouseUp]]'''() is called when we release the left mouse button.
*'''[[on.mouseMove]]'''() is called when the mouse moves
*'''[[on.grabDown]]'''() ? (software only ?)
*'''[[on.grabMove]]'''() ? (software only ?)
*'''[[on.grabUp]]'''() ? (software only ?)
*'''[[on.rightMouseDown]]'''() ? (software only ?)
*'''[[on.rightMouseUp]]'''() ? (software only ?)

----

*'''[[on.cutEnabled]]'''() ? (software only ?)
*'''[[on.copyEnabled]]'''() ? (software only ?)
*'''[[on.pasteEnabled]]'''() ? (software only ?)
*'''[[on.cut]]'''() ? (software only ?)
*'''[[on.copy]]'''() ? (software only ?)
*'''[[on.paste]]'''() ? (software only ?)

----

== D2Editor ==

*'''[[D2Editor.newRichText]]'''() creates a new RichText object (default values : x, y, width, height = 0)
*'''[[D2Editor.resize]]'''(width, height)
*'''[[D2Editor.move]]'''(x, y)
*'''[[D2Editor.setText]]'''(string)
*'''[[D2Editor.getText]]'''() returns the RichText value
*'''[[D2Editor.setReadOnly]]'''(bool) bool : true/false : If true, the content becomes read-only, i.e. non-editable.
*'''[[D2Editor.setFormattedText]]'''() - ?

Example of a valid function using the D2Editor
<source lang="lua">
function createRichTextBox
box = D2Editor.newRichText()
box:move(50, 50)
box:resize(50, 50)
box:setText("Hello World !")
end</source>

== External Links ==

An interesting page about LUA code optimization, that can be really useful, especially for calculators : [http://trac.caspring.org/wiki/LuaPerformance Lua Performance]

== Online Demo ==

[[Document Player]]

Overview of the API

2013-06-29T09:40:42Z

Jonius7: /* Standard Library */

Note: Neither the ''io'' nor ''os'' libraries are present for the TI-Nspire, which seems to be running a light version of Lua 5.1.4.

== Standard Library ==

( This has been taken from [http://www.wowwiki.com/Lua_functions a WoWWiki page] - See the full, official documentation [http://www.lua.org/manual/5.1/manual.html here] )

Basic Library Functions

*'''[[G]]''' - Global Variable - A global variable (not a function) that holds the global environment (that is, _G._G = _G). Lua itself does not use this variable; changing its value does not affect any environment, nor vice-versa. (Use setfenv to change environments.) - taken from Lua docs
*'''[[assert]]'''(value[, errormsg]) - asserts a value evaluates to true. If it is, returns value, otherwise causes a Lua error to be thrown.
*'''[[collectgarbage]]'''
*'''[[error]]'''
*'''[[getfenv]]'''(function or integer) - Returns the table representing the stack frame of the given function or stack level.
*'''[[getmetatable]]'''(obj, mtable) - Returns the metatable of the given table or userdata object.
*'''[[next]]'''(table, index) - Returns the next key, value pair of the table, allowing you to walk over the table.
*'''[[newproxy]]'''(boolean or proxy) - Creates a userdata with a sharable metatable.
*'''[[print]]''' - print (···) - Receives any number of arguments, and prints their values to stdout, using the tostring function to convert them to strings. print is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use string.format. - taken from Lua Docs
*'''[[select]]'''(index, list) - Returns the number of items in list or the value of the item in list at index.
*'''[[setfenv]]'''(function or integer, table) - Sets the table representing the stack frame of the given function or stack level.
*'''[[setmetatable]]'''(obj, mtable) - Sets the metatable of the given table or userdata object.
*'''[[tostring]]''' - tostring (e) - Receives an argument of any type and converts it to a string in a reasonable format. For complete control of how numbers are converted, use string.format. If the metatable of e has a "__tostring" field, then tostring calls the corresponding value with e as argument, and uses the result of the call as its result. - taken from Lua Docs.
*'''[[tonumber]]''' - tonumber (e) - Receives an argument of the string type and converts it to a number when possible. If the metatable of e has a "__tonumber" field, then tonumber calls the corresponding value with e as argument, and uses the result of the call as its result. - taken from Lua Docs.

*'''[[type]]'''(var) - Returns the type of variable as a string, "number", "string", "table", "function" or "userdata".
*'''[[unpack]]'''(table[, start][, end]) - Returns the contents of its argument as separate values.
*'''[[xpcall]]'''(func, err) - Returns a boolean indicating successful execution of func and calls err on failure, additionally returning func's or err's results.

== Concepts and Basics ==

This part will explain you how the Lua actually works inside the OS and help you to figure out what you're doing when you write a script for the TI-Nspire. Before reading this, you have to know all about the Lua basics.

The Lua is an interpreted script language which means that it isn't as fast as ASM/C programs, but is still better than the TI-BASIC. One good thing is that this language is in a complete harmony with the OS with basic events and a powerfull graphic context. First, we have to understand how this works. Basicly the script is launched before the executive engine. This means that we can neither evaluate expressions nor use some of the standard API (like platform, var) until the engine is launched. Here is a call summary :

*Launch string library
*Launch math library
*...
*Open and launch User's Lua script
*...
*Launch var API (store, recall, ...)
*Launch platform API (window, gc, ...)
*...
*Link events (pseudo code)
<source lang="lua">while(Exit)
------- Some OS routines here

---- Begin of Event link
buffer:captureDataFromKeyPad() -- (N) some underground routines to catch events
if buffer.charInput ~= "" then -- (N)
on.charIn(buffer.charInput)
buffer.charInput= "" -- (N)
end
if buffer.arrowKey ~= "" then -- (N)
on.arrowKey(buffer.arrowKey)
buffer.arrowKey = "" -- (N)
end
----- etc ...
if platform.window.isInvalidate then
platform.gc():purge() -- (N) Empty buffer before starting to draw
on.paint(platform.gc()) -- save all the things we have to draw
platform:paint() -- (N) draw all those things
platform.window.isInvalidate = false -- say that the window has been drawn
end
----- End of Event link
end''
Note : the (N) commented line only indicates the meaning of the routine. Those functions don't really exist.</source>

Now we can understand how everything is linked, just by a main loop. This helps you to understand that you don't have to code a loop yourself, because the screen wouldn't be refreshed. This also helps to see when the screen gets refreshed. In other words, we cannot use niether '''gc''' nor '''platform.gc()''' (which are the same) in order to draw somthing on the screen if we are outside of '''on.paint()''' (except if your outside function is called within on.paint() ). This also means that we don't need to pass '''gc''' as parameter, because we can rather use '''platform.gc()''' for any functions called within on.paint(). This is exactly what [https://github.com/adriweb/BetterLuaAPI-for-TI-Nspire/blob/master/BetterLuaAPI.lua the BetterLuaAPI library for Nspire] does.

Here is an example of a simple Lua program that displays a message only when a key is pressed (and let the screen blank otherwise).
<source lang="lua"> function on.paint(gc)
if message then
gc:setFont("sansserif", "r", 10) -- initialize font drawing
gc:drawString(message, 0, 0, "top") -- display the message at (0, 0) coordinates
message = nil -- erase the message
timer.start(1) -- start a timer to exit on.paint() but keep in mind that we have to redraw the screen
end
end

function on.timer()
timer.stop()
platform.window:invalidate()
end

function on.charIn(ch)
message = "Hello World !" -- store a message
platform.window:invalidate() -- force display
end</source>
When you open the document, the script is read once. It initializes and overwrites all the functions and globals with the ones you defined. Thus, '''message''' is nil. Once the '''on.paint()''' event is called, '''message''' is nil, thus, nothing is done. When you press a key that calls '''on.charIn()''' (see below for more information), '''message''' is now "Hello World" and we tell the '''platform''' that the screen has to be refreshed. Then, '''on.paint()''' is called again, '''message''' is not nil then we display it, erase '''message''' and launch a timer. Why is that ? Because if we call '''platform.window:invalidate()''' right there, we won't refresh the screen. Why again ? Just look at the pseudo-code above. We set the window as drawn after each call of on.paint(). Thus a timer is necessary to manually recall '''on.paint()''' and exit the '''on.paint()''' function to draw the screen. When the timer is ended, '''on.timer()''' is called and we refresh the screen. The screen is then redrawn but there is nothing to draw because '''message''' is nil. Thus, the graphic context lets the screen blank.

== gc (as in Graphics Context) ==

Note: You need to add “gc:” before each of these commands in order to use them. ex. '''gc:setAlpha(...)'''. You can also call gc like this : '''platform.gc():setAlpha(...)'''. Then you can use the gc library in a function where gc is not passed as an argument. but this function *has* to be called within '''on.paint(gc)'''

The maximum screen resolution available to Lua programs is 318 by 212 pixels.

*'''[[gc:begin]]''' -
*'''[[gc:clipRect]]''' -
*'''[[gc:drawArc]]'''(x, y, width, height, start angle, finish angle) Note, to draw a circle, use drawArc(x - diameter/2, y - diameter/2, diameter,diameter,0,360) where x and y are the coordinates of the middle.
*'''[[gc:drawImage]]'''(image,x,y) First argument in format “[[TI.Image]]”, x and y the coords.
*'''[[gc:drawLine]]'''(xstart, ystart, xend, yend) Draws a line starting at the point (xstart,ystart) and ending at the point (xend, yend)
*'''[[gc:drawPolyLine]]'''(int list1 [,int list2, .., int listN]) Draws a shape from a list contaning successively the x and y coordinates of each point the line have to draw.

*'''[[gc:drawRect]]'''(x, y, xwidth, yheight) Draws a rectangle at (x,y) with the “x” side being “xwidth” long and the “y” side being “yheight” long
*'''[[gc:drawString]]'''(string, x, y, PositionString) PositionString is the string’s anchor point and can be “bottom”, “middle”, or “top”.
*'''[[gc:fillArc]]'''(x, y, width, height, start angle, finish angle) see drawArc
*'''[[gc:fillPolygon]]'''(int list1 [,int list2, .., int listN]) see drawPolyLine
*'''[[gc:fillRect]]'''(x, y, width, height) see drawRect
*'''[[gc:finish]]''' -
*'''[[gc:getStringHeight]]'''(string)
*'''[[gc:getStringWidth]]'''(string)
*'''[[gc:isColorDisplay]]''' Bool (Read-only) Returns 1 if color, 0 if not.
*'''[[gc:setAlpha]]'''(int) - where the argument is an int between 0 and 255. Sets the transparency.
*'''[[gc:setColorRGB]]'''(red, green, blue) RGB values are integers, from 0 to 255.
*'''[[gc:setFont]]'''(font, type, size), with font : {“sansserif”, "serif", ..}, type {“b”, “r”, “i”}, size(int)
*'''[[gc:setPen]]'''(size, smooth) size {“thin”, “medium”, "thick"}, smooth {“smooth”, "dotted", "dashed"}

== platform ==

These are mainly read-only. These work by writing "'''platform.'''" in front of them. Example : "'''platform.window:invalidate()'''"

*'''[[platform.apilevel]]''' : Returns the version of the API. Currently (OS 3.0.1) returns 1.0.0.
*'''[[platform.window]]'''

:*'''[[platform.window:width]]''' - Returns the width of the window. Ex : ''platform.window:height()''
:*'''[[platform.window:height]]''' - Returns the height of the window
:*'''[[platform.window:invalidate]]''' - Repaints the window (it calls '''on.paint(gc)''')

*'''[[platform.isDeviceModeRendering]]''' Returns true or false whether the unit is "rendering" or not
*'''[[platform.gc]]''' - Other way to call '''gc'''. Use it like that : '''platform.gc():setAlpha(...)''' for example. This is useful when you're in a function outside '''on.paint(gc)''' (but this function has to be called within [[on.paint]](gc).)
*'''[[platform.isColorDisplay]]''' Returns ''true'' if the unit the code is being run on has a color display (-> Nspire CX), and ''false'' otherwise.

== cursor ==

*'''[[cursor.hide]]'''() - hides the cursor (mouse pointer)
*'''[[cursor.set]]'''(string) - string can be one of those : (interrogation, crosshair, text, pointer, link select, diag resize, wait busy, hollow pointer, rotation, pencil, zoom box, arrow, zoom out, dotted arrow, clear, animate, excel plus, mod label, writing, unavailable, resize row, resize column, drag grab, hand open, hand closed, hand pointer, zoom in, dilation, translation).
*'''[[cursor.show]]'''() - Shows the cursor on screen

== document ==

*'''[[document.markChanged]]'''() - Flag the document as "changed" so the user has to save it after using it.

== clipboard ==

*'''[[clipboard.addText]]'''()
*'''[[clipboard.getText]]'''()

== locale ==

*'''[[locale.name]]'''() - Returns the current language the calculator is set in, formatted as ISO-639 (i.e : "fr", "en", "it" ...).

== image ==

*'''[[image.copy]]'''(image, width, height) - returns a new Image which has a new scale. Width is the final width, Heigth, the final height of the image.
*'''[[image.height]]'''(image) - returns the height of the image given in parameter
*'''[[image.new]]'''(string) - Creates a new image from the string given in parameter (see TI.Image).
*'''[[image.width]]'''(image) - returns the width of the image given in parameter

== timer ==

*'''[[timer.getMilliSecCounter]]'''() - Returns the amount of milliseconds elapsed since last calculator reboot. (in TI's Computer software, returns an absolute negative time)
*'''[[timer.start]]'''(int) - Starts a timer with 1 second.
*'''[[timer.stop]]'''() - Stops a timer

== toolpalette ==

*'''[[toolpalette.enable]]'''(string)
*'''[[toolpalette.enableCopy]]'''()
*'''[[toolpalette.enableCut]]'''()
*'''[[toolpalette.enablePaste]]'''()
*'''[[toolpalette.register]]'''(table)

== var ==

*'''[[var.list]]'''() - returns a list of all the variables in the entire Activity
*'''[[var.monitor]]'''() - ?
*'''[[var.recall]]'''(string) - returns the variable value which name is given in parameter
*'''[[var.recallstr]]'''(string) - returns the variable value converted to string which name is given in parameter
*'''[[var.store]]'''(string, value) - store in the variable, which name is given in parameter, the value
*'''[[var.unmonitor]]'''() - ?

== Events ==

*'''[[on.paint]]'''(gc) is called when the GUI is painted. 'gc' is the Graphics Context (see above)
*'''[[on.resize]]'''() is called when the window is rezised
*'''[[on.timer]]'''() is called when the timer has been finished. Here an example of using timer to play an animation :
<source lang="lua"> x = 1
animating = false
function on.paint(gc)
gc:setFont("sansserif", "r", 10)
gc:drawString(tostring(x), 0, 0, "top")
if animating then
x = x + 1
timer.start(0.5)
end
end

function on.charIn(ch)
animating = not animating -- switch state
platform.window:invalidate() -- recall graph engine
end

function on.timer()
timer.stop()
platform.window:invalidate() -- recall graph engine
end
</source>
----

*'''[[on.arrowKey]]'''(key) is called when an '''arrow key''' from the clickPad/TouchPad is pressed (right, left, up, down)
*'''[[on.arrowLeft]]'''() is called when the '''left''' arrow is pressed
*'''[[on.arrowRight]]'''() is called when the '''right''' arrow is pressed
*'''[[on.arrowUp]]'''() is called when the up '''arrow''' is pressed
*'''[[on.arrowDown]]'''() is called when the '''down''' arrow is pressed

----

*'''[[on.up]]'''() -- probably for the touchpad up motion
*'''[[on.down]]'''() -- probably for the touchpad down motion

----

*'''[[on.enterKey]]'''() is called when the '''enter''' key is pressed.
*'''[[on.escapeKey]]'''() is called when the '''escape''' key is pressed.
*'''[[on.tabKey]]'''() is called when the '''tab''' key is pressed.
*'''[[on.deleteKey]]'''() is called when the '''delete''' key is pressed.
*'''[[on.backspaceKey]]'''() is called when the '''clear''' key is pressed.
*'''[[on.returnKey]]'''() is called when the '''return''' key is pressed.
*'''[[on.contextMenu]]'''() is called when the combo-key '''Ctrl Menu''' is pressed.
*'''[[on.backtabKey]]'''() is called when the combo-key '''Maj Tab''' is pressed.
*'''[[on.clearKey]]'''() is called when the combo-key '''Ctrl Clear''' is pressed.
*'''[[on.help]]'''() is called when the combo-key '''Ctrl H''' is pressed.

*'''[[on.charIn]]'''(string) is called when the Nspire detects a non arrow key being pressed. ch is the character it detect. If you want to auto start an event in the file linked to key r(like a reset) put on.charIn(“r”) where you want.

*'''[[on.blink]]'''() ? is called when the focus is lost on the page (like launching the document, changing page etc...)

----

*'''[[on.deactivate]]'''() ? is called when the focus is lost on the page (like launching the document, changing page etc...)
*'''[[on.activate]]'''() ? is called when the focus is on the page (like launching the document, changing page etc...)

----

*'''[[on.mouseDown]]'''(x, y) is called when we press the left mouse button. X and Y are the pressed point coordinates.
*'''[[on.mouseUp]]'''() is called when we release the left mouse button.
*'''[[on.mouseMove]]'''() is called when the mouse moves
*'''[[on.grabDown]]'''() ? (software only ?)
*'''[[on.grabMove]]'''() ? (software only ?)
*'''[[on.grabUp]]'''() ? (software only ?)
*'''[[on.rightMouseDown]]'''() ? (software only ?)
*'''[[on.rightMouseUp]]'''() ? (software only ?)

----

*'''[[on.cutEnabled]]'''() ? (software only ?)
*'''[[on.copyEnabled]]'''() ? (software only ?)
*'''[[on.pasteEnabled]]'''() ? (software only ?)
*'''[[on.cut]]'''() ? (software only ?)
*'''[[on.copy]]'''() ? (software only ?)
*'''[[on.paste]]'''() ? (software only ?)

----

== D2Editor ==

*'''[[D2Editor.newRichText]]'''() creates a new RichText object (default values : x, y, width, height = 0)
*'''[[D2Editor.resize]]'''(width, height)
*'''[[D2Editor.move]]'''(x, y)
*'''[[D2Editor.setText]]'''(string)
*'''[[D2Editor.getText]]'''() returns the RichText value
*'''[[D2Editor.setReadOnly]]'''(bool) bool : true/false : If true, the content becomes read-only, i.e. non-editable.
*'''[[D2Editor.setFormattedText]]'''() - ?

Example of a valid function using the D2Editor
<source lang="lua">
function createRichTextBox
box = D2Editor.newRichText()
box:move(50, 50)
box:resize(50, 50)
box:setText("Hello World !")
end</source>

== External Links ==

An interesting page about LUA code optimization, that can be really useful, especially for calculators : [http://trac.caspring.org/wiki/LuaPerformance Lua Performance]

== Online Demo ==

[[Document Player]]