README for Ruby/Qt(ver 2.x) 
September 1, 2002
1. What's this?

This is a Qt extension library for Ruby (http://www.ruby-lang.org/) developed with SWIG (http://www.swig.org/) and Ruby module for SWIG (swigruby; www.goto.info.waseda.ac.jp/%7Efukusima/ruby/swig-j.html).  Qt extension library for Ruby was originally included as a example of swigruby package written by the author of swigruby.  I extended it for practical use.  I have been using Linux system for development of this program.
From ver.0.14, support for Windows version of Qt library (non-commercial version 2.3.0) is added.  
If you use non-commercial version of Qt lib., please refer to non-commercial licence in Qt web site.  
Packages for Linux are named ruby-qt2-x.xx.tar.gz or ruby-qt2-x.xx.rpm.
A package of Windows version of Ruby/Qt2 is named ruby-qt2-x.xxmswin32.lzh and you need MS Visual C++ v.6.0 for compiling (A binary package is also availabel).  
Ruby is a object oriented script language that is very useful for a variety of purpose.  Qt is a class library for C++ including many data classes and widget classes for X window system. (See http://www.troll.no) 
You can write a hello world example program with Ruby/Qt extension such like: 

--- From here ---
#!/usr/local/bin/ruby
require 'qt2'
include Qt2
a = QApplication.new([$0] + ARGV)
hello = QPushButton.new('Hello world!')
hello.resize(100, 30)
a.connect( hello, QSIGNAL('clicked()'), a, QSLOT('quit()'))
a.setMainWidget(hello)
hello.show
a.exec
---End---

2. How to install?
2-1. Install on Linux system using rpm and tar.gz

2-1-1. Preparation for install
The environment used for developing the Ruby-Qt is :
linux 2.4.18 on i686 ( Redhat 7.2)
and packages you need to compile the extension and run it is:
ruby-1.6.5.tar.gz from http://www.ruby-lang.org/
qt-x11-2.3.1.tar.gz with patches for Japanese language. (You can find them in http://www.kde.gr.jp)

I used following swing package to generate qt2_wrap.cc file from Qt interface files  but you don't need it if you want only to compile Ruby/Qt2 extension library and use it.  

swig1.3.13.tar.gz

2-1-2. rpm package
I prepared a rpm source package and binary rpm packages for some environment based on Redhat distribution.  Please, refer my home page for details.

2-1-3. tar.gz package
Extract files from the ruby-qt-xxx.tar.gz file after downloading in an appropriate place.  Then set QTDIR to the directory where Qt lib is installed.  

Use setup.rb to install Ruby/Qt.  For detail, see setup.doc.en included in the package.  The extconf.rb in each source directory assumes Qt header files and Qt library files in ($QTDIR)/include and ($QTDIR)/lib, respectedly.  If you have them in the different place, rewrite extconf.rb or  make Makefile manually in each directory as folows:
(in each directory)
ruby extconf.rb --with-qt2-lib=... --with-qt2-include=...
Example:

%ruby setup.rb config
%ruby setup.rb setup
(switch to root)
%ruby setup.rb install

Please check qt2.so and qt2.rb files are copied in appropriate places.  (qt2.so should be copied to the directory such like /usr/local/lib/ruby/1.6/ixxx-linux and qt.rb should be in the directory such like /usr/local/lib/ruby/1.6.)

You will need OpenGL library such as MESA to compile qt2gl module.
If you see some error for compiling a specific module, you can eliminate it using
%ruby setup.rb config --without=(error module)
in config stage.

2-2. Install on Windows
For compiling Ruby/Qt2 on Windows, you will need MS Visual C++ v.6.  I have used MS Visual C++ v.6 pl. 5 with mswin32 version of ruby on Japanese version of Windows2000.  

The procedure is the same as in Linux.
(Please use setup.rb for compile and install.)
Qt library name is set to qt-mt230nc.dll.  If you use commercial version of Qt lib, check extconf.rb in each source directory.

3.  Files included in the package
3-a. Files in the root directory are as follows:
extconf.rb...    Ruby script to make Makefile
moc_qrobject.cpp  moc_rsignal.cc moc_rslot.cc ... source file containing Qt meta-objects generated by moc (metaobject compiler) in Qt library package.
qrbfunction.cc qrbfunction.h qreventfilter.cpp
qr2eventfilter.hqrobject.cppqrobject.h
rsignal.cpp rsignal.h rslot.cpp qt_wrap.h
qrmovie.h qrmovie.cpp etc... source files containing supplement classes for Qt module
qt2_wrap.cpp ... source file including interface functions generated by swigruby. 
lib/qt2.rb ... ruby script for Qt module.

3-b. Modules of Qt library.
In Qt library, an extension part related such as openGL is provided as "module" library.  They are usually installed automatically if you don't add --no-<module> command to configure script when you install Qt library.  And if you don't have a library necessary to the module, the configure script will automatically omit the module.  
In Ruby/Qt (later from 0.11), classes and functions related to these modules are loaded independently from main library for Ruby/Qt(qt2.so).  The setup.rb install all modules as default.

4. How to use it.

The package included example and tutorial programs translated from C++ sources originally included in the Qt library package.  The example directory included hello2, signal, and classbrowser. The classbrowser directory included class browser for Qt module written in ruby with Ruby/Qt.  Please refer for individual classes and functions in Ruby/Qt. 

* Comments for programming

a.  Names of classes and functions are the same as Qt-C++ library.  But some overloaded functions has different names in Ruby/Qt. In version 0.13 or later, I implemented overloaded function as possible as I can.  (Some code may be incompatible between v. 0.13 and v.0.12.)

b.  General overloading for Qt+C++ function is not implemented.  But, by calling catchEvent in initialize function in a ruby script, you can overload event related functions such as repaintEvent() in the ruby script.  On usage of these event functions, please refer to t14/t14.rb in the tutorial directory.  

c.  Connection between Qt-C++ or ruby signals and slots is implemented in the current version.  A signal in ruby script is defined as a instance of RSignal class.  You can use any method in ruby as slot to connect a Qt-C++ signal or an instance of RSignal class in ruby script.  Please see example/signal or example/dclock example in the package.  
Arguments for QSIGNAL and QSLOT suported in Ruby/Qt2 is as follows:

(QListViewItem*)
(QListViewItem*,const QPoint&)
(QListBoxItem*,const QPoint &)
(QListBoxItem*)
(int,QIconViewItem*,const QPoint&)
(QIconViewItem*)
(QIconViewItem*,constQPoint&)
(QDropEvent*)
(const QColor&)
(const QRect&)
(const QSize&)
(VALUE*)
(const QString&)
(const char*)
(bool)
(double)
(int)



5.  Acknowledgment
I thank the authors of ruby, SWIG, and swigruby.  
Have fun!

COPYING
see COPYING file.



**************************************
Nobuyuki Horie, Ph.D.
Lab. Genetic Engineering/Univ. of Shizuoka
mail: horie@smail.u-shizuoka-ken.ac.jp
home page: http://www.u-shizuoka-ken.ac.jp




