wxLuaBinding 2.8.12 - Writing and Generating Binding Files

Table of Contents

1 - Binding File Descriptions

bindings/genwxbind.lua

• The binding file generator that converts the *.i interface files into a set of C++ files to be compiled into a library and linked to or compiled along with your program.
• bindings/wxwidgets/wxbase_rules.lua (for example) is a rules file that determines where and what interface files genwxbind.lua should read, how it should name the output files and generated classes, what extra header code to add, among other things. Documentation for creating a rule file is provided inside the ones provided by wxLua and you should copy an existing one to use as a starting point for your own.
• The rules files are actual Lua programs that genwxbind.lua runs before processing the interface files, but after it has created various structures used for parsing allowing for customization by either adding to the structures or changing them.
• Command line usage of genwxbind.lua
  • lua -e"rulesFilename=\"wxwidgets/wx_rules.lua\"" genwxbind.lua
  • Informational messages, warnings, and errors are printed to the console.
  • The output files are only overwritten if they differ.

*.i interface files

• Contain a skeleton of the C/C++ functions, classes, global variables, #defines that should be made accessible to Lua.
• See Interface File Constructs below.
• The structure of wxLua's interface files follows the wxWidgets documentation, typically alphabetical.
  • Class constructors first, class member functions, %operators, %members.

*_datatypes.lua files

• These are generated files that contain Lua tables of typedefs, datatypes, and preprocessor conditions defined in a binding that may be used by another binding by adding them to the datatype_cache_input_fileTable variable of the rules file.
• The checking of known datatypes enforces that the generated bindings will work correctly. If a datatype is missing it will be unusable in Lua.
• The items are added to the typedefTable, dataTypeTable, and preprocConditionTable variables of the genwxbind.lua program.
• All of the wxWidgets types are added to the bindings/wxwidgets/wx_datatypes.lua file which may be used by external bindings that use datatypes declared in the wxLua wxWidgets bindings. Note: Each bindings/wxwidgets/wxXXX_rules.lua file will generate a wxXXX_datatypes.lua datatype file, but these are all gathered together into the wx_datatype.lua file.

wxluasetup.h

• Contains #defines of all of the wxLUA_USE_wxXXX for C++ compilation of the wxWidgets bindings.
• This file is special to wxLua's wxWidgets binding.
• If wxLUA_USE_XXX is 1 then it's compiled in and will be accessible to wxLua scripts, else skipped when compiling the generated cpp files to generate a smaller library.
• It provides an additional way to cut down on the size of wxLua by removing large parts of the bindings that will not be used. These defines mixed with wxWidget's own wxUSE_XXX #defines control what parts of wxWidgets is available to wxLua programs.
• For example, if you exclude wxColour by setting wxLUA_USE_wxColourPenBrush=0 then all functions that take or return a wxColour will be excluded, the best thing to do is to test things out and see what works for you.

overrides.hpp

• Contains functions that cannot be automatically wrapped.
• You can name the file anything you want and have multiple files since it is specified as a table in the rules file.
  • override_fileTable = { "override.hpp" }
• Functions that take pointers or references and return values through the variables passed in must be reworked to return multiple values.
• It is important to document the new signature of the overridden function, in wxLua we put comments like these into the interface files.
  • // %override single_output_type ClassName::FuncName(C++ style input parameters)
  • // %override [type1 output_name1, type2 output_name2] ClassName::FuncName(reworked C++ style input parameters that the Lua function actually takes)
• In order for the %overload functionality to work and to get the proper signatures; the function parameters in the .i file should match the actual parameters that the %override code implements. The interface files for wxLua always have these three lines, where the first line is for documentation purposes only, the second line is the original C++ function declaration for reference purposes to compare what wxWidgets expects to get, and the third line is the correct calling semantics for the %overridden function.
  • // %override void wxFrame::SetStatusWidths(Lua table with number indexes and values)
  • // C++ Func: virtual void SetStatusWidths(int n, int *widths)
  • virtual void SetStatusWidths(LuaTable intTable)

2 - Generated Files

