nclua
nclua copied to clipboard
Event handling and 2D graphics for Lua scripts
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/nclua.
For the latest sources, cf. https://github.com/telemidia/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.
Building the repository
Dependencies
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.
Linux
On Ubuntu-based distros, to install the dependencies run:
$ sudo apt-get install -y git gcc g++ autotools-dev dh-autoreconf \
liblua5.2-dev libglib2.0-dev libpango1.0-dev \
librsvg2-dev libgtk-3-dev libsoup2.4-dev -qq
To build with autotools run:
$ ./bootstrap
$ ./configure --prefix=/usr/
$ make
Canvas API
For a complete reference, cf. nclua/canvas.c.
Functions:
-
canvas.new
creates a new canvas -
canvas:attrAntiAlias
gets or sets the anti-alias attribute -
canvas:attrClip
gets or sets the clip region -
canvas:attrColor
gets or sets the color attribute -
canvas:attrCrop
gets or sets the crop region -
canvas:attrFilter
gets or sets the filter attribute -
canvas:attrFlip
gets or sets the flip attribute -
canvas:attrFont
gets or sets the font attribute -
canvas:attrLineWidth
gets or sets the line width attribute -
canvas:attrOpacity
gets or sets the opacity attribute -
canvas:attrRotation
gets or sets the rotation attribute -
canvas:attrScale
gets or sets the scale attribute -
canvas:attrSize
gets the dimensions in pixels -
canvas:clear
clears canvas -
canvas:compose
composes two canvas -
canvas:drawEllipse
draws an ellipse -
canvas:drawLine
draws a line -
canvas:drawPolygon
draws a polygon -
canvas:drawRect
draws a rectangle -
canvas:drawRoundRect
draws a rectangle with rounded corners -
canvas:drawText
draws text -
canvas:flush
commits the pending operations -
canvas:measureText
measures text -
canvas:pixel
gets or sets pixel
Internal functions (for debugging):
-
canvas:_dump_to_file
dumps canvas content to PNG file -
canvas:_dump_to_memory
dumps canvas content to memory address -
canvas:_resize
resizes canvas content -
canvas:_surface
returns a pointer to canvas content
Dir API
For a complete reference, cf. nclua/dir.c.
Functions:
-
dir.dir
gets an iterator for path -
dir.test
tests whether path satisfies a given query
Event API
For a complete reference, cf. User API section in nclua/event/init.lua.
Event classes:
-
ncl
NCL (Nested Context Language) events -
key
keyboard input -
pointer
mouse input -
http
HTTP requests -
tcp
TCP/IP messages -
user
user defined
Functions:
-
event.post
posts event into input or output queues -
event.register
registers event handler -
event.timer
sets up timer that calls a function when expired -
event.unregister
unregisters event handler -
event.uptime
returns the up-time since script started
Libnclua API (C code)
The libnclua API is used by C programs to run NCLua scripts.
Core functions (cf. lib/nclua.c):
-
nclua_open
opens the library -
nclua_close
closes the library -
nclua_cycle
processes pending events -
nclua_receive
receives an event -
nclua_send
sends an event -
nclua_paint
paints top-level canvas onto memory -
nclua_resize
resizes top-level canvas
Wrapper functions (cf. lib/ncluaw.c, Lua-free interface):
-
ncluaw_event_key_init
initializes key event -
ncluaw_event_ncl_init
initializes NCL event -
ncluaw_event_pointer_init
initializes pointer event -
ncluaw_event_clone
clones event -
ncluaw_event_free
frees event -
ncluaw_event_equals
compares events -
ncluaw_open
opens the wrapper library -
ncluaw_close
closes the wrapper library -
ncluaw_at_panic
installs panic function -
ncluaw_cycle
processes pending events -
ncluaw_receive
receives event -
ncluaw_send
sends event -
ncluaw_send_key_event
sends key event -
ncluaw_send_ncl_event
sends NCL event -
ncluaw_send_pointer_event
sends pointer event -
ncluaw_paint
paints top-level canvas onto memory -
ncluaw_resize
resizes top-level canvas
Copyright (C) 2013-2018 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.