wxLua/docs/binding.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="Content-Style-Type" content="text/css" />
  <meta name="generator" content="pandoc" />
  <meta name="author" content="John Labenski" />
  <meta name="date" content="2022-11-06" />
  <title>wxLua 3.2.0.2 - Writing and Generating Binding Files</title>
  <style type="text/css">code{white-space: pre;}</style>
  <style type="text/css">
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
  margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; line-height: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #007020; font-weight: bold; }
code > span.dt { color: #902000; }
code > span.dv { color: #40a070; }
code > span.bn { color: #40a070; }
code > span.fl { color: #40a070; }
code > span.ch { color: #4070a0; }
code > span.st { color: #4070a0; }
code > span.co { color: #60a0b0; font-style: italic; }
code > span.ot { color: #007020; }
code > span.al { color: #ff0000; font-weight: bold; }
code > span.fu { color: #06287e; }
code > span.er { color: #ff0000; font-weight: bold; }
  </style>
  <link rel="stylesheet" href="wxlua.css" type="text/css" />
</head>
<body>
<div id="header">
<h1 class="title">wxLua 3.2.0.2 - Writing and Generating Binding Files</h1>
<h2 class="author">John Labenski</h2>
<h3 class="date">2022-11-06</h3>
</div>
<p>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, <a href="wxlua.html">wxlua.html</a>, describes in detail how the object will be named and where it will be placed in Lua.</p>
<p>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 <code>wxLua/apps/wxluacan</code> directory.</p>
<p>The interface files are stripped down skeletons of C/C++ header files. The program <code>bindings/genwxbind.lua</code> parses these files and generates C functions that are exposed to Lua by a generated <code>wxLuaBinding</code> 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 <code>bindings/wxwidgets/*.i</code> 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 <code>%override</code> individual function bindings with your own code to implement it in any way you want.</p>
<h2 id="table-of-contents">Table of Contents</h2>
<ol style="list-style-type: decimal">
<li><a href="#C1">Binding File Descriptions</a></li>
<li><a href="#C2">Generated Files</a></li>
<li><a href="#C3">Binding C++ Virtual Functions</a></li>
<li><a href="#C4">Interface File Constructs</a><br /> 4.1 <a href="#C4.1">Special Function Parameters</a><br /> 4.2 <a href="#C4.2">C++ Class Member Function Directives</a><br /> 4.3 <a href="#C4.3">Comments</a><br /> 4.4 <a href="#C4.4">Interface Tags</a></li>
</ol>
<p><a name="C1"/></p>
<h2 id="binding-file-descriptions">1 - Binding File Descriptions</h2>
<h3 id="bindingsgenwxbind.lua">bindings/genwxbind.lua</h3>
<ul>
<li>This program is the binding file generator that converts the *.i interface files into a set of C/C++ files to be compiled into a library and linked to or compiled along with your program.</li>
<li><code>bindings/wxwidgets/wxbase_rules.lua</code> (for example) is a rules file that determines where and what interface files <code>genwxbind.lua</code> should read, how it should name the generated classes and output files, what extra header code to add, among other things. Documentation for creating a rule file is in each of the ones provided by wxLua and you should copy one to use as a starting point for your own.</li>
<li>The rules files are actual Lua programs that <code>genwxbind.lua</code> 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.</li>
<li>Command line usage of genwxbind.lua
<ul>
<li><code>lua -e&quot;rulesFilename=&quot;wxwidgets/wx_rules.lua&quot;&quot; genwxbind.lua</code></li>
<li>Informational messages, warnings, and errors are printed to the console.</li>
<li>The output files are only overwritten if they differ.</li>
</ul></li>
</ul>
<h3 id="i-interface-files">*.i interface files</h3>
<ul>
<li>Contain a skeleton of the C/C++ functions, classes, global variables, #defines that should be made accessible to Lua.</li>
<li>See <a href="#C4">Interface File Constructs</a> below.</li>
<li>The structure of wxLua's interface files follows the wxWidgets documentation, typically alphabetical.
<ul>
<li>Class constructors first, class member functions, %operators, %members.</li>
</ul></li>
</ul>
<h3 id="datatypes.lua-files">*_datatypes.lua files</h3>
<ul>
<li>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 <code class="sourceCode lua"><span class="kw">datatype_cache_input_fileTable</span></code> variable of the rules file.</li>
<li>The checking of known datatypes enforces that the generated bindings will work correctly. If a datatype is missing it will be unusable in Lua.</li>
<li>The items are added to the <code class="sourceCode lua"><span class="kw">typedefTable</span></code>, <code class="sourceCode lua"><span class="kw">dataTypeTable</span></code>, and <code class="sourceCode lua"><span class="kw">preprocConditionTable</span></code> variables of the <code>genwxbind.lua</code> program.</li>
<li>All of the wxWidgets types are added to the <code>bindings/wxwidgets/wx_datatypes.lua</code> file which may be used by external bindings that use datatypes declared in the wxLua wxWidgets bindings.</li>
<li>Each <code>bindings/wxwidgets/wx*_rules.lua</code> file will generate its own <code>wx*_datatypes.lua</code> datatype file, but these are gathered together into the <code>wx_datatype.lua</code> file for use by others.</li>
</ul>
<h3 id="wxluasetup.h">wxluasetup.h</h3>
<ul>
<li>Contains #defines of all of the <code>wxLUA_USE_XXX</code> for C++ compilation of the wxWidgets bindings.</li>
<li>This file is special to wxLua's wxWidgets binding.</li>
<li>If <code>wxLUA_USE_XXX</code> is 1 then it's compiled in and will be accessible to wxLua scripts, else skipped when compiling the binding cpp files to create a smaller library.</li>
<li>The primary reason to change the default, which has everything enabled, would be to cut down on the size of wxLua by removing the parts of the bindings that will not be used. Functionalty can also be removed if some sandboxing is required. These defines mixed with wxWidget's own <code>wxUSE_XXX</code> #defines control what parts of wxWidgets is available to wxLua programs.</li>
<li>For example, if you exclude the <code>wxColour</code> class by #defining <code>wxLUA_USE_wxColourPenBrush=0</code> then all functions that take or return a <code>wxColour</code> will be excluded. The best thing to do is to test things out and see what works for you.</li>
</ul>
<h3 id="overrides.hpp">overrides.hpp</h3>
<ul>
<li>Contains functions that cannot be automatically wrapped.</li>
<li>You can name the file anything you want and have multiple files since it is specified as a table in the rules file.
<ul>
<li><code class="sourceCode lua"><span class="kw">override_fileTable</span> <span class="ot">=</span> <span class="ot">{</span> <span class="st">&quot;override.hpp&quot;</span> <span class="ot">}</span></code></li>
</ul></li>
<li><p>Functions that take pointers or references and return values through the variables passed in must be reworked to return multiple values.</p></li>
<li><p>In order for the <code>%overload</code> functionality to work and to get the proper signatures; the function parameters in the .i file should match the actual parameters that the <code>%override</code> 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, this is what wxWidgets expects to get, and the third line is the correct calling semantics for the <code>%overridden</code> function.</p></li>
</ul>
<pre><code>    // %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)</code></pre>
<p><a name="C2"/></p>
<h2 id="generated-files">2 - Generated Files</h2>
<p>The binding generator <code>genwxbind.lua</code> generates a number of files and you can specify both their names and directories.</p>
<ul>
<li>A single header file is generated that typically does not have to be included by any files other than those generated by the bindings.
<ul>
<li>Contains all the #includes and exports the tags, structs, and functions for use in a DLL.</li>
</ul></li>
<li>The only function that absolutely must be called is <code>wxLuaBinding_[hook_cpp_binding_classname]_init()</code>.
<ul>
<li><p>It is probably easiest to declare the function using <code>extern bool wxLuaBinding_[hook_cpp_binding_classname]_init();</code> in your C++ file rather than including the header.</p></li>
<li>This function contains a static instance of the generated <code>wxLuaBinding</code> derived class that is added to a static wxList of bindings. There should only be one of the binding classes created as they all share the same structures anyway.</li>
<li>The function <code>static wxLuaBindingList* wxLuaBinding::GetBindingList()</code> can be used to iterate through the bindings, if needed.</li>
<li><p>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.</p></li>
</ul></li>
<li>Each *.i binding file will have a *.cpp file generated that contains:
<ul>
<li>Unique integer types, <code>int s_wxluatag_CLASS_NAME</code>, for each class that are mapped through the wxLuaBindClass struct. When the binding is initialized, a unique the tag index will be assigned to the class for marking the Lua userdata wrapper with its type.</li>
<li>C functions, <code>int ClassMethodFunction(lua_State* L)</code>, that are called for the class methods.</li>
<li>A <code>wxLuaBindMethod</code> struct for each class to map the method function names to the C functions.</li>
</ul></li>
<li>A single C++ file to pull all the remaining parts together that contains:
<ul>
<li>A <code>wxLuaBindEvent</code> struct that contains all the <code>wxEventType</code> values and their associated <code>wxEvent</code> classes to push into the Lua binding table.</li>
<li>A <code>wxLuaBindDefine</code> struct that contains all the numerical values to push into the Lua binding table.</li>
<li>A <code>wxLuaBindString</code> struct that contains all the strings to push into the Lua binding table.</li>
<li>A <code>wxLuaBindObject</code> struct that contains all the objects to push as userdata into the Lua binding table.</li>
<li>A <code>wxLuaBindMethod</code> struct that contains all the global C functions to push into the Lua binding table.</li>
<li>A <code>wxLuaBindClass</code> struct that contains the class names, all the <code>wxLuaBindMethod</code> structs from each *.i generated cpp files, and their tags.</li>
<li>A <code>wxLuaBinding</code> derived class that actually pushes the bindings into Lua.</li>
</ul></li>
</ul>
<p><a name="C3"/></p>
<h2 id="binding-c-virtual-functions">3 - Binding C++ Virtual Functions</h2>
<p>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 <code>wxLuaPrintout</code> 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.</p>
<p>The wxWidgets class <code>wxPrintout</code> has a number of virtual functions, but lets focus on <code>virtual bool wxPrintout::OnBeginDocument(int startPage, int endPage)</code> 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 <code>modules/wxbind/include/wxcore_wxlcore.h</code> and <code>modules/wxbind/src/wxcore_wxlcore.cpp</code> and you should review it before reading further. You will also need to look at <code>samples/printing.wx.lua</code> to see the Lua code that overrides the function and <code>modules/wxlua/wxlbind.cpp</code> for the metatable functions Lua uses to handle a call to a function.</p>
<p>Below is a list of the function calls for <code>wxPrintout::OnBeginDocument()</code> and notes about how it all works.</p>
<ul>
<li>Create a userdata <code>wxLuaPrintout</code> in Lua, replace the function <code>OnBeginDocument()</code> with our own function in Lua, and begin the printing process, perhaps doing a print preview. The code for this is in the <code>printing.wx.lua</code> sample.</li>
<li>The wxWidgets printing framework calls <code>virtual wxPrintout::OnBeginDocument(...)</code>, but we've subclassed wxPrintout and so its function <code>wxLuaPrintout::OnBeginDocument(...)</code> gets called.
<ul>
<li>The class <code>wxLuaPrintout</code> keeps a refed copy of the <code>wxLuaState</code> from when it was created since otherwise the function <code>wxLuaPrintout::OnBeginDocument()</code> wouldn't know what <code>lua_State</code> is active since wxWidgets doesn't know anything about wxLua.</li>
</ul></li>
<li>In <code>wxLuaPrintout::OnBeginDocument()</code> we first check to see if <code>wxLuaState::GetCallBaseClassFunction()</code> is true, if not, check to see if <code>wxLuaState::HasDerivedMethod(this, &quot;OnBeginDocument&quot;)</code> is true, where <em>this</em> is the particular instance of the <code>wxLuaPrintout</code> class.
<ul>
<li>If we're not supposed to call the base class and there is a Lua function that replaces <code>OnBeginDocument()</code> we'll use it. First push the <code>wxLuaPrintout</code> and the parameters to the function that's already been pushed on the stack by a successful call to <code>wxLuaState::HasDerivedMethod()</code> when it calls <code>wxLuaObject::GetObject()</code>. Call it and then get the result, if any, pop the result, and reset the stack to the starting point.</li>
<li>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 <code>wxPrintout::OnBeginDocument(...)</code> explicitly.</li>
</ul></li>
<li>Here's the tricky part for Lua derived functions that then call the base class function. In this case we're not calling the &quot;base&quot; class function of <code>wxLuaPrintout</code>, but rather <code>wxPrintout</code> since <code>wxLuaPrintout</code> is a hollow shell that merely forwards calls to Lua or to the base class.
<ul>
<li>When in Lua we call <code>_OnBeginDocument(...)</code> on the <code>wxLuaPrintout</code> userdata object, the function <code>wxluabind__index_wxLuaBindClass(...)</code> in <code>modules/wxlua/wxbind.cpp</code> is called. This is the function that handles all function calls for wxLua userdata objects. It performs a lookup to see if the function exists and pushes it onto the stack for Lua to call <strong>after</strong> this function has returned.</li>
<li>This is why we set a variable using <code>wxLuaState::Set/GetCallBaseClassFunction()</code> to remember if the Lua function was called with a preceding &quot;_&quot;.</li>
<li>The reason why we need to reset the <code>GetCallBaseClassFunction()</code> 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 <code>wxLuaPrintout::OnPrintPage(...)</code> fail since they are directed to call the base class function and not our derived Lua functions.</li>
</ul></li>
</ul>
<p>To summarize, here's the function calls and where in each function <code>wxLuaPrintout::OnBeginDocument()</code> is when you override the function in Lua.</p>
<ol style="list-style-type: decimal">
<li>wxWidgets calls <code>wxLuaPrintout::OnBeginDocument(...)</code> in C++.</li>
<li><code>wxLuaPrintout::OnBeginDocument(...)</code> runs the code to call the derived Lua function <code>OnBeginDocument(...)</code> by calling <code>wxLuaState::LuaCall()</code> on it. (GetCallBaseClassFunction() and HasDerivedMethod() are both true)</li>
<li><code>wxluabind__index_wxLuaBindClass(...)</code> is called when, in Lua, the function <code>_OnBeginPrinting()</code> is called for the <code>wxLuaPrintout</code> userdata. The flag <code>wxLuaState::GetCallBaseClassFunction()</code> is set to true, and the C function <code>wxLua_wxPrintout_OnBeginDocument()</code> (in <code>modules/wxbind/src/wxcore_print.cpp</code>) is run by Lua which calls back to <code>wxLuaPrintout::OnBeginDocument(...)</code>.</li>
<li>We enter <code>wxLuaPrintout::OnBeginDocument(...)</code> a second time, the first time through is still stalled at <code>wxLuaState::LuaCall()</code> running Lua's <code>OnBeginDocument()</code> function, but this time we just call <code>wxPrintout::OnBeginDocument()</code> and return.</li>
<li>The <code>wxLuaState::LuaCall()</code> function finishes and the first call to the function <code>wxLuaPrintout::OnBeginDocument(...)</code> returns.</li>
<li>Success!</li>
</ol>
<p><a name="C4"/></p>
<h2 id="interface-file-constructs">4 - Interface File Constructs</h2>
<p><a name="C4.1"/></p>
<h3 id="special-function-parameters">4.1 - Special Function Parameters</h3>
<ul>
<li><p>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.</p></li>
<li><strong>const wxArrayString&amp; choices or wxArrayString choices</strong>
<ul>
<li>The binding generator will read from Lua either a wxArrayString or a numerically indexed table of strings for that parameter and convert them into a wxArrayString for the C++ function.</li>
<li>If the parameter is either <code>wxArrayString&amp; choices</code> or <code>wxArrayString* choices</code>, the generator will not perform the table conversion, but will require a wxArrayString userdata since it's assumed that the C++ function will modify the wxArrayString that's passed to it for the caller to use as a return value.</li>
</ul></li>
<li><strong>const wxArrayInt&amp; choices or wxArrayInt choices</strong>
<ul>
<li>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.</li>
<li>If the parameter is either <code>wxArrayInt&amp; choices</code> or <code>wxArrayInt* choices</code>, the generator will not perform the table conversion, but will require a wxArrayInt userdata since it's assumed that the C++ function will modify the wxArrayInt that's passed to it for the caller to use as a return value.</li>
</ul></li>
<li><strong>IntArray_FromLuaTable</strong>
<ul>
<li>The binding generator will read from Lua a numerically indexed table array of integers and pass two parameters (int count, int* array) to the function.</li>
<li>The int* array will be automatically deleted and the function must not take ownership of it and delete it itself.</li>
</ul></li>
<li><strong>LuaTable tableName</strong>
<ul>
<li>The &quot;datatype&quot; 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.</li>
<li>Any function declaration that uses this as a parameter must be an %overrride as the generated code will not compile.</li>
<li>This is useful for functions like wxFrame::SetStatusWidths().</li>
</ul></li>
<li><strong>LuaFunction functionName</strong>
<ul>
<li>The &quot;datatype&quot; 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.</li>
<li>Any function declaration that uses this as a parameter must be an %overrride as the generated code will not compile.</li>
</ul></li>
<li><strong>voidptr_long</strong>
<ul>
<li>This is for functions that take a (void <em>) pointer 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</em> pointer value.</li>
<li>See Get/SetClientData() functions in the wxWidgets bindings.</li>
</ul></li>
</ul>
<p><a name="C4.2"/></p>
<h3 id="c-class-member-function-directives">4.2 - C++ Class Member Function Directives</h3>
<ul>
<li><strong>const</strong>
<ul>
<li>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.</li>
</ul></li>
<li><strong>static</strong>
<ul>
<li>Can be used with class member functions inside the <em>class</em> tag.</li>
<li>Do not use with C style global functions.</li>
<li>The generated code will call ClassName::FunctionName() and not use the object even if called with an object.</li>
<li>Example : In the class wxFileName the function<br /> <em>&quot;static wxFileName DirExists(const wxString&amp; dir)&quot;</em><br /> <code class="sourceCode lua"><span class="kw">dir</span> <span class="ot">=</span> <span class="kw">wx</span><span class="ot">.</span><span class="kw">wxFileName</span><span class="ot">.</span>DirExists<span class="ot">(</span><span class="st">&quot;/some/dir&quot;</span><span class="ot">)</span></code> or<br /> <code class="sourceCode lua"><span class="kw">f</span> <span class="ot">=</span> <span class="kw">wx</span><span class="ot">.</span>wxFileName<span class="ot">();</span> <span class="kw">dir</span> <span class="ot">=</span> <span class="kw">f</span><span class="ot">.</span>DirExists<span class="ot">(</span><span class="st">&quot;/some/dir&quot;</span><span class="ot">)</span></code></li>
<li>The bindings generate code to make the function accessible in the class table (first example above) as well as when called using a object.</li>
</ul></li>
<li><strong><em>virtual</em></strong>
<ul>
<li><em>Currently ignored - TODO perhaps</em></li>
</ul></li>
</ul>
<p><a name="C4.3"/></p>
<h3 id="comments">4.3 - Comments</h3>
<ul>
<li><strong>//</strong> as in C++ to comment out the rest of a line of text.</li>
<li><strong>/* ... */</strong> to comment multiline blocks.</li>
</ul>
<p><a name="C4.4"/></p>
<h3 id="interface-tags">4.4 - Interface Tags</h3>
<p>The descriptions below use <code>wx</code> the name of the binding table in Lua. Other bindings would, of course, use their own tables.</p>
<p><strong><em>%alias</em></strong></p>
<ul>
<li>Reference a class by another name (currently unused).</li>
</ul>
<p><strong><em>class [%delete] ClassName [: public BaseClassName [, public BaseClassName2]]<br />{<br /> ClassName(...)<br /> member functions<br /> ...<br />};</em></strong></p>
<ul>
<li>Declare a class and optionally its base class.</li>
<li>All methods of the base class can be called by an instance of the class.</li>
<li>If the class is in a namespace, such as <code>ns::ClassName</code>, the class must be declared as <code>class [...] ns::ClassName</code> and the constructor must also be declared as <code>ns::ClassName(...)</code>. The generator will change the &quot;::&quot; to &quot;_&quot; for use in Lua.</li>
<li><strong><em>%delete</em></strong> can be used for classes you want the Lua garbage collector to delete when the object goes out of scope.
<ul>
<li>For example; a <code>wxPoint</code> should be deleted when there are no longer any references to it, but <code>wxWindows</code> are typically attached to a parent and the parent <code>wxWindow</code> will delete its children, not Lua.</li>
<li>Simple classes like <code>wxPoint</code> or ref-counted <code>wxObject</code> dervied classes like <code>wxPen</code> are often returned by C++ functions on the stack. wxLua will make a 'new' object, copy the value using the C++ '=' operator, and set a flag that this new object is to be deleted when the Lua garbage collector calls the wxLua collection function.</li>
<li>Classes that will always be &quot;owned&quot; and deleted by other objects should not use this tag.</li>
<li>See also %gc, %ungc, %gc_this, %ungc_this.</li>
</ul></li>
</ul>
<p><strong><em>#define NUMBER_NAME [Value]</em></strong></p>
<ul>
<li>Declare a number which can be accessed in Lua using <code>wx.NUMBER_NAME</code>.</li>
<li>The <em>NUMBER_NAME</em> can be a #define, an integer, a double...</li>
<li>The optional parameter <em>[Value]</em> can be used to override or set the numerical value. This can be used to set preprocessor directives such as, <em>&quot;#define A_DEFINE&quot;</em> that don't have a value itself. In this case assign it to be 1 using <code>#define A_DEFINE 1</code>.</li>
<li>There are many examples of <em>#define</em> in <code>bindings/wxwidgets/defsutils.i</code>.</li>
</ul>
<p><strong><em>#define_object OBJECT_NAME</em></strong></p>
<ul>
<li>Declares an object in the binding table which can be accessed in Lua using <em>wx.OBJECT_NAME</em>.</li>
<li>This tag must be used inside the corresponding <em>class</em> tag so that the object's class methods can be known to Lua and the generator can assign the correct class type to it.</li>
<li>An example of this is in the wxPoint class interface in <em>bindings/wxwidgets/gdi.i</em>, <em>&quot;#define_object wxDefaultPosition&quot;</em> where wxWidgets has created wxDefaultPosition as <em>&quot;const wxPoint wxDefaultPosition;&quot;</em>.</li>
</ul>
<p><strong><em>#define_pointer POINTER_NAME</em></strong></p>
<ul>
<li>Declares a pointer to an object in the binding table which can be accessed in wxLua using <em>wx.POINTER_NAME</em>.</li>
<li>This tag must be used inside the corresponding <em>class</em> tag so that the pointer's methods can be known to Lua and the generator can assign the correct class type to it.</li>
<li>An example of this is in the wxPenList class interface in <em>bindings/wxwidgets/gdi.i</em>, <em>&quot;#define_pointer wxThePenList&quot;</em> where wxWidgets has created the wxThePenList as <em>&quot;wxPenList</em> wxThePenList;&quot;*.</li>
</ul>
<p><strong><em>#define_string STRING_NAME [Value]</em></strong></p>
<ul>
<li>Declares a string in the binding table which can be accessed in wxLua using <em>wx.STRING_NAME</em>.</li>
<li>The <em>STRING_NAME</em> must be defined as <em>&quot;const char</em> STRING_NAME = &quot;str&quot;* or some way that allows it to be converted easily to <em>&quot;const char</em>&quot;*.</li>
<li>The optional parameter <em>[Value]</em> can be the actual string value to use and should be &quot;str&quot; or a const char* variable declared elsewhere.</li>
</ul>
<p><strong><em>#define_wxstring STRING_NAME [Value]</em></strong></p>
<ul>
<li>Declares a string in the binding table which can be accessed in wxLua using <em>wx.STRING_NAME</em>.</li>
<li>The <em>STRING_NAME</em> must be defined as <em>&quot;const wxChar</em> STRING_NAME = _(&quot;str&quot;) or wxT(&quot;str&quot;)&quot;* or some way that allows it to be converted easily to <em>&quot;const wxChar</em>&quot;* in Unicode or not.</li>
<li>The optional parameter <em>[Value]</em> can be the actual string value to use and should be _(&quot;str&quot;), wxT(&quot;str&quot;), or a const wxChar* variable declared elsewhere.</li>
<li>Note : wxString is not used since tou 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.</li>
</ul>
<p><strong><em>enum [Enum_Type or ClassName::Enum_Type or Namespace::Enum_Type]<br />{<br /> ENUM_ITEM1<br /> ENUM_ITEM2<br /> ...<br /> };</em></strong></p>
<ul>
<li>Declares enumerations in the binding table which can be accessed in wxLua using <em>wx.ENUM_ITEM1</em> as it could be in C++, meaning that the <em>Enum_Type</em> is stripped off.</li>
<li>If the enum is a part of a class use <em>&quot;enum ClassName::Enum_Type&quot;</em> and the enums will be accessed in wxLua as <em>&quot;wx.ClassName.ENUM_ITEM1&quot;</em>.</li>
</ul>
<p><strong><em>functions : return_type FUNCTION_NAME(int value, ...)</em></strong></p>
<ul>
<li>Declares a global C style function in the binding table which can be accessed in wxLua using <em>wx.FUNCTION_NAME(int value, ...)</em>.</li>
<li>An example of this is in <em>bindings/wxwidgets/datetime.i</em>, <em>&quot;wxString wxNow()&quot;</em>.</li>
</ul>
<p><strong><em>%gc</em></strong></p>
<ul>
<li>Use before a userdata parameter of a function or its return value only.</li>
<li>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.</li>
<li>This is for C++ functions that change the 'ownership' of a userdata object and 'release' it from being deleted by something else and now it is up to wxLua to delete it to avoid a memory leak.</li>
<li>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.</li>
<li>Note that by default, functions that return a pointer '*' or a reference '&amp;' do NOT add the return value to the list of objects to be garbage collected even if it is a <em>class</em> data type with the <em>%delete</em> tag. This is because it is assumed that the return value is 'owned' by someone else that will delete it. Use the <em>%gc</em> tag to override this behavior.</li>
<li>See also <em>%ungc</em>.</li>
</ul>
<p><strong><em>%gc_this</em></strong></p>
<ul>
<li>Use for class member functions only.</li>
<li>Declares that after calling this function the object itself (not the return value) should be garbage collected by Lua.</li>
<li>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.</li>
<li>If a class has the <em>%delete</em> tag, this tag would only make sense if at least one function that has the <em>%ungc_this</em> tag.</li>
<li>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.</li>
<li>See also <em>%ungc_this</em>.</li>
</ul>
<p><strong><em>#if wxLUA_USE_XXX &amp;&amp; %__WXMSW__<br /> Interface file data...<br />#endif // wxLUA_USE_XXX</em></strong></p>
<ul>
<li>The C++ generated code within this block will be surrounded by <em>&quot;#if wxLUA_USE_XXX &amp;&amp; __WXMSW__&quot; ... #endif</em>.</li>
<li>You can use any #defined value in the #if statement as well as the operators !, &amp;, |.</li>
</ul>
<p><strong><em>#include &quot;headerfile.h&quot;</em></strong></p>
<ul>
<li>Include a C/C++ header file by generating the C code <em>#include &quot;headerfile.h&quot;</em>.</li>
</ul>
<p><strong><em>%includefile interfacefile.i - DEPRECATED and probably does not work</em></strong></p>
<ul>
<li>Includes another wrapper file that is added to the list of files to process.</li>
</ul>
<p><strong><em>member variables of classes : int m_x</em></strong></p>
<ul>
<li>Declare a property to access member variables in a class.</li>
<li>The variables will be accessible only using the '.' convention as if they were table members.</li>
<li>If the variable is const, it is only read-only.</li>
</ul>
<p><strong><em>%member_func int m_x</em></strong></p>
<ul>
<li>Declare a function to access member variables in a class.</li>
<li>This tag must be used inside of the <em>class</em> tag.</li>
<li>The generated functions in the example above will be named Get_m_x() and Set_m_x(int x) therefore, you may want to use <em>%rename</em> in conjunction with <em>%member</em>.</li>
<li>For example, in wxPoint <em>&quot;%rename X %member int x&quot;</em> will generate wxPoint methods named &quot;pt:GetX()&quot; and &quot;pt:SetX(5)&quot; for the wxPoint class as well as properties to access them as if they were table members, print(pt:x) and &quot;pt:x = 5&quot;.</li>
</ul>
<p><strong><em>operators for classes : bool operator==(const wxPoint&amp; otherPt) const</em></strong></p>
<ul>
<li>Declare that the operator == is defined for the class which can be accessed in wxLua using <em>point:op_eq(otherPoint)</em>.</li>
<li>The functions that will be generated for the declared operators use the semantics given below.</li>
<li><p>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, the Lua operators, the '=' and '==' operators (for example) are useful as userdata pointer assignment and pointer comparisons respectively. This is equivalent to using pointers in C, as in *&quot;wxPoint <em>pt = &amp;otherPt&quot;</em>, which merely increases the ref count of the object and is useful as is.</p></li>
<li><p>This is a list of all possible operator functions:</p>
<table>
<tbody>
<tr class="odd">
<td align="left"><strong>Relational and equality operators</strong></td>
<td align="left"></td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">==</td>
<td align="left">op_eq()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">!=</td>
<td align="left">op_ne()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">&gt;</td>
<td align="left">op_gt()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">&lt;</td>
<td align="left">op_lt()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">&gt;=</td>
<td align="left">op_ge()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">&lt;=</td>
<td align="left">op_le()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left"><strong>Logical operators</strong></td>
<td align="left"></td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">!</td>
<td align="left">op_not()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">&amp;&amp;</td>
<td align="left">op_land()</td>
<td align="left">&quot;l&quot; stands for logical</td>
</tr>
<tr class="odd">
<td align="left">||</td>
<td align="left">op_lor()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left"><strong>Bitwise operators</strong></td>
<td align="left"></td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">~</td>
<td align="left">op_comp()</td>
<td align="left">bitwise NOT or complement</td>
</tr>
<tr class="even">
<td align="left">&amp;</td>
<td align="left">op_and()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">|</td>
<td align="left">op_or()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">^</td>
<td align="left">op_xor()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">&lt;&lt;</td>
<td align="left">op_lshift()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">&gt;&gt;</td>
<td align="left">op_rshift()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left"><strong>Inplace bitwise assignment operators</strong></td>
<td align="left"></td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">&amp;=</td>
<td align="left">op_iand()</td>
<td align="left">&quot;i&quot; stands for inplace</td>
</tr>
<tr class="odd">
<td align="left">|=</td>
<td align="left">op_ior()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">^=</td>
<td align="left">op_ixor()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">&gt;&gt;=</td>
<td align="left">op_irshift()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">&lt;&lt;=</td>
<td align="left">op_ilshift()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left"><strong>Arithmetic operators</strong></td>
<td align="left"></td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">=</td>
<td align="left">op_set()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">+</td>
<td align="left">op_add()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">-</td>
<td align="left">op_sub()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">*</td>
<td align="left">op_mul()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">/</td>
<td align="left">op_div()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">%</td>
<td align="left">op_mod()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left"><strong>Unary arithmetic operators</strong></td>
<td align="left"></td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">-</td>
<td align="left">op_neg()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left"><strong>Inplace arithmetic assignment operators</strong></td>
<td align="left"></td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">+=</td>
<td align="left">op_iadd()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">-=</td>
<td align="left">op_isub()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">*=</td>
<td align="left">op_imul()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">/=</td>
<td align="left">op_idiv()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">%=</td>
<td align="left">op_imod()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left"><strong>Increment arithmetic operators</strong></td>
<td align="left"></td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left">++</td>
<td align="left">op_inc()</td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">--</td>
<td align="left">op_dec()</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="left"><strong>Other operators</strong></td>
<td align="left"></td>
<td align="left"></td>
</tr>
<tr class="even">
<td align="left">[]</td>
<td align="left">op_index()</td>
<td align="left">Array indexing</td>
</tr>
<tr class="odd">
<td align="left">()</td>
<td align="left">op_func()</td>
<td align="left">Function call</td>
</tr>
<tr class="even">
<td align="left">*</td>
<td align="left">op_deref()</td>
<td align="left">Dereference/Indirection</td>
</tr>
</tbody>
</table></li>
</ul>
<p><strong><em>%not_overload int FUNC_NAME(int value)</em></strong></p>
<ul>
<li>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.</li>
<li>This can be used when a class has two functions with the same name that have mutually exclusive #ifdef conditions.</li>
<li>This can happen when, for example, a function is &quot;void DoStuff()&quot; and then in a later version of the C++ library &quot;bool DoStuff(int flag)&quot;.</li>
</ul>
<p><strong><em>%override wxLua_ClassName_FunctionName<br /> // any code or comments can go within the %override ... %end block<br /> static int LUACALL wxLua_ClassName_FunctionName(lua_State* L)<br /> {<br /> ...<br /> }<br /> %end</em></strong></p>
<ul>
<li>Replace the generated binding code with this handwritten code.</li>
<li>The lines of C++ code between %override and %end is copied verbatim into the binding code.</li>
<li>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.</li>
<li>See the function wxLua_wxConfigBase_GetNextGroup in <em>bindings/wxwidgets/overrides.hpp</em> for an example of this and many other examples of when %override is necessary.</li>
<li>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 <em>genwxbind.lua</em> on them. Then look at the C++ output for that function and copy it into your %override file and adjust as necessary.</li>
</ul>
<p><strong><em>%override_name CFunctionNameTheOverrideUses</em></strong></p>
<ul>
<li>The binding generator will automatically generate names for the functions it binds, which is by default wxLua_ClassName_FunctionName.</li>
<li>There are other special cases, please review the output of the generated bindings to determine what the default will be.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p><strong><em>%rename NEW_FUNC_NAME void FUNC_NAME()</em></strong></p>
<ul>
<li>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().</li>
<li>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.</li>
<li>An example of when this is necessary is
<ul>
<li>wxSize wxWindow::GetClientSize()</li>
<li>void wxWindow::GetClientSize(int* width, int* height)</li>
<li>Since Lua cannot pass the int *width and *height by reference, we change the function to have this signature.
<ul>
<li>[int width, int height] = wxWindow::GetClientSize()</li>
<li>However there is not anyway to distinguish between getting ints or a wxSize since we cannot check the left hand side, the return values.</li>
<li>The only solution seems to be to %rename the int width, height function to GetClientSizeWH()</li>
</ul></li>
</ul></li>
</ul>
<p><strong><em>%skip</em></strong></p>
<ul>
<li>The next item is skipped, either a single line or a whole class.</li>
</ul>
<p><strong><em>struct [%delete] StructName<br />{<br /> member variables<br /> ...<br />};</em></strong></p>
<ul>
<li>Declare a struct.</li>
<li>If the struct is in a namespace, such as <code>ns::StructName</code>, the struct must be declared as <code>struct [...] ns::StructName</code> and the constructor must also be declared as <code>ns::StructName(...)</code>. The generator will change the &quot;::&quot; to &quot;_&quot; for use in Lua.</li>
<li><strong><em>%delete</em></strong> can be used for structs you want the Lua garbage collector to delete when the object goes out of scope.</li>
<li>See <strong><em>class</em></strong> for more information. The wxLua binding treats classes and structs nearly the same.</li>
</ul>
<p><strong><em>typedef KNOWN_DATATYPE</em></strong> <strong><em>UNKNOWN_DATATYPE</em></strong></p>
<ul>
<li>Declares to the binding that the <em>UNKNOWN_DATATYPE</em> should be treated as <em>KNOWN_DATATYPE</em>.</li>
<li>An example of this is <em>&quot;typedef long wxTextCoord&quot;</em> where the wxTextCoord is just a long integer.</li>
<li>Without the <code>typedef</code> 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 had been made.</li>
</ul>
<p><strong><em>%ungc</em></strong></p>
<ul>
<li>For use before a userdata parameter of a function or its return value only.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>See also <em>%gc</em>.</li>
</ul>
<p><strong><em>%ungc_this</em></strong></p>
<ul>
<li>For a class member functions only and may be necessary for classes that use the <em>%delete</em> tag.</li>
<li>Declares that after calling this function the object itself (not return value) will not be garbage collected by Lua.</li>
<li>See also <em>%gc_this</em>.</li>
</ul>
<p><strong><em>%wxchkver_X_Y_Z</em></strong></p>
<ul>
<li>The next item will be <em>#if wxCHECK_VERSION(X,Y,Z).</em></li>
<li>The Y and Z parameters are optional and default to 0.</li>
<li><em>%wxchkverXY is now deprecated, please use %wxchkver_X_Y_Z</em></li>
</ul>
<p><strong><em>%wxcompat_X_Y</em></strong></p>
<ul>
<li>The next item will be <em>#if (defined(WXWIN_COMPATIBILITY_X_Y</em>) &amp;&amp; <em>WXWIN_COMPATIBILITY_X_Y)</em>.</li>
<li>The rest of the string beyond &quot;%wxcompat&quot; is appended to &quot;WXWIN_COMPATIBILITY&quot; so hopefully all future versions of wxWidgets should be supported.</li>
<li><em>%wxcompatXY is now deprecated, please use %wxcompat_X_Y</em></li>
</ul>
<p><strong>Standard wxWidgets #defines for conditional use using the #if directive</strong></p>
<pre><code>    %__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__</code></pre>
<p><strong><em>%wxEventType wxEVT_XXX</em></strong></p>
<ul>
<li>Declares a wxEventType <em>wxEVT_XXX</em> which can be accessed in Lua using <em>wx.wxEVT_XXX</em>.</li>
<li>This tag must be used inside of the <code>class</code> 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.</li>
<li>An example of this is the wxCommandEvent class's interface in <em>bindings/wxwidgets/event.i</em>, <em>&quot;%wxEventType wxEVT_COMMAND_ENTER&quot;</em>.</li>
</ul>
</body>
</html>