Skip to content

Latest commit

 

History

History
1756 lines (1516 loc) · 89.1 KB

wxlua.md

File metadata and controls

1756 lines (1516 loc) · 89.1 KB
Raw

% wxLua 3.2.0.2 - User Manual % John Labenski, Paul Kulchenko % 2022-11-06

wxLua is a Lua scripting language wrapper around the wxWidgets cross-platform C++ GUI library. It consists of two IDE type editors that can edit, debug, and run Lua programs (wxLua and wxLuaEdit), an executable for running standalone wxLua scripts (wxLuaFreeze), a Lua module that may be loaded using require("wx"){.lua} when using the standard Lua executable, and a library for extending C++ programs with a fast, small, fully embeddable scripting language.

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, booleans, strings, functions, tables, and userdata. Perhaps the most powerful feature of the Lua language is that tables can be used as either numerically indexed arrays or associative arrays that can cross-reference any variable type to any other variable type.

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, file and image manipulation, drawing, networking, 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 the bindings by turning off preprocessor directives.

Additionally, wxLua adds a library for manipulating the bits of integer numbers using a back-ported bit32 library from Lua 5.2.

References:

wxLua website - http://wxlua.sourceforge.net wxLua Sourceforge page - http://sourceforge.net/projects/wxlua Lua website - http://www.lua.org wxWidgets website - http://www.wxwidgets.org Mailing list - [email protected]

Table of Contents

  1. Version Information
  2. Requirements
  3. Brief Introduction to Lua
  4. Bit Library
  5. Programming in wxLua
    5.1 Naming, location, and usage of the wxWidgets objects declared in the C++ header files in the wx Lua table
  6. wxLua Samples and How to Run Them
    6.1 How to Run the Samples
    6.2 Provided Samples
  7. wxLua Applications
    7.1 wxLua
    7.2 wxLuaEdit
    7.3 wxLuaFreeze
    7.4 Lua Module using require()
  8. wxLua Utils
    8.1 bin2c.lua
  9. wxLua Sourcecode Modules
  10. wxLua C++ Programming Guide
    10.1 Data stored in Lua's LUA_REGISTRYINDEX table
    10.2 Functions to Create a wxLuaState
    10.3 Using a wxLuaState

1 - Version Information

  • The wxLua version number is set to the stable version of wxWidgets that it has been updated to.

    • The revision number (X.Y.Z.revision) can be thought of as the wxLua version number.

  • Lua 5.1.5, 5.2.3, or 5.3

    • wxLua uses a nearly unmodified copy of Lua 5.1.5 or 5.2.3.
    • Official patches on www.lua.org are applied as they are released.
    • In MSW the Lua executable has a manifest set to load version 6 of the comctrl32.dll (if available) so that in MS Windows 7+ the controls look modern. When not running wxLua GUI code the executable behaves no differently.
    • Any program that works using the official release of Lua will work in wxLua.

  • wxWidgets 3.x

    • wxLua currently compiles with wxWidgets versions 2.8.x, 2.9.x, and 3.x.
    • It may compile with newer versions of wxWidgets as well as older ones.
    • The interface files have #ifdefs for 2.6, 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.6.
    • Note for wxWidgets < 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 >= 2.9 the wxStyledTextCtrl is now part of the main distribution.
    • The wxLua library links to these wxWidgets libs: stc, xrc, html, media, adv, net, xml, core, base, tiff, jpeg, png, zlib, regex, expat.
    • See the wxLua install.html for more information.

2 - Requirements

Lua programmers 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 for will need a development library of wxWidgets; typically the source code that you have compiled on your system. More information about compiling wxLua is contained in the wxLua install.html file.

3 - Brief Introduction to Lua

