3
LGI is Lua binding to Gnome platform. It is implemented as dynamic
4
binding using gobject-introspection. This means that all libraries
5
with support for gobject-introspection can be used by LGI without any
6
need to compile/install anything, assuming that proper .typelib file
7
is installed and available.
13
LGI depends on `gobject-introspection >= 1.30` package. To build,
14
gobject-introspection development package must also be installed.
15
Note that required gobject-introspection version is unfortunately
16
rather new, currently mostly available only in unreleased-yet versions
17
of major distributions (part of GNOME-3.2, e.g. Fedora 16). There is
18
planned work to make LGI mostly work also with older
19
gobject-introspection versions, which are part of GNOME-3.0. Pre-3.0
20
versions are not planned to be supported at all.
22
In order to be able to use assorted gobject-based libraries through
23
LGI, these libraries must have properly installed `.typelib` files.
24
Most, if not all distributions already do this properly.
26
### Supported platforms
28
LGI is currently tested on Linux (all sane Linux distributions should work
29
fine) and Cygwin. There is no principal obstacle for supporting other
30
platforms, as long as gobject-introspection library (and of course Lua) is
31
ported and working there.
33
### Installing via LuaRocks
35
The preferred way to install LGI is using luarocks. As of writing
36
this document, LGI is not yet available on public luarocks server, so
37
plain `luarocks install lgi` does not work yet, although it will be
38
preferred way to install LGI in the future. Currently, LGI source
39
must be downloaded, unpacked and installed using `luarocks make`.
41
### Installing using Makefile
43
Another way to install LGI is using makefiles:
46
sudo make install [PREFIX=prefix-path] [DESTDIR=destir-path]
48
Default `PREFIX` is `/usr/local` and default `DESTDIR` is empty.
52
All LGI functionality is available in Lua module lgi, which is loaded
53
by using Lua `require` construct:
55
local lgi = require 'lgi'
57
All gobject-introspection accessible modules are now accessible in lgi table:
63
To create instance of the class, simply 'call' the class in the namespace:
65
local window = Gtk.Window()
67
To access object properties and call methods on the object instances,
68
use normal Lua object access notation:
70
window.title = 'I am a window'
72
window.title = window.title .. ' made by Lgi'
74
Note that properties can have `-` (dash) character in them. It is
75
illegal in Lua, so it is translated to `_` (underscore).
77
window.has_resize_grip = true
79
It is also possible to assign properties during object construction:
81
local window = Gtk.Window {
82
title = 'I am a window made by Lgi',
83
has_resize_grip = true
86
Note that structures and unions are handled similarly to classes, but
87
structure fields are accessed instead of properties.
89
To connect signal to object instance, assign function to be run to
90
`on_signalname` object slot:
92
window.on_destroy = function(object)
93
print('destroying', object)
96
Note that Lua has nice syntactic sugar for objects, so previous
97
construction can also be written like this:
99
function window:on_destroy()
100
print('destroying', self)
103
Note that potential dashes in signal names are also translated to
104
underscores to cope well with Lua identifier rules.
106
Enumerations and bitflags are grouped in the enumeration name table,
107
and real names are enumeration nicks uppercased. For example,
108
`GTK_WINDOW_TOPLEVEL` identifier is accessible as
109
`Gtk.WindowType.TOPLEVEL`.
111
There is no need to handle any kind of memory management; LGI handles
112
all reference counting internally in cooperation with Lua's garbage
115
For APIs which use callbacks, provide Lua function which will be
116
called when the callback is invoked. It is also possible to pass
117
coroutine instance as callback argument, in this case, coroutine is
118
resumed and returning `coroutine.yield()` returns all arguments passed
119
to the callback. The callback returns when coroutine yields again or
120
finishes. Arguments passed to `coroutine.yield()` call or exit status
121
of the coroutine are then used as return value from the callback.
123
See examples in `samples` source directory to dive deeper into the LGI
added
removed
docs/overview.md
