README for wxRuby version 0.6.0 (BETA)
   Released under the wxWidgets 3 license (see LICENSE)
   This file last updated 2004-11-12


--------------------------------------------------------------------
INTRODUCTION

wxRuby is an extension library for the Ruby language that
gives access to the wxWindows 2.4.x (also known as wxWidgets)
cross-platform, native-widget, GUI toolkit. 

The wxRuby project website is:
  http://rubyforge.org/projects/wxruby/

The wxWidgets project website is:
  http://wxwidgets.org/


--------------------------------------------------------------------
REQUIREMENTS

* Ruby 1.8.x (or 1.6.5+ on some platforms)
* wxWindows 2.4.x (perhaps known as wxWidgets 2.4.x), without unicode

Primary development is under Debian GNU/Linux ("Sarge").

It seems to work quite well under MS Windows native, and can also 
be compiled with Cygwin. A Mac OS X version is also available.



--------------------------------------------------------------------
INSTALL FROM SOURCE

From the src/ directory:
	
	> ruby extconf.rb
	> make     [[[or nmake, depending on your platform]]]
	> ruby install.rb

Note that on some systems you may need to be root to do the 
install step. As an alternative, you may be able to copy 
wxruby.so to a directory that you have rights in, and include 
that directory in the Ruby library search path. Hopefully 
later we can describe that process in more detail in each 
platform-specific README that has this issue.

--------------------------------------------------------------------
CONTENTS

The src/ directory contains all the C++ source code and headers. It 
also contains .t files, which are templates that are processed by 
wxpp.rb to generate .h and .cpp files. It is similar to SWIG, but 
simpler, and specific to wxRuby.

The samples/ directory contains many sample programs that show how 
to use wxRuby. The samples are not well-organized yet, and they 
do not use a consistent coding style. But they should help you 
get started.


--------------------------------------------------------------------
DOCUMENTATION

Generally, the main wxWindows documentation will apply, with the 
following changes:

1. Classes are inside the Wx module, and class names do not 
begin with Wx. So instead of WxWindow, you would refer to 
Wx::Window.

2. Method names are all lower case, with underlines. So instead 
of calling SetWindowStyle, you would call set_window_style. 
Instead of EVT_BUTTON it is evt_button.

3. Constants are all upper case, with underlines, regardless of 
whether the original wxWindows constant was all caps or mixed 
case.

4. Constants are inside the Wx module, and do not begin with 
Wx. So instead of WXK_UP it is Wx::K_UP, instead of wxSUNKEN_BORDER 
it is Wx::SUNKEN_BORDER, instead of wxNullColour it is 
Wx::NULL_COLOUR, 


To handle an event, you use one of the evt_xxx methods, but 
instead of passing a function, you provide a block. Generally, 
it is best to simply delegate the handling to some other method, 
which may or may not want the event itself. For example:

    evt_char {|event| onChar(event)}
    evt_menu(Calendar_File_Quit) {onQuit}


--------------------------------------------------------------------
PLATFORM-SPECIFIC ISSUES

Please see the other README files for problems, suggestions, and 
other information for specific platforms:

  README.linux
  README.osx
  README.mingw
  README.mswin
  
We have not yet attempted or heard reports of attempted builds with 
other compilers (such as Borland), or other platforms.

--------------------------------------------------------------------
KNOWN PROBLEMS

* NOTE: The following classes have known problems that may cause 
  crashes if you use set_client_data and/or get_client_data: 
    Choice, ComboBox, CommandEvent, SocketEvent, EvtHandler,
    ListBox, Socket

* NOTE: The following classes have known problems that may cause 
  crashes if you use these methods:
  - Event (get_event_object)
  - ListCtrl (on_get_item_attr, on_get_item_image, on_get_item_text)
  - TreeCtrl (on_compare_items)

* Not all classes and methods have been implemented yet.

* Certain features do not manage memory correctly, and may 
crash during garbage collection. One example is ClientData 
in listboxes and choices. These will be fixed soon. 

* Many objects that get created will never be freed, so it 
is likely that any app that runs for a long time will use 
up a ton of memory.

* The samples generally work, but they are not written in 
a recommended style. Also, a few of them have a couple 
features that are not implemented or do not work correctly.

* We have almost no documentation yet.

* wxRuby is not yet compatible with unicode versions of 
wxWidgets. This will definitely be fixed as soon as is 
practical.



--------------------------------------------------------------------
CREDITS

Current maintainer: Kevin Smith
  e-mail: <wxruby@qualitycode.com> (but please send questions to the 
  wxruby mailing list, because you will get a faster answer, and 
  everyone can benefit!)
  
Original author: Park Heesob

Thanks also to other folks who have contributed in many ways to 
this project, including (in no particular order):
 Curt Hibbs, Rich Kilmer, Gergely Kontra, Nick, Gour,
 Nobuaki Arima, Roy Varghese, John Platte, Alan Chen,
 Robert P. Carlin, Gerard A.W. Vreeswijk, 
 and everyone who has posted to the mailing list or sent feedback.
 (NOTE: This list is now out of date. I will try to update it 
 in the next version to recognize several recent contributors)
--------------------------------------------------------------------