This short primer is meant to give you a good enough feeling for Lua that you should be able to understand the sample programs and begin to write your own. It assumes that you have a cursory understanding of general programming techniques. You should, in any case, read the Lua documentation at www.lua.org.

  • Comments

    • Single line comments

      • -- rest of line is commented{.lua}

    • Multiple line block or inline comments

      • --[[ multiple line or inline comment ... ]]{.lua}

  • Variables

    • Variables are not permanently typed and you can freely overwrite them with other values or types, there is no "const" keyword.
    • Variables are global unless you put the keyword local{.lua} in front of them, this is sometimes good practice.
    • The scope of local{.lua} variables is limited to the current scope and its children.
    • 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.
    • Local variables are faster than global variables because they do not require a table lookup for use.
    • A local{.lua} variable created with the same name as a global variable supersedes the global variable within the scope of the local variable.
    • The function type(var_name){.lua} returns the variable type as a string.
      • The eight variables types are: nil, boolean, number, string, table, function, userdata, thread{.lua}

  • Lua Types

    • nil : A special value meaning NULL or nothing.

      • a = nil; local b; print(a, b, type(a), type(b)){.lua} ; prints "nil nil nil nil"
      • Variables that have not been assigned a value are nil{.lua} and any variable can be reset back to nil{.lua} at any time to allow the Lua garbage collector to delete them if there are no other references to it.
      • This value is often returned for functions that fail.
      • You can provide an inline alternative to nil{.lua} using the or{.lua} keyword since nil{.lua} evaluates to false.
        • print(tonumber("a"), tonumber("a") or 1){.lua} ; prints "nil 1"

    • boolean : true{.lua} or false{.lua}

      • a = true; b = false; print(a, b, type(a), type(b)){.lua} ; prints "true false boolean boolean"
      • Note that nil{.lua} works as false{.lua}, but the number 0 evaluates as true{.lua} since it has a value, i.e. not nil{.lua}, use (a ~= 0){.lua}.
      • a = 0; if a then print(a) end{.lua} ; prints "0" since the variable "a{.lua}" evaluates to true{.lua}.

    • number : All numbers in Lua are double valued floating point numbers.

      • a = 1; b = 3.14; print(a, b, type(a), type(b)){.lua} ; prints "1 3.14 number number"
      • n = (1E1 * 3.14 * math.sin(1) / 4)*math.pow(2.5e-1, 4){.lua}
      • Variables can be coerced into numbers using the function tonumber(variable){.lua} which returns nil{.lua} on failure.
      • Additional math functions are in the math{.lua} table.

    • string : Strings in Lua can have embedded nulls "\0" and use the same escape characters as C.

      • a = "hello"; b = a; b = "hi"; print(a, b, #a, type(a)){.lua} ; prints "hello hi 5 string"

      • 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.

      • String variables are copy on write and the example above shows that overwriting "b" does not change "a".

      • s = "How are 'you'!"{.lua} or s = 'How\tare "You"!\n'{.lua} are both valid since either " or ' can be used to quote strings. ('\t' = tab, '\n' = line feed)

      • s = [[How are "'you'"!]]{.lua} ; double brackets can be used to create multiline strings that include new lines and whitespace.

      • Concatenate strings using the ..{.lua} operator

        • str1 = "hello"; str2 = "number"; str3 = str1.." "..str2.." "..tostring(2).."!"{.lua}
        • Numbers can be coerced into strings as ("A "..2){.lua}, but not (2.."A"){.lua} since the left hand side of the ..{.lua} operator must be a string.
        • Many strings should be concatenated together by putting them into a table array using table.insert(){.lua} (or appended using table[#table+1] = "hello"{.lua}) and then table.concat(){.lua} called to create the single string result. The concatenation operator ..{.lua} is slower since each intermediary string has to be reallocated and hashed. The table.concat(){.lua} method only has to allocate and hash the resultant string once and its speed is quite competitive to other scripting languages.

      • Variables can be coerced into strings using the function tostring(variable){.lua} which returns nil{.lua} on failure.

      • Additional string functions are in the string{.lua} table.

    • table : Tables can be indexed by and hold values of numbers, strings, functions, userdata, other tables...

      • a = {5}; b = a; b[1] = 6; print(a, b, a[1], b[1], b[2], type(a), type(b)){.lua}

        • prints "table: 01780F98 table: 01780F98 6 6 nil table table"
        • Printing a table is the same as calling tostring(t){.lua} on the table which displays the variable type and its memory address.
        • Assigning a variable to an existing table does not copy the table values and you can use either variable to access and modify the table elements.
        • There is no built-in deep or shallow table copy function, but it is easy enough to write your own. The reason is that tables can contain back-references to themselves and to other parts of the table and having a prior knowlege of how the table is constructed helps in writing a copy function that works quickly and behaves as desired.

      • t = {}{.lua} creates an empty table.

        • You must declare a variable as a table before using its indexes.

      • t = { ["a"] = 5, "first", "second", B = 7 }; print(t.a, t["a"], t[0], t[1], t[2], t.B, t.b, t.c){.lua}

        • prints "5 5 nil first second 7 nil nil"

        • Set values as : t.a = 2; t["a"] = 3; t[10] = 4{.lua}

        • Elements are automatically created when assigning new values to elements that don't already exist and accessing elements that don't exist returns nil{.lua}.

        • Clear values by setting them to nil{.lua}, e.g. t.a = nil{.lua}

        • The length operator #t{.lua} returns 2 since there are only two contiguous integer table indexes starting from 1 even though in this case there are actually 4 entries in the table.

          • The length of a table used as an array with holes (nil values) is undefined.
          • The only guarantee is that the value at t[#t+1]{.lua} will be nil{.lua}.
          • This is an optimization detail, if you want to use a table as an array you must simply fill the 1..N indicies with values.

        • Lua table arrays have a starting index of 1.

        • for k, v in ipairs(t) do print(k, v) end{.lua} ; Note: (k = key, v = value)

          • prints only the array values : "1 first" and "2 second"

        • for k, v in pairs(t) do print(k, v) end{.lua} ; Note: (k = key, v = value)

          • prints all table values (unordered) : "1 first", "2 second", "a 5", "B 7"

      • Functions defined by Lua are placed into tables, a namespace if you will, to keep the global namespace uncluttered.

        • See table.XXX, string.XXX, math.XXX, os.XXX{.lua} etc. in the Lua documentation.
        • wxLua places the wxWidgets bindings into the wx.XXX{.lua} table "namespace".

      • The global table is called _G{.lua} and you can display it as you would any table using : - for k, v in pairs(_G) do print(k, v) end{.lua}

      • Additional table functions are in the table{.lua} table.

    • userdata : A pointer to a C/C++ object.

      • A metatable (see Lua documentation) may be assigned to it to allow it to act as a table or be called as a function, among other things.
      • wxLua uses userdata types to wrap the wxWidgets C++ objects to make them useable in a Lua program.

    • function : A handle to a function.

      • function f(a, b) return a+b end; print(f, f(1,2), type(f)){.lua}

      • f = function (a, b) return a+b end; print(f, f(1,2), type(f)){.lua}

        • Both lines above print "function: 01DE2AF8 3 function", where 01DE2AF8 is the unique memory address of the function.
        • Printing a function is the same as calling tostring(f){.lua} on the function which displays the variable type and its memory address.

      • Functions can return multiple values and be passed more or less variables than specified.

      • Unassigned inputs are set to nil{.lua} and unassigned return values are discarded.

      • Functions can be assigned to variables or put into tables.

        • t = {}; t["Add"] = f; print(t.Add(1, 2), t.Add){.lua} ; prints "3 function: 01DE2AF8
        • If you plan on putting a function into a table you may want to declare the function local since it won't be garbage collected until the local variable goes out of scope and the table is garbage collected or the table's index to the function is set to nil{.lua}.

      • Boolean, number, and string parameters are passed to functions by value and changes to them within the function body does not modify the original variable's value.

      • Tables and userdata are passed to functions by reference and changes to them within the function body does modify the original variable's value.

      • function table_append(t, v) t[#t+1] = v; v = 0; end; tbl = {}; item = "hello"; table_append(tbl, item); print(tbl[#tbl], item){.lua}

      • prints "hello hello", i.e. tbl[1] == "hello"{.lua} and the variable "item{.lua}" still equals "hello" and was not changed.

  • Operators

    • Relational : == ~= < > <= >={.lua} (Note: not equal is ~={.lua})
    • Logical: and, or, not{.lua}
    • Precedence (low to high):
      1. or{.lua}
      2. and{.lua}
      3. < > <= >= ~= =={.lua}
      4. ..{.lua} (string concatenation)
      5. + -{.lua}
      6. * / %{.lua}
      7. not # -{.lua} (unary)
      8. ^{.lua}

  • Keywords

    • and break do else elseif end false for function if in local nil not or repeat return then true until while{.lua}

  • do ... end

    • Create a new local scope in a do ... end{.lua} block.
    • Note : You cannot write function printHi() return; print("hi") end{.lua}, but you can write function printHi() do return end; print("hi") end{.lua} which can be useful for debugging functions.
        do
            -- create a new local scope
            local a = 2
        end
  • if (bool) then ... elseif (bool) then ... else ... end
        local a, b, c = 1, 2, 3 -- can assign multiple values
        a = 1; b = 2; c = 3     -- use ; for multiple lines of code on single line
        a, b, c = 1, 2, 3       -- this works too

        if (a == 1) and ((b <= 2) or (c ~= 3)) then
            print(a+b/c)
        elseif a == 2 then      -- no parentheses necessary
            print(a)
        else
            print(b)
        end
  • There is no case statement, but table[value] = function() ... end{.lua} may be used to simulate one.
        case = {}
        case[1] = function() print("Hello #1") end -- anonymous function
        case[2] = function() print("Hello #2") end
        ...
        if case[value] then
            case[value]()
        else
            print("Unknown case value")
        end
  • while (bool) ... end
    • Note : there is no "continue" keyword only break{.lua}
        function Check5(val) -- returns nil if val ~= 5
            if val == 5 then
                return true
            end
        end

        local a = 1
        while a < 10 do
            print(a)
            if Check5(a) then break end
            a = a + 1 -- no increment operator
        end
  • You can simulate a "continue" statement by adding an inner while loop (doesn't print # 5).
        local a = 0
        while a < 10 do while true do
            a = a + 1 -- no increment operator
            if Check5 (a) then
                break -- break in the inner while loop to "continue" in the outer loop
            else
                print(a)
            end

            break end -- break out of inner while loop
        end
  • repeat ... until (bool)
    • Note : there is no "continue" keyword only break{.lua}
        local a = 10
        repeat
            local temp = a * 2
            print(temp, type(temp))
            a = a - 1 -- no decrement operator
        until a < 0
  • for var = init_value, end_value [, increment] do ... end
    • Note : there is no "continue" keyword only break{.lua}
    • 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.
    • Copy the loop counter variable to a separate variable if you need to save it when breaking for example.
        local a = "hello"
        for a = 1, 10 --[[, increment]] do -- optional increment value, default increment is 1
            local temp = a * 2
            print(temp)
        end

        print(a) -- a == "hello" since loop counter variable is local to the loop
  • functions

    • Input any number of parameters by value, tables and userdata are passed by reference.

    • Missing input variables are assigned the value nil{.lua}, extra inputs are discarded.

    • Return values using the "return{.lua}" keyword.

    • Not all return values need to be used and extra ones will be discarded.

      • The symbol "_" is a valid variable name and is often used as a dummy variable to receive return values that you do not want.

        • function GetNums() return 3, 4, 5, 6 end; local _, num2 = GetNums(){.lua}

      • You may also use the select(n, ...){.lua} function to choose return values to use.

        • print(select("#", GetNums()), "and", select(3, GetNums())){.lua} ; prints "4 and 5 6".
        • Note select(n, ...){.lua} returns all args after n{.lua}, but if the left hand side is a single variable the others are discarded.

    • Tables can be used as containers for input values to functions using the unpack(table, [i, [, j]]){.lua} function.

      • This is useful for creating complex inputs to a function or storing them for reuse.
      • print(string.find(unpack({"Hello", "ll", 1, 1}))){.lua} ; prints "3 4"

    • Vararg inputs are written as function dostuff( ... ) end{.lua}

      • The number of args is found using: local n_args = select("#", ...){.lua}
      • The args can be converted into table using: local args = { ... }{.lua}
      • A particular arg can be chosen using: local arg3 = select(3, ...){.lua}
        • See above about using select(){.lua} to pick return values of a function as well.
        -- Print the keys in table t that have the given values.
        function PrintKeys(t, values, cmp_case)
            -- use nested functions for repetitive code or to simplify code
            local function cmp_values(a, b)
                if cmp_case then -- can use upvalue variables
                return a == b
                else
                    return string.lower(a) == string.lower(b)
                end
            end
            local function find_key(t, val)
                for k,v in pairs(t) do
                    if cmp_values(val, v) then return k end
                end
            end
            for i = 1, #values do
                print(find_key(t, values[i]), values[i])
            end
        end

        data = {a1 = "a2", b1 = "b2", c1 = "c2"}

        -- prints "a1 a2", "b1 b2", "nil C2"
        PrintKeys(data, {"a2", "b2", "C2"}, true)

        -- Varargs example demonstrating the different ways to handle them.
        function Varargs(...)
            local args = {...}
            print(select("#", ...), #{...}, #args, args[2], unpack({...}, 2, 2))
            return args, unpack(args) -- same as return ...
        end

        -- prints "4 4 4 20 20" and "table: 0183B820 10 30 5"
        vals, val1, _, val3 = Varargs(10, 20, 30, 40)
        print(vals, val1, val3, select("#", Varargs(10, 20, 30, 40)))

4 - Bit Library

wxLua automatically loads a library for manipulating the bits of an integer number and puts it into the global bit32{.lua} 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 powers of 2 (perhaps one is a bit mask) this fails, 0x01 + 0x03 = 0x04 or bitwise 0100 (oops) instead of the desired 0011.

wxLua uses a bitlib library backported from Lua 5.2 and since the code for it is very small, it's embedded into the wxLua sourcecode.

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).

The logical operations start with "b" for "bit" to avoid clashing with reserved words; although "xor" isn't a reserved word, it is consistent.

bit32.rshift(x, disp){.lua} - returns x shifted logically right disp places or left if negative bit32.band(...){.lua} - returns the bitwise and of the input values bit32.bnot(x){.lua} - returns the one's complement of x bit32.bor(...){.lua} - returns the bitwise or of the input values bit32.btest(···){.lua} - returns true if the and of the input values is not 0 bit32.bxor(...){.lua} - returns the bitwise exclusive or of the input values bit32.extract(n, field [, width]){.lua} - returns the number of bits set in n for the given 0-31 starting field to optionally field+width-1 bit32.replace(n, v, field [, width]){.lua} - returns n with the bits in field to optionally field+width-1 replaced by the value v bit32.lrotate(x, disp){.lua} - returns x rotated disp bits to the left bit32.lshift(x, disp){.lua} - returns x shifted left disp places or right if negative bit32.rrotate(x, disp){.lua} - returns x rotated disp bits to the right bit32.rshift(x, disp){.lua} - returns x shifted right disp places or left if negative

5 - Programming in wxLua

Programming in wxLua means that you're writing programs in the Lua language using an additional table of functions, objects, numbers, strings, and "classes" in the namespace table wx{.lua} from wxWidgets. Additional wxWidgets libraries are added as their own bindings and placed in their own "namespace" table, but for the examples below the wx{.lua} table is used.

wxLua creates five Lua tables for the binding functions and objects. These are in addition to the standard Lua tables; coroutine, debug, io, math, os, package, string, table{.lua}. Note that the wxaui and wxstc libraries have been separated into their own tables since they are fairly specialized libraries.

bit32 - A backport of the Lua 5.2 bit32 library for manipulating integer bits added to Lua 5.1. wxlua - Special functions for introspecting wxLua or generic functions that wxLua provides that are independent of wxWidgets. wx - wxWidgets functions, classes, defines, enums, strings, events, and objects are placed here. wxaui - The wxWidgets Advanced User Interface library. wxstc - The wxStyledTextCtrl wrapper around the Scintilla text editor.

The semantics for accessing wxWidgets elements in wxLua tries to map closely to the underlying C++ notation so that the official C++ documentation may be used as a reference, http://www.wxwidgets.org/docs. The most common cases where wxLua deviates from C++ are for functions with values passed by reference that will be changed; wxLua will typically return multiple values instead. Please see the wxluaref.html document that lists all the wxWidgets objects wrapped by wxLua and take note of the functions that are marked %override since you will need to use them as described in that document. You should also look at the binding.html file, even if you do not plan to write your own bindings, to get a better understanding of the wxluaref.html file.

Strings : 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 preferrably 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.

wxArrayString and wxSortedArrayString : Function parameters that take a "const wxArrayString& 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& 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.

wxArrayInt : Function parameters that take a "const wxArrayInt& 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& 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.

Coroutines : wxLua works with coroutines with one important caveat.
NEVER connect an event handler function callback from within a coroutine{.boldred}

  1. There is no way for wxLua to detect that a coroutine is closed until the garbage collector runs which is usually too late and the program crashes.
  2. The callback function will probably only be called when the coroutine is yielded and Lua throws an error for this condition.
  3. The one exception to this rule is if the whole wxLua program is run in a coroutine that never yields, which doesn't make typically make sense.

5.1 - Naming, location, and usage of the wxWidgets objects declared in the C++ header files in the wx{.lua} Lua table

  • #define NUMBER_DEFINE VALUE

    • All #defined numerical values are available as wx.NUMBER_DEFINE{.lua}
    • Example "#define wxID_ANY -1" is accessed as wx.wxID_ANY{.lua}
    • Declared in the bindings using the %define tag.

  • [int, double, etc] NUMBER_VARIABLE;

    • All global numerical variables are available as wx.NUMBER_VARIABLE{.lua}
    • Example : "extern const int wxInvalidOffset;" is accessible as wx.wxInvalidOffset{.lua}.
    • Declared in the bindings using the %define tag.

  • enum ENUM_NAMESPACE [or CLASSNAME::ENUM_NAMESPACE] { ENUM_NAME }

    • All global enums, named or not, are available as wx.ENUM_NAME{.lua}

      • Example : "enum wxDirection { wxLEFT, ... }" is accessible as wx.wxLEFT{.lua}

    • All enums that are members of classes are available as wx.CLASSNAME.ENUM_NAME{.lua}

      • Example : "enum wxFTP::TransferMode { ASCII, ... }" is accessible as wx.wxFTP.ASCII{.lua}

    • This follows the C++ semantics that you do not specify the name of an enum, but you do have to use its scope if it is a class member.

    • Declared in the bindings using the %enum tag.

  • #define STRING_DEFINE wxT("String Value")

    • All #defined string values are available as wx.STRING_DEFINE{.lua}
    • Example : "#define wxIMAGE_OPTION_CUR_HOTSPOT_X wxT("HotSpotX")" is accessible as wx.wxIMAGE_OPTION_CUR_HOTSPOT_X{.lua}
    • Declared in the bindings using the %define_string tag.

  • const wxChar STRING_VARIABLE;*

    • All global string variables are available as wx.STRING_VARIABLE{.lua}
    • No examples yet.
    • Declared in the bindings using the %define_string tag.

  • wxEVT_XXX for wxEvtHandler::Connect()

    • All wxEVT_XXX wxEventTypes (an integer) are available as wx.wxEVT_XXX{.lua}

      • Example : wx.wxEVT_COMMAND_MENU_SELECTED{.lua} for menu item selection.

    • wxLua does not use the static event tables, the EVT_XXX() macros, since it is not a compiled language, but rather the corresponding wxEVT_XXX identifier. The wxluaref.html manual contains a complete mapping between the two.

    • Use the wxEvtHandler::Connect() function to connect event types to a wxEvtHandler; typically a wxWindow derived class.

      • Example : EVT_MENU(id, func) use window:Connect(menuId, wx.wxEVT_COMMAND_MENU_SELECTED, Lua function){.lua}. The Lua function must have the signature of function MenuEvent(event) ... handle event ... return{.lua} where the event variable will be the wxEvent dervied class that the wxEventType was declared in, which in this case is a wxCommandEvent.

      • Example : EVT_PAINT(func) use window:Connect(wx.wxEVT_PAINT, Lua function){.lua}. There is no Id used for this connect event function call since the paint event handler function is directly connected to the window. In the menu case, the handler is typically connected to a parent window, perhaps a wxFrame. The menu event event generated by the menu travels up the chain of window parents until a handler is found. The Id is needed to determine where the event came from.

        • Note: You must always create a wxPaintDC for wxEVT_PAINT to clear the update region.
        • local dc = wx.wxPaintDC(event:GetEventObject():DynamicCast("wxWindow")){.lua} and then call dc:delete(){.lua} 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.

    • Declared in the bindings using the %define_event tag.

  • Objects of classes or structs OBJECT_NAME

    • All global objects that are classes or structs are available as wx.OBJECT_NAME{.lua}
    • Example : "const wxImage wxNullImage;" is accessible as wx.wxNullImage{.lua} and functions from the wxImage class can be called as wx.wxNullImage:Ok(){.lua} which should return false.
    • Declared in the bindings using the %define_object tag.

  • Pointers to classes or structs POINTER_NAME

    • All global pointers that are classes or structs are available as wx.POINTER_NAME{.lua}
    • Example : "extern wxPenList wxThePenList;"* is accessible as wx.wxThePenList{.lua} and functions from the wxPenList class can be made as pen = wx.wxThePenList:FindOrCreatePen(wx.wxColour(1,2,3), 1, wx.wxSOLID){.lua}
    • Declared in the bindings using the %define_object tag.

  • Global C style functions VAR_TYPE FUNCTION_NAME(int a, const wxString& str)

    • All global C style functions are available as wx.FUNCTION_NAME(1, "Hello"){.lua}
    • Example : "extern wxString wxGetUserHome(const wxString& name)"{.lua} is accessible as home_dir = wx.wxGetUserHome("john"){.lua} where wxString means to input a Lua string and a Lua string is returned.
    • Declared in the bindings using the %function tag.

  • C++ Classes CLASS_NAME

    • All C++ classes are available as wx.CLASS_NAME{.lua}, 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.

      • Example : pt = wx.wxPoint(1, 2); pt2 = wx.wxPoint(pt){.lua}
      • 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.
      • Member functions inherited from the base class(es) are also available and may be overloaded as well.
      • The C++ classes are exposed as tables in Lua, but have a __call{.lua} metatable item so they can be called as a function. If you need to get the constructor function itself you can use wx.CLASS_NAME.new(...){.lua} which is the constructor exposed as a Cfunction.

    • The C++ class objects are pushed into Lua as a userdata wrapping a void* pointer to the C++ object.

      • A special metatable is set on the userdata with these entries :
        • __index{.lua} to call functions on the object or to get member variable values.
        • __newindex{.lua} to set new functions or values or set member variable values.
        • __tostring{.lua} to allow print() to show something useful
          • print(wx.wxPoint()){.lua} prints "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, but it will be unique within a run.
        • __gc{.lua} to tell wxLua when the userdata is no longer used so wxLua can delete the C++ object if appropriate.

    • Declared in the bindings using the %class tag.

    • Deleting class userdata can be done using the wxLua added class member function delete().

      • All classes that have the %delete binding tag will be eventually garbage collected when they go out of scope.

      • Classes without the %delete tag are assumed to be eventually attached to another object that will delete them for you.

      • 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.

      • However! Some graphical device interface (GDI) classes need to be deleted immediately after you are done using them.

        • This is really a problem only in MS Windows. Windows 95 based systems are allowed only dozens of GDI objects at any one time, but even in NT systems (XP, Vista, 7) 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.
        • In any case, just delete(){.lua} them when done so that your program will work equally well in MSW as it would in Linux or OSX.

      • Additionally, since the Lua userdata that wxLua pushes into Lua only store a void* pointer to the C++ class object, Lua can only think they are of size void* which are 8 bytes on 64-bit x86 machines. 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.

      • The solution is to use the delete(){.lua} function on certain types of userdata when you are done.

      • Care must be taken to ensure that you're not silently creating too many temporary objects.

        • Example: wxDC:SetPen(wx.wxPen(wx.wxColour(1,2,3), 1, wx.wxSOLID)){.lua}; notice that both a wxPen and a wxColour have been created, but there is no way for you to call delete(){.lua} on them so they will collect until Lua runs its garbage collector.
        • You can force garbage collection using collectgarbage("collect"){.lua} in Lua, but this may cause slight pauses in your program's execution.
        • It is a good idea to collect all the garbage at the end of your initialization function to at least start out with a clean slate since program startup time is usually not a concern.

      • This is a list of classes by order of importance of deleting them:

        • Must delete : wxDC, wxPaintDC, and ALL classed derived from wxDC.{.boldred}
        • Must delete if > 50 : wxBitmap, wxBrush, wxColour, wxCursor, wxFont, wxIcon, wxPen, wxRegion{.boldred}
          • To be sure, delete them when you're done and not worry.
        • Must delete if large and you're creating many of them : wxImage, wxBitmap, etc.
        • Don't bother : wxPoint, wxRect... etc
        • Never delete : wxWindows attached their their parents (use Destroy()) or the wxMenuItems returned from a wxMenu.
          • Safe rule, don't delete(){.lua} things that aren't yours. Refer to the wxWidgets documentation about whether an object will take ownership of an object passed to it.

      • How to tell how many userdata objects you currently have?

        • Print the output of wxlua.GetGCUserdataInfo(true){.lua} to show what objects will be garbage collected when their reference count goes to zero and the Lua garbage collector runs.

        • Print the output of wxlua.GetTrackedObjectInfo(true){.lua} to get class objects that wxLua has pushed into Lua that may or may not be garbage collected.

        • Call the function wxlua.LuaStackDialog(){.lua} when you run your program and examine the items in the Lua LUA_REGISTRYINDEX table. Expand "wxLua objects pushed" and "wxLua gc objects to delete" tables.

    • Member functions of the class are called using the colon ':' convention and NOT the period '.'. This is because ':' in Lua puts the object itself on the stack, the "self" as it's called. The "self" is used by the binding code to call the function with. If you really want to use the '.' notation you can pass the "self" to the function as the first parameter. There are two exceptions to the ':' calling convention rule, properties and static functions. Please see the sections below about why they only use the '.' convention.

      • Example : size = wx.wxSize(1, 2); size:SetWidth(10); size.SetHeight(size, 11); print(size:GetWidth(), size.GetHeight(size)){.lua} where we create a wxSize, set a new width and height, and then print the numerical values.
      • Functions may be renamed in the bindings using the %rename tag in the interface files. You call the functions in Lua using the name after the %rename tag with the same parameters as the original function. This is only done for special cases that would be awkward, if not impossible, to wrap otherwise.

    • Property functions allow you to read and/or write values to a class using the '.' convention and a shortened name.

      • These are generated on the fly when the function is called on a wxLua userdata and work only for functions following these rules.

        • GetXXX() takes no values and returns one.
        • SetXXX(value) takes one value and returns none.

      • The Get/Set part of the function name is removed leaving only XXX and you do not call them like a function using "()", but rather like accessing a table member, without the "()".

      • Example : "rect = wx.wxRect(wx.wxPoint(1,2), wx.wxSize(3,4)); rect:SetX(20); rect.X = 10; print(rect.X, rect.X == rect:GetX(), rect.X == rect.GetX(rect)){.lua}" should print "10, true, true".

      • Note : There is no way to find out from Lua if the code used a '.' or a ':' to call the function and therefore properties cannot be made to work for the ':' calling convention since in that case we have to remove the object (the self) that Lua automatically pushes onto the stack that we don't need or want.

      • Note : Since these methods are generated at runtime they will not work for static functions in the class table, but they will work for static functions called from a userdata object.

      • Below is a list of what works and doesn't, the example is for a static class member function, but the same works for a regular class member function.

        • Works (static functions only) : print(wx.wxFileName.GetCwd()){.lua} and print(wx.wxFileName.GetCwd){.lua} prints that it's a function.
        • Fails (static functions only) : print(wx.wxFileName:GetCwd()){.lua} and print(wx.wxFileName:GetCwd){.lua} since there is no "self" for the ':' operator to push.
        • Works : f = wx.wxFileName("a"); print(f.GetCwd()){.lua} and print(f.GetCwd){.lua} prints that it's a function.
        • Fails : f = wx.wxFileName("a"); print(f:GetCwd()){.lua} and print(f:GetCwd){.lua} since there is no "self" for the ':' operator to push.
        • Works : f = wx.wxFileName("a"); print(f.Cwd){.lua}
        • Fails : f = wx.wxFileName("a"); print(f.Cwd()){.lua} and print(f:Cwd){.lua} and print(f:Cwd()){.lua}

      • Note : Are properties really necessary? Confusing? Useful? I'd stick with the Get/Set functions. - JL

    • Member variables allow you to read and/or write to member variables of a class.

      • Declared in the interface files using the %member or %member_func tag.

      • Example : In the interface file gdi.i this is declared for wxPoint : "%rename X %member_func int x"

      • The wxPoint class does not have functions to access the int x, y member variables so we create our own.

      • The %member_func tag creates functions called Get/Set[variable name] or in this case Getx() and Setx(value), but these aren't too pretty so we use the %rename tag to rename them to GetX() and SetX(value). It additionally creates properties for the x variable so the '.' calling convention also works.

      • These two methods of getting and setting the x and y member of the wxPoint class are interchangeable.

        • Example : pt = wx.wxPoint(1,2); pt.x = 10; pt:SetY(11); print(pt.x, pt:GetY()){.lua}

      • If the %member tag is used (as opposed to the %member_func) the Get/Set functions are not generated and the member variables are accessible only through the properties.

      • If the member variable is constant (const) the variable is read-only and you cannot set its value.

    • Static functions are part of the table that holds the class and can be called with or without a class instance (a userdata).

      • Example : f = wx.wxFileName('dummy'); f.GetCwd() == wx.wxFileName.GetCwd(){.lua}
      • Note that you always use the '.' calling convention since static C++ functions do not require the object "self" or in Lua's case the userdata.
      • See the properties section about the difference between '.' and ':' and why using a ':' cannot be made to work reliably when you don't want or need the self pushed onto the stack.

    • Enum members are also part of the table that holds the class and are used by accessing the class table itself.

      • Example : "enum wxFTP::TransferMode { ASCII, ... }" is accessible as wx.wxFTP.ASCII{.lua}

    • Operator functions allow you to use C++ operators in Lua.

      • Lua has a limited set of operators, see the Lua primer, whereas C++ can define many more. Also, not all C++ operators are defined for all classes and very few classes can be mixed with other classes. Operators for classes must be declared in C++. Therefore Lua uses functions to call these operators rather than try to directly modify the existing ones in Lua and then declare the remaining ones as functions.

      • Note also that declaring every operator for all classes in wxLua is usually not necessary because in C++ they typically shadow an existing function that wxLua already wraps.

      • The Lua = operator for a class object will merely create a reference to the object and this itself is useful and why wxLua does not try to override the default behavior.

      • Declared in the interface files using the %operator tag.

      • This is a list of all possible operator functions:

        Relational and equality operators == op_eq() != op_ne() > op_gt() < op_lt() >= op_ge() <= op_le() Logical operators ! op_not() && op_land() "l" stands for logical || op_lor() Bitwise operators ~ op_comp() bitwise NOT or complement & op_and() | op_or() ^ op_xor() << op_lshift() >> op_rshift() Inplace bitwise assignment operators &= op_iand() "i" stands for inplace |= op_ior() ^= op_ixor() >>= op_irshift() <<= op_ilshift() Arithmetic operators = op_set()

        •                                         op\_add()

        •                                         op\_sub()

        * op_mul() / op_div() % op_mod() Unary arithmetic operators

        •                                         op\_neg()       negate

        Inplace arithmetic assignment operators += op_iadd() -= op_isub() *= op_imul() /= op_idiv() %= op_imod() Increment arithmetic operators ++ op_inc() -- op_dec() Other operators [] op_index() Array indexing () op_func() Function call * op_deref() Dereference/Indirection

      • Example : pt = wx.wxPoint(1,2); pt = pt + 1{.lua} gives an error since we're trying to use the Lua operator and even in C++ this wouldn't compile since there is no operator defined for adding a single number to a wxPoint.

      • Example : pt1 = wx.wxPoint(1,2); pt2 = pt1; print(pt2:GetX()); pt2:SetX(10); print(pt1:GetX(), pt1 == pt2){.lua} the = operator works in this case because we are not copying the values of pt1, but rather the address of pt1 to pt2, meaning that pt2 is pt1 and when we set the value for pt2 we're also setting the value for pt1. We know this because the Lua == operators tells us that they have the same address and if you type print(pt1, pt2){.lua} the result is "userdata: 0x858df5c [wxPoint(0x84ab550, 251)], userdata: 0x858df5c [wxPoint(0x84ab550, 251)]". See the wxLua userdata metatable function __tostring{.lua} above.

      • Example : pt1 = wx.wxPoint(1,2); pt2 = wx.wxPoint(); pt2:op_set(pt1); pt1:SetX(10); print(pt2:GetX()); print(pt2:op_eq(pt1)){.lua} Creates pt1 and also creates pt2, but we don't care what value it has since we use op_set() to call the C++ = operator to copy the values from pt1. We then change the value of pt1, test if pt2 has changed, it hasn't, and the test to see if they're still equal and as expected, they're not.

    • Virtual functions

      • You cannot arbitrarily override C++ virtual functions in wxLua as this must be done in C++. The C++ class must be subclassed and the virtual functions overridden to check to see if there is a Lua function to call instead of the base class function. This has only been implemented for cases where it is necessary. In many cases you can intercept the appropriate wxEvent and change the behavior from within the handler.
      • Examples of virtual functions that must or can be overridden are in the wxLuaPrintout class, see the printing sample, and wxLuaHtmlWindow, see html sample. The only virtual functions that you can override are marked with comments in the binding files and wxluaref.htm.
      • Prepend the function name with an underscore, '_' in order to directly access the C++ base class function that you have overridden in Lua.
      • Adding virtual functions to wxLua will be done on a case by case basis. If it is absolutely necessary to override a virtual function for a class you should ask about adding it on the wxLua mailing list. The reason why they have not already been added is that there is a price to pay in terms of binding size and speed.

    • Overriding member functions with Lua functions

      • You may override class member functions for a wxLua userdata and still be able to call back to the Cfunction by prepending the function name with an underscore '_'.
      • The Lua function that you assign to a userdata will be called directly from Lua without regard to the existing Cfunction(s), but will never be called by the C++ class functions.
      • Example : p = wx.wxPoint(1,2); p.GetX = function(self) return 10-self:_GetX() end; print(p:GetX(), p:_GetX()){.lua} ; prints "9, 1".
      • Note : Make sure that if you want to call the base function you use the '_' in your overridden function since otherwise you'll get recursion.

    • Extending classes

      • Lua functions may be added to classes that will not be called by C++, but can be called from Lua. This makes sense if you would like to keep functions that act on a particular class with it rather than having global functions that take that class as a parameter.
      • Example : r = wx.wxRect(1,2,3,4); r.PrintXY = function(self) print(self:GetX(), self:GetY()) end; r:PrintXY(){.lua} adds the function PrintXY() to the wxRect instance r. The userdata, class instance, r is passed to the Lua function as the parameter "self" which is pushed onto the stack when the PrintXY() function is called with the ':' notation.
      • Note that the above example is the same as : r = wx.wxRect(1,2,3,4); function wxRect_PrintXY(r) print(r:GetX(), r:GetY()) end; wxRect_PrintXY(r){.lua}.
      • You may also create the Lua function beforehand and then assign it to the rect object. function wxRect_PrintXY_func(self) print(self:GetX(), self:GetY()) end; r1 = wx.wxRect(1,2,3,4); r1.PrintXY = wxRect_PrintXY_func; r1:PrintXY(){.lua}. You can see that using this idea you can write a Lua function that creates a new wxRect, sets your extra functions for it, and returns it for use.

6 - wxLua Samples and How to Run Them

There are a number of sample programs in the wxLua/samples directory. These programs demonstrate how to write simple programs and try to show how to use some of the many classes of wxWidgets. They are a good resource to learn how to write your own more complicated programs.

We welcome any enhancements or additional samples that might be generally useful to the wxLua community. Please understand that any code you contribute has to be maintained and easily understood, so the code must be simple and clear.

If something in wxLua seems to not work as expected it is best to try to duplicate your error in the simplest possible way in one of the samples and ask on the [email protected] mailing list.

Why are the samples named sample.wx.lua? To allow them to be colorized correctly in syntax highlighting editors, yet denote to people that they are for wxLua and must be run using a wxLua executable or the wxLua module.

6.1 - How to Run the Samples

The examples below are for MS Windows .exe executables, but the same applies for Linux or OSX, just remove the .exe extension from the executable. See also wxLua Applications for more information about these programs.

  • On the command line run wxlua.exe sample.wx.lua
  • On the command line run wxluafreeze.exe sample.wx.lua
  • Open the Lua program in wxlua.exe and choose the menu item 'Run'.
  • Open the Lua program in wxluaedit.exe and select the menu item 'wxLua->Run' or press the toolbar 'play' button to run it.
  • Use wxLua as a Lua module using the function require("wx"){.lua}, run lua.exe sample.wx.lua

    • In order to use wxLua as a module, the Lua code must have require("wx"){.lua} to load the wxLua bindings in the beginning and wx.wxGetApp():MainLoop(){.lua} at the end to run the wxWidgets event loop.

    • To be sure - From the command line you can create wxFrames or wxDialogs and populate them, but nothing will happen when you call Show() on them since the wxEventLoop is not running.

      • For example, run this code in the Lua console:
      • require("wx"){.lua}
      • f = wx.wxFrame(wx.NULL, -1, "Title"){.lua}
      • f:Show(){.lua}
      • Note that the wxFrame is not shown or if it is you won't be able to use it...
      • wx.wxGetApp():MainLoop(){.lua}
      • The wxFrame is now shown and you can interact with it nomally, but the Lua console prompt is hung in the MainLoop() function while wxWidgets processes events. When you close the wxFrame or the last top-level window, the MainLoop() exits and control is returned to the Lua console.
      • You can now create new wxFrames or wxDialogs, but you always have to call wx.wxGetApp():MainLoop(){.lua} in order to use them.

    • You may need to adjust the package.cpath{.lua} variable to have it point to the correct location of the wx.so or wx.dll shared library for require("wx"){.lua} to load.

6.2 - Provided Samples

  • bindings.wx.lua

    • This is a MUST use program, at least once, to get a better understanding of the bindings.
    • Lets you explore the C++ binding structs from within Lua using a wxListCtrl. This program shows the raw data that is used to push the bindings into Lua when a wxLuaState is created.
    • Take note of the menu item "Show Lua stack dialog..." and the code for it. You can use this dialog to debug your own programs by viewing the stack, local and global variables, as well as the Lua registry which is only accessible in C.

  • calculator.wx.lua

    • A simple calculator program that demonstrates loading and using controls from an XRC resource, accelerator tables, and event handling.
    • This programs loads the file calculator.xrc to create its GUI.

  • choices.wx.lua

    • Demonstrates a number of controls that offer choices to the user, wxRadioBox, wxListBox, wxComboBox, wxChoice, and wxCheckListBox.
    • It uses a wxNotebook and wxSizers for layout.

  • coroutine.wx.lua

    • A demo of how to use coroutines in wxLua using wxEVT_IDLE to call coroutine.resume().

  • dialog.wx.lua

    • A simple temperature conversion program to/from Fahrenheit to/from Celsius. Shows the use of wxSizers, wxButtons, and the wxTextCtrl.

  • editor.wx.lua

    • This is the editor that the wxLua application apps/wxlua uses.
    • It uses the wxStyledTextCtrl for the editor and can run and debug Lua programs.
    • For more information see the wxLua application notes below.

  • grid.wx.lua

    • A very simple demo of the wxGrid class.

  • htmlwin.wx.lua

    • Shows the wxLuaHtmlWindow and it's virtual functions as well as adding custom widgets to a wxHtmlWindow.

  • luamodule.wx.lua

    • A sample for loading the wxLua "wx" module using Lua's require function when wxLua is compiled as a shared library.
    • Run this program using the Lua executable and not wxLua or wxLuaFreeze since the wxLua library is loaded at run-time.
    • See also wrapmodule.wx.lua for more information about loading Lua modules.

  • mdi.wx.lua

    • Shows the MDI classes, wxMDIParentFrame and wxMDIChildFrame.

  • media.wx.lua

    • A sample for the wxMediaCtrl that can load and play audio and video files.

  • minimal.wx.lua

    • A minimal sample that creates a wxFrame, wxMenuBar, and wxStatusBar.

  • printing.wx.lua

    • Demonstrates how to use the printing architecture and some wxDC drawing classes in wxLua.

  • scribble.wx.lua

    • A simple drawing program that shows how to handle wxMouseEvents and wxDC drawing as well as creating a custom control.

  • sizer.wx.lua

    • A simple wxSizer demonstration.

  • tree.wx.lua

    • A wxTreeCtrl demonstration.

  • wrapmodule.wx.lua

    • This is a wrapper program to allow you to use the wx shared library as a Lua module (using require) to run the provided samples without having to edit them.
    • See How to Run the Samples for other ways to run the samples.
    • The search path for the module may need to be specified if it is not in the same directory as the sample you want to run.
      • You can add a line like the one below to the top of wrapmodule.wx.lua (adjusted as necessary) for your paths.
      • The list of paths is a semicolon separated list of paths to ?.so (for Unix type shared libraries) and ?.dll (for MSW).
      • '?' is equivalent to '*', meaning match anything for typical shells like a DOS or Bash prompt.
      • You might as well include paths to both Unix and MSW libraries so that the script can be run on either platform without modification since typically only the libraries that work on any given platform will be installed.
      • package.cpath = ";;../lib/?.so;../lib/vc_dll/?.dll;../lib/bcc_dll/?.dll;../lib/mingw_dll/?.dll;"

  • unittest.wx.lua

    • Tests that the binding generator is working properly as well as wxLua itself.
    • This is also a good reference for how to call various objects since it tries to test all the valid methods.

  • validator.wx.lua

    • Tests the wxGenericValidator and wxTextValidator.

  • veryminimal.wx.lua

    • A wxFrame only.

  • wxluasudoku.wx.lua

    • A complete Sudoku solver and program to play Sudoku puzzles. This program demonstrates most things that might be required for typical GUI programs; drawing, printing, event handling, custom dialogs, key and mouse events, menu, toolbar, statusbar, etc...
    • The program is broken into two parts and the code put in two separate Lua tables to make things easier to understand. The sudoku solver code is in the "sudoku" table at the top of the listing and the wxWidgets GUI code in the "sudokuGUI" table at the bottom.

7 - wxLua Applications

The applications that wxLua provides are in the wxLua/apps directory. These are C++ programs that are compiled against the wxWidgets library and the wxWidgets wxStyledTextCtrl library.

  • 7.1 - wxLua

    • This is a wxLua IDE editor program written in Lua that has a nice editor using the wxStyledTextCtrl.

    • The Lua code for it is in samples/editor.wx.lua

    • You can fully debug Lua programs, step through them line by line, set break points, view call stack, etc.

    • The File, Edit, and Search menus offer typical editor functionality.

    • The Debug menu contains the items to run and debug your programs.

      • Compile - test compilation of your program, does not run it, but checks the Lua syntax.

      • Run - Run the current program independently in a separate process.

        • The wxLua program is run with the command '$wxLua editor_filename' and therefore you need to have saved it to disk.

      • Attach - Attach the debugger to a process, you must start the debuggee process by hand by running another wxLua process as "wxLua -dHOSTNAME:PORT program.lua" using the appropriate values for HOSTNAME:PORT as shown in the wxLua status window after selecting Attach. You can abort the debugging by selecting Stop Debugging.

      • Start Debugging - Start debugging the current program where you can then Step, Step Over, Continue, Break.

        • A TCP debugger server is started on a port in the range 1551-1559 listening for a connection from the localhost.
        • A new wxLua process is created (see Attach) as a debuggee client and the code in the current editor is sent to the debugee to run.

      • Console - Use a dialog with a text control to show the output from Lua print statements when running or debugging programs.

      • Stop Debugging - Stop debugging and close the debuggee process.

      • Step - Take one step in debugging the program.

      • Step Over - Step over a function call.

      • Step Out - Step out of a function call.

      • Continue - Continue running the program.

      • Break - Break a running program.

      • View Call Stack - View the current call stack of a Lua program being debugged showing all variables and their values.

      • View Watches - Set and view watches of variables for the Lua program being currently debugged.

      • Show Output Window - Show or hide the output window for messages during debugging.

      • Clear Output Window - When checked, clear the text in the output window when starting to debug.

    • This program can also run Lua or wxLua programs on the command line just like the Lua executable.

      • The command line switches can be displayed by running wxLua -h.

      • The editor is run if no parameters are given.

      • Note that the switches -c (print console), -q (don't quit if no top level window open), -e (execute Lua code) must be specified before -d, -o, -r.

      • The switches -d (run as debuggee), -o (open files to edit), and -r (run file) are mutually exclusive and you can only use one.

      • If -d, -o, or -r are not given but there is at least one parameter on the command line, it is interpreted to be a program name and wxLua will try to run it, any parameters after the program name are pushed into the Lua as a table named 'arg'.

        • wxLua editor.wx.lua is the same as just running wxLua itself. You can run the editor this way to customize it, but please don't forget to post any enhancements to the wxlua-users mailing list so they can be incorporated back into wxLua.

      • If you want to run a program or provide arguments to your Lua program that use -X or /X semantics you need to use -- to stop the wxLua program from interpreting the args.

        • In the example below, we don't want wxLua to interpret the second -c or give an error for the -g arg, but rather pass the args to myprogram.lua.

        • wxLua -c -e "a = 12; b = 3" -- myprogram.lua -c 12 -g

          • The wxLua program will display a console window to display print statements, run the string "a = 12; b = 3", then run myprogram.lua and push into Lua a table named 'arg' with the indices :
          • [-5] = 'd:\wxLua\bin\wxlua.exe', [-4] = '-c', [-3] = '-e', [-2] = 'a = 12; b = 3', [-1] = '--', [0] = '../samples/unittest.wx.lua'
          • [1] = '-c', [2] = '12', [3] = '-g'
          • This is the same table that Lua executable creates, where arg[0] is the name of the Lua program run and positive indices are args to the Lua program and the most negative index is the name of the executable.

        • wxLua -c -e "a = 12; b = 3" -r myprogram.lua -- -c 12 -g

          • Gives the same results, but the Lua arg table starts with [1] = '--' which should probably be ignored.

  • 7.2 - wxLuaEdit

    • This is another IDE type program written in C++ that runs wxLua programs in the main thread and can therefore be "dangerous." However it works fairly well and uses wxYield events to keep the editor GUI responsive while running, though this does sacrifice speed. It does not allow step-by-step debugging of Lua programs. However, it does provide a Lua shell to try things out very quickly and you can interactively manipulate or introspect a program as it runs in the "Output" window.
    • Run wxLua Program - Runs the program in the current notebook tab and outputs any print or error messages to the "Output" window. A new lua_State is created for each run and is accessible in the Output window until a new one is run.
    • Stop wxLua Program - Stops the currently running wxLua program. This only stops the program if Lua is actually running meaning that the Lua parser is running. Once you've created a top level window the wxWidgets event system runs in the background and calls the wxLuaState as necessary for event handling. This is why Lua is considered to be not running even though your programing is "running."
    • Stack Tree - Show the stack of the current lua_State. Current means which output window you're looking at, either the Shell or the Output.
    • Toggle Breakpoint - Add a breakpoint to the line of code and when the Lua parser reaches it throw an error. You can then use the print() statement in the Output window or the stack tree to view the current state of Lua. You cannot view local variables however and apparently this is a limitation of Lua itself. You cannot also continue running the program.
    • The editor uses the wxStEdit library from wxcode.sourceforge.net for the editor. The code is included in the wxLua source package or as an external when checking out the code using Subversion.

  • 7.3 - wxLuaFreeze

    • This is the simplest incarnation of a wxLua program that makes use of the wxLua library. Once compiled, it can run Lua programs on the command line as wxLuaFreeze program.lua. Additionally you can use the wxluafreeze.lua script to append a single file Lua program to the end of wxLuaFreeze to run. Please see readme.txt in apps/wxluafreeze and also either run wxluafreeze.lua with no arguments or read the the Usage() function in it. You should give the output of wxluafreeze.lua a new name so you don't modify the original, though you may do this if you like. Once a program has been "frozen" to the end of wxLuaFreeze it automatically runs it and any arguments passed to it on the command line are pushed into Lua as the args table. For MSWindows a program called 'upx' can be used to compress the executable to about 1.5 Mb from 4.5 Mb, using VC6 in release mode as the compiler.

  • 7.4 - Lua Module using require()

    • As described before, wxLua can be initialized using Lua's require("wx"){.lua} function.
    • Section 6.1 - How to Run the Samples has more informaton about using wxLua from the Lua console.

8 - wxLua Utils

Utility programs for wxLua are located in the wxLua/util directory.

  • 8.1 - bin2c.lua

    • bin2c.lua is a Lua program to convert a file into a const char* string to be included into a C/C++ program.
    • You can then run the script in C++ by calling wxLuaState::LuaDoBuffer(string_var, string_len, "Lua program").
    • Help is shown if no arguments are given when run or you can read its Usage() function.

9 - wxLua Sourcecode Modules

wxLua is broken up into "modules" that are compiled into libraries so that you can choose to link to some or all of them. The directory structure of the modules dir is such that you need only add the #include path to wxLua/modules in your compiler settings and then in the code always write #include "modulename/optionalsubname/filename.h".

  • Lua

    • The source code of Lua itself. It is the original unmodified source for the version, with some of the header files copied to the include directory for the installation routines.
    • Patches released for the version are applied as they come out, see wxLua/docs/changelog.txt.
    • Compilation of this module generates a Lua library and two executables, lua.exe and luac.exe.

  • wxbind

    • The output of the interface files in wxLua/bindings/wxwidgets are generated in this directory. They are the wrappers for the wxWidgets library.
    • You do not need to regenerate them unless you have edited the interface files themselves.
    • You should NOT edit these files directly as they will be overwritten if you regenerate the bindings, the fix should really go into the interface files themselves.
    • To initialize this library in a C++ program and have it pushed into Lua you should have the code "extern bool wxLuaBinding_wxXXX_init();" and then somewhere in your app initialization or at least before you create a wxLuaState call wxLuaBinding_wxXXX_init(). This is because different compilers seem to have problems with the various techniques we've tried to automatically initialize the binding and may even throw out the whole library when linking unless you explicitly use something in it. Replace the XXX with the name of the library you want installed, see modules/wxbind/include/wxbinddefs.h for a list of them.
    • You should preferably use the macros in modules/wxbind/include/wxbinddefs.h to make it easy to install a standard set of them or all of them. They do some simple checks to determine if the binding will be available based on the wxWidgets wxUSE_XXX directives.
    • Compilation of this module generates a number of libraries corresponding to the libraries that wxWidgets generates, wxadv, wxaui, wxbase, wxcore, wxgl, wxhtml, wxmedia, wxnet, wxstc, wxxml, and wxxrc.

  • wxlua

    • This is the core library of wxLua itself. It contains the wxLuaState class and helper functionality.
    • You must at least link to this library.
    • The public C++ side of wxLua is almost entirely contained in modules/wxlua/wxlstate.h.
    • This library also contains some bindings that are useful for debugging and getting information about wxLua.
    • To initialize this library in a C++ program and have it pushed into Lua you should have the code "extern bool wxLuaBinding_wxlua_init();" and then somewhere in your app initialization or at least before you create a wxLuaState call wxLuaBinding_wxlua_init().
    • Compilation of this module generates a 'wxlua' library.

  • wxlua/debug

    • This is a simple debug library for Lua that provides some tools and a widget for showing the stack and browsing the locals, globals, and registry variables.
    • Compilation of this module generates a 'wxluadebug' library.

  • wxlua/debugger

    • This is a socket library for one wxLua program to communicate with another for debugging purposes. It is currently used in the wxlua app (samples/editor.wx.lua).
    • This lib depends on the wxluadebug lib.
    • To initialize this library in a C++ program and have it pushed into Lua you should have the code "extern bool wxLuaBinding_wxluadebugger_init();" and then somewhere in your app initialization or at least before you create a wxLuaState call wxLuaBinding_wxluadebugger_init().
    • Compilation of this module generates a 'wxluadebugger' library.

10 - wxLua C++ Programming Guide

The documentation for the wxLua library is in the header files and descriptions are given for each function, enum, etc. Please read through them to get a feel for what functions wxLua provides. Below is a brief synopsis of wxLua for C++ programmers.

Lua uses char strings while wxWidgets uses the wxString class which uses the wxChar data type. Depending on whether you have compiled wxWidgets in Unicode mode or not, wxChar can be either wchar or char. Therefore, wxLua uses the functions "wxString lua2wx(const char str)"* and "const wxCharBuffer wx2lua(const wxString& str)" to translate between the two. Note that wxCharBuffer can be used as a const char* string directly without any casting.

The core of wxLua is based upon a ref counted wxLuaState class derived from the wxWidget's wxObject class. The wxLuaState class contains as a member of its ref data the 'C' lua_State struct which is the heart of Lua. Since the class is ref counted, it should be passed as const wxLuaState& and can be used in much the same way as a wxBitmap, wxPen, or any of the other wxObject derived classes that make use of its ref counting mechanism. What this means for wxLua is that instead of keeping pointers to the lua_State you have instances of the wxLuaState, there is a slight overhead for this, but it is minimal. When the lua_State is closed, all the wxLuaStates sharing the ref data can check their ref data to see if the lua_State is NULL and segfaults from dangling pointers are avoided. The reason why this is a good idea is that wxWidgets has delayed wxWindow deletion and things can get out of order. Care must be taken for pushed event handlers from Lua because if the lua_State is closed, but the window hasn't been deleted just yet... It's best to have a way to check and the wxLuaState wraps this all up.

When the wxLuaState is Ok() the wxLuaState has its ref data and the lua_State is created. If it's not Ok() then most wxLuaState functions will assert in debug mode, so it's always best to compile in debug mode until you're sure things are working properly.

The wxLuaState contains all of the Lua 'C' functions, such as lua_gettop(lua_State* L), but as member functions named lua_GetTop() which use the internal lua_State and check for its validity before use. The functions are capitalized to make them easier to find in an editor. If you want the greatest performance just use wxLuaState::GetLuaState() and directly manipulate the returned pointer to the lua_State.

It is instructive to follow the creation of the wxLuaState by looking at bool wxLuaState::Create(wxEvtHandler *handler, wxWindowID id) in wxLua/modules/wxlua/src/wxlstate.cpp.

  1. The lua_State is created using lua_open() and then the standard Lua libraries are loaded, base, table, string, math, and so on using luaL_openlibs(L) as well as luaopen_bit(L) to open the bit32 library we use.

  2. The function wxLuaState::Create(L, wxLUASTATE_USESTATE) is called to finish setting up the lua_State.

    1. The wxObject::m_refData is created as a new wxLuaStateRefData(). This ref data class contains a pointer to the lua_State struct and to a shared wxLuaStateData class that is also created. If a Lua program running in this wxLuaState creates coroutines, each will have their own wxLuaStateRefData and associated lua_State, but they will all share the same wxLuaStateData class.
    2. The C lua_State is added to a hash table to allow looking up the owner wxLuaStateRefData when Lua calls the C wxLua binding functions with the lua_State as the only parameter. A new wxLuaState with the wxLuaStateRefData set using wxObject::SetRefData(), which does not "ref" the data, but simply sets it, is used since we do not want an extra "ref". The same wxLuaState is pushed into the LUA_REGISTRYINDEX table as a lightuserdata using the &wxlua_lreg_wxluastate_key as a secondary means to find the wxLuaState "owner" of the lua_State which will be used for coroutines since there is no way to determine when a coroutine (new lua_State) is created and then silently destroyed.
    3. The tables and values that wxLua uses to store information about the bindings or track its state are pushed into the LUA_REGISTYINDEX. Information about these items can be found in the next section.
    4. We register a print() function for Lua to get the output of Lua print() statements to send messages as wxLuaEvents, see wxEVT_LUA_PRINT.

  3. The bindings are registered by calling wxLuaState::RegisterBindings().

    • Each binding that is loaded are derived wxLuaBinding classes whose member data variables point to structs in each binding. A single static instance of each binding class are installed into a wxList when the wxLuaBinding_XXX_init() functions are called. The reason behind the need for running the init function from the binding libraries is to stop certain compilers from throwing out the whole binding library, which happens even if the binding was added to the list from within the library.
    1. Each binding has wxLuaBinding::RegisterBinding(...) called for it.
      • luaI_openlib(L, "binding_namespace", fake luaL_Reg, 0) ; is called to have Lua create the tables that we will install the bindings into. This allows wxLua to look like a standard Lua library even though it works a little differently.
        • LUA_REGISTRYINDEX["_LOADED"][binding_namespace] = table
        • LUA_GLOBALSINDEX[binding_namespace] = table
        • LUA_GLOBALSINDEX["package"]["loaded"][binding_namespace] = table
      • wxLuaBinding::DoRegisterBinding(...) is called to actually push the bindings into the "binding_namespace" table we've created in Lua.

  4. At the end of creation a wxLuaEvent is sent with the wxEVT_LUA_CREATION event type.

10.1 - Data stored in Lua's LUA_REGISTRYINDEX table

wxLua stores its bookkeeping data in the Lua's LUA_REGISTRYINDEX table that the wxLuaState creates and uses. The keys are const char* strings with its address pushed as a light userdata. Pushing the string itself requires that it be hashed and it was found to take a considerable amount of the total time of a function call. A list of all of the tables is at the top of the wxlstate.h header file.

10.2 - Functions to Create a wxLuaState

  • wxLuaState(bool create = false)

    • If create is false, default constructor, you must call Create(...) to actually use it.
    • If create is true, you now have a working wxLuaState, i.e. a lua_State, with all the bindings attached.

  • wxLuaState(wxEvtHandler *handler, wxWindowID id = wxID_ANY)

    • Creates a complete wxLuaState, but you can provide an event handler, e.g. a wxApp or wxWindow derived class, to get and handle the wxLuaEvents, see also Get/SetEventHandler().

  • wxLuaState(lua_State* L, wxLuaState_Type type = wxLUASTATE_GETSTATE)

    • type = wxLUASTATE_GETSTATE means that the lua_State must already have been created using a wxLuaState and so this new wxLuaState will merely attach to the corresponding ref data.
    • type = wxLUASTATE_SETSTATE means that this new lua_State that you have created will have the wxLua bindings pushed into it if wxLUASTATE_OPENBINDINGS is set and then be ready for running wxLua programs. The wxLuaState will not close the lua_State, but will remove itself from Lua and do cleanup when there are no more instances of them if wxLUASTATE_STATICSTATE is set.

10.3 - Using a wxLuaState

  • int LuaDoString(const wxString &script, const wxString& name = wxEmptyString)

    • Runs the script as a string with the given name. The name is only used if Lua errors out and then the debug message will contain that name.
    • Returns Lua's error code LUA_ERRXXX or 0 on success.

  • int LuaDoBuffer(const char *buffer, size_t len, const char *name)

    • Run a buffer, perhaps from bin2lua.lua, that you've compiled with your program.
    • Returns Lua's error code LUA_ERRXXX or 0 on success.

  • int LuaDoFile(const wxString &filename)

    • Run a Lua file from disk.
    • Returns Lua's error code LUA_ERRXXX or 0 on success.

  • int LuaPCall(int narg, int nresults)

    • Uses lua_call to run a chunk on the stack, but sets things up for wxLua first.
    • Returns Lua's error code LUA_ERRXXX or 0 on success.

  • There are many other functions which are documented in wxLua/modules/wxlua/wxlstate.h.