• A single header file is generated that typically does not have to be included by any files other than those generated by the bindings.
  • Contains all the #includes and exports the tags, structs, and functions for use in a DLL.
• The only function that absolutely must be called is wxLuaBinding_[hook_cpp_binding_classname]_init().
  • It is probably easiest to declare the function using extern bool wxLuaBinding_[hook_cpp_binding_classname]_init(); in your file rather than including the header.
  • This function contains a static instance of the generated wxLuaBinding derived class that is put into a static wxList of bindings. There should only be one of the binding classes created as they all share the same structures anyway.
  • static wxLuaBindingList* wxLuaBinding::GetBindingList()
  • Note: A variety of different ways to automatically initialize the bindings were tried that would invariably fail with certain compilers, but work with others. Having to call the init function before creating a wxLuaState seems to work everywhere as it guarantees that when the bindings are compiled as a library, at least something in it is used and the linker won't throw the whole lib out.
• Each binding file, *.i will have a *.cpp file generated for it that contains:
  • int s_wxluatag_CLASS_NAME for each class that is mapped through the wxLuaBindClass struct and when the binding is initialized will contain the tag index that Lua assigns to the class for the userdata.
  • The C functions, int ClassMethodFunction(lua_State* L), that are called for the class methods.
  • A wxLuaBindMethod struct for each class to map the method function names to the C functions.
• A single C++ file to pull all the remaining parts together that contains:
  • A wxLuaBindEvent struct that contains all the wxEventType values and their associated wxEvent classes to push into the Lua binding table.
  • A wxLuaBindDefine struct that contains all the numerical values to push into the Lua binding table.
  • A wxLuaBindString struct that contains all the strings to push into the Lua binding table.
  • A wxLuaBindObject struct that contains all the objects to push as userdata into the Lua binding table.
  • A wxLuaBindMethod struct that contains all the global C functions to push into the Lua binding table.
  • A wxLuaBindClass struct that contains the class names, all the wxLuaBindMethod structs from each *.i generated cpp files, and their tags.
  • A wxLuaBinding derived class that actually pushes the bindings into Lua.

3 - Binding C++ Virtual Functions

• Create a userdata wxLuaPrintout in Lua, replace the function OnBeginDocument with our own one in Lua, and begin the printing process, perhaps doing a print preview? The code for this is in the printing.wx.lua sample.
• The wxWidgets printing framework calls virtual wxPrintout::OnBeginDocument(...), but we've subclassed wxPrintout and so the the function wxLuaPrintout::OnBeginDocument(...) gets called.
  • The class wxLuaPrintout keeps a refed copy of the wxLuaState from when it was created since otherwise the function wxLuaPrintout::OnBeginDocument() wouldn't know what lua_State is active since wxWidgets doesn't know anything about wxLua.
  • In the past wxLua would iterate through a list of wxLuaStates to try to find the C++ userdata object, the wxLuaPrintout instance, in order to find the correct lua_State. This can impose a large performance penalty if there are multiple states and/or a large number of userdata objects.
• In wxLuaPrintout::OnBeginDocument() we first check to see if wxLuaState::GetCallBaseClassFunction() is true, if not then check to see if wxLuaState::HasDerivedMethod(this, "OnBeginDocument") is true, where this is the particular instance of the wxLuaPrintout class.
  • If we're not supposed to call the base class and there is a Lua function that replaces "OnBeginDocument" we'll call it. First we push the wxLuaPrintout and the parameters to the function that's already been pushed on the stack by a successful call to wxLuaState::HasDerivedMethod() when it calls wxLuaObject::GetObject(). We then get the result, if any, pop the result, and reset the stack to the starting point.
  • On the other hand; if we're supposed to call the base class function or there isn't a derived Lua method we'll just call wxPrintout::OnBeginDocument(...) explicitly.
