wxlua/docs/wxlua.html at master · LuaDist/wxlua · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>

<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>wxLua Documentation</title>

<meta content="John Labenski" name="author"></head><body>
<h2><u>wxLua
2.8.10 - Documentation</u></h2>
<a href="http://wxlua.sourceforge.net">wxLua</a> is
a <a href="http://www.lua.org">Lua</a>
scripting
language wrapper around the <a href="http://www.wxwidgets.org">wxWidgets</a>
cross-platform GUI library. It consists of two IDE type editors that
can edit and run Lua programs (wxLua and wxLuaEdit), an
executable for
running
standalone wxLua
scripts (wxLuaFreeze), a Lua module to load using&nbsp;<i>require("wx")</i>
when using
the standard Lua executable, and a
library for
extending C++ programs with a fast, small,
fully
embeddable scripting language.<br>
<br>
Lua is a small scripting language written in ANSI
C that can load and run
interpreted scripts as either files or strings. The Lua language is
fast, dynamic, and easy to learn. Lua contains a limited
number of data types,
mainly numbers, strings, functions,&nbsp;tables, and userdata.
Perhaps the most
powerful
feature of the Lua language is that the tables can be used as either
arrays
or hash tables that can cross-reference numbers, strings,
functions, and/or
subtables.<br>
<br>
wxLua adds to this small and elegant language the power of
the
C++ wxWidgets cross-platform GUI library. This includes the ability to
create complex user interface dialogs, image manipulation, file
manipulation, sockets, displaying HTML, and printing to name a few.
You can use as
much or as little of wxWidgets as you like and C++ developers can trim
down the size by turning off preprocessor directives.<br>
<br>
Additionally,
wxLua adds a library for manipulating the bits of integer numbers using
the Bitlib library from Reuben Thomas.<br>
<h3>References:</h3>
wxLua website : <a href="http://wxlua.sourceforge.net">http://wxlua.sourceforge.net</a><br>
wxLua Sourceforge page : <a href="http://sourceforge.net/projects/wxlua">http://sourceforge.net/projects/wxlua</a><br>
Lua website : <a href="http://www.lua.org">http://www.lua.org</a><br>
wxWidgets website : <a href="http://www.wxwidgets.org">http://www.wxwidgets.org</a><br>
Bitlib
library : <a href="http://rrt.sc3d.org/Software/Lua/">http://rrt.sc3d.org/Software/Lua/</a><br>
User
and developer mailing list :
wxlua-users@lists.sourceforge.net
<h2 style="text-decoration: underline;">Contents</h2>
<ol>
<li><a href="#Version_Information">Version
Information</a></li>
<li><a href="#wxLua_Requirements">Requirements</a></li>
<li><a href="#Introduction_to_Lua_very_brief">Introduction
to Lua
(very brief)</a></li>
<li><a href="#Bit_Library">Bit
Library</a></li>
<li><a href="#wxLua_Programming_in_Lua">Programming
in wxLua</a></li>
<li><a href="#wxLua_Samples">wxLua
Samples and How
to Run Them</a></li>
<ol>
<li><a href="#How_to_run_the_samples">How to Run
the Samples</a></li>
<li><a href="#Provided_samples">Provided Samples</a></li>
</ol>
<li><a href="#wxLua_Applications">wxLua
Applications</a></li>
<ol>
<li><a href="#wxLua">wxLua</a></li>
<li><a href="#wxLuaFreeze">wxLuaFreeze</a></li>
<li><a href="#wxLuaEdit">wxLuaEdit</a></li>
</ol>
<li><a href="#wxLua_Utils">wxLua Utils</a></li>
<ol>
<li><a href="#bin2c.lua">bin2c.lua</a></li>
<li><a href="#wrapmodule.wx.lua">wrapmodule.wx.lua</a></li>
</ol>
<li><a href="#wxLua_Sourcecode_Modules">wxLua
Sourcecode Modules</a></li>
<li><a href="#wxLua_Programming_in_C">wxLua C++
Programming Guide</a></li>
<ol>
<li><a href="#Data_stored_in_Luas_LUA_REGISTRYINDEX">Data
stored in Lua's LUA_REGISTRYINDEX table</a></li>
<li><a href="#Functions_to_Create_a_wxLuaState">Functions
to Create a wxLuaState</a></li>
<li><a href="#Using_a_wxLuaState">Using a
wxLuaState</a></li>
</ol>
</ol>
<h2><a name="Version_Information"></a><u>Version
Information</u></h2>
<ul>
<li>The wxLua
version number is set to the stable version of
wxWidgets that it has been updated to. It should also compile with
newer versions of wxWidgets as well as older ones.</li>
<li>Lua
5.1.4</li>
<ul>
<li>wxLua
uses an unmodified copy of Lua 5.1.4 (with patches applied)</li>
<li>Any
program
that works using the official
release of Lua will work in wxLua.</li>
</ul>
<li>wxWidgets
2.8.10 (&gt;= 2.6.3)</li>
<ul>
<li>The interface
files have #ifdefs for 2.4, but
they are not maintained anymore since in some cases the complexity of
maintaining backwards compatibility is not worth it and it is better to
take advantage of the fixes and additions to newer versions of
wxWidgets. With a little work you may be able to resurrect it to
work with wxWidgets 2.4. </li>
<li>Note for wxWidgets
&lt; 2.9 :
wxLua makes use of the wxStyledTextCtrl contrib library
in wxWidgets/contrib/src/stc. You need to have compiled this into a
library if you want to compile the wxLua apps. In wxWidgets &gt;=
2.9 the wxStyledTextCtrl is now part of the main library.</li>
<li>The
wxLua library links to these wxWidgets libs: stc, xrc, html, media,
adv, net, xml, core, base, tiff, jpeg, png, zlib, regex, expat.</li>
<li>See
install.html for more information.</li>
</ul>
</ul>
<h2><a name="wxLua_Requirements"></a><u>Requirements</u></h2>
An end user of wxLua can use the binary packages of wxLua and
everything that's needed is contained within it. C++ programmers or
users on platforms that we don't provide binaries will need a
development library of wxWidgets, typically the source
code itself that you have compiled on your system. More
information about
compiling wxLua is contained in the install.htm file and on <a href="http://wxlua.sourceforge.net/">http://wxlua.sourceforge.net</a>.
<h2><a name="Introduction_to_Lua_very_brief"></a><u>Introduction
to Lua (very brief)</u></h2>
Assuming that you have a cursory understanding of programming
techniques, this primer should give you a good enough feel for Lua to
understand the sample programs and begin to write your own. You should
in any case read the documentation at <a href="http://www.lua.org">www.lua.org</a>.<br>
<ul>
<li><b>Comments</b></li>
<ul>
<li>Line comments are marked by <i>-- rest of line is
commented</i></li>
<li>Block Comments are <i>--[[
multiple line comment ]]</i></li>
</ul>
<li><b>Variables</b></li>
<ul>
<li>Variables are not permanently typed and you can
freely
overwrite
them with other values or types, there is no "const" keyword.</li>
<li>Variables are global unless you put the keyword
"local" in front of them, this is sometimes good practice.</li>
<li>The
scope of local variables is limited to the current
scope and it's children.</li>
<li>Local variables can be
harder to debug because they are stored on the stack and you need the
Lua debug
functions to resolve the name.</li>
<li>A local
variable created with the same name as a global
variable only temporarily supersedes the global.</li>
<li>Use
the function <i>type(var_name)</i> to
get the variable type as a string.</li>
<ul>
<li>"nil",
"boolean", "number",
"string", "table",
"userdata", "function"</li>
</ul>
</ul>
<li><b>Lua
Types</b></li>
<ul>
<li><b>nil</b>
: A special value meaning NULL or
nothing.</li>
<ul>
<li>Variables that are not
assigned a value are nil and can
be reset back to nil at any time.</li>
<li>This value is
often returned for functions that fail.</li>
<li>You can
provide an inline alternative to nil using the 'or' keyword since nil
evaluates to false.</li>
<ul>
<li><span style="font-style: italic;">print(tonumber("a"),
tonumber("a") or 1)</span> -&gt; prints "nil 1"</li>
</ul>
</ul>
<li><b>boolean</b>
: true or false, nil works as
false, but the number 0 evaluates as true. </li>
<ul>
<li>Note: <i>"a = 0; if a
then print(a) end"</i>
evaluates "a" to
true since it has a value, i.e. not nil, use <i>"a ~= 0"</i>.</li>
</ul>
</ul>
<ul>
<li><b>number</b>
: All numbers in Lua are double
valued floating
point numbers. </li>
<ul>
<li><i>mynumber =
(1E1+ 2e-2 * 3.14 / (4 * 1)
)*math.pow(2.5e+2, 4)</i></li>
<li>Variables can be
coerced into numbers using the
function <i>tonumber(variable)</i> which returns <i>nil</i>
on failure.</li>
<li>Additional math functions are in the <i>math</i>
table.</li>
</ul>
<li><b>string</b> :
Strings in Lua can have
embedded nulls "\0" and use the same escape characters as C.</li>
<ul>
<li>Strings are internally hashed by Lua so that
there is only one
copy
of a particular string stored at any one time no matter how many
variables reference it.</li>
<li><i>mystring = "How
are 'you'!"</i> or <i>mystring
= 'How\tare "You"!\n'</i> are both valid since either " or ' can
be used
to quote strings. ('\t' = tab, '\n' = line feed)</li>
<li><i>mystring
= [[How are
"'you'"!]]</i>
means take everything
including new lines and whitespace literally.</li>
<li>Concatenate
two strings using the .. operator</li>
<ul>
<li><i>str1
= "hello"; str2 = "number"; str3 =
str1.."
"..str2.." "..tostring(2).."!"</i></li>
<li>Numbers
can be typically coerced into strings as <i>("A
"..1)</i>, but not <i>(1.." A")</i> since in the
second case the string "A" cannot be coerced into a number.</li>
<li>If
many strings need to be concatenated together it is best to insert them
into a table using table.insert() and then call table.concat() to
create the
single output string. The reason why the concat operator .. is slower
is that it requires an allocation of memory for each new string and
then it must be hashed. The table.concat() method's speed is quite
competitive to other scripting languages.</li>
</ul>
<li>Variables
can be coerced into strings using the
function <i>tostring(variable)</i> which returns <i>nil</i>
on failure. </li>
<li>Additional string functions are in
the <i>string</i>
table.</li>
</ul>
<li><b>table</b> :
Tables can be indexed by
numbers, strings,
functions, other tables...</li>
<ul>
<li><i>mytable
= {}</i> a default empty table,
you must declare a variable as a table before using it's indexes.</li>
<li><i>mytable = { ["index1"] = 1, "first value",
"second
value", index2 = 2 }</i></li>
<ul>
<li><i>print(mytable.index1,
mytable["index1"],
mytable[1],
mytable[2], mytable.index2, mytable.index10)</i></li>
<li>Outputs
this : "1, 1, first value, second value, 2,
nil"</li>
<li>Set values as : <i>mytable.index1 =
2;
mytable["index10"] = 3; mytable[10] = 4</i></li>
<li>New
values that don't already exist are automatically
created</li>
<li>Clear values by setting them to <i>nil</i>
: <i>mytable.index1
= nil</i></li>
<li>The length operator <i>#mytable</i>
returns 2 since there are only two contiguous numeric table indexes
starting from 1 even though in this case there are actually 4 entries
in the table. Lua table arrays have a starting index of 1.</li>
</ul>
<li>Note: Functions
defined by Lua are placed into tables,
a namespace if you will, to keep the global namespace uncluttered.</li>
<ul>
<li>See table.XXX, string.XXX, math.XXX, os.XXX etc.
in the Lua
documentation.</li>
<li>wxLua places the wxWidgets
bindings into the wx.XXX
table "namespace".</li>
<li>The global table is called _G
and you can display it
or any table using (k = key, v = value) </li>
<ul>
<li><i>for
k, v in pairs(_G) do print(k, v) end</i></li>
</ul>
</ul>
</ul>
<li><b>userdata</b> :</li>
<ul>
<li>This is a C/C++ pointer to an object that by itself
cannot be used in Lua.</li>
<li>A metatable (see Lua documentation) may be
assigned to it to allow it to act like a table or be called like a
function, among other things.</li>
<li>This
is the datatype that wxLua uses wrap wxWidgets C++ objects
that are pushed into Lua. The metatable that is assigned to the
userdata when created determines what type of C++ object and therefore
what functions are available to be called on it.</li>
</ul>
<li><b>function</b>
:</li>
<ul>
<li><i>function SumDiff(a, b)
print(a, b);
return a+b, a-b end</i></li>
<ul>
<li><i>num_sum,
num_diff = SumDiff(2, 3)</i></li>
</ul>
<li>Can
return multiple values and be passed less or more
variables
than specified. The unhandled returns or inputs are set to <span style="font-style: italic;">nil</span>
or if
there are extra thrown out. </li>
<li>Variables can be
assigned to functions if desired or
functions can be put into tables</li>
<ul>
<li><i>PrintWarning
= function(msg) print("Warning:
"..msg) end</i></li>
<li><i>FuncTable = {};
FuncTable["Warning"] =
PrintWarning; FuncTable.Warning("I'm broke")</i></li>
</ul>
</ul>
<ul>
<li>Values passed to functions are local
copies and not
modified unless they are tables or userdata</li>
</ul>
<ul>
<ul>
<li><i>function AppendToTable(atable, val)
atable[#atable+1] = val end</i></li>
<ul>
<li><i>mytable
= {}; AppendToTable(mytable,
"hello")</i>
adds "hello" to index 1, i.e. mytable[1] == "hello"</li>
</ul>
<ul>
<li>Note that the table is not returned, but modified
in place, also note that we can use table.insert() to append to
a
table instead of the above method.</li>
</ul>
</ul>
</ul>
</ul>
<li><b>Operators</b></li>
<ul>
<li>Relational : == ~= &lt; &gt; &lt;=
&gt;=
(Note: not equal is ~=) </li>
<li>Logical: <i>and,
or,
not</i></li>
<li>Precedence (low to high):</li>
<ul>
<li>or<br>
</li>
<li> and<br>
</li>
<li> &lt; &gt; &lt;= &gt;= ~= ==<br>
</li>
<li> ..<br>
</li>
<li> + -<br>
</li>
<li> * / %<br>
</li>
<li> not #
- (unary)<br>
</li>
<li> ^ </li>
</ul>
</ul>
<li><b>Keywords</b></li>
<ul>
<li><i>and break do else elseif end false for function
if in
local nil not or repeat return then true until while</i> </li>
</ul>
<li><b>do ... end</b></li>
<ul>
<li>Create a new local scope in a <span style="font-style: italic;">do end</span> block.</li>
<li>Note : You cannot write <i>function
printHi() return; print("hi") end</i>, but you can have <i>function
printHi() do return end; print("hi") end</i> which can be useful
for debugging functions.</li>
</ul>
</ul>
<blockquote>
<pre>do<br> -- create a new local scope<br> local a = 2<br>end<br></pre>
</blockquote>
<ul>
<li><b>if
(bool) then ...
elseif (bool) then ... else ...
end</b></li>
</ul>
<blockquote>
<pre>local a, b, c = 1, 2, 3 -- can assign multiple values<br>a = 1; b = 2; c = 3 -- use ; for multiple lines of code on single line<br>a, b, c = 1, 2, 3 -- this works too<br>if (a == 1) and ((b &lt;= 2) or (c ~= 3)) then <br> print(a+b/c) <br>elseif a == 2 then -- no parentheses necessary<br> print(a)<br>else<br> print(b)<br>end</pre>
</blockquote>
<ul>
<ul>
<li>There
is no case
statement, but <i>table[value] =
function() ... end</i> may be used to simulate one.</li>
<blockquote>
<pre>mycase = {}<br>mycase[1] = function() print("Hello #1") end<br>mycase[2] = function() print("Hello #2") end<br>...<br>if mycase[value] then<br> mycase[value]()<br>else<br> print("Unknown case value")<br>end</pre>
</blockquote>
</ul>
<li><b>while
(bool) ...
end</b></li>
<ul>
<li>Note : there is no <i>continue</i>
keyword
only <i>break</i></li>
</ul>
</ul>
<blockquote>
<pre>function CheckA(val) if val == 5 then return true end end -- returns nil if val ~= 5<br>local a = 1<br>while a &lt; 10 do<br> print(a)<br> a = a + 1 -- no increment operator<br> if CheckA(a) then break end<br>end</pre>
</blockquote>
<ul>
<ul>
<li>You
can make a
"fake" continue by adding a while loop (doesn't
print # 5). <br>
</li>
</ul>
</ul>
<blockquote>
<pre>local a = 1<br>while a &lt; 10 do while true do<br> a = a + 1 -- no increment operator<br> if CheckA(a) then <br> break <br> else<br> print(a)<br> end<br>break end end</pre>
</blockquote>
<ul>
<li><b>repeat
... until
(bool)</b></li>
<ul>
<li>Note : there is no
continue keyword only break</li>
</ul>
</ul>
<blockquote>
<pre>local a = 1<br>repeat<br> local temp = a * 2<br> print(temp, type(temp))<br> a = a + 1 -- no increment operator<br>until a &gt; 10</pre>
</blockquote>
<ul>
<li><b>for
var = init_value,
end_value [, increment] do
... end</b></li>
<ul>
<li>Note : there is no
continue keyword only break</li>
<li>You cannot modify the
loop variable, limit, or increment from within the loop. The
loop counter variable is local to the
loop and the final print(a) statement below will print that a = "hello"
as
it did before the loop.</li>
<li>Copy the loop counter variable to a separate
variable if you need to save it when breaking for example.</li>
</ul>
</ul>
<blockquote>
<pre>local a = "hello"<br>for a = 1, 10 --[[, increment]] do -- optional increment value, else 1<br> local temp = a * 2<br> print(temp)<br>end<br>print(a) -- a == "hello" since loop counter variable is local to the loop<br></pre>
</blockquote>
<ul>
<li><b>functions</b></li>
<ul>
<li>Input any number of values by value, tables and userdata
are
passed by
reference</li>
<li>Missing input variables are assigned
the value nil, extra inputs are discarded.</li>
<li>Return
values using the "return" keyword</li>
<li>Not all return
values need to be used and extra ones will be discarded. </li>
<ul>
<li>The
symbol "_"
is a valid variable name and is often used as a dummy variable to
receive return values that you do not want.</li>
<ul style="font-style: italic;">
<li>function GetNums()
return 3, 4 end; local _, num2 = GetNums()</li>
</ul>
<li>You
may also use the <span style="font-style: italic;">select(n,
...)</span> function to choose return values to use.</li>
</ul>
<li>Tables
can be used as containers for input values to functions using the
unpack(table, [i, [, j]]) function. This is useful for creating complex
inputs to a function or storing them for reuse.</li>
<ul>
<li><span style="font-style: italic;">print(string.find(unpack({"Hello",
"ll", 1, 1})))</span> -&gt; prints "3 4"</li>
</ul>
<li>Vararg
inputs are written as <span style="font-style: italic;">function
dostuff( ... )</span></li>
<ul>
<li>The number of
args is found using: <span style="font-style: italic;">local
n = select("#", ...)</span></li>
<li>The args can be
converted into table using: <span style="font-style: italic;">local
args = { ... }</span></li>
<li>A particular arg can be
chosen using: <span style="font-style: italic;">local
arg3 = select(3, ...)</span> </li>
<ul>
<li>Note
<span style="font-style: italic;">select(n, ...)</span>
returns
all args after <span style="font-style: italic;">n</span>,
but if the left hand side is a single variable the others are
discarded. See above about using <span style="font-style: italic;">select()</span>
to pick return values of a function as well.</li>
</ul>
</ul>
</ul>
</ul>
<blockquote>
<pre>function DoStuff(a, b, c)<br> a = b*c -- does not change global and/or input number a<br> local function Calc(a)<br> return a*2<br> end<br>	<br> return Calc(a)*b*c -- or for multiple values "return a*b*c, a*b"<br>end<br>-- call function<br>a = 10<br>result = DoStuff(a, 1, 2)<br>-- can also put function into a table<br>stuff = {}<br>stuff.DoStuff = DoStuff<br>result = stuff.DoStuff(1, 2, 3)<br>print(a, result) -- "10, 72" since a is not changed</pre>
</blockquote>
<h2 style="text-decoration: underline;"><a name="Bit_Library"></a>Bit
Library</h2>
wxLua automatically loads a library for manipulating
the bits of an integer and puts it into the global "bit" table. This is
because wxWidgets often uses enumeration flags to control the behavior
of functions and for compactly storing status information. You can
easily "or" bits by adding them together and
this is the preferred method, for example 0x02 + 0x04 = 0x06 or bitwise
0110. If the bits you're trying to "or" are not unique
(perhaps one is a bit mask) this fails, 0x01 + 0x03 =
0x04 or bitwise 0100 (oops).<br>
<br>
wxLua uses the bitlib library written by
Reuben Thomas and since the code for it is very small, it's embedded
into
the wxLua sourcecode. <br>
<br>
All
function arguments should be integers. The number of bits available for
logical operations depends on the data type used to represent Lua
numbers; this is typically 8-byte IEEE floats, which give 53 bits (the
size of the mantissa).<br>
The logical operations start with "b"
for "bit" to avoid clashing with reserved words; although "xor" isn't a
reserved word, it seemed better to use "bxor" for consistency.<br>
<ul>
<li>bit.bnot(a)
returns the one's complement of a</li>
<li>bit.band(w1,...)
returns the bitwise and of the w's</li>
<li>bit.bor(w1,...)
returns the bitwise or of the w's</li>
<li>bit.bxor(w1,...)
returns the bitwise exclusive or of the w's</li>
<li>bit.lshift(a,b)
returns a shifted left b places</li>
<li>bit.rshift(a,b)
returns a shifted logically right b places</li>
<li>bit.arshift(a,b)
returns a shifted arithmetically right b places (works on negative
numbers too)</li>
<li>bit.mod(a,b) returns the integer
remainder of a divided by b</li>
</ul>
<h2><a name="wxLua_Programming_in_Lua"></a><u>Programming
in wxLua</u></h2>
Programming in wxLua means that you're writing Lua programs using the
Lua
language using an additional table of functions, objects, numbers,
strings, and
"classes" in the namespace <b><i>wx</i></b>
from
wxWidgets. Additional libraries may be added as bindings and can be
placed in their own "namespace" table, but for the examples below we
will use the <i><b>wx</b></i> table. <br>
<br>
The list below are the tables that wxLua creates containing the binding
functions or
objects. These are in addition to the standard Lua tables; <span style="font-weight: bold;">coroutine, debug, io, math, os,
package, string, table</span>. Note that the wxaui and wxstc
libraries have been separated into their own tables since they are
fairly specialized libraries.<br>
<ul>
<li><span style="font-weight: bold;">bit</span>
- The bit
library from Reuben Thomas for manipulating integer bits.</li>
<li><span style="font-weight: bold;">wxlua</span>
- Special
functions for introspecting into wxLua or generic functions that wxLua
provides that are independent of wxWidgets.</li>
<li><span style="font-weight: bold;">wx</span>
- wxWidgets
functions, classes, defines, enums, strings, events, and
objects are placed here.</li>
<li><b>wxaui</b>
- The wxWidgets Advanced User Interface
library.<span style="font-weight: bold;"></span></li>
<li><span style="font-weight: bold;">wxstc</span>
- The
wxStyledTextCtrl wrapper around the Scintilla text editor.</li>
</ul>
The
semantics for accessing wxWidgets elements in wxLua tries
to map as closely as possible to the underlying C++
notation so that the official C++ documentation may be used as
a reference, <a href="http://www.wxwidgets.org/docs">http://www.wxwidgets.org/docs</a>.
The most common case where wxLua deviates from C++ is when
values are passed by reference to a function to be
changed; wxLua will return multiple values instead. Please see
the <b><i>wxluaref.html</i></b>
document that lists all the wxWidgets objects wrapped by wxLua and take
note of the functions that are marked <span style="font-style: italic;">%override</span> since you
will need to
use them as described in that document. You should also look at the <b><i>binding.html</i></b>
file, even if you do not plan to write your own bindings, to get a
better understanding of the <b><i>wxluaref.html</i></b>
file.<br>
<br>
<u><b>Strings</b></u>: wxLua does not
typically
use the
wxString class for strings,
rather it
uses Lua strings. This means that all wxWidgets functions
that take a wxString parameter take either a wxString userdata or
(preferred) a Lua string (Lua variables that are of type(var) ==
"string"). Functions that return wxStrings convert the value into
a Lua string for convenience. The conversion from
the Lua ANSI C 8-bit char* string to a wxString (which may be a Unicode
wchar* string) is done internally.<br>
<br>
<u><b>wxArrayString and wxSortedArrayString:</b></u>
Function
parameters that take a "const wxArrayString&amp; arr" or
"wxArrayString arr" will accept either a wxArrayString userdata
or a Lua table that has numeric indexes and string values and convert
it into
a wxArrayString for the function call. If the function call is
"wxArrayString&amp; arr" or "wxArrayString* arr" you must provide a
wxArrayString userdata since the C++ function will most
likely modify
the wxArrayString that's passed to it.<br>
<br>
<u><b>wxArrayInt</b></u>: Function
parameters
that take a "const wxArrayInt&amp; arr" or "wxArrayInt arr" will
accept either a wxArrayInt userdata or a Lua table that has numeric
indexes and numeric values and convert it into a wxArrayInt for the
function call. If the function call is "wxArrayInt&amp; arr" or
"wxArrayInt*
arr" you must provide a wxArrayInt userdata since the C++ function
will most likely modify the wxArrayInt that's passed to it.
<br>
<br>
<b>Location of the wxWidgets objects declared in a
C++ header files in the <i>wx</i> Lua
table</b>
<ul>
<li><b>#define
NUMBER_DEFINE VALUE</b> </li>
<ul>
<li>All
#defined numerical values are available as <i>wx.NUMBER_DEFINE</i></li>
<li>Example <i>"#define wxID_ANY -1"</i> is
accessed as <i>wx.wxID_ANY</i></li>
<li>Declared
in the bindings using the <i>%define</i>
tag<br>
</li>
</ul>
<li><b>[int,
double, etc] NUMBER_VARIABLE;</b></li>
<ul>
<li>All
global numerical variables are available as <i>wx.NUMBER_VARIABLE</i></li>
<li>Example : <i>"extern const int wxInvalidOffset;"</i>
is accessible as <i>wx.wxInvalidOffset</i>.</li>
<li>Declared
in the bindings using the <i>%define</i>
tag</li>
</ul>
<li><b>enum ENUM_NAMESPACE [or
CLASSNAME::ENUM_NAMESPACE] { ENUM_NAME }</b></li>
<ul>
<li>All global enums, named or not, are available as <i>wx.ENUM_NAME</i></li>
<ul>
<li>Example : <i>"enum wxDirection { wxLEFT,
... }"</i>
is accessible as <i>wx.wxLEFT</i></li>
</ul>
<li>All
enums that are members of classes are available as <i>wx.CLASSNAME.ENUM_NAME</i></li>
<ul>
<li>Example : <i>"enum wxFTP::TransferMode {
ASCII, ... }"</i> is accessible as <i>wx.wxFTP.ASCII</i></li>
</ul>
<li>This follows the C++ semantics that you do not
have to
specify the name of an enum, but you do have to use its scope if it is
a class member.</li>
<li>Declared in the bindings using
the <i>%enum</i>
tag</li>
</ul>
<li><b>#define
STRING_DEFINE wxT("String Value")</b></li>
<ul>
<li>All
#defined string values are available as <i>wx.STRING_DEFINE</i></li>
<li>Example : <i>"#define
wxIMAGE_OPTION_CUR_HOTSPOT_X wxT("HotSpotX")"</i> is
accessible as <i>wx.wxIMAGE_OPTION_CUR_HOTSPOT_X</i></li>
<li>Declared in the bindings using the <i>%define_string</i>
tag</li>
</ul>
<li><b>const wxChar*
STRING_VARIABLE;</b></li>
<ul>
<li>All global
string variables are available as <i>wx.STRING_VARIABLE</i></li>
<li>No examples yet.</li>
<li>Declared in the
bindings using the <i>%define_string</i>
tag</li>
</ul>
<li><b>wxEVT_XXX
for wxEvtHandler::Connect()</b></li>
<ul>
<li>All
<i>wxEVT_XXX</i> wxEventTypes (an integer) are
available as <i>wx.wxEVT_XXX</i></li>
<ul>
<li>Example : <i>wx.wxEVT_COMMAND_MENU_SELECTED</i>
for menu item selection.<br>
</li>
</ul>
<li>wxLua
does not use the static event tables since it is
not a compiled language. Rather the wxEvtHandler::Connect() function is
used
to connect event types to a wxEvtHandler, typically a wxWindow
derived class. Therefore you do not use EVT_XXX() macros, but the
corresponding wxEVT_XXX. The wxluaref.html manual contains a complete
mapping between the two. </li>
<ul>
<li>Example : <i>EVT_MENU(id,
func)</i> use <i>window:Connect(menuId,
wx.wxEVT_COMMAND_MENU_SELECTED, Lua function)</i>. The Lua
function must have the signature of <i>"function
MenuEvent(event) ...
handle event ... return"</i> where the event variable will be of
the wxEvent class
the wxEventType was declared in, which in this case is a
wxCommandEvent.</li>
</ul>
<ul>
<li>Example
: <i>EVT_PAINT(func)</i>
use <i>window:Connect(wx.wxEVT_PAINT, Lua function)</i>.
There is no id used for this connect event
function call since you are directly connecting the paint event to the
window, whereas in the menu case you are handling a menu event
from the menu that travels up the chain of window parents until a
handler is found, therefore you need the Id to determine where
the
event came from. </li>
<ul>
<li>Note: You must
always create a wxPaintDC for wxEVT_PAINT.</li>
</ul>
<ul>
<li><span style="font-style: italic;">local
dc =
wx.wxPaintDC(event:GetEventObject():DynamicCast("wxWindow"))</span>
and then call <span style="font-style: italic;">dc:delete()</span>
at the end of the function because the paint event clears the
"dirty" region to repaint and if it is not cleared another paint event
will be sent... and so on.</li>
</ul>
</ul>
<li>Declared
in the
bindings using the <i>%define_event</i>
tag</li>
</ul>
<li><b>Objects
of classes or structs OBJECT_NAME</b></li>
<ul>
<li>All
global objects that are classes or structs are
available as <i>wx.OBJECT_NAME</i></li>
<li>Example
: <i>"const wxImage wxNullImage;"</i>
is accessible as <i>wx.wxNullImage</i> and functions from
the wxImage class can be called as <i>wx.wxNullImage:Ok()</i>
which should
return false.</li>
<li>Declared in the bindings using the <i>%define_object</i>
tag</li>
</ul>
<li><b>Pointers to
classes or structs POINTER_NAME</b></li>
<ul>
<li>All
global pointers that are classes or structs are
available as <i>wx.POINTER_NAME</i></li>
<li>Example
: <i>"extern wxPenList*
wxThePenList;"</i> is accessible as <i>wx.wxThePenList</i>
and
functions from the wxPenList class can be made as <i>"pen =
wx.wxThePenList:FindOrCreatePen(wx.wxColour(1,2,3), 1, wx.wxSOLID)"</i></li>
<li>Declared in the bindings using the <i>%define_object</i>
tag</li>
</ul>
<li><b>Global<i> </i>C
style
functions
VAR_TYPE FUNCTION_NAME(int a, const wxString&amp; str)</b></li>
<ul>
<li>All global C style functions are available as <i>wx.FUNCTION_NAME(1,
"Hello")</i></li>
<li>Example : <i>"extern
wxString
wxGetUserHome(const wxString&amp; name)"</i> is accessible as
<i>"home_dir = wx.wxGetUserHome("john")"</i>
where wxString means to input a Lua string and a Lua string is
returned.</li>
<li>Declared in the bindings using the <i>%function</i>
tag</li>
</ul>
<li><b>C++ Classes
CLASS_NAME</b></li>
<ul>
<li>All C++ classes
are available as <i>wx.CLASS_NAME</i>,
however in order to use one you must call one of the constructors first
or get the class as a return value from another function call.</li>
<ul>
<li>Example : <i>"pt = wx.wxPoint(1,
2); pt2 = wx.wxPoint(pt)"</i>.</li>
<li>Multiple member functions
with the same
name are overloaded as in C++ and
the proper function to call
is determined at runtime. This is one of the reasons why wxLua is
stricter about type than Lua. For example; string arguments do
not accept numbers which Lua would silently convert. </li>
<li>Member functions from
the
base class(es) are also available
and may be overloaded as well. </li>
<li>The C++ classes
are exposed as tables in Lua, but have a __call
metatable item so they can be called as a function. If you need to get
the
constructor function itself you can use <i>wx.CLASS_NAME.new(...)</i>
which is the constructor exposed as a Cfunction.</li>
</ul>
<li>The
C++ class objects are pushed into Lua as a userdata wrapping a void*
pointer to the C++ object.</li>
<ul>
<li>A special metatable
is set on the userdata with these entries :</li>
<ul>
<li>__index to call functions on the object or
to get member variable values.</li>
<li>__newindex to set new functions or values or set
member variable values.</li>
<li>__tostring to allow print() to show something useful</li>
<ul>
<li>print(wx.wxPoint()) "userdata: 0x858df5c
[wxPoint(0x84ab550, 251)]", where 0x858df5c is the Lua userdata
address, 0x84ab550 is the address of the wxPoint object, and
251 is the wxLua type that wxLua uses to determine that this Lua
userdata wraps a wxPoint. The wxPoint type may not always be 251 since
it depends on the number and order in which the bindings were
initialized.</li>
</ul>
<li>__gc to tell wxLua when the userdata is no longer
used so wxLua can delete the C++ object if appropriate. </li>
</ul>
</ul>
<li>Declared
in the bindings using the <i>%class</i>
tag</li>
<li><span style="font-weight: bold;">Deleting
class userdata</span> can be done using the wxLua added class
member function delete().</li>
<ul>
<li>All classes
that have the %delete binding tag will be eventually garbage collected
when they go out of scope.</li>
<li>Classed without the
%delete tag are assumed to be eventually attached to another object
that will delete them for you.</li>
<li>The Lua garbage
collector uses an incremental collector that waits until the data size
reaches a limit and slowly removes them to avoid program slowdown. This
is a good thing and makes Lua programs run at an even pace.</li>
<li>However!
Some graphical device interface (GDI) classes need to be deleted
immediately when you are done with them.</li>
<ul>
<li>This
is really a MS Windows problem, in Win95 based systems the number that
you could create was severely limited, but even in NT systems (XP,
Vista) you
will have problems if you've created hundreds of them. One visible sign
that something is wrong is when controls, like menus, stop redrawing
themselves properly and the program becomes sluggish.</li>
<li>In
any case, just delete() them when done so that your program will work
equally well in MSW as it would in Linux or OSX.</li>
</ul>
<li>Additionally,
since the Lua userdata that wxLua pushes into Lua only store a void*
pointer to the C++ class object, Lua only
thinks they are of size void* which are on 32bit x86 machines only 8
bytes.
However, the class might store a 1024x768 x 3 bytes/pixel
image as a wxImage (2.36Mb). There have been a number of
discussions about this on the Lua mailing list, but currently there is
no way to let Lua know the true size of a userdata to help it better
decide when and what to garbage collect. The core of
Lua could be modified, but that would make it harder to use wxLua as a
loadable module.</li>
<li>The solution is to use the delete()
function on certain types of userdata when you are done.</li>