Menu
▾
▴
wxlua-commit
|
From: John L. <jr...@us...> - 2007-06-14 01:23:46
|
Update of /cvsroot/wxlua/wxLua/docs In directory sc8-pr-cvs9.sourceforge.net:/tmp/cvs-serv14159/wxLua/docs Modified Files: binding.html changelog.txt wxlua.html wxluaref.html Log Message: Changed the Delete() function from the %delete tag for classes to just delete() to avoid any future name clashes since delete() is never allowed to be a function name in C++. Moved the wxStyledTextCtrl class and it's 1268 defines into the wxstc table. Moved wxLuaObject, wxLuaDebugger (and friends) into the wxlua table and added more functions for inspecting userdata and the bindings. Fix mismatches between the bindings base classes and what they really are. Index: wxluaref.html =================================================================== RCS file: /cvsroot/wxlua/wxLua/docs/wxluaref.html,v retrieving revision 1.22 retrieving revision 1.23 diff -C2 -d -r1.22 -r1.23 *** wxluaref.html 13 Jun 2007 04:15:22 -0000 1.22 --- wxluaref.html 14 Jun 2007 01:23:09 -0000 1.23 *************** *** 7,11 **** </head> <body> ! <h1>wxLua 2.8.0.0 Class Reference for wxWidgets 2.8.0</h1> <h2>wxWidgets Classes</h2> <a href="#wxANIHandler">wxANIHandler</a> - (Not in wxWidgets reference manual)<br> --- 7,11 ---- </head> <body> ! <h1>wxLua 2.8.4.0 Class Reference for wxWidgets 2.8.4</h1> <h2>wxWidgets Classes</h2> [...1611 lines suppressed...] + <font color=#AA0000><font size=+1><i>%class</i> <i>%delete</i> <b><a name="wxLuaDebuggerEvent">wxLuaDebuggerEvent</a></b>, <a href="#wxEvent">wxEvent</a></font></font><blockquote> + <font color=#007755> <i>%define_event</i> wxEVT_WXLUA_DEBUGGER_DEBUGGEE_CONNECTED // EVT_WXLUA_DEBUGGER_DEBUGGEE_CONNECTED(id, fn)</font><br> + <font color=#007755> <i>%define_event</i> wxEVT_WXLUA_DEBUGGER_DEBUGGEE_DISCONNECTED // EVT_WXLUA_DEBUGGER_DEBUGGEE_DISCONNECTED(id, fn)</font><br> + <font color=#007755> <i>%define_event</i> wxEVT_WXLUA_DEBUGGER_BREAK // EVT_WXLUA_DEBUGGER_BREAK(id, fn)</font><br> + <font color=#007755> <i>%define_event</i> wxEVT_WXLUA_DEBUGGER_PRINT // EVT_WXLUA_DEBUGGER_PRINT(id, fn)</font><br> + <font color=#007755> <i>%define_event</i> wxEVT_WXLUA_DEBUGGER_ERROR // EVT_WXLUA_DEBUGGER_ERROR(id, fn)</font><br> + <font color=#007755> <i>%define_event</i> wxEVT_WXLUA_DEBUGGER_EXIT // EVT_WXLUA_DEBUGGER_EXIT(id, fn)</font><br> + <font color=#007755> <i>%define_event</i> wxEVT_WXLUA_DEBUGGER_STACK_ENUM // EVT_WXLUA_DEBUGGER_STACK_ENUM(id, fn)</font><br> + <font color=#007755> <i>%define_event</i> wxEVT_WXLUA_DEBUGGER_STACK_ENTRY_ENUM // EVT_WXLUA_DEBUGGER_STACK_ENTRY_ENUM(id, fn)</font><br> + <font color=#007755> <i>%define_event</i> wxEVT_WXLUA_DEBUGGER_TABLE_ENUM // EVT_WXLUA_DEBUGGER_TABLE_ENUM(id, fn)</font><br> + <font color=#007755> <i>%define_event</i> wxEVT_WXLUA_DEBUGGER_EVALUATE_EXPR // EVT_WXLUA_DEBUGGER_EVALUATE_EXPR(id, fn)</font><br> + <br> + int GetLineNumber() const<br> + int GetReference() const<br> + <a href="#wxString">wxString</a> GetFileName() const<br> + <a href="#wxString">wxString</a> GetMessage() const<br> + //const wxLuaDebugData GetDebugData() const<br> + </blockquote><font color=#AA0000><i>%endclass</i></font><br> </body> </html> Index: wxlua.html =================================================================== RCS file: /cvsroot/wxlua/wxLua/docs/wxlua.html,v retrieving revision 1.24 retrieving revision 1.25 diff -C2 -d -r1.24 -r1.25 *** wxlua.html 12 Jun 2007 20:36:10 -0000 1.24 --- wxlua.html 14 Jun 2007 01:23:09 -0000 1.25 *************** *** 272,288 **** elseif (bool) then ... else ... end</b></li> ! </ul><blockquote> <pre>local a, b, c = 1, 2, 3 -- can assign multiple values<br>a = 1; b = 2; c = 3 -- use ; for multiple lines of code on single line<br>a, b, c = 1, 2, 3 -- this works too<br>if (a == 1) and ((b <= 2) or (c ~= 3)) then <br> print(a+b/c) <br>elseif a == 2 then -- no parentheses necessary<br> print(a)<br>else<br> print(b)<br>end</pre></blockquote><ul><ul> ! <li>There is no case statement, but a table[value] = function() ... end may be used to simulate one.</li> <blockquote> ! <pre>mycase = {}<br>mycase[1] = function() print("Hello #1") end<br>mycase[2] = function() print("Hello #2") end<br>...<br>if mycase[value] then<br> mycase[value]()<br>else<br> print("Unknown case value")<br>end</pre></blockquote></ul> ! <li><b>while (bool) ... end</b></li> <ul> <li>Note : there is no <i>continue</i> keyword only <i>break</i></li> </ul> ! </ul><blockquote> <pre>function CheckA(val) if val == 5 then return true end end<br>local a = 1<br>while a < 10 do<br> print(a)<br> a = a + 1 -- no increment operator<br> if CheckA(a) then break end<br>end</pre></blockquote><ul><ul> ! <li>You can make a "fake" continue by doing this, doesn't --- 272,285 ---- elseif (bool) then ... else ... end</b></li> ! </ul><blockquote> <pre>local a, b, c = 1, 2, 3 -- can assign multiple values<br>a = 1; b = 2; c = 3 -- use ; for multiple lines of code on single line<br>a, b, c = 1, 2, 3 -- this works too<br>if (a == 1) and ((b <= 2) or (c ~= 3)) then <br> print(a+b/c) <br>elseif a == 2 then -- no parentheses necessary<br> print(a)<br>else<br> print(b)<br>end</pre></blockquote><ul><ul><li>There is no case statement, but a table[value] = function() ... end may be used to simulate one.</li> <blockquote> ! <pre>mycase = {}<br>mycase[1] = function() print("Hello #1") end<br>mycase[2] = function() print("Hello #2") end<br>...<br>if mycase[value] then<br> mycase[value]()<br>else<br> print("Unknown case value")<br>end</pre></blockquote></ul><li><b>while (bool) ... end</b></li> <ul> <li>Note : there is no <i>continue</i> keyword only <i>break</i></li> </ul> ! </ul><blockquote> <pre>function CheckA(val) if val == 5 then return true end end<br>local a = 1<br>while a < 10 do<br> print(a)<br> a = a + 1 -- no increment operator<br> if CheckA(a) then break end<br>end</pre></blockquote><ul><ul><li>You can make a "fake" continue by doing this, doesn't *************** *** 329,334 **** size of the mantissa).<br>The logical operations start with "b" for "bit" to avoid clashing with reserved words; although "xor" isn't a ! reserved word, it seemed better to use "bxor" for consistency.<br><ul><li>bit.bnot(a) returns the one's complement of a</li><li>bit.band(w1,...) returns the bitwise and of the w's</li><li>bit.bor(w1,...) returns the bitwise or of the w's</li><li>bit.bxor(w1,...) returns the bitwise exclusive or of the w's</li><li>bit.lshift(a,b) returns a shifted left b places</li><li>bit.rshift(a,b) returns a shifted logically right b places</li><li>bit.arshift(a,b) returns a shifted arithmetically right b places (works on negative ! numbers too)</li><li>bit.mod(a,b) returns the integer remainder of a divided by b</li></ul><h2><a name="wxLua_Programming_in_Lua"></a><u>Programming in wxLua</u></h2> Programming in wxLua means that you're writing lua programs using the --- 326,339 ---- size of the mantissa).<br>The logical operations start with "b" for "bit" to avoid clashing with reserved words; although "xor" isn't a ! reserved word, it seemed better to use "bxor" for consistency.<br><ul><li>bit.bnot(a) ! returns the one's complement of a</li><li>bit.band(w1,...) ! returns the bitwise and of the w's</li><li>bit.bor(w1,...) ! returns the bitwise or of the w's</li><li>bit.bxor(w1,...) ! returns the bitwise exclusive or of the w's</li><li>bit.lshift(a,b) ! returns a shifted left b places</li><li>bit.rshift(a,b) ! returns a shifted logically right b places</li><li>bit.arshift(a,b) ! returns a shifted arithmetically right b places (works on negative ! numbers too)</li><li>bit.mod(a,b) returns the integer ! remainder of a divided by b</li></ul><h2><a name="wxLua_Programming_in_Lua"></a><u>Programming in wxLua</u></h2> Programming in wxLua means that you're writing lua programs using the *************** *** 342,346 **** placed in their own "namespace" table, but for the examples below we will use the <i><b>wx</b></i> table. <br> ! <br>The semantics for accessing wxWidgets elements in wxLua tries to map as closely as possible to the underlying C++ notation so that the official C++ documentation may be used as --- 347,359 ---- placed in their own "namespace" table, but for the examples below we will use the <i><b>wx</b></i> table. <br> ! <br>Tables that wxLua creates containing the binding functions or ! objects.<br><ul><li><span style="font-weight: bold;">bit</span> - The bit ! library from Reuben Thomas for manipulating integer bits.</li><li><span style="font-weight: bold;">wxlua</span> - Special ! functions for introspecting into wxLua or generic functions that wxLua ! provides that are independent of wxWidgets.</li><li><span style="font-weight: bold;">wx</span> - All wxWidgets ! functions, classes, defines, enums, strings, events, and ! objects are placed here.</li><li><span style="font-weight: bold;">wxstc</span> - The ! wxStyledTextCtrl wrapper around the Scintilla text editor.</li></ul>The ! semantics for accessing wxWidgets elements in wxLua tries to map as closely as possible to the underlying C++ notation so that the official C++ documentation may be used as *************** *** 367,371 **** the lua ANSI C 8-bit char* string to a wxString (which may be a unicode w_char* string) is done internally.<br> ! <br><u><b>wxArrayString / wxSortedArrayString:</b></u> Function parameters that take a "const wxArrayString& arr" or --- 380,384 ---- the lua ANSI C 8-bit char* string to a wxString (which may be a unicode w_char* string) is done internally.<br> ! <br><u><b>wxArrayString and wxSortedArrayString:</b></u> Function parameters that take a "const wxArrayString& arr" or *************** *** 496,510 **** name are overloaded (as in C++) and the proper function to call ! is determined at runtime. </li> <li>Functions from the base class(es) are also available and may be overloaded as well.</li> <li>The C++ classes are tables in lua, but have a __call ! metatable so they can be called as a function. If you need to get the constructor function itself you can use <i>wx.CLASS_NAME.new(...)</i> ! which is the constructor exposed as a cfunction.</li> </ul> <li>Declared in the bindings using the <i>%class</i> ! tag</li> <li><b>Function calls</b> ! to the class member ! functions are made using the colon ':' convention and NOT the period '.'. This is because ':' in lua puts the object itself on the --- 509,573 ---- name are overloaded (as in C++) and the proper function to call ! is determined at runtime. </li> <li>Member functions from ! the base class(es) are also available and may be overloaded as well.</li> <li>The C++ classes are tables in lua, but have a __call ! metatable item so they can be called as a function. If you need to get ! the constructor function itself you can use <i>wx.CLASS_NAME.new(...)</i> ! which is the constructor exposed as a Cfunction.</li> </ul><li>The ! C++ classes are pushed into lua as a userdata with a special metatable ! that finds the function to call at runtime. This is done to </li> <li>Declared in the bindings using the <i>%class</i> ! tag</li><li><span style="font-weight: bold;">Deleting ! class userdata</span> can be done using the wxLua added class ! member delete() function.</li><ul><li>All classes ! that have the %delete binding tag will be eventually garbage collected ! when they go out of scope.</li><li>Classed without the ! %delete tag are assumed to be eventually attached to another object ! that will delete them for you.</li><li>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.</li><li>However! ! Some graphical device interface (GDI) classes need to be deleted ! immediately when you are done with them.</li><ul><li>This ! is really a MS Windows problem, in Win95 based systems the number that ! you could create was severly limited, but even in NT systems (XP) 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 or completely and the program becomes sluggish.</li><li>In ! any case, just delete() them when done so that your program will work ! equally well in MSW as it would in Linux or OSX.</li></ul><li>Additionally, ! since the userdata that wxLua pushes into lua are C++ classes, ! lua only thinks they are of size void* pointers, 8 bytes, ! but 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. (Besides modifying the core of ! lua, which some people are against since wxLua can be loaded as a ! module.)</li><li>The solution is to use the delete() ! function on certain types of userdata when you are done.</li><li>This ! is a list of classes by order of importance of deleting them</li><ul><li style="font-weight: bold;">Must delete : wxDC, wxPaintDC any ! and ALL classed derived from a wxDC</li><li><span style="font-weight: bold;">Must delete if > 50 : ! wxBitmap, wxBrush, wxColour, wxCursor, wxFont, wxIcon, ! wxPen, wxRegion</span> </li><ul><li>To ! be sure, delete them when you're done and not worry.</li></ul><li>Must delete ! if large and you're creating many of them : wxImage, wxBitmap</li><li>Don't ! bother : wxPoint, wxRect... etc</li><li>Never delete : ! wxWindows attached their their parents, use Destroy(), wxMenuItems ! returned from a wxMenu.</li><ul><li>Safe rule, don't ! delete() things that aren't yours. Refer to the wxWidgets documentation ! about whether an object will take ownership of an object passed to ! it. </li></ul></ul><li>How to tell how ! many userdata objects you currenty have? </li><ul><li>Call ! the function wxlua.StackDialog() when you run you program using ! "wxlua.exe program.lua" or in wxLuaEdit.exe.</li><li>This ! function requires that wxLuaDebug C++ library to be compiled with it so ! it does not work with wxLuaFreeze.exe.</li></ul></ul> ! <li><b>Member functions</b> ! of the class are called using the colon ':' convention and NOT the ! period '.'. This is because ':' in lua puts the object itself on the *************** *** 539,552 **** returns none.</li> </ul><li>The Get/Set part of the function name is removed leaving only XXX and you ! do not use them like ! a function call using (), but rather like accessing a table member.</li> </ul> <ul> <li>Example : <i>"rect = ! wx.wxRect(wx.wxPoint(1,2), wx.wxSize(3,4)); rect.X = 10; print(rect.X)"</i></li> <li>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.</li> <li>Note : Are properties really necessary? Confusing? Useful? --- 602,638 ---- returns none.</li> </ul><li>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 "()".</li> </ul> <ul> <li>Example : <i>"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))"</i> ! should print "10, true, true".</li> <li>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.</li><li>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.</li><li>Below is a ! list of what works and doesn't, the example is for a static function, ! but the same works for a regular class member function.</li><ul><li>Works ! (static functions only) : <span style="font-style: italic;">"print(wx.wxFileName.GetCwd())"</span> ! and <span style="font-style: italic;">"print(wx.wxFileName.GetCwd)"</span> ! prints that it's a function.</li><li>Fails (static ! functions only) : <span style="font-style: italic;">"print(wx.wxFileName:GetCwd())"</span> ! and <span style="font-style: italic;">"print(wx.wxFileName:GetCwd)"</span></li><li>Works ! : <span style="font-style: italic;">"f = ! wx.wxFileName("a"); print(f.GetCwd())"</span> and <span style="font-style: italic;">"f = wx.wxFileName("a"); ! print(f.GetCwd)"</span> prints that it's a function.</li><li>Fails ! : <span style="font-style: italic;">"f = ! wx.wxFileName("a"); print(f:GetCwd())"</span> and <span style="font-style: italic;">"f = wx.wxFileName("a"); ! print(f:GetCwd)"</span></li><li>Works : <span style="font-style: italic;">"f = wx.wxFileName("a"); ! print(f.Cwd)"</span></li><li>Fails : <span style="font-style: italic;">"f = wx.wxFileName("a"); ! print(f.Cwd())"</span> and <span style="font-style: italic;">"f ! = wx.wxFileName("a"); print(f:Cwd)"</span> and <span style="font-style: italic;">"f = wx.wxFileName("a"); ! print(f:Cwd())"</span></li></ul> <li>Note : Are properties really necessary? Confusing? Useful? *************** *** 674,678 **** 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 for do so in terms ! of binding size and speed.</li></ul><li><b>Extending classes</b> </li> <ul><li>You may add your --- 760,774 ---- 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 for do so in terms ! of binding size and speed.</li></ul><li><span style="font-weight: bold;">Overriding ! member functions</span> with lua functions</li><ul><li>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 '_'.</li><li>The lua function that you assign ! to a userdata will be called directly from lua without regard to the ! existing Cfunction(s).</li><li>Example : <span style="font-style: italic;">"p = wx.wxPoint(1,2); p.GetX = ! function(self) return 10-self:_GetX() end; print(p:GetX(), p:_GetX())"</span> ! prints "9, 1".</li><li>Note : Make sure that if you want to ! call the base function you use the '_' since otherwise you'll get ! recursion. </li></ul><li><b>Extending classes</b> </li> <ul><li>You may add your *************** *** 749,753 **** <li>Lets you explore the C++ binding structs from within lua using a wxListCtrl. This is the raw data that is used to push the ! bindings into lua when a wxLuaState is created.</li> </ul> <li><b>calculator.wx.lua</b></li> <ul> <li>A simple calculator program the demonstrates loading and --- 845,850 ---- <li>Lets you explore the C++ binding structs from within lua using a wxListCtrl. This is the raw data that is used to push the ! bindings into lua when a wxLuaState is created.</li><li>Take ! note of </li> </ul> <li><b>calculator.wx.lua</b></li> <ul> <li>A simple calculator program the demonstrates loading and *************** *** 806,810 **** <ul> <li>A wxTreeCtrl demonstration.</li> </ul> <li><b>unittest.wx.lua</b></li> <ul> <li>Tests ! the binding generator for various things.</li> </ul> <li><b>validator.wx.lua</b></li> <ul> <li>Tests the wxGenericValidator and wxTextValidator.</li> </ul> <li><b>veryminimal.wx.lua</b></li> --- 903,909 ---- <ul> <li>A wxTreeCtrl demonstration.</li> </ul> <li><b>unittest.wx.lua</b></li> <ul> <li>Tests ! that the binding generator is working properly and so it wxLua itself.</li><li>This ! is also a good reference for how to call various objects since it tries ! to test all the valid methods.</li> </ul> <li><b>validator.wx.lua</b></li> <ul> <li>Tests the wxGenericValidator and wxTextValidator.</li> </ul> <li><b>veryminimal.wx.lua</b></li> *************** *** 1046,1050 **** directly as they will be overwritten if you regenerate the bindings, the fix should really go into the interface files themselves. </li> ! <li>To initialize this library in a C++ program you should have the code <i>"extern bool wxLuaBinding_wx_init();"</i> and then somewhere in your app initialization or at least before you --- 1145,1150 ---- directly as they will be overwritten if you regenerate the bindings, the fix should really go into the interface files themselves. </li> ! <li>To initialize this library in a C++ program to have it pushed ! into lua you should have the code <i>"extern bool wxLuaBinding_wx_init();"</i> and then somewhere in your app initialization or at least before you *************** *** 1059,1063 **** wxStyledTextCtrl editor contrib of wxWidgets that you must have compiled and also link to.</li> <li>To initialize this ! library in a C++ program you should have the code <i>"extern bool wxLuaBinding_wxstc_init();"</i> and then somewhere in your app initialization or at least before you --- 1159,1163 ---- wxStyledTextCtrl editor contrib of wxWidgets that you must have compiled and also link to.</li> <li>To initialize this ! library in a C++ program to have it pushed into lua you should have the code <i>"extern bool wxLuaBinding_wxstc_init();"</i> and then somewhere in your app initialization or at least before you *************** *** 1068,1072 **** this library.</li> <li>The public C++ side of wxLua is almost entirely contained ! in <i>modules/wxlua/include/wxlstate.h</i>.</li> </ul> <li><b>wxluadebug</b></li> <ul> <li>This is a simple debug library for lua that provides some --- 1168,1178 ---- this library.</li> <li>The public C++ side of wxLua is almost entirely contained ! in <i>modules/wxlua/include/wxlstate.h</i>.</li><li>To ! initialize this ! library in a C++ program to have it pushed into lua you should ! have the code <i>"extern bool wxLuaBinding_wxlua_init();"</i> ! and then somewhere in your app initialization or at least before you ! create a wxLuaState call <i>wxLuaBinding_wxlua_init()</i>.</li> ! </ul> <li><b>wxluadebug</b></li> <ul> <li>This is a simple debug library for lua that provides some *************** *** 1075,1079 **** communicate to another for debugging purposes. It is currently used in the wxlua app.</li> <li>This lib depends on the wxluadebug ! lib.</li> </ul> </ul><h2><a name="wxLua_Programming_in_C"></a><u>wxLua C++ Programming --- 1181,1190 ---- communicate to another for debugging purposes. It is currently used in the wxlua app.</li> <li>This lib depends on the wxluadebug ! lib.</li><li>To initialize this ! library in a C++ program to have it pushed into lua you should ! have the code <i>"extern bool wxLuaBinding_wxluasocket_init();"</i> ! and then somewhere in your app initialization or at least before you ! create a wxLuaState call <i>wxLuaBinding_wxluasocket_init()</i>.</li> ! </ul> </ul><h2><a name="wxLua_Programming_in_C"></a><u>wxLua C++ Programming Index: binding.html =================================================================== RCS file: /cvsroot/wxlua/wxLua/docs/binding.html,v retrieving revision 1.20 retrieving revision 1.21 diff -C2 -d -r1.20 -r1.21 *** binding.html 12 Jun 2007 00:08:36 -0000 1.20 --- binding.html 14 Jun 2007 01:23:09 -0000 1.21 *************** *** 1,6 **** <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head> ! <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>wxLua Binding HowTo</title> <meta content="John Labenski" name="author"></head> ! <body><h2><u>wxLuaBinding - writing and generating the binding --- 1,6 ---- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head> ! <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>wxLua Binding HowTo</title> ! <meta content="John Labenski" name="author"></head> <body><h2><u>wxLuaBinding - writing and generating the binding *************** *** 11,15 **** 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++. <br> <br>Binding files are provided for the <b>wxWidgets</b> cross --- 11,17 ---- 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.html wxLua documentation describes in detail how the object ! will be named and where it will be placed in lua.<br> <br>Binding files are provided for the <b>wxWidgets</b> cross *************** *** 20,25 **** an example of this in the <i>apps/wxluacan/src</i> directory.<br> ! </div><br> ! <div style="text-align: justify;">The interface files are skeletons of the C/C++ header files that the program --- 22,27 ---- an example of this in the <i>apps/wxluacan/src</i> directory.<br> ! </div><br><div style="text-align: justify;">The ! interface files are skeletons of the C/C++ header files that the program *************** *** 54,59 **** Class Member Function Directives</a></li> <li><a href="#Comments_">Comments</a></li> <li><a href="#Interface_Tags">Interface Tags</a></li> </ol> ! </ol></div> ! <h2><a name="Binding_File_Descriptions"></a><u>Binding File Descriptions</u></h2> <h3>bindings/genwxbind.lua</h3> --- 56,60 ---- Class Member Function Directives</a></li> <li><a href="#Comments_">Comments</a></li> <li><a href="#Interface_Tags">Interface Tags</a></li> </ol> ! </ol></div><h2><a name="Binding_File_Descriptions"></a><u>Binding File Descriptions</u></h2> <h3>bindings/genwxbind.lua</h3> *************** *** 90,95 **** of wxLua's interface files follows the wxWidgets documentation, typically alphabetical.</li> <ul> <li style="text-align: justify;">Class constructors ! first, class member functions, %operators, %members, ! %properties.</li> </ul> </ul><h3>wxluasetup.h </h3> <ul> <li>Contains #defines of all of the wxLUA_USE_wxXXX --- 91,95 ---- of wxLua's interface files follows the wxWidgets documentation, typically alphabetical.</li> <ul> <li style="text-align: justify;">Class constructors ! first, class member functions, %operators, %members.</li> </ul> </ul><h3>wxluasetup.h </h3> <ul> <li>Contains #defines of all of the wxLUA_USE_wxXXX *************** *** 143,147 **** the %overridden function.</li> <ul> <li>// %override void wxFrame::SetStatusWidths(lua table with ! number indexes and values)</li> <li>//virtual void SetStatusWidths(int n, int *widths)</li> <li>virtual void SetStatusWidths(LuaTable intTable)</li> </ul> --- 143,148 ---- the %overridden function.</li> <ul> <li>// %override void wxFrame::SetStatusWidths(lua table with ! number indexes and values)</li> <li>// C++ Func: virtual ! void SetStatusWidths(int n, int *widths)</li> <li>virtual void SetStatusWidths(LuaTable intTable)</li> </ul> *************** *** 156,164 **** and exports the tags, structs, and functions for use in a DLL.</li> </ul> <li>The ! only function that absolutely must be called is <b>wxLuaBinding_[hook_cpp_binding_classname]_init()</b>. ! It is probably easiest to declare the function using <i>extern bool wxLuaBinding_[hook_cpp_binding_classname]_init();</i> in your ! file to rather than including the header.</li> <ul> <li>This function contains a static instance of the generated wxLuaBinding derived class that is put into a static wxList of --- 157,166 ---- and exports the tags, structs, and functions for use in a DLL.</li> </ul> <li>The ! only function that absolutely must be called is <b>wxLuaBinding_[hook_cpp_binding_classname]_init()</b>. </li><ul><li>It ! is probably easiest to declare the function using <i>extern bool wxLuaBinding_[hook_cpp_binding_classname]_init();</i> in your ! file to rather than including the header.</li></ul> <ul> ! <li>This function contains a static instance of the generated wxLuaBinding derived class that is put into a static wxList of *************** *** 311,317 **** <ul> <li>These parameters are interpreted by the generator to ! implement code to handle special cases.</li> <li><i><b>const wxArrayString& ! choices or wxArrayString choices</b></i></li> <ul> <li>The binding generator will read from lua either a wxArrayString or a a --- 313,320 ---- <ul> <li>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.</li> <li><b>const wxArrayString& ! choices or wxArrayString choices</b></li> <ul> <li>The binding generator will read from lua either a wxArrayString or a a *************** *** 319,329 **** them into a wxArrayString for the C++ ! function.</li> <li>If either <i><b>wxArrayString& ! choices</b></i> or <i><b>wxArrayString* choices</b></i> 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.</li> </ul> <li><i><b>const wxArrayInt& ! choices or wxArrayInt choices</b></i></li> <ul> <li>The binding generator will read from lua a --- 322,332 ---- them into a wxArrayString for the C++ ! function.</li> <li>If either <b>wxArrayString& ! choices</b> or <b>wxArrayString* choices</b> 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.</li> </ul> <li><b>const wxArrayInt& ! choices or wxArrayInt choices</b></li> <ul> <li>The binding generator will read from lua a *************** *** 332,341 **** them into a wxArrayInt for the C++ ! function.</li> <li>If either <i><b>wxArrayInt& ! choices</b></i> ! or <i><b>wxArrayInt* choices</b></i> 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.</li> </ul> <li style="font-weight: bold; font-style: italic;">IntArray_FromLuaTable</li> <ul> <li>The binding generator will read from lua a numerically indexed table of --- 335,344 ---- them into a wxArrayInt for the C++ ! function.</li> <li>If either <b>wxArrayInt& ! choices</b> ! or <b>wxArrayInt* choices</b> 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.</li> </ul> <li style="font-weight: bold;">IntArray_FromLuaTable</li> <ul> <li>The binding generator will read from lua a numerically indexed table of *************** *** 345,357 **** automatically deleted and the function should not take ownership of it and delete it itself.</li> ! </ul> <li><i><b>LuaTable ! tableName</b></i></li> <ul> <li>The "datatype" LuaTable does not actually exist, but is ! used exclusively for %overridden functions in the .i interface files. It directs the binding generator to expect a lua table for that ! parameter. Note that you absolutely must have overrriden this function as the generated code will not compile.</li> <li>This is useful for functions like ! wxFrame::SetStatusWidths as shown above.</li> </ul> </ul><h3><a name="C_Class_Member_Function_Directives"></a>C++ Class Member Function Directives</h3> --- 348,367 ---- automatically deleted and the function should not take ownership of it and delete it itself.</li> ! </ul> <li><b>LuaTable ! tableName</b></li> <ul> <li>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. </li><li>Note : You absolutely must <span style="font-style: italic;">%overrride</span> this ! function as the generated code will not compile.</li> <li>This is useful for functions like ! wxFrame::SetStatusWidths as shown above.</li> </ul><li style="font-weight: bold;">LuaFunction functionName</li><ul><li>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. </li><li>Note : You absolutely must <span style="font-style: italic;">%overrride</span> this ! function ! as the generated code will not compile.</li></ul> </ul><h3><a name="C_Class_Member_Function_Directives"></a>C++ Class Member Function Directives</h3> *************** *** 361,391 **** files.</li> </ul> <li><b>static</b> </li> <ul> <li>For class member functions inside the <i>%class</i> ! tag, do not use for C style functions! </li> <li>The generated code will call ! ClassName::FunctionName and not use an object. </li> <li>wxLua ! requires that an instance of the class be created ! however.</li> <ul> <li>Example : In the %class wxFileName the function <i>"static wxFileName DirName(const wxString& ! dir)"</i></li> <li>wxLua code : <i>f = ! wx.wxFileName(); dir = f:DirName("/some/dir")</i></li> <li>or ! <i>wx.wxFileName.DirName("/some/dir"):GetFullPath()</i></li> </ul> <li>The bindings generate code to make the function ! accessible in the class table as well as when called using a object.<br> </li> </ul> <li><b><i>virtual</i></b></li> <ul> <li><i>Currently ignored - TODO perhaps<br> ! </i></li> </ul> ! </ul><h3><a name="Comments_"></a>Comments ! </h3> ! <ul> <li><b>//</b> as in C++ to ! comment out a whole or ! the rest of a line of text.</li> <li><b>/* ... */</b> ! to comment blocks.</li> </ul><h3><a name="Interface_Tags"></a>Interface Tags</h3> <b><i>%alias</i><br> </b>Reference a class by another name (currently unused). ! <br><br> ! <i><b>%class [%delete] [%noclassinfo] [%encapsulate] ClassName [, BaseClassName] <br> </b>ClassName(...)<br> --- 371,398 ---- files.</li> </ul> <li><b>static</b> </li> <ul> <li>For class member functions inside the <i>%class</i> ! tag, do not use for C style global functions! </li> <li>The generated code will call ! ClassName::FunctionName and not use an object. </li> <li>Example ! : In the %class wxFileName the function <i>"static wxFileName DirName(const wxString& ! dir)"</i></li><ul> <li>wxLua code : <span style="font-style: italic;">"dir = ! wx.wxFileName.DirExists("/some/dir")"</span> or <i>"f = ! wx.wxFileName(); dir = f.DirName("/some/dir")"</i></li> </ul> <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.<br> </li> </ul> <li><b><i>virtual</i></b></li> <ul> <li><i>Currently ignored - TODO perhaps<br> ! </i></li> </ul></ul><h3><a name="Comments_"></a>Comments ! </h3><ul> <li><b>//</b> as in C++ to ! comment out the rest of a line of text.</li> <li><b>/* ! ... */</b> ! to comment multiline blocks.</li> </ul><h3><a name="Interface_Tags"></a>Interface Tags</h3> <b><i>%alias</i><br> </b>Reference a class by another name (currently unused). ! <br><br><i><b>%class [%delete] [%noclassinfo] [%encapsulate] ClassName [, BaseClassName] <br> </b>ClassName(...)<br> *************** *** 400,419 **** you must use %class ... ns::ClassName and the constructor must also be ! ns::ClassName. </li> <li><i><b>%delete</b></i> 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 where 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.</li> <li><i><b>%noclassinfo</b></i> ! is for ! classes that do not have DECLARE_XXX_CLASS in their declaration, e.g. wxPoint and any non wxObject ! derived classes.</li> <li> <i><b>%encapsulate</b></i> is for <b>all</b> classes --- 407,428 ---- 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. </li> <li><i><b>%delete</b></i> is for classes that you want the lua garbage collector to ! delete when the variable goes out of scope. </li><ul><li>For ! example, a wxPoint should be deleted where 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.</li></ul> <li><i><b>%noclassinfo</b></i> ! is for all classes that do not have DECLARE_XXX_CLASS in their declaration, e.g. wxPoint and any non wxObject ! derived classes.</li><ul><li>You can use the ! samples/bindings.wx.lua program to test if the assigned classinfo is ! correct.</li></ul> <li> <i><b>%encapsulate</b></i> is for <b>all</b> classes *************** *** 421,425 **** wxObject derived to aid in deleting them. The macros wxLUA_DECLARE_ENCAPSULATION and wxLUA_IMPLEMENT_ENCAPSULATION are used ! to wrap the object in a wxObject derived class.<br> </li> </ul><b><i>%define NUMBER [Value]</i><br> --- 430,435 ---- wxObject derived to aid in deleting them. The macros wxLUA_DECLARE_ENCAPSULATION and wxLUA_IMPLEMENT_ENCAPSULATION are used ! to wrap the object in a wxObject derived class so that a single list of ! tracked objects can be maintained.<br> </li> </ul><b><i>%define NUMBER [Value]</i><br> *************** *** 444,448 **** 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 data type to it. </li> <li>An example of this is in the wxCommandEvent interface in <i>bindings/wxwidgets/event.i</i>, <i>"%define --- 454,458 ---- 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. </li> <li>An example of this is in the wxCommandEvent interface in <i>bindings/wxwidgets/event.i</i>, <i>"%define *************** *** 455,465 **** so that the object's class methods can be known to lua and the generator ! can assign the correct data type to it.</li> <li>An example of this is in the wxPoint interface in <i>bindings/wxwidgets/gdi.i</i>, <i>"%define %object wxDefaultPosition"</i> where wxWidgets has created wxDefaultPosition as <i>"const wxPoint wxDefaultPosition;"</i>.<br> ! </li> ! </ul><i><b>%define_pointer POINTER</b></i><br> <ul> <li>Declares a pointer to an object in the binding table which --- 465,474 ---- 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 interface in <i>bindings/wxwidgets/gdi.i</i>, <i>"%define %object wxDefaultPosition"</i> where wxWidgets has created wxDefaultPosition as <i>"const wxPoint wxDefaultPosition;"</i>.<br> ! </li></ul><i><b>%define_pointer POINTER</b></i><br> <ul> <li>Declares a pointer to an object in the binding table which *************** *** 470,474 **** so that the pointer's methods can be known to lua and the ! generator can assign the correct data type to it.</li> <li>An example of this is in the wxPenList interface in <i>bindings/wxwidgets/gdi.i</i>, --- 479,483 ---- 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 interface in <i>bindings/wxwidgets/gdi.i</i>, *************** *** 476,481 **** has created the wxThePenList as <i>"wxPenList* wxThePenList;"</i>.<br> ! </li> ! </ul><i><b>%define_string STRING [Value]</b></i><br> <ul> <li>Adds a string to the binding table which is accessed in wxLua using <i>wx.STRING</i>. </li> <li>The --- 485,489 ---- has created the wxThePenList as <i>"wxPenList* wxThePenList;"</i>.<br> ! </li></ul><i><b>%define_string STRING [Value]</b></i><br> <ul> <li>Adds a string to the binding table which is accessed in wxLua using <i>wx.STRING</i>. </li> <li>The *************** *** 488,496 **** optional parameter <i>[Value]</i> can be the actual string value to use and should be _("str"), ! wxT("str"), or a const wxChar* variable declared elsewhere.</li> <li>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.<br> ! </li> </ul><i><b>%enum [Enum_Type] or [ClassName::Enum_Type]</b><br> ENUM_ITEM1<br> --- 496,506 ---- optional parameter <i>[Value]</i> can be the actual string value to use and should be _("str"), ! wxT("str"), or a const wxChar* variable declared elsewhere.</li> <li>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.</li><li>Note ! : Why not use const char*? There currently isn't a need for it, but it ! would be easy to add if there was.</li> </ul><i><b>%enum [Enum_Type] or [ClassName::Enum_Type]</b><br> ENUM_ITEM1<br> *************** *** 537,547 **** be used inside of the <i>%class</i> tag. </li> <li>The generated ! functions will be named Get_m_x() and Set_m_x(int x) therefore it is recommended that you use <i>%rename</i> in conjunction with <i>%member</i>. </li> <li>For example, in wxPoint <i>"%rename X ! %member int m_x"</i> will generate wxPoint methods named GetX() and ! SetX(int x) for the wxPoint class.</li> </ul><i><b>%operator bool operator==(const wxPoint& --- 547,560 ---- be used inside of the <i>%class</i> tag. </li> <li>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 <i>%rename</i> in conjunction with <i>%member</i>. </li> <li>For example, in wxPoint <i>"%rename X ! %member int x"</i> will generate wxPoint methods named <span style="font-style: italic;">"pt:GetX()"</span> and ! <span style="font-style: italic;">"pt:SetX(5)"</span> ! for the wxPoint class as well as properties to access them as if they ! were table members, <span style="font-style: italic;">print(pt:x)</span> ! and <span style="font-style: italic;">"pt:x = 5"</span>.</li> </ul><i><b>%operator bool operator==(const wxPoint& *************** *** 605,609 **** 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> </ul><i><b>%override wxLua_ClassName_FunctionName <br> </b>// any code or comments can go within the %override ... %end --- 618,624 ---- 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 "void DoStuff()" and then ! in a later version of the C++ library "bool DoStuff(int flag)".</li> </ul><i><b>%override wxLua_ClassName_FunctionName <br> </b>// any code or comments can go within the %override ... %end *************** *** 640,644 **** 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.</li> <li>However, if the function is --- 655,660 ---- 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 *************** *** 689,694 **** %rename the int width, height function to GetClientSizeWH() </li> </ul> ! </ul> ! </ul><b><i>%skip</i><br> </b><ul> <li>The next item is skipped, either a single line or a --- 705,709 ---- %rename the int width, height function to GetClientSizeWH() </li> </ul> ! </ul></ul><b><i>%skip</i><br> </b><ul> <li>The next item is skipped, either a single line or a Index: changelog.txt =================================================================== RCS file: /cvsroot/wxlua/wxLua/docs/changelog.txt,v retrieving revision 1.35 retrieving revision 1.36 diff -C2 -d -r1.35 -r1.36 *** changelog.txt 12 Jun 2007 00:08:36 -0000 1.35 --- changelog.txt 14 Jun 2007 01:23:09 -0000 1.36 *************** *** 90,93 **** --- 90,103 ---- was called "base_XXX" before there would have been a problem. + - Changed the Delete() function from the %delete tag for classes to just + delete() to avoid any future name clashes since delete() is never allowed + to be a function name in C++. + + - Moved the wxStyledTextCtrl class and it's 1268 defines into the wxstc table. + - Moved wxLuaObject, wxLuaDebugger (and friends) into the wxlua table and + added more functions for inspecting userdata and the bindings. + - Added the bit library from Reuben Thomas and put it into the bit table. + - Fix mismatches between the bindings base classes and what they really are. + version 2.8.0.0 (released 24/12/2006) -------------------------------------------------------------------- |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X