The NCLua library adds event handling and 2D graphics to Lua scripts.
Programs written in C can use libnclua to run embedded NCLua scripts, i.e.,
Lua scripts that use the APIs exported by libnclua; Lua scripts can also use
libnclua, either through the C API or by requiring the appropriated modules
-- e.g., canvas
for 2D graphics, event
for general event handling,
event.stopwatch
for stopwatch timers, event.tcp_socket
for asynchronous
TCP sockets, event.http_soup
for asynchronous HTTP requests, etc. The
NCLua library comes with a standalone interpreter, called nclua
(cf. src/nclua.c), which can be used to run NCLua scripts.
For stable releases and binaries, cf. http://www.telemidia.puc-rio.br/~gflima/software/nclua.
For the latest sources, cf. https://github.com/gflima/nclua.
NCLua is the Lua dialect used by the Brazilian digital TV middleware, called Ginga (cf. http://www.ginga.org.br). The reference implementation of Ginga (>= 0.14) uses libnclua to run NCLua scripts.
Required:
- Lua >= 5.2, http://www.lua.org
- Cairo >= 1.10, http://cairographics.org
- GLib >= 2.32, https://developer.gnome.org/glib
- Pango >= 1.30, http://www.pango.org
Optional:
- GIO >= 2.32, https://developer.gnome.org/gio
- Libsoup >= 2.42, https://developer.gnome.org/libsoup
- GTK+ >= 3.4.2, http://www.gtk.org
GIO is used by the tcp
event class, Libsoup is used by the http
event
class, and GTK+ is used by the nclua
binary. These libraries are
optional, if they are not present the corresponding modules are not built.
For a complete reference, cf. nclua/canvas.c.
Functions:
canvas.new
creates a new canvascanvas:attrAntiAlias
gets or sets the anti-alias attributecanvas:attrClip
gets or sets the clip regioncanvas:attrColor
gets or sets the color attributecanvas:attrCrop
gets or sets the crop regioncanvas:attrFilter
gets or sets the filter attributecanvas:attrFlip
gets or sets the flip attributecanvas:attrFont
gets or sets the font attributecanvas:attrLineWidth
gets or sets the line width attributecanvas:attrOpacity
gets or sets the opacity attributecanvas:attrRotation
gets or sets the rotation attributecanvas:attrScale
gets or sets the scale attributecanvas:attrSize
gets the dimensions in pixelscanvas:clear
clears canvascanvas:compose
composes two canvascanvas:drawEllipse
draws an ellipsecanvas:drawLine
draws a linecanvas:drawPolygon
draws a polygoncanvas:drawRect
draws a rectanglecanvas:drawRoundRect
draws a rectangle with rounded cornerscanvas:drawText
draws textcanvas:flush
commits the pending operationscanvas:measureText
measures textcanvas:pixel
gets or sets pixel
Internal functions (for debugging):
canvas:_dump_to_file
dumps canvas content to PNG filecanvas:_dump_to_memory
dumps canvas content to memory addresscanvas:_resize
resizes canvas contentcanvas:_surface
returns a pointer to canvas content
For a complete reference, cf. User API section in nclua/event/init.lua.
Event classes:
ncl
NCL (Nested Context Language) eventskey
keyboard inputpointer
mouse inputhttp
HTTP requeststcp
TCP/IP messagesuser
user defined
Functions:
event.post
posts event into input or output queuesevent.register
registers event handlerevent.timer
sets up timer that calls a function when expiredevent.unregister
unregisters event handlerevent.uptime
returns the up-time since script started
The libnclua API is used by C programs to run NCLua scripts.
Core functions (cf. lib/nclua.c):
nclua_open
opens the librarynclua_close
closes the librarynclua_cycle
processes pending eventsnclua_receive
receives an eventnclua_send
sends an eventnclua_paint
paints top-level canvas onto memorynclua_resize
resizes top-level canvas
Wrapper functions (cf. lib/ncluaw.c, Lua-free interface):
ncluaw_event_key_init
initializes key eventncluaw_event_ncl_init
initializes NCL eventncluaw_event_pointer_init
initializes pointer eventncluaw_event_clone
clones eventncluaw_event_free
frees eventncluaw_event_equals
compares eventsncluaw_open
opens the wrapper libraryncluaw_close
closes the wrapper libraryncluaw_at_panic
installs panic functionncluaw_cycle
processes pending eventsncluaw_receive
receives eventncluaw_send
sends eventncluaw_send_key_event
sends key eventncluaw_send_ncl_event
sends NCL eventncluaw_send_pointer_event
sends pointer eventncluaw_paint
paints top-level canvas onto memoryncluaw_resize
resizes top-level canvas
Copyright (C) 2013-2016 PUC-Rio/Laboratorio TeleMidia
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the "GNU Free Documentation License" file as part of this distribution.