Overview of the API

From Inspired-Lua Wiki
Jump to: navigation, search

Note: The Lua version that comes with OS 3.x is 5.1.4, without the io nor os libraries.

Tutorials on Nspire Lua scripting in general are available here : http://inspired-lua.org/

Standard Library[edit]

( This has been taken from a WoWWiki page - See the full, official documentation here )

Common Lua Functions[edit]

  • 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 - among other things, force free unused memory.
  • error(str) - generates an error with the str message.
  • 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(...) - Receives any number of arguments, and prints their values. Not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use string.format.
  • 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.

Coroutines Library[edit]

The coroutines are useful tools to control the running of differents parts of a code ("threads").

create, wrap, resume, yield, status, running

More information can be fouded in the coroutines page.

String Library[edit]

byte, char, dump, find, format, gmatch, gsub, len, lower, match, rep, reverse, sub, upper

Math Library[edit]

abs, acos, asin, atan, atan2, ceil, cos, cosh, deg, exp, floor, 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

D2Editor[edit]

The Lua 2D editor bindings enable 2D rich text editors to be created and manipulated within scripts.

  • D2Editor:createChemBox() : Inserts a Chem Box in the current cursor position of the editor.
  • D2Editor:createMathBox() : Inserts a Math Box (Expression Box) in the current cursor position of the editor.
  • D2Editor:getExpression() : Returns the contents of the text editor as a UTF-8 encoded string.
  • D2Editor:getExpressionSelection() : Returns three values: the contents of the text editor (UTF-8 encoded string), the cursor position, and the selection start.
  • D2Editor:getText() : same as getExpression : Returns the contents of the text editor as a UTF-8 encoded string.
  • D2Editor:hasFocus() : Returns true if the editor has focus; otherwise returns false.
  • D2Editor:isVisible() : Returns true if the editor is visible; otherwise returns false.
  • D2Editor:move() : Sets the parent-relative location of the upper left corner of the text editor. Both x and y must be between -32767 and 32767.
  • D2Editor:newRichText() : Creates and returns a new 2D rich text editor.
  • D2Editor:registerFilter(handlerTable) : This routine registers a table of handler functions that can alter events before they are sent to the 2D editor widget, or unregisters if nil is passed.
  • D2Editor:resize(w, h) : Changes the width and height of the text editor. Both width and height must be > 0 and < 32768.
  • D2Editor:setBorder(thickness) : Sets the editor's border thickness. The thickness value must be between 0 and 10.
  • D2Editor:setBorderColor(color) : Sets the editor's border color. The color value must be between 0 and 16777215 (0x000000 and 0xFFFFFF).
  • D2Editor:setColorable(true or false) : Makes the expression colorable or uncolorable.
  • D2Editor:setDisable2DinRT(true or false) : Turns on/off 2D layout of math input to the text box.
  • D2Editor:setExpression(...) : Sets the text content of the text editor.
  • D2Editor:setFocus(true or false) : Sets the user input focus on the editor if true (the default). This is usually called from the on.getFocus event handler.
  • D2Editor:setFontSize(size) : Sets the text font size in the editor. Only 7, 9, 10, 11, 12, or 24 for the handheld, any on the desktop software.
  • D2Editor:setMainFont(family, style) : Sets the main font family ("serif" or "sansserif") and style ("r", "b", "i", "bi").
  • D2Editor:setReadOnly(true or false) : Makes the text editor content modifiable (false) or unmodifiable (true) by the user. If a Boolean value is not specified, defaults to true.
  • D2Editor:setSelectable(true or false) : Makes the text editor content selectable (true) or unselectable (false) by the user. If a Boolean value is not specified, defaults to true.
  • D2Editor:setSizeChangeListener(function(editor, w, h)) : Sets the callback function for when the editor contents exceed the current editor size, when the contents fit on fewer lines, or when the contents fit on a single line of smaller width.
  • D2Editor:setTextChangeListener(function(editor)) : Sets the callback function for when the text expression changes, which will be to the editor object. This allows for processing text input as it occurs.
  • D2Editor:setText(...) : Same as setExpression : Sets the text content of the text editor.
  • D2Editor:setTextColor(color) : Sets the editor text color. The color value must be between 0 and 16777215 (0x000000 and 0xFFFFFF).
  • D2Editor:setVisible(true or false) : Sets the visibility of the text editor.
  • D2Editor:setWordWrapWidth(width) : Sets the rich text editor word-wrapping width in pixels. Ignored if the editor is in 2D mode. To indicate widget width, sets to 0. To disable wrapping, sets to < 0. The width must be -32767 to 32767.

Events[edit]

