The binding generator for wxLua provides information for Lua code to interface to a C/C++ API. The C/C++ objects are created in Lua as userdata and manipulated using the same functional semantics as you would in C/C++. The wxLua manual, wxlua.html, describes in detail how the object will be named and where it will be placed in Lua.

wxLua has binding files for the wxWidgets cross-platform GUI library and the wxStyledTextCtrl contrib library of the wxWidgets library. The binding generator is flexible enough to be used to create bindings for other projects. This allows wxLua to be integrated as a scripting language in C++ projects. There is an example in the wxLua/apps/wxluacan directory.

The interface files are stripped down skeletons of C/C++ header files. The program bindings/genwxbind.lua parses these files and generates C functions that are exposed to Lua by a generated wxLuaBinding derived class. The whole process of generation is automatic and no editing of the output files should be attempted. If there are any problems, the interface files or the generator should be fixed. Some examples of the interface files are in the bindings/wxwidgets/*.i directory. Before writing your own, take some time to examine them and note the differences between them and the original C++ code. If the automatic bindings do not generate suitable code for a specific function you can %override individual function bindings with your own code to implement it in any way you want.

Table of Contents

  1. Binding File Descriptions
  2. Generated Files
  3. Binding C++ Virtual Functions
  4. Interface File Constructs
    4.1 Special Function Parameters
    4.2 C++ Class Member Function Directives
    4.3 Comments
    4.4 Interface Tags

1 - Binding File Descriptions

bindings/genwxbind.lua

*.i interface files

*_datatypes.lua files

wxluasetup.h

overrides.hpp

    // %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

The binding generator genwxbind.lua generates a number of files and you can specify both their names and directories.

3 - Binding C++ Virtual Functions

The only way to handle C++ virtual functions in wxLua is to subclass the C++ class you want to be able to write Lua functions for and bind the subclassed version. The hand coded wxLuaPrintout class is a good example of this. Below is a description of how the C++ code and Lua work to allow overriding a C++ virtual class member function from Lua.

The wxWidgets class wxPrintout has a number of virtual functions, but lets focus on virtual bool wxPrintout::OnBeginDocument(int startPage, int endPage) as an example, since if you override this function you must also call the base class function for printing to operate correctly. The source code for the class wxLuaPrintout located in modules/wxbind/include/wxcore_wxlcore.h and modules/wxbind/src/wxcore_wxlcore.cpp and you should review it before reading further. You will also need to look at samples/printing.wx.lua to see the Lua code that overrides the function and modules/wxlua/wxlbind.cpp for the metatable functions Lua uses to handle a call to a function.

Below is a list of the function calls for wxPrintout::OnBeginDocument() and notes about how it all works.

To summarize, here's the function calls and where in each function wxLuaPrintout::OnBeginDocument() is when you override the function in Lua.

  1. wxWidgets calls wxLuaPrintout::OnBeginDocument(...) in C++.
  2. wxLuaPrintout::OnBeginDocument(...) runs the code to call the derived Lua function OnBeginDocument(...) by calling wxLuaState::LuaCall() on it. (GetCallBaseClassFunction() and HasDerivedMethod() are both true)
  3. 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(...).
  4. 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.
  5. The wxLuaState::LuaCall() function finishes and the first call to the function wxLuaPrintout::OnBeginDocument(...) returns.
  6. Success!

4 - Interface File Constructs

4.1 - Special Function Parameters

4.2 - C++ Class Member Function Directives

4.3 - Comments

4.4 - Interface Tags

The descriptions below use wx the name of the binding table in Lua. Other bindings would, of course, use their own tables.

%alias

class [%delete] ClassName [: public BaseClassName [, public BaseClassName2]]
{
ClassName(...)
member functions
...
};

#define NUMBER_NAME [Value]

#define_object OBJECT_NAME

#define_pointer POINTER_NAME

#define_string STRING_NAME [Value]

#define_wxstring STRING_NAME [Value]

enum [Enum_Type or ClassName::Enum_Type or Namespace::Enum_Type]
{
ENUM_ITEM1
ENUM_ITEM2
...
};

functions : return_type FUNCTION_NAME(int value, ...)

%gc

%gc_this

#if wxLUA_USE_XXX && %__WXMSW__
Interface file data...
#endif // wxLUA_USE_XXX

#include "headerfile.h"

%includefile interfacefile.i - DEPRECATED and probably does not work

member variables of classes : int m_x

%member_func int m_x

operators for classes : bool operator==(const wxPoint& otherPt) const

%not_overload int FUNC_NAME(int value)

%override wxLua_ClassName_FunctionName
// any code or comments can go within the %override ... %end block
static int LUACALL wxLua_ClassName_FunctionName(lua_State* L)
{
...
}
%end

%override_name CFunctionNameTheOverrideUses

%rename NEW_FUNC_NAME void FUNC_NAME()

%skip

struct [%delete] StructName
{
member variables
...
};

typedef KNOWN_DATATYPE UNKNOWN_DATATYPE

%ungc

%ungc_this

%wxchkver_X_Y_Z

%wxcompat_X_Y

Standard wxWidgets #defines for conditional use using the #if directive

    %__WINDOWS__
    %__WIN16__
    %__WIN32__
    %__WIN95__
    %__WXBASE__
    %__WXCOCOA__
    %__WXWINCE__
    %__WXGTK__
    %__WXGTK12__
    %__WXGTK20__
    %__WXMOTIF__
    %__WXMOTIF20__
    %__WXMAC__
    %__WXMAC_CLASSIC__
    %__WXMAC_CARBON__
    %__WXMAC_OSX__
    %__WXMGL__
    %__WXMSW__
    %__WXOS2__
    %__WXOSX__
    %__WXPALMOS__
    %__WXPM__
    %__WXSTUBS__
    %__WXXT__
    %__WXX11__
    %__WXWINE__
    %__WXUNIVERSAL__
    %__X__
    %__WXWINCE__

%wxEventType wxEVT_XXX