• Here's the tricky part for Lua derived functions that then call the base class function. In this case we're not calling the "base" class function of wxLuaPrintout, but rather wxPrintout since wxLuaPrintout is a hollow shell that merely forwards calls to Lua or to the base class.
  • When in Lua we call _OnBeginDocument(...) on the wxLuaPrintout userdata object, the function wxluabind__index_wxLuaBindClass(...) in modules/wxlua/src/wxbind.cpp is called. This is the function that handles all function calls for wxLua userdata objects that does a lookup to see if the function exists and pushes it onto the stack for Lua to call after this function has returned.
  • This is why we set a variable using wxLuaState::Set/GetCallBaseClassFunction() to remember if the Lua function was called with a preceding "_".
  • The reason why we need to reset the GetCallBaseClassFunction() from within our derived C++ virtual class function is that wxWidgets may immediately call another C++ virtual function, but the wxLuaState is still flagged to call the base class and so calls to functions like wxLuaPrintout::OnPrintPage(...) fail since they are directed to call the base class function and not our derived Lua functions.

• wxWidgets calls wxLuaPrintout::OnBeginDocument(...) in C++
• wxLuaPrintout::OnBeginDocument(...) runs the code to call the derived Lua function OnBeginDocument by calling wxLuaState::LuaCall on it. (GetCallBaseClassFunction() and HasDerivedMethod() are both true)
• wxluabind__index_wxLuaBindClass(...) is called when in Lua the function "_OnBeginPrinting" is called for the wxLuaPrintout userdata, the flag wxLuaState::GetCallBaseClassFunction is set to true, and the C function wxLua_wxPrintout_OnBeginDocument (in modules/wxbind/src/wxcore_print.cpp) is run by Lua which calls back to wxLuaPrintout::OnBeginDocument(...).
• We enter wxLuaPrintout::OnBeginDocument(...) a second time, the first time through is still stalled at wxLuaState::LuaCall() running Lua's OnBeginDocument() function, but this time we just call wxPrintout::OnBeginDocument() and return.
• The wxLuaState::LuaCall() function finishes and the first call to the function wxLuaPrintout::OnBeginDocument(...) returns.
• Success!

4 - Interface File Constructs

4.1 - Special Function Parameters

• These parameters are interpreted by the generator to implement code to handle a few special cases so we don't have to write overrides for them.
• const wxArrayString& choices or wxArrayString choices
  • The binding generator will read from Lua either a wxArrayString or a a numerically indexed table of strings for that parameter and convert them into a wxArrayString for the C++ function.
  • If either wxArrayString& choices or wxArrayString* choices is used, the generator will not do the table conversion, but look for a wxArrayString userdata since it's assumed that the C++ function will modify the wxArrayString that's passed to it.
• const wxArrayInt& choices or wxArrayInt choices
  • The binding generator will read from Lua a wxArrayInt or a numerically indexed table of integers for that parameter and convert them into a wxArrayInt for the C++ function.
  • If either wxArrayInt& choices or wxArrayInt* choices is used, the generator will not do the table conversion, but look for a wxArrayInt userdata since it's assumed that the C++ function will modify the wxArrayInt that's passed to it.
• IntArray_FromLuaTable
  • The binding generator will read from Lua a numerically indexed table of integers and create two parameters (int count, int* array) to pass to a function.
  • The int* array will be automatically deleted and the function should not take ownership of it and delete it itself.
• LuaTable tableName
  • The "datatype" LuaTable does not actually exist, but is used exclusively for %override functions in the .i interface files. It directs the binding generator to expect a Lua table for that parameter.
  • Note : You absolutely must %overrride this function as the generated code will not compile.
  • This is useful for functions like wxFrame::SetStatusWidths as shown above.
• LuaFunction functionName
  • The "datatype" LuaFunction does not actually exist, but is used exclusively for %override functions in the .i interface files. It directs the binding generator to expect a Lua function for that parameter.
  • Note : You absolutely must %overrride this function as the generated code will not compile.
• voidptr_long
  • This is for functions that take a (void *) pointer to something and DO NOT EVER TRY TO CAST IT, ACCESS IT, OR DELETE IT. This tag will allow the Lua code to put a number (perhaps a table index) as the void* pointer.
  • See Get/SetClientData() functions in the wxWidgets bindings.

