[Wxlua-commit] wxLua/bindings readme.txt,NONE,1.1

[John L. <jr...@us...>]

Update of /cvsroot/wxlua/wxLua/bindings
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv9007/wxLua/bindings

Added Files:
	readme.txt 
Log Message:
add readme.txt to descibe the wrapper files


--- NEW FILE: readme.txt ---
readme.txt - describes binding files for wxLua

The bindings for wxLua provide information for lua to interface with
the wxWindows C++ API. The binding files are a skeleton that the program
genwxbind.lua parses and turns into C functions that are imported into lua.

------------------------------------------------------------------------------
BINDING FILES
------------------------------------------------------------------------------

wxluasetup.h contains all wxLUA_USE_wxXXX
    if wxLUA_USE_XXX is 1 then it's compiled in, else ignored
    when compiling the generated cpp files.

*.i are the binding files broken up by functionality

overrides.hpp contains functions that cannot be automatically wrapped
   Functions that take pointers or references and return values through
   the variables passed in must be reworked to return multiple values.

genwxbind.lua reads wx.rules to generate the bindings 

The wrapper files have been divided in what I think is a reasonable way. 
There may be some problems with them that will arise when you start to try 
to exclude different classes in the wxluasetup.h file.

------------------------------------------------------------------------------
WRAPPER CONSTRUCTS
------------------------------------------------------------------------------

%if wxLUA_USE_XXX
    All code is ignored if wxLUA_USE_XXX is 0
    set the values of wxLUA_USE_XXX in luasetup.h
%endif wxLUA_USE_XXX

%win - the next item will #ifdefed __WXMSW__ 
%gtk - the next item will #ifdefed __WXGTK__ 

%skip - the next item is skipped, either a single item or a whole class

%stop - immediately stop processing wrapper files

%override ... %end - replace code wrapper code with this handwritten code

%builtin - this is a global function

%constructor - this is an alternate name for a constuctor
    note: it does seem possible to read the items off the stack
        and by determining their type choose the appropriate constuctor.

%rename NEW_NAME void DoStuff() - rename a method to a new name
    wxLua knows the function as void NEW_NAME() though it's accessed
    in C using DoStuff

%alias - reference a class by another name (currently unused)

%property - not really sure?

%enum [SomeEnum_Type] or [SomeBaseClass::SomeEnum_Type]
   enum_item1
   enum_item2
%end
    This adds items to a global list of enums, you may have more than
    one of the same enum. The "SomeEnum_Type" is stripped off so that
    in wxLua you get the value of the enum with "wx.enum_item1". If 
    a base class is necessary use "%enum SomeBaseClass::SomeEnum_Type"
    you still get the value in wxLua using "wx.enum_item1". 
    Is this Ok? There doesn't seem to be any conflicts yet.

%define SOME_NUMBER - adds SOME_NUMBER to a global list as a number

%define %string SOME_STRING 
    adds SOME_STRING to a global list as a string
    SOME_STRING must be defined as const wxChar * SOME_STRING = _("str") or wxT("str")
    or some way to allow it to be converted easily to const wxChar *
    in unicode or not, wxWindows does this and it's good practice
    why not use the original wxString value?
    You can't get the data from a wxString if you need to convert from unicode
    VC has problems having a wxString as a member of a struct

%define %object SOME_OBJECT
    declares a global object, use inside a class so that
    the object's methods can be known to lua

%define %pointer SOME_POINTER
    declare a global pointer, use inside a class so that
    the pointer's methods can be known to lua

%define %event wxEVT_SIZE
    declare an event type, use inside the wxEvent derived class
    it corresponds to, so the event's methods can be found

%class SomeClass [, SomeBaseClass]  
    %define %object wxTheSomeClass <- must go in the class
    %define %pointer wxTheSomeClassPointer <- must go in the class

    int GetStuff(bool all_of_it) const <- member functions
    void SetStuff(int stuff)
    %member int m_x
%endclass
    Declare a class and optionally it's base class. All the methods of the
    base class can be accessed by the class. 

%member - declare a member variable for a class
    %member int m_x 
         methods Get_m_x() and Set_m_x(val)
         properties class.m_x = val and val = class.m_x
    %rename X %member int m_x
         methods GetX() and SetX(val)
         properties class.m_x = val and val = class.m_x

%include "somefile.h" - includes a header file, C code is #include "somefile.h"

%includefile somewrapper.i - includes another wrapper file that is immediately
    processed, when finished processing continues on the original wrapper