README for Ruby/Qt(ver 2.x)
August 18, 2001
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 in X window system.  I have been using Linux system for
development of this program and checking on Solaris 2.6.
From ver.0.14, support for Windows version of Qt library
(non-commercial version 2.3.0) is added.  A package of Windows version
of Ruby/Qt2 is named ruby-qt2.mswin32.x.xx.lzh and you need MS Visual
C++ v.6.0.
Ruby is a object oriented script language that is very useful for
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 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

2-1-1. Preparation for install
The environment used for developing the Ruby-Qt is :
linux 2.4.7 on i686 ( Redhat 7.1j)
and packages you need to compile the extension and run it is:
ruby-1.6.4.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.6.tar.gz

2-1-2. Install procedure
Extract files from the ruby-qt-xxx.tar.gz file after downloading in an
appropriate place.  Then make Makefile by "ruby extconf.rb
--with-qt2-dir=..." command.  You need to define QTDIR in the command
line.  Compile *.cpp files by entering "make", and install them by
entering "make install".  (You may need to be root in the last step.)

Example:

2-1-2-a. Extraction of files
$mkdir rubyqt
$cd rubyqt
$cp (hoge)/ruby-qt2-xxx.tar.gz .
$tar xvfz ruby-qt2-xxx.tar.gz
$cd qt

2-1-2-b. Make Makefile
If you install qt library in /usr/lib/qt, add --with-qt2-dir=/usr/lib/qt
When you installed Qt header files and library files to separated
place, add
--with-qt2-include=<where header files are> --with-qt2-lib=<where lib
files are>

$ruby extconf.rb --with-qt2-dir=/usr/lib/qt

2-1-2-c. Compile and install files
$make
(Please neglect warnings here  and wait for a while. (^_^))
Resulting qt.so file is very large. (~6Mb) If you don't like it, please
strip it.
$make install
(You may need to be root.)

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.)


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

Extract lzh file of Ruby/Qt2 in a appropriate directory and in a root
directory, execute
ruby extconf.rb --with-qt2-dir=<where Qt library for Windows installed>
makes make file.  Then,
'nmake' and 'nmake install' for compiling and install.


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).
 Files for the modules are under "qt2/modules" directory.
To install these modules, enter...
ruby extconf.rb --with-qt2-dir=<where Qt library installed>
make
make install
in each directory such as opengl, canvas or table.
As to usage of these modules, see the examples.

On Windows, use nmake instead of make program.

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.

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



