<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>LGI Overview</title>
<link rel="stylesheet" type="text/css" href="default.css" />
</head>
<body>
<h1>LGI Overview</h1>
<p>LGI is Lua binding to Gnome platform. It is implemented as dynamic
binding using gobject-introspection. This means that all libraries
with support for gobject-introspection can be used by LGI without any
need to compile/install anything, assuming that proper .typelib file
is installed and available.</p>
<h2>Installation</h2>
<h3>Dependencies</h3>
<p>LGI depends on <code>gobject-introspection >= 1.30</code> package. To build,
gobject-introspection development package must also be installed.
Note that required gobject-introspection version is unfortunately
rather new, currently mostly available only in unreleased-yet versions
of major distributions (part of GNOME-3.2, e.g. Fedora 16). There is
planned work to make LGI mostly work also with older
gobject-introspection versions, which are part of GNOME-3.0. Pre-3.0
versions are not planned to be supported at all.</p>
<p>In order to be able to use assorted gobject-based libraries through
LGI, these libraries must have properly installed <code>.typelib</code> files.
Most, if not all distributions already do this properly.</p>
<h3>Supported platforms</h3>
<p>LGI is currently tested on Linux (all sane Linux distributions should work
fine) and Cygwin. There is no principal obstacle for supporting other
platforms, as long as gobject-introspection library (and of course Lua) is
ported and working there.</p>
<h3>Installing via LuaRocks</h3>
<p>The preferred way to install LGI is using luarocks. As of writing
this document, LGI is not yet available on public luarocks server, so
plain <code>luarocks install lgi</code> does not work yet, although it will be
preferred way to install LGI in the future. Currently, LGI source
must be downloaded, unpacked and installed using <code>luarocks make</code>.</p>
<h3>Installing using Makefile</h3>
<p>Another way to install LGI is using makefiles:</p>
<pre><code>make
sudo make install [PREFIX=prefix-path] [DESTDIR=destir-path]
</code></pre>
<p>Default <code>PREFIX</code> is <code>/usr/local</code> and default <code>DESTDIR</code> is empty.</p>
<h2>Quick overview</h2>
<p>All LGI functionality is available in Lua module lgi, which is loaded
by using Lua <code>require</code> construct:</p>
<pre><code>local lgi = require 'lgi'
</code></pre>
<p>All gobject-introspection accessible modules are now accessible in lgi table:</p>
<pre><code>local Gtk = lgi.Gtk
local Gio = lgi.Gio
local GLib = lgi.GLib
</code></pre>
<p>To create instance of the class, simply 'call' the class in the namespace:</p>
<pre><code>local window = Gtk.Window()
</code></pre>
<p>To access object properties and call methods on the object instances,
use normal Lua object access notation:</p>
<pre><code>window.title = 'I am a window'
window:show_all()
window.title = window.title .. ' made by Lgi'
</code></pre>
<p>Note that properties can have <code>-</code> (dash) character in them. It is
illegal in Lua, so it is translated to <code>_</code> (underscore).</p>
<pre><code>window.has_resize_grip = true
</code></pre>
<p>It is also possible to assign properties during object construction:</p>
<pre><code>local window = Gtk.Window {
title = 'I am a window made by Lgi',
has_resize_grip = true
}
</code></pre>
<p>Note that structures and unions are handled similarly to classes, but
structure fields are accessed instead of properties.</p>
<p>To connect signal to object instance, assign function to be run to
<code>on_signalname</code> object slot:</p>
<pre><code>window.on_destroy = function(object)
print('destroying', object)
end
</code></pre>
<p>Note that Lua has nice syntactic sugar for objects, so previous
construction can also be written like this:</p>
<pre><code>function window:on_destroy()
print('destroying', self)
end
</code></pre>
<p>Note that potential dashes in signal names are also translated to
underscores to cope well with Lua identifier rules.</p>
<p>Enumerations and bitflags are grouped in the enumeration name table,
and real names are enumeration nicks uppercased. For example,
<code>GTK_WINDOW_TOPLEVEL</code> identifier is accessible as
<code>Gtk.WindowType.TOPLEVEL</code>.</p>
<p>There is no need to handle any kind of memory management; LGI handles
all reference counting internally in cooperation with Lua's garbage
collector.</p>
<p>For APIs which use callbacks, provide Lua function which will be
called when the callback is invoked. It is also possible to pass
coroutine instance as callback argument, in this case, coroutine is
resumed and returning <code>coroutine.yield()</code> returns all arguments passed
to the callback. The callback returns when coroutine yields again or
finishes. Arguments passed to <code>coroutine.yield()</code> call or exit status
of the coroutine are then used as return value from the callback.</p>
<p>See examples in <code>samples</code> source directory to dive deeper into the LGI
features.</p>
</body></html>