4.2 - C++ Class Member Function Directives

• const
  • This function attribute is ignored since wxLua doesn't create const objects, it's safe to leave it in the interface files as a reminder.
• static
  • For class member functions inside the %class tag, do not use for C style global functions.
  • The generated code will call ClassName::FunctionName() and not use an object.
  • Example : In the %class wxFileName the function "static wxFileName DirExists(const wxString& dir)"
    • wxLua code : "dir = wx.wxFileName.DirExists("/some/dir")" or "f = wx.wxFileName(); dir = f.DirExists("/some/dir")"
  • The bindings generate code to make the function accessible in the class table (first example above) as well as when called using a object.
• virtual
  • Currently ignored - TODO perhaps

4.3 - Comments

• // as in C++ to comment out the rest of a line of text.
• /* ... */ to comment multiline blocks.

4.4 - Interface Tags

• Declare a class and optionally its base class.
• All the methods of the base class can be accessed by an instance of the class.
• Note: If your class is in a namespace such as ns::ClassName you must use %class ... ns::ClassName and the constructor must also be ns::ClassName. The generator will change the "::" to "_" however for useage in Lua.
• %delete is for classes that you want the Lua garbage collector to delete when the variable goes out of scope.
  • For example, a wxPoint should be deleted when there are no longer any references to it, but wxWindows are typically attached to a parent and the parent wxWindow should delete its children, not Lua.
  • Classes, like the simple wxPoint or ref counted wxObject classes like wxPen, can use the '=' operator to make a copy of the object. Therefore the bindings will make a 'new' object then copy it.
  • Classes that are always "owned" by other objects that will delete them should not use this tag.
  • Cases where a class object would be typically owned, perhaps after calling a function with them as a parameter, but may not start off that way can use the %delete tag, but the function that takes ownership should use the %ungc tag before the parameter.

• Adds a number to the binding table which is accessed in wxLua using wx.NUMBER.
• The NUMBER can be a #define or an int.
• The optional parameter [Value] can be the actual numerical value to use. This if useful when you want Lua to know about a preprocessor directive such as, "#define A_DEFINE" that doesn't have a value itself. In this case assign it to be 1 using "%define A_DEFINE 1".
• There are many examples of %define in bindings/wxwidgets/defsutils.i.

• Declares a wxEventType wxEVT_XXX which can be accessed in wxLua using wx.wxEVT_XXX.
• This tag must be used inside of the %class tag for the wxEvent derived class it corresponds to so the event's methods can be known to Lua and the generator can assign the correct class type to it.
• An example of this is in the wxCommandEvent interface in bindings/wxwidgets/event.i, "%define %event wxEVT_COMMAND_ENTER".

• Declares an object in the binding table which can be accessed in wxLua using wx.OBJECT.
• This tag must be used inside the corresponding %class tag so that the object's class methods can be known to Lua and the generator can assign the correct class type to it.
• An example of this is in the wxPoint interface in bindings/wxwidgets/gdi.i, "%define %object wxDefaultPosition" where wxWidgets has created wxDefaultPosition as "const wxPoint wxDefaultPosition;".

• Declares a pointer to an object in the binding table which can be accessed in wxLua using wx.POINTER.
• This tag must be used inside the corresponding %class tag so that the pointer's methods can be known to Lua and the generator can assign the correct class type to it.
• An example of this is in the wxPenList interface in bindings/wxwidgets/gdi.i, "%define %pointer wxThePenList" where wxWidgets has created the wxThePenList as "wxPenList* wxThePenList;".

• Adds a string to the binding table which is accessed in wxLua using wx.STRING.
• The STRING must be defined as "const wxChar* STRING = _("str") or wxT("str")" or some way that allows it to be converted easily to "const wxChar*" in Unicode or not.
• The optional parameter [Value] can be the actual string value to use and should be _("str"), wxT("str"), or a const wxChar* variable declared elsewhere.
• Note : Why not use wxString? You can't get the data from a wxString if you need to convert from Unicode and VC has problems having the class wxString as a member of a struct.
• Note : Why not use const char*? There currently isn't a need for it, but it would be easy to add if there was.

