[Wxlua-commit] wxLua/docs wxlua.html,1.13,1.14

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

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

Modified Files:
	wxlua.html 
Log Message:
add more to docs
make a copy of the initial pen to use since we'll modify it


Index: wxlua.html
===================================================================
RCS file: /cvsroot/wxlua/wxLua/docs/wxlua.html,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -d -r1.13 -r1.14
*** wxlua.html	28 Feb 2007 00:47:33 -0000	1.13
--- wxlua.html	28 Feb 2007 04:28:32 -0000	1.14
***************
*** 126,133 ****
    <ul>
  
!     <li>All variables are untyped and you can freely overwrite
  them with other values or types, there is no "const" keyword.</li>
  
!     <li>All variables are global unless you put the keyword
  "local" in front of them, this is sometimes good practice.</li>
  
--- 126,134 ----
    <ul>
  
!     <li>Variables are not permanently typed and you can freely
! overwrite
  them with other values or types, there is no "const" keyword.</li>
  
!     <li>Variables are global unless you put the keyword
  "local" in front of them, this is sometimes good practice.</li>
  
***************
*** 139,143 ****
  
      <li>Use the function <i>type(var_name)</i> to
! get the type as a string, "string", "number", "boolean", "table",
  "userdata", "function".</li>
  
--- 140,145 ----
  
      <li>Use the function <i>type(var_name)</i> to
! get the type as a string, "nil", "boolean", "number",
! "string", "table",
  "userdata", "function".</li>
  
***************
*** 149,154 ****
  
      <li><b>nil</b> : A special value meaning NULL or
! nothing, all
! variables that are not assigned a value are nil.</li>
  
      <li><b>boolean</b> : true or false, nil works as
--- 151,164 ----
  
      <li><b>nil</b> : A special value meaning NULL or
! nothing.</li>
! 
!     <ul>
! 
!       <li>Variables that are not assigned a value are nil and can
! be reset back to nil at any time.</li>
! 
!       <li>This value is often returned for functions that fail.</li>
! 
!     </ul>
  
      <li><b>boolean</b> : true or false, nil works as
***************
*** 186,191 ****
  
      <li><b>string</b> : Strings in lua can have
! embedded nulls "\0" and
! follow the same escape characters as C.</li>
  
      <ul>
--- 196,200 ----
  
      <li><b>string</b> : Strings in lua can have
! embedded nulls "\0" and use the same escape characters as C.</li>
  
      <ul>
***************
*** 234,238 ****
  
        <li><i>mytable = {}</i> a default empty table,
! must declare table
  variable before using it's indexes.</li>
  
--- 243,247 ----
  
        <li><i>mytable = {}</i> a default empty table,
! you must declare table
  variable before using it's indexes.</li>
  
***************
*** 262,266 ****
          <li>The length operator <i>#mytable</i>
  returns 2 since there are only two contiguous numeric table indexes
! starting from 1.</li>
  
        </ul>
--- 271,276 ----
          <li>The length operator <i>#mytable</i>
  returns 2 since there are only two contiguous numeric table indexes
! starting from 1 even though in this case there are actually 4 entries
! in the table.</li>
  
        </ul>
***************
*** 272,276 ****
  
          <li>See string.XXX, math.XXX, os.XXX etc in the lua
! documentation</li>
  
          <li>wxLua places the wxWidgets bindings into the wx.XXX
--- 282,286 ----
  
          <li>See string.XXX, math.XXX, os.XXX etc in the lua
! documentation.</li>
  
          <li>wxLua places the wxWidgets bindings into the wx.XXX
***************
*** 290,293 ****
--- 300,318 ----
      </ul>
  
+     <li><b>userdata</b> :</li>
+ 
+     <ul>
+ 
+       <li>This is a C/C++ pointer to an object that by itself
+ cannot be used in lua.</li>
+ 
+       <li>Through the metatable (see lua documentation) functions
+ can be attached to it to operate on it or with it.</li>
+ 
+       <li>This is the datatype that wxLua uses when you
+ create wxWidgets C++ objects.</li>
+ 
+     </ul>
+ 
      <li><b>function</b> :</li>
  
***************
*** 304,310 ****
        </ul>
  
!       <li>Can return multiple values and be passed less variables
  than specified. The unhandled returns or inputs are set to
! nil. </li>
  
        <li>Variables can be assigned to functions if desired or
