wxLua 2.8.10 - FAQ

1. Why wxLua?
1. What's best for my needs: wxLua, wxPython, wxSomethingElse?
2. Can I use wxLua as script interpreter embedded in my own C++ applications?
2. How to learn wxLua
1. Read the wxLua documentation
2. Read the C++ wxWidgets documentation
3. Run and trace through the samples
3. Programming in wxLua
1. wxStrings?
2. wxArrayString and wxSortedArrayString?
3. wxArrayInt?
4. When and how should you delete() objects?
5. Why do the samples use the function main() and is it special to wxLua?
6. Why are the arguments shifted +1 for error messages from class member function calls?

1. Why wxLua?

• Because the Lua language is easy and "fun" to program in.
• It vaguely looks like BASIC or C which many people are familiar with.
• The code is very readable, almost no special notation, gotchas, or oddball constructs that require a large shift in thinking from BASIC or C.
• Size : The Lua interpreter itself is ~100Kb, wxWidgets adds the remaining few Mb.
• Speed : Lua is one of the fastest interpreted languages, see the Great Computer Language Shootout.
• Again, why Lua? See http://www.lua.org/about.html

1. What's best for my needs: wxLua, wxPython, wxSomethingElse?

• It depends: wxPython has a much larger footprint and greater overhead than wxLua, but it does provide more add-ons from the Python standard library.
• On the other hand, wxLua is as large as the wxWidgets library + ~100Kb for Lua + ~500Kb for the wxLua library.
• wxLua can be easily interfaced with C++ code making it a powerful extension language, which is exactly the intent of its designers.
• In conclusion, if you want to write an entire application in a scripting language and you need things supported by Python which are not present in wxLua out-of-the-box, then you should use wxPython. Instead, if you want to write applications with little overhead or extend your C++ applications, go for wxLua.

2. Can I use wxLua as script interpreter embedded in my own C++ applications?

• Yes! That's explained on the wxLua homepage.
• This is one of the strong points of wxLua: it can be a lightweight, fast interpreter to extend your application and let the user customize it...
• You may create as many wxLua interpreters in a single program as you like.

2. How to Learn wxLua

1. Read the wxLua documentation

• wxlua.html is the manual for wxLua that describes the Lua language as well as where the wxWidgets C++ are placed in Lua and how to use them.
• wxluaref.html is an autogenerated document that can be thought of as a reference manual of what wxLua binds from wxWidgets. It also has usage notes for the cases where wxLua differs from C++ wxWidgets.
• binding.html describes how to write your own bindings for a C or C++ library, but people who will only write Lua code should also read it to be able to interpret the wxluaref.html document.

2. Read the C++ wxWidgets documentation

• wxLua is mapped very closely to wxWidgets which means that descriptions for the functions and values there also apply to wxLua. See the wxluaref.html document to verify that this is the case and any non typical behavior will be clearly marked.
• See the wxWidgets Wiki for examples of code, beginner howtos, and other useful bits of information that might be useful.
• See wxPython documentation and their Wiki, but note that wxLua follows the C++ notation a little closer than wxPython does.

3. Run and trace through the samples

• The samples try to show off various classes and their usage.
• unittest.wx.lua is used to confirm that wxLua is operating properly, however it provides a wealth of information about what is allowed in terms of calling functions, casting classes to other classes, using virtual functions, and derived functions.
• binding.wx.lua traverses the C structs that store the data used for wxLua and it's worth taking the time to browse them to see how it all fits together.

3. Programming in wxLua

1. wxStrings?

• wxLua uses Lua strings and so all functions that take or return a wxString take or return a Lua string.
• However, you can also use a wxString if you really want.

2. wxArrayString and wxSortedArrayString?

• All functions that take a wxArrayString or wxSortedArrayString can also take a numerically indexed table of strings.
• Functions that return wxArrayStrings or wxSortedArrayStrings will return a wxArrayString or wxSortedArrayString unless specified otherwise in wxluaref.html

3. wxArrayInt?

• All functions that take a wxArrayInt can also take a numerically indexed table of numbers.
• Functions that return wxArrayInts will return a wxArrayInt unless specified otherwise in wxluaref.html.

4. When and how should you delete() objects?

• You should read the subsection "C++ Classes CLASS_NAME" of the "Programming in wxLua" section of the wxlua.html manual.
• In short, all objects that you create that deal with graphics should be delete()ed as soon as they're no longer used. Functions that take a "const wxPen& pen" or any wxObject derived class that are passed to a function that is const and not a pointer* will make a refed copy of them and so you may delete them.
• Use the function "table = wxlua.GetGCUserdataInfo()" to get a table of items that are tracked and either have an active variable pointing to them or are waiting to be garbage collected.
• Class objects that have the %delete tag in their declaration (see wxluaref.html) will be automatically garbage collected or can be delete()ed with the wxLua added function for the class. There are, of course, exceptions and these occur when you pass the object to a function with the %ungc tag on the parameter you pass the object to. The ungarbage collect tag specifies that the object is now owned by something else and you can no longer delete it in wxLua.
• Bottom line - don't worry about delete()ing anything except:
• Graphics objects (for MSW really).
• Classes that specifically state (in wxluaref.html) that you should delete() them because the garbage collector may not do so soon enough.
• Objects that may be very large, like a wxImage(1000, 1000).

5. Why do the samples use the function main() and is it special to wxLua?

• There's nothing special about the function main() other than that it's a common name for an entry point into a program.
• It is often helpful and a good idea to encapsulate the program initialization code within a function so that you can use local variables and not pollute the global table with temporary variables that won't be needed again.
• Additionally, it allows you to break out of this initialization code at any point by putting "do return end" inside of the function for debugging, as opposed to wrapping parts you don't want using "if false then ... end".

6. Why are the arguments shifted +1 for error messages from class member function calls?

• Because the ':' calling convention is syntaxic sugar for putting the 'self' as the first parameter.
• s = wx.wxSize(1, 2); s:Set(3, 4) is the same as s.Set(s, 3, 4) and the first parameter is always the self, therefore s.Set(s, "hello", 4) or s:Set("hello", 4) will give an error that parameter 2 is not a number.
• Unfortunately there is no way to tell whether the user has used the '.' or ':' calling convention and so the error message cannot be tailored for both static and nonstatic member functions. Just remember that the first parameter for nonstatic class member functions called using the ':' notation is the 'self'.