• This adds enumerations to the binding table which can be accessed in wxLua using wx.ENUM_ITEM1 as it could be in C++, meaning that the Enum_Type is stripped off.
• If the enum is a part of a class use "%enum ClassName::Enum_Type" and the enums will be accessed in wxLua as "wx.ClassName.ENUM_ITEM1".

• Declares a global C style function in the binding table which can be accessed in wxLua using wx.FUNCTION(int value, ...).
• An example of this is in bindings/wxwidgets/datetime.i, "%function wxString wxNow()".

• For use before a userdata parameter of a function or its return value only.
• Declares that the parameter passed to the function or return value should be garbage collected or able to be delete()ed by the Lua program.
• This is for C++ functions that when passed a userdata object will 'release' it from being deleted by something else and now it is up to wxLua to delete it to avoid a memory leak. This can also be used for return values.
• You should verify that the generated code is appropriate as this has only been implemented for pointers '*'. It can be extened for other cases as they needed, please send a message to the wxlua-users mailing list with your special circumstances.
• Note that by default, functions that return a pointer '*' or a reference '&' do NOT add the return value to the list of objects to be garbage collected even if it is a %class data type with the %delete tag. This is because it is assumed that the return value is 'owned' by someone else that will delete it. Use the %gc tag to override this behavior.
• See also %ungc.

• For a class member functions only and is typically not necessary to have for classes that use the %delete tag.
• Declares that after calling this function the object itself (not return value) should be garbage collected by Lua.
• This is for functions that when called will release the object from being deleted by something else and therefore it should be deleted in wxLua by either the garbage collector or when a Lua program calls the delete() function on it.
• You should verify that the generated code is appropriate as this has only been implemented for return pointers '*'. It can be extened for other cases as they needed, please send a message to the wxlua-users mailing list with your special circumstances.
• See also %ungc_this.

• The C++ generated code within this block will be surrounded by "#if wxLUA_USE_XXX && __WXMSW__" ... #endif.
• You can use any #defined value in the %if statement as well as the operators !, &, |.

• Include a C/C++ header file by generating the C code #include "headerfile.h".

• Includes another wrapper file that is added to the list of files to process.

• Declare a property to access member variables in a class.
• This tag must be used inside of the %class tag.
• The variables will be accessible only using the '.' convention as if they were table members.
• If the variable is const, it is only read-only.

• Declare a function to access member variables in a class.
• This tag must be used inside of the %class tag.
• The generated functions in the example above will be named Get_m_x() and Set_m_x(int x) therefore it is recommended that you use %rename in conjunction with %member.
• For example, in wxPoint "%rename X %member int x" will generate wxPoint methods named "pt:GetX()" and "pt:SetX(5)" for the wxPoint class as well as properties to access them as if they were table members, print(pt:x) and "pt:x = 5".

• Declare that the operator == is defined for the class which can be accessed in wxLua using point:op_eq(otherPoint).
• This tag must be used inside of the %class tag.
• The functions that will be generated for the declared operators use the semantics given below.
• The reason that the operators are not overridden in Lua using the metatable is that Lua only defines a limited set of operators. Having some operators overridden and some not is probably more confusing that not overriding any. Secondly, by leaving the Lua operators alone the = and == operators (for example) can be useful as userdata pointer assignment and pointer comparisons respectively. This is equivalent to using pointers in C, as in "wxPoint *pt = &otherPt", which merely increases the ref count of the object and is useful as is.

• 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()
  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

• Declare to the binding generator that even though the FUNC_NAME function has two or more different signatures to not generate code to overload it.
• This can be used when a class has two functions with the same name that have mutually exclusive #ifdef conditions.
• This can happen when, for example, a function is "void DoStuff()" and then in a later version of the C++ library "bool DoStuff(int flag)".

