← Back to branch summary

~ubuntu-branches/ubuntu/natty/lua-gtk/natty

« back to all changes in this revision

Viewing changes to doc/en/call.html

  • Committer: Bazaar Package Importer
  • Author(s): Enrico Tassi
  • Date: 2009-05-17 18:16:21 UTC
  • mfrom: (1.2.1 upstream) (4.1.1 experimental)
  • Revision ID: james.westby@ubuntu.com-20090517181621-9kmdd82nxg54jsio
http://bugs.debian.org/507205
http://bugs.debian.org/522087
http://bugs.debian.org/498120
* new upstream snapshot comprising many more GNOME libraries:
    Gtk, GDK, GLib, Pango, Atk, Libxml2, Cairo, Clutter, Gtkhtml, 
    GtkSourceView, Gio, Gtkspell and GConf. 
* new upstream release includes a new configure script written in Lua,
  no more bashisms there (Closes: #507205)
* renamed binary packages to liblua5.1-gnome-*
* updated standards-version to 3.8.1, no changes needed
* patch to load .so.* version of libraries and not .so (that was requiring
  -dev packages) (Closes: #522087)
* removed redundant Architecture line from the source stanza of control
  (Closes: #498120)
* updated copyright file, Wolfgang Oertl holds it for 2009 too.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/call.html
 
1
 
 
2
<p>
 
3
The most important part of LuaGnome is the ability to call almost any function
 
4
provided by the supported libraries.  This section explains how to do this.
 
5
</p>
 
6
 
 
7
<h3>Non-object-oriented calls</h3>
 
8
 
 
9
<p>
 
10
Using a syntax very similar to the C API, you can call a function like in
 
11
the following example:
 
12
</p>
 
13
 
 
14
<%= inline_code [[
 
15
require "glib"
 
16
print(glib.get_user_name())
 
17
print(glib.build_filename("one", "two", "three"))
 
18
]] %>
 
19
 
 
20
<p>
 
21
Note how the <code>glib</code> object is used.  It is a module that provides
 
22
the bindings to GLib, and has a prefix for functions built in, in this case
 
23
"g_".  While you could also call <code>glib.g_get_user_name()</code>, the
 
24
preferred usage is without that prefix.
 
25
</p>
 
26
 
 
27
 
 
28
<h3>Object-oriented calls (methods)</h3>
 
29
 
 
30
<p>
 
31
Most of the supported functions can be considered methods, with their first
 
32
argument being the object to manipulate.  The following examples demonstrate
 
33
how such methods are called:
 
34
</p>
 
35
 
 
36
<%= copy_file "doc/en/call1.lua" %>
 
37
 
 
38
<p>
 
39
When calling a method on an object, the library function to call is computed
 
40
using the object's type name and the method name.  In the example above,
 
41
from the type <code>GMatchInfo</code> and the method name
 
42
<code>get_string</code>, the computed function name is
 
43
<code>g_match_info_get_string</code>.
 
44
</p>
 
45
 
 
46
<p>
 
47
Fortunately most of the GLib/GDK/Gtk/... functions have consistent names,
 
48
always starting with the mangled type name and a method name.  In some cases
 
49
aliases have been defined where this pattern is not followed.
 
50
</p>
 
51
 
 
52
<p>
 
53
See also the page on <a href="objects.html">Objects</a>.
 
54
</p>
 
55
 
 
56
 
 
57
<h3>Arguments</h3>
 
58
 
 
59
<p>
 
60
Refer to the official C API documentation of the library for the specification
 
61
of the argument list.  Most of the C types are supported by LuaGnome, which has
 
62
to convert Lua values to C before calling a library function.  Even multiple
 
63
indirections (pointer to pointer to something) are supported.
 
64
</p>
 
65
 
 
66
<p>
 
67
Simple data types like strings, numbers, but also objects are quite easy to
 
68
convert.  Other types like function pointers, boxed values, void pointers and
 
69
others are more involved and are explained in detail on separate pages.
 
70
</p>
 
71
 
 
72
<h3>Return values</h3>
 
73
 
 
74
<p>
 
75
Each function may have none, one or multiple return values.  The called C
 
76
function can have only one "real" return value, of course.  Multiple values
 
77
can, however, be returned by providing a pointer as argument, and the library
 
78
function stores additional values at this location, as in the following example:
 
79
</p>
 
80
 
 
81
<div class="code"><code>
 
82
// this is C code.
 
83
gchar *endptr = NULL;
 
84
gint64 val = g_ascii_stroll("123foo", &amp;endptr, 0);
 
85
// endptr now points to the "f" in the given string.
 
86
</code></div>
 
87
 
 
88
<p>
 
89
A one-to-one emulation of this in Lua might look like this ugly contraption:
 
90
</p>
 
91
 
 
92
 
 
93
<%= inline_code [[
 
94
require "glib"
 
95
 
 
96
-- this is NOT how it is done
 
97
endptr = gnome.pointer "char*"
 
98
val = glib.ascii_stroll("123foo", endptr, 0)
 
99
print(val, endptr.content)
 
100
]] %>
 
101
 
 
102
<p>
 
103
Instead, Lua's ability to return multiple values from functions is used.  You
 
104
only have to provide the initialization as argument, and the return values are
 
105
returned in order.  LuaGnome is fairly adept at figuring out which arguments
 
106
are used as output, and which are not.
 
107
</p>
 
108
 
 
109
<p>
 
110
As a special case, a double pointer argument like <code>char**</code>
 
111
or <code>GError**</code> is an output argument; that is, the called function
 
112
will place a pointer at the given location.  If you specify nil, then no
 
113
output is generated.  If you want the function to receive a valid pointer to
 
114
a location that contains NULL, and whose content is returned, you have to
 
115
use <code>gnome.NIL</code>.
 
116
</p>
 
117
 
 
118
<%= inline_code [[
 
119
&gt; require "glib"
 
120
&gt; print(glib.ascii_strtoll("123foo", nil, 0))
 
121
123
 
122
&gt; print(glib.ascii_strtoll("123foo", gnome.NIL, 0))
 
123
123    foo
 
124
]] %>
 
125