Thread: [Wxlua-commit] wxLua/docs wxlua.html,1.33,1.34

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/wxlua/wxLua/docs
In directory sc8-pr-cvs9.sourceforge.net:/tmp/cvs-serv19898/wxLua/docs

Modified Files:
	wxlua.html 
Log Message:
Some comment cleanup
Document wxLuaState creation a little better


Index: wxlua.html
===================================================================
RCS file: /cvsroot/wxlua/wxLua/docs/wxlua.html,v
retrieving revision 1.33
retrieving revision 1.34
diff -C2 -d -r1.33 -r1.34
*** wxlua.html	3 Aug 2007 14:29:09 -0000	1.33
--- wxlua.html	4 Sep 2007 22:21:10 -0000	1.34
***************
*** 279,310 ****
  printHi() do return end; print("hi") end</i> which can be useful
  for debugging functions.</li> </ul>
! </ul><blockquote> <pre>do<br> -- create a new local scope<br> local a = 2<br>end<br></pre></blockquote><ul>
! <li><b>if
  (bool) then ...
  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 &lt;= 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 &lt; 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 adding a while loop (doesn't
  print # 5). <br></li> </ul>
! </ul><blockquote><pre>local a = 1<br>while a &lt; 10 do while true do<br> a = a + 1 -- no increment operator<br> if CheckA(a) then <br> break <br> else<br> print(a)<br> end<br>break end end</pre></blockquote><ul>
! <li><b>repeat
  ... until
  (bool)</b></li> <ul> <li>Note : there is no
  continue keyword only break</li> </ul>
! </ul><blockquote> <pre>local a = 1<br>repeat<br> local temp = a * 2<br> print(temp, type(temp))<br> a = a + 1 -- no increment operator<br>until a &gt; 10</pre></blockquote><ul>
! <li><b>for
  var = init_value,
  end_value [, increment] do
--- 279,307 ----
  printHi() do return end; print("hi") end</i> which can be useful
  for debugging functions.</li> </ul>
! </ul><blockquote> <pre>do<br> -- create a new local scope<br> local a = 2<br>end<br></pre></blockquote><ul><li><b>if
  (bool) then ...
  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 &lt;= 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 &lt; 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 adding a while loop (doesn't
  print # 5). <br></li> </ul>
! </ul><blockquote><pre>local a = 1<br>while a &lt; 10 do while true do<br> a = a + 1 -- no increment operator<br> if CheckA(a) then <br> break <br> else<br> print(a)<br> end<br>break end end</pre></blockquote><ul><li><b>repeat
  ... until
  (bool)</b></li> <ul> <li>Note : there is no
  continue keyword only break</li> </ul>
! </ul><blockquote> <pre>local a = 1<br>repeat<br> local temp = a * 2<br> print(temp, type(temp))<br> a = a + 1 -- no increment operator<br>until a &gt; 10</pre></blockquote><ul><li><b>for
  var = init_value,
  end_value [, increment] do
***************
*** 317,322 ****
  it did before the loop. Copy the loop counter variable to a separate
  variable if you need to save it when breaking for example.</li> </ul>
! </ul><blockquote> <pre>local a = "hello"<br>for a = 1, 10 --[[, increment]] do -- optional increment value, else 1<br> local temp = a * 2<br> print(temp)<br>end<br>print(a) -- a == "hello" since loop counter variable is local to the loop<br></pre></blockquote><ul>
! <li><b>functions</b></li>
  <ul> <li>Input any number of values by value, tables are
  passed by
--- 314,318 ----
  it did before the loop. Copy the loop counter variable to a separate
  variable if you need to save it when breaking for example.</li> </ul>
! </ul><blockquote> <pre>local a = "hello"<br>for a = 1, 10 --[[, increment]] do -- optional increment value, else 1<br> local temp = a * 2<br> print(temp)<br>end<br>print(a) -- a == "hello" since loop counter variable is local to the loop<br></pre></blockquote><ul><li><b>functions</b></li>
  <ul> <li>Input any number of values by value, tables are
  passed by
***************
*** 324,330 ****
  the value nil, extra inputs are discarded.</li> <li>Return
  values using the "return" keyword</li> <li>Not all return
! values need to be used and extra ones will be discarded.&nbsp;</li><ul><li>The symbol "_"
  is a valid variable name and is often used as a dummy variable to
! receive return values that you do not want.</li><ul style="font-style: italic;"><li>function GetNums() return 3, 4 end; &nbsp;local _, num2 = GetNums()</li></ul><li>You may also use the <span style="font-style: italic;">select(n,
  ...)</span> function to choose return values to use.</li></ul><li>Tables
  can be used as containers for input values to functions using the
--- 320,329 ----
  the value nil, extra inputs are discarded.</li> <li>Return
  values using the "return" keyword</li> <li>Not all return
! values need to be used and extra ones will be discarded. </li><ul><li>The
! symbol "_"
  is a valid variable name and is often used as a dummy variable to
! receive return values that you do not want.</li><ul style="font-style: italic;"><li>function GetNums()
! return 3, 4 end; local _, num2 = GetNums()</li></ul><li>You
! may also use the <span style="font-style: italic;">select(n,
  ...)</span> function to choose return values to use.</li></ul><li>Tables
  can be used as containers for input values to functions using the
***************
*** 340,350 ****
  chosen using: <span style="font-style: italic;">local
  arg3 = select(3, ...)</span> </li><ul><li>Note
! <span style="font-style: italic;">select(n, ...)</span> returns
  all args after <span style="font-style: italic;">n</span>,
  but if the left hand side is a single variable the others are
  discarded. See above about using <span style="font-style: italic;">select()</span>
  to pick return values of a function as well.</li></ul></ul>
! </ul></ul><blockquote> <pre>function DoStuff(a, b, c)<br> a = b*c -- does not change global and/or input number a<br> local function Calc(a)<br> return a*2<br> end<br>	<br> return Calc(a)*b*c -- or for multiple values "return a*b*c, a*b"<br>end<br>-- call function<br>a = 10<br>result = DoStuff(a, 1, 2)<br>-- can also put function into a table<br>stuff = {}<br>stuff.DoStuff = DoStuff<br>result = stuff.DoStuff(1, 2, 3)<br>print(a, result) -- "10, 72" since a is not changed</pre>
! </blockquote><h2 style="text-decoration: underline;"><a name="Bit_Library"></a>Bit
  Library</h2>
  wxLua automatically loads a library for manipulating
--- 339,349 ----
  chosen using: <span style="font-style: italic;">local
  arg3 = select(3, ...)</span> </li><ul><li>Note
! <span style="font-style: italic;">select(n, ...)</span>
! returns
  all args after <span style="font-style: italic;">n</span>,
  but if the left hand side is a single variable the others are
  discarded. See above about using <span style="font-style: italic;">select()</span>
  to pick return values of a function as well.</li></ul></ul>
! </ul></ul><blockquote> <pre>function DoStuff(a, b, c)<br> a = b*c -- does not change global and/or input number a<br> local function Calc(a)<br> return a*2<br> end<br>	<br> return Calc(a)*b*c -- or for multiple values "return a*b*c, a*b"<br>end<br>-- call function<br>a = 10<br>result = DoStuff(a, 1, 2)<br>-- can also put function into a table<br>stuff = {}<br>stuff.DoStuff = DoStuff<br>result = stuff.DoStuff(1, 2, 3)<br>print(a, result) -- "10, 72" since a is not changed</pre></blockquote><h2 style="text-decoration: underline;"><a name="Bit_Library"></a>Bit
  Library</h2>
  wxLua automatically loads a library for manipulating
***************
*** 416,420 ****
  The most common case where wxLua deviates from C++ is when
  values are passed by reference to a function to be
! changed, wxLua will return multiple values instead. Please see
  the <b><i>wxluaref.html</i></b>
  document that lists all the wxWidgets objects wrapped by wxLua and take
--- 415,419 ----
  The most common case where wxLua deviates from C++ is when
  values are passed by reference to a function to be
! changed; wxLua will return multiple values instead. Please see
  the <b><i>wxluaref.html</i></b>
  document that lists all the wxWidgets objects wrapped by wxLua and take
***************
*** 917,921 ****
  mailing list.<br>
  <br>Why are the samples named <span style="font-style: italic;">sample.wx.lua</span>?
! To allow them to be colorized correctly in syntax hi-lighting
  editors, yet denote to people that they are for wxLua and must
  be run using a wxLua exectuable or the wxLua module. <br>
--- 916,920 ----
  mailing list.<br>
  <br>Why are the samples named <span style="font-style: italic;">sample.wx.lua</span>?
! To allow them to be colorized correctly in syntax hilighting
  editors, yet denote to people that they are for wxLua and must
  be run using a wxLua exectuable or the wxLua module. <br>
***************
*** 1155,1159 ****
  Runs the program
  in the current notebook tab and outputs any print or error messages to
! the "Output" window.</li> <li><i>Stop wxLua Program</i>
  - Stops the
  currently running wxLua program. This only stops the program if Lua is
--- 1154,1160 ----
  Runs the program
  in the current notebook tab and outputs any print or error messages to
! the "Output" window. A new lua_State is created for each run and is
! accessible in the Output window until a new one is run.</li> <li><i>Stop
! wxLua Program</i>
  - Stops the
  currently running wxLua program. This only stops the program if Lua is
***************
*** 1161,1165 ****
  created a top level window the wxWidgets event system runs in the
  background and calls the wxLuaState as necessary for event handling.
! This is why Lua is considered not running even though your programing
  is "running."</li> <li><i>Stack Tree</i> -
  Show the stack of the
--- 1162,1167 ----
  created a top level window the wxWidgets event system runs in the
  background and calls the wxLuaState as necessary for event handling.
! This is why Lua is considered to be not running even though your
! programing
  is "running."</li> <li><i>Stack Tree</i> -
  Show the stack of the
***************
*** 1322,1327 ****
  two. Note that wxCharBuffer can be used as a const char* string
  directly without any casting.<br>
! <br>The core of wxLua is based upon a ref counted class called
! wxLuaState
  derived from the wxWidget's wxObject class. The wxLuaState class
  contains as a member of it's ref data the 'C' lua_State struct which is
--- 1324,1329 ----
  two. Note that wxCharBuffer can be used as a const char* string
  directly without any casting.<br>
! <br>The core of wxLua is based upon a ref counted wxLuaState
! class
  derived from the wxWidget's wxObject class. The wxLuaState class
  contains as a member of it's ref data the 'C' lua_State struct which is
***************
*** 1358,1363 ****
  looking
  at bool wxLuaState::Create(wxEvtHandler *handler, wxWindowID id) in
! <i>wxLua/modules/wxlua/src/wxlstate.cpp</i>.<br>
! <ol> <li>The
  wxObject::m_refData is created as a new wxLuaStateRefData(). This ref
  data class contains a pointer to the lua_State struct and to a shared
--- 1360,1373 ----
  looking
  at bool wxLuaState::Create(wxEvtHandler *handler, wxWindowID id) in
! <i>wxLua/modules/wxlua/src/wxlstate.cpp</i>.<br><ol>
! <li>The
! lua_State
! is created using
! lua_open() and then the standard Lua libraries are loaded, base, table,
! string,
! math, and so on using luaL_openlibs(L) as well
! as luaopen_bit(L) to open the bit library we use. </li><li>The
! function wxLuaState::Create(L, wxLUASTATE_USESTATE) is called to finish
! setting up the lua_State.</li><ol><li>The
  wxObject::m_refData is created as a new wxLuaStateRefData(). This ref
  data class contains a pointer to the lua_State struct and to a shared
***************
*** 1365,1397 ****
  this wxLuaState creates coroutines, each will
  have their own wxLuaStateRefData and associated lua_State, but they
! will all share the same wxLuaStateData class. </li> <li>The
! lua_State
! is created using
! lua_open() and then the standard Lua libraries are loaded, base, table,
! string,
! math, and so on using luaL_openlibs(L). The C lua_State is added to a
  hash table to allow
  looking up the owner wxLuaStateRefData when Lua calls the C wxLua
! binding functions with the lua_State as the only parameter. The
! wxLuaStateRefData is also pushed into the
  LUA_REGISTRYINDEX table as a lightuserdata using the
! "wxLuaStateRefData" key as a secondary means to find the wxLuaState
! "owner" of the lua_State.</li> <li>A wxLua registry is
! created in Lua's LUA_REGISTRYINDEX table with the
! "wxLuaReferences" key. Items in this table are unique integer keys used
! to identify the wxWidgets (or other) classes used as userdata
! in wxLua. It is also used to store references to data that are not to
! be
! garbage collected until the reference is released.</li> <li>We
! register a print() function for Lua to get the output of lua print()
  statements to send messages as wxLuaEvents, see
! wxEVT_LUA_PRINT. </li> <li>The bindings are
  registered by calling wxLuaState::RegisterBindings(true). </li> <ul>
! <li>Each
  binding that is loaded are copies of derived wxLuaBinding
  classes that are installed into a wxList when the
  wxLuaBinding_XXX_init() functions
  are called when the application is initialized (see above about the
! wxbind module). </li> <li>YOU MUST ALWAYS KEEP THE
  SAME BINDINGS AND KEEP THEM IN
  THE SAME ORDER THROUGHOUT THE LIFE OF YOUR WXLUASTATES. This is because
--- 1375,1413 ----
  this wxLuaState creates coroutines, each will
  have their own wxLuaStateRefData and associated lua_State, but they
! will all share the same wxLuaStateData class.</li><li>The
! wxLuaStateData constructor make a copy of the static binding list,
! wxLuaBinding::GetBindingList(), using wxLuaBinding::Clone()
! function so that the member variables of the wxLuaBindings are
! independent for each wxLuaState, however the binding data structs are
! not since they are too large to make full copies of them. The
! restriction imposed on the bindings by not copying them is that they
! have to be kept in the same order so long as any wxLuaStates exist so
! that the order of the tags (numerical references of the C++ classes)
! are maintained.</li><li>The
! C lua_State is added to a
  hash table to allow
  looking up the owner wxLuaStateRefData when Lua calls the C wxLua
! binding functions with the lua_State as the only parameter. A new
! wxLuaState with the wxLuaStateRefData set using wxObject::SetRefData(),
! which does not "ref" the data, but simply sets it, is used since we do
! not want an extra "ref". The
! same wxLuaState is pushed into the
  LUA_REGISTRYINDEX table as a lightuserdata using the
! wxlua_pushkey_wxLuaState() key as a secondary means to find the
! wxLuaState
! "owner" of the lua_State which will be used for coroutines since there
! is no way to determine when a coroutine (new lua_State) is created and
! then destroyed.</li></ol> <li>We
! register a print() function for Lua to get the output of Lua print()
  statements to send messages as wxLuaEvents, see
! wxEVT_LUA_PRINT.</li><li>The bindings are
  registered by calling wxLuaState::RegisterBindings(true). </li> <ul>
! </ul><ul><li>Each
  binding that is loaded are copies of derived wxLuaBinding
  classes that are installed into a wxList when the
  wxLuaBinding_XXX_init() functions
  are called when the application is initialized (see above about the
! wxbind module).</li></ul><ul><li>YOU
! MUST ALWAYS KEEP THE
  SAME BINDINGS AND KEEP THEM IN
  THE SAME ORDER THROUGHOUT THE LIFE OF YOUR WXLUASTATES. This is because
***************
*** 1400,1411 ****
  any previously
  created wxLuaStates will lookup classes using the wrong overwritten
! tags.</li> </ul> <li>Each binding has
! wxLuaBinding::RegisterBinding(...) called for it.</li> <ul>
! <li>wxLuaBinding::RegisterFunctions(...)
! is called </li> <li>A "namespace" table in Lua (e.g. wx)
  is
  created if necessary and a tag in the wxLuaRegistry is associated with
! it.</li> <li>wxLuaBinding::RegisterGeneratedClasses() is
! called to actually push the bindings into Lua.</li> </ul> <li>At
  the end of creation a wxLuaEvent is sent with the wxEVT_LUA_CREATION
  event type.</li>
--- 1416,1442 ----
  any previously
  created wxLuaStates will lookup classes using the wrong overwritten
! tags.</li></ul><ol><li>Hash tables are created
! in Lua's LUA_REGISTRYINDEX table to store information that is
! tied to the lua_State, but should be hidden from the Lua script code.</li><ol><li>wxlua_pushkey_wxLuaReferences(L) :
! Items in this table are unique integer tags used
! to identify the wxWidgets (or other) classes used as userdata
! in wxLua. It is also used to store references to data that are not to
! be
! garbage collected until the reference is released.</li><li>wxlua_pushkey_wxLuaClasses(L) : A
! mapping between the C++ classnames to their wxLuaBindClass
! structs stored as lightuserdata.</li><li>wxlua_pushkey_wxLuaDerivedMethods(L) :
! Stores derived methods added to a userdata object in Lua. </li></ol><li>Each
! binding has
! wxLuaBinding::RegisterBinding(...) called for it.</li><ul><li>wxLuaBinding::RegisterFunctions(...)
! is called </li><li>A "namespace" table in Lua (e.g. wx)
  is
  created if necessary and a tag in the wxLuaRegistry is associated with
! it.</li><li>wxLuaBinding::RegisterGeneratedClasses() is
! called to actually push the bindings into Lua.</li></ul><li>Once
! all of the bindings have been installed we link
! together the wxLuaBindClass::baseclass pointers.</li><li>Now
! that the base classes are found, we can link together the
! wxLuaBindMethod::basemethod pointers to allow determining which
! overloaded function to call at run-time quickly.</li> </ol><li>At
  the end of creation a wxLuaEvent is sent with the wxEVT_LUA_CREATION
  event type.</li>
***************
*** 1415,1423 ****
  that the
  wxLuaState creates and uses. There are C #defines, <i>void
! wxlua_pushkey_wxLuaReferences(L)</i> for example, to push the
! value of index to use.<br>
  <ul> <li>wxLuaReferences</li> <ul> <li>Tables
  indexed
! on the numeric "tags" that are used as metatables for the
  userdata pushed into Lua.</li> <ul> <li>The
  metatable for a class has these key value pairs</li> <ul> <li>"wxLuaBindClass"
--- 1446,1458 ----
  that the
  wxLuaState creates and uses. There are C #defines, <i>void
! wxlua_pushkey_wxLuaReferences(L)</i>
! for example, to push the
! value of index to use. The key is a light userdata, an int, because a
! pushing a string requires that it be hashed and was found to take a
! considerable amount of the total time of a function call.<br>
  <ul> <li>wxLuaReferences</li> <ul> <li>Tables
  indexed
! on the numeric "tags" generated by luaL_ref() that are used as
! metatables for the
  userdata pushed into Lua.</li> <ul> <li>The
  metatable for a class has these key value pairs</li> <ul> <li>"wxLuaBindClass"
***************
*** 1430,1434 ****
  wxluabind__tostring_wxLuaBindClass(L)</li> </ul> </ul>
  <li>Or, references to objects we want to keep a
! handle to to avoid garbage collection by Lua .</li> </ul>
  <li>wxLuaClasses</li> <ul> <li>This is a
  table t[wxLuaBindClass.name] =
--- 1465,1470 ----
  wxluabind__tostring_wxLuaBindClass(L)</li> </ul> </ul>
  <li>Or, references to objects we want to keep a
! handle to to avoid garbage collection by Lua where the index is also
! generated by luaL_ref().</li> </ul>
  <li>wxLuaClasses</li> <ul> <li>This is a
  table t[wxLuaBindClass.name] =

Thread: [Wxlua-commit] wxLua/docs wxlua.html,1.33,1.34

wxlua-commit