• Replace the generated binding code with this handwritten code.
• The lines of C++ code between %override and %end is copied verbatim into the binding code.
• This is necessary for functions that take pointers or references and return values though them. Since Lua cannot have values passed by reference the only solution is to return multiple values.
• See the function wxLua_wxConfigBase_GetNextGroup in bindings/wxwidgets/overrides.hpp for an example of this and many other examples of when %override is necessary.
• The program genwxbind.lua uses the function signature, wxLua_ClassName_FunctionName for class member functions, to lookup whether there was a %override or not. Therefore, it is important that you get the signature correct. The simplest way to get started with your own %override is to add the function to your interface files and run genwxbind.lua on them. Then look at the C++ output for that function and copy it into your %override file and adjust as necessary.

• The binding generator will automatically generate names for the functions it binds, which is by default wxLua_ClassName_FunctionName.
• There are other special cases, please review the output of the generated bindings to determine what the default will be.
• However, if the function is overloaded (two or more with same name) additional C functions created will have 1,2,3... appended to their name.
• In order to enforce that the %override that you have written will be used for the proper function you can use this tag followed by the exact same name you gave the C function in your override.

• This tag is DEPRECATED and does nothing! These "functions" are generated on the fly.
• Defines a way to access Get/SetNAME() class member functions as variables.
• This tag must be used inside of the %class tag.
• The Get/SetNAME() functions must exist already.
• An example of this is in the wxSize class in bindings/wxwidgets/gdi.i where the "%property Height, read, write" is declared. In wxLua you can read and write to the Height variable using the wxSize::GetHeight() and wxSize::SetHeight(int height) as "size = wx.wxSize(1,2); size.Height = 3; print(size.Height)". Note that the period, not colon, is used to access the property for both reading and writing.

• Rename a C/C++ method to a new name which can be accessed in Lua as NEW_FUNC_NAME() though it's accessed in C using FUNC_NAME().
• This can be necessary when there are two overloaded C functions that are hard or impossible to distinguish between the two and so it is necessary to rename them for the Lua script to access them correctly.
• An example of when this is necessary is
  • wxSize wxWindow::GetClientSize()
  • void wxWindow::GetClientSize(int* width, int* height)
  • Since Lua cannot pass the int *width and *height by reference, we change the function to have this signature.
    • [int width, int height] = wxWindow::GetClientSize()
    • However there is not anyway to distinguish between getting ints or a wxSize since we cannot check the left hand side, the return values.
    • The only solution seems to be to %rename the int width, height function to GetClientSizeWH()

• The next item is skipped, either a single line or a whole class.

• Declares to the binding that the UNKNOWN_DATATYPE should be treated as KNOWN_DATATYPE.
• An example of this is "%typedef long wxTextCoord" where the wxTextCoord is just a long integer.
• Without the %typedef the binding generator would give an error about an unknown data type, since it would assume that a typo or an error in the interface file has been made.

• For use before a userdata parameter of a function or its return value only.
• Declares that the parameter passed to the function or return value should not be garbage collected or able to be delete()ed by the Lua program.
• This is for functions that when passed a userdata object will take 'ownership' of it and wxLua should not delete it to avoid double deletion. This can also be used for return values.
• You should verify that the generated code is appropriate as this has only been implemented for pointers '*'. It can be extened for other cases as they needed, please send a message to the wxlua-users mailing list with your special circumstances.
• See also %gc.

• For a class member functions only and may be necessary for classes that use the %delete tag.
• Declares that after calling this function the object itself (not return value) will not be garbage collected by Lua.
• See also %gc_this.

• The next item will be #if wxCHECK_VERSION(X,Y,Z).
• The Y and Z parameters are optional and default to 0.
• %wxchkverXY is now deprecated, please use %wxchkver_X_Y_Z

• The next item will be #if (defined(WXWIN_COMPATIBILITY_X_Y) && WXWIN_COMPATIBILITY_X_Y).
• The rest of the string beyond "%wxcompat" is appended to "WXWIN_COMPATIBILITY" so hopefully all future versions of wxWidgets should be supported.
• %wxcompatXY is now deprecated, please use %wxcompat_X_Y