--- 329,336 ----
        </ul>
  
!       <li>Can return multiple values and be passed less or more
! variables
  than specified. The unhandled returns or inputs are set to
! nil or if there are extra thrown out. </li>
  
        <li>Variables can be assigned to functions if desired or
***************
*** 325,330 ****
      <ul>
  
!       <li>Values passed to functions are local and not
! modified unless they are tables</li>
  
      </ul>
--- 351,356 ----
      <ul>
  
!       <li>Values passed to functions are local copies and not
! modified unless they are tables or userdata</li>
  
      </ul>
***************
*** 337,346 ****
  atable[#atable+1] = val end</i></li>
  
!         <li><i>mytable = {}; AppendToTable(mytable, "hello")</i>
  adds "hello" to index 1, eg. mytable[1] == "hello"</li>
  
!         <li>Note that the table is not returned, but modified
  inplace.</li>
  
        </ul>
  
--- 363,381 ----
  atable[#atable+1] = val end</i></li>
  
!         <ul>
! 
!           <li><i>mytable = {}; AppendToTable(mytable,
! "hello")</i>
  adds "hello" to index 1, eg. mytable[1] == "hello"</li>
  
!         </ul>
! 
!         <ul>
! 
!           <li>Note that the table is not returned, but modified
  inplace.</li>
  
+         </ul>
+ 
        </ul>
  
***************
*** 349,353 ****
    </ul>
  
!   <li>Operators :</li>
  
    <ul>
--- 384,388 ----
    </ul>
  
!   <li><b>Operators</b></li>
  
    <ul>
***************
*** 356,360 ****
  Note: not equal is ~= </li>
  
!     <li>Logical: and or not</li>
  
      <li>Precedence:</li>
--- 391,395 ----
  Note: not equal is ~= </li>
  
!     <li>Logical: <i>and or not</i></li>
  
      <li>Precedence:</li>
***************
*** 396,409 ****
    </ul>
  
!   <li>Keywords</li>
  
    <ul>
  
!     <li>and break do else elseif end false for function if in
! local nil not or repeat return then true until while </li>
  
    </ul>
  
!   <li>do ... end</li>
  
    <ul>
--- 431,445 ----
    </ul>
  
!   <li><b>Keywords</b></li>
  
    <ul>
  
!     <li><i>and break do else elseif end false for function
! if in
! local nil not or repeat return then true until while</i> </li>
  
    </ul>
  
!   <li><b>do ... end</b></li>
  
    <ul>
***************
*** 411,414 ****
--- 447,455 ----
      <li>Create a new local scope in a do end block.</li>
  
+     <li>Note : You cannot write <i>function
+ printHi() return; print("hi") end</i>, but you can have <i>function
+ printHi() do return end; print("hi") end</i> which can be useful
+ for debugging functions.</li>
+ 
    </ul>
  
***************
*** 422,431 ****
  <ul>
  
!   <li>if (bool) then ... elseif (bool) then ... else ... end</li>
  
  </ul>
  
  <blockquote>
!   <pre>local a, b, c -- can't assign all at once when using local keyword<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>
--- 463,473 ----
  <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>
***************
*** 439,443 ****
  
      <blockquote>
!       <pre>mycase = {}<br>mycase[1] = function() print("Hello") end<br>...<br>if mycase[value] then<br> mycase[value]()<br>else<br> print("Unknown case value")<br>end</pre>
  
      </blockquote>
--- 481,485 ----
  
      <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>
***************
*** 445,453 ****
    </ul>
  
!   <li>while (bool) ... end</li>
  
    <ul>
  
!     <li>Note : there is no continue keyword only break</li>
  
    </ul>
--- 487,496 ----
    </ul>
  
!   <li><b>while (bool) ... end</b></li>
  
    <ul>
  
!     <li>Note : there is no <i>continue</i> keyword
! only <i>break</i></li>
  
    </ul>
***************
*** 456,460 ****
  
  <blockquote>
!   <pre>function CheckA(val) if a == 5 then return true 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>
--- 499,503 ----
  
  <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>
***************
*** 462,466 ****
  <ul>
  
!   <li>repeat ... until (bool)</li>
  
    <ul>
--- 505,525 ----
  <ul>
  
!   <ul>
! 
!     <li>You can make a "fake" continue by doing this, doesn't
! print # 5.</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 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>
***************
*** 479,483 ****
  <ul>
  
!   <li>for var = init_value, end_value [, increment] do ... end</li>
  
    <ul>
--- 538,543 ----
  <ul>
  
!   <li><b>for var = init_value, end_value [, increment] do
! ... end</b></li>
  
    <ul>
***************
*** 496,500 ****
  <ul>
  
!   <li>functions</li>
  
    <ul>
--- 556,560 ----
  <ul>
  
!   <li><b>functions</b></li>
  
    <ul>
***************
*** 505,509 ****
      <li>Missing input variables are assigned the value nil</li>
  
!     <li>Return values using "return" keyword</li>
  
      <li>Not all return values need to be assigned to variables</li>
--- 565,569 ----
      <li>Missing input variables are assigned the value nil</li>
  
!     <li>Return values using the "return" keyword</li>
  
      <li>Not all return values need to be assigned to variables</li>
***************
*** 514,518 ****
  
  <blockquote>
!   <pre>function DoStuff(a, b, c)<br> a = b*c -- does not change global 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 = 21<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)</pre>
  
  </blockquote>
--- 574,578 ----
  
  <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 = 21<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(result)</pre>
  
  </blockquote>
***************
*** 651,655 ****
  
        <li>wxLua does not use the static event tables since it is
! not a compiled language. Rather the wxEvent::Connect function is used
  to connect event types to an event handler, typically a wxWindow
  derived class. Therefore you do not use EVT_XXX, but the
--- 711,716 ----
  
        <li>wxLua does not use the static event tables since it is
! not a compiled language. Rather the wxEvtHandler::Connect function is
! used
  to connect event types to an event handler, typically a wxWindow
  derived class. Therefore you do not use EVT_XXX, but the
***************
*** 1118,1122 ****
      <li>Deprecated, wxWidgets is not actively maintaining the
  docking library FL
! contrib.</li>
  
    </ul>
--- 1179,1183 ----
      <li>Deprecated, wxWidgets is not actively maintaining the
  docking library FL
! contrib and neither are we.</li>
  
    </ul>
***************
*** 1159,1163 ****
    <ul>
  
!     <li>Demonstrates how to use the printing and some wxDC
  drawing classes in wxLua.</li>
  
--- 1220,1225 ----
    <ul>
  
!     <li>Demonstrates how to use the printing architecture and
! some wxDC
  drawing classes in wxLua.</li>
  
***************
*** 1503,1508 ****
  create a wxLuaState call <i>wxLuaBinding_wx_init()</i>.
  This is because different compilers seem to have problems with the
! various techniques we've tried to automatically initialize this or
! throw out the whole library unless you explicitly use something in it.</li>
  
    </ul>
--- 1565,1572 ----
  create a wxLuaState call <i>wxLuaBinding_wx_init()</i>.
  This is because different compilers seem to have problems with the
! various techniques we've tried to automatically initialize the binding
! or
! throw out the whole library when linking unless you explicitly use
! something in it.</li>
  
    </ul>
***************
*** 1573,1577 ****
  Lua uses char strings while wxWidgets uses the wxString class which
  uses the wxChar data type. Depending on whether you have compiled
! wxWidgets in Unicode mode or not wxChar can be either w_char
  or char. Therefore, wxLua uses the functions <i>"wxString
  lua2wx(const char* str)"</i> and <i>"const wxCharBuffer
--- 1637,1641 ----
  Lua uses char strings while wxWidgets uses the wxString class which
  uses the wxChar data type. Depending on whether you have compiled
! wxWidgets in Unicode mode or not, wxChar can be either w_char
  or char. Therefore, wxLua uses the functions <i>"wxString
  lua2wx(const char* str)"</i> and <i>"const wxCharBuffer
***************
*** 1613,1619 ****
  The wxLuaState contains all of the lua 'C' functions, such as
  lua_gettop(lua_State* L), but as member functions named lua_GetTop()
! which<br>
! 
! use the internal lua_State and check for it's validity before use when
  compiled in debug mode. The functions are capitalized to make them
  easier to find in an editor. If you want the greatest performance just
--- 1677,1682 ----
  The wxLuaState contains all of the lua 'C' functions, such as
  lua_gettop(lua_State* L), but as member functions named lua_GetTop()
! which use the internal lua_State and check for it's validity before use
! when
  compiled in debug mode. The functions are capitalized to make them
  easier to find in an editor. If you want the greatest performance just