Events are one of the most fundamental things to know about the Nspire Lua language. You can see how events are managed inside the Lua implementation here.

  • on.paint(gc) is called when the GUI is painted. 'gc' is the Graphics Context
  • on.resize is called when the window is rezised
  • on.timer is called at each timer ticks. See timer.
  • on.arrowKey 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.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 ? is pressed.
  • on.charIn is called when the Nspire detects a non arrow key being pressed.
  • on.createMathBox called when there is a MathBox created.
  • on.create called when the script gets created. Deprecated in 3.2. See on.contruction.
  • on.construction called when the script gets created.
  • on.deactivate called when the focus is lost on the page (like launching the document, changing page etc...)
  • on.activate called when the focus is on the page (like launching the document, changing page etc...)
  • on.destroy is called when the document is about to get closed (or cut)
  • on.getFocus is called when the script receives user input focus.
  • on.loseFocus is called when the script loses user input focus.
  • on.mouseDown 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 is called when the grabbing motion is detected
  • on.grabUp is called after the grabbing action.
  • on.rightMouseDown is called when the user pushes the "right click" button
  • on.rightMouseUp is called when the user releases the "right click" button
  • on.keyboardUp() which fires when the tablet's on-screen keyboard gets shown.
  • on.keyboardDown() which fires when the tablet's on-screen keyboard gets hidden.
  • on.varChange is called when a monitored variable gets changed.
  • on.getSymbolList is called when the script app symbol list is being serialized to the clipboard.
  • on.save is called when the script app is saved to the document or copied to the clipboard.
  • on.restore is called when the script application is restored from its saved state in a document or when the app is pasted into a document..
  • on.cut is called when the user cuts something.
  • on.copy is called when the user copies something.
  • on.paste is called when the user pastes something.

Graphics Operations[edit]

gc is the Nspire's graphic context. A graphics context is a module that has a handle to the script’s graphics output window and a library of graphics routines that are used to draw on the window. A graphics context is supplied to the script ”on.paint” event handler each time the window needs to be redrawn. The graphics context employs a pixel-based coordinate system with the origin in the upper left corner of the drawing window.

  • gc:clipRect(op, x, y, width, height) - Sets the clipping rectangle for subsequent graphics operations.
  • gc:drawArc(x, y, width, height, start angle, finish angle).
  • 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, position) position is the string’s anchor point and can be "baseline", “bottom”, “middle”, or “top”.
  • gc:fillArc(x, y, width, height, start angle, finish angle) see gc:drawArc
  • gc:fillPolygon(int list1 [,int list2, .., int listN]) see gc:drawPolyLine
  • gc:fillRect(x, y, width, height) see gc:drawRect
  • gc:getStringHeight(string) - Returns the string's height.
  • gc:getStringWidth(string) - Returns the string's width
  • gc:setAlpha(alpha) - where alpha is an integer between 0 and 255. Sets the transparency. Not available anymore in 3.2+
  • 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(thickness, smoothness) : thickness {“thin”, “medium”, "thick"}, smoothness {“smooth”, "dotted", "dashed"}

Images[edit]

  • image.copy(theImage, width, height) : Returns a copy of the input image scaled to fit the specified pixel width and height.
  • image.height(theImage) : Returns the height of the image
  • image.new(theImage) : Allocates a new TI.Image
  • image.rotate(theImage, angle) : Returns a rotated copy of theImage by angle degrees
  • image.width(theImage) : Returns the width of the image

Physics Engine[edit]

A port of Chipmunk Physics 5.3 has been embedded as an optional module (you have to 'require' it at the beginning of your script, in order to use it)

  • Arbiters and Collision Pairs
  • Bodies
  • Bounding Boxes
  • Circle Shapes
  • Constraints
  • Misc
  • Polygon Shapes
  • Segment Shapes
  • SegmentQueryInfo
  • Shape Queries
  • Shapes
  • Space Queries
  • Spaces
  • Vectors

Platform[edit]

  • platform.isColorDisplay() : Returns true if the display of the host platform is color-capable (Nspire CX and emulator). Returns false if the display is grayscale (Nspire non-CX).
  • platform.isDeviceModeRendering() : Returns true if the script is running on the hand-held device or in the emulator (with the calculator view), and false if the script is running in the normal view of the emulator.
  • platform.isTabletModeRendering() : Returns true if the script is running on a tablet device (iPad app) and false otherwise.
  • platform.window : Returns the window object currently owned by the script application. The window object contains several other methods.
  • platform.withGC(...) : executes a function which a passed dummy gc.
  • platform.registerErrorHandler(...) : A global error handler for the lua script.
  • platform.hw() : returns a number corresponding to the type of device the script is running on.

Timer[edit]

Toolpalette[edit]

The tool palette provides a menu of commands, selectable by the user, that invoke functionality of the script app. The menu itself is accessible by pressing the "Menu" button.

  • register(menuStructure) : Registers the menuStructure table.
  • enable(toolname, itemname, state) : Enables or disables a menu item in the tool palette.
  • enableCopy(state) : This routine enables / disables the Edit > Copy menu command.
  • enableCut(state) : This routine enables / disables the Edit > Cut menu command.
  • enablePaste(state) : This routine enables / disables the Edit > Paste menu command.

var[edit]

'var' functions allows the script to interact with BASIC variables.

  • var.list() - Lists of names of variables currently used.
  • var.monitor(name) - Turns on monitoring of the math variable with given name.
  • var.unmonitor(name) - Turns off monitoring of the math variable with given name.
  • var.makeNumericList(name) : Creates a list in the symbol table with the given name, which is optimized to hold numeric values.
  • var.recall(name) : Returns the value of a math variable with the given name.
  • var.recallAt(name, col [,row]) : Recalls a value from a cell of a list or matrix in the symbol table.
  • var.recallstr(name) : Returns the value of a math variable with the given name as a string.
  • var.store(name, value) : Stores value as a math variable with the given name.
  • var.storeAt(name, numericValue, col [,row]) : Stores a numeric value into an element of a math list or matrix with the given name.

Misc.[edit]