README for Ruby/Qt2(Qt v2.x)
August 17, 2001

1.これはなにか？

SWIG(http://www.swig.org/)とSWIGのRuby module(SWIG/Ruby,
http://www.goto.info.waseda.ac.jp/%7Efukusima/ruby/swig-j.html)
を利用してruby(http://www.Ruby-lang.org/ja/)のQt用拡張ライブラリーを作っ
てみました。中身は、swigrubyのexampleに含まれていたものを発展させた形に
なっています。
Ruby/Qt2は、Qt library ver.2.x に対応したものです。
開発はLinuxで行っており、Solaris
2.6でも作動を確認しています。また、Ver. 0.14よりWindows版のQt
library(non-comercial version,
2.3.0)にも対応しました。なお、Linux(unix)版とWindows版ではパッケージに含
まれるqt2_wrap.cppのみそれぞれの環境によって異なりますので、必要に合わせ
て入手してください。
(Linux版はruby-qt2-x.xx.tar.gz、Windows版はruby-qt2.mswin32.x.xx.lzhとな
っています。また、Windows版のコンパイルにはMS-Visual C++
ver.6が必要です。
Rubyはオブジェクト指向のスクリプト言語です。詳しくは上のウェブサイトを参
照
してください。
QtはTroll Tech(http://www.troll.no)のX window system
のwidgetを含むクラスライブラリーです。この拡張ライブラリーを用いると、例
えば次のようにプログラムを組むことができます。

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

2.インストールの仕方
2-1.Linuxの場合

作成した環境は以下の通りです。
linux 2.4.7 on i686 (Redhat 7.1j)

実行するには以下のものをインストールする必要があります。
ruby-1.6.4.tar.gz
qt-x11-2.3.1.tar.gz
Qtライブラリーにはhttp://www.kde.gr.jpより入手した日本語対応の
パッチを当てたものを使用しました。

なお、ソースファイルそのものの作成には
swig1.3.6.tar.gz
を用いましたが、拡張ライブラリーのコンパイルには必要ありません。

インストールは、このパッケージを適当なところで展開した後、
ruby extconf.rb --with-qt2-dir=/usr/lib/qt
(Qtライブラリーが/usr/lib/qtにインストールされている場合）
によりMakefileを作成してmake およびmake installしてください。

Qtライブラリーのインストールしてある場所を--with-qt-dir=で指定してくださ
い。
以下に詳しいインストールの手順を示します。
a.ファイルの展開

$mkdir rubyqt
$cd rubyqt
$cp (hoge)/ruby-qt2-xxx.tar.gz .
$tar xvfz ruby-qt2-xxx.tar.gz
$cd qt

b.Makefileの作成

--with-qt2-dir=以下にQtライブラリーのインストールされているディレクトリ
ーを指定してください。
(例：QTDIRが/usr/lib/qtの場合)
もし、Qtのヘッダーとライブラリーファイルが別々の所にインストールされてい
る場合は、
--with-qt2-lib=<Qtのライブラリーファイルのある場所>
--with-qt2-include=<Qtのヘッダーファイルのある場所>というように指定して
ください。

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

c.コンパイル
$make

(ワーニングがでますが、無視してください。）

d.インストール（たぶんrootになる必要があります。）

$make install

(qt2.soとqt2.rbが適切な場所、たとえば、/usr/local/lib/ruby/1.6/i586-linu
x
および/usr/local/lib/ruby/1.6などにコピーされたことを確認してください。
）

2-2. Windowsの場合

実際に使用した環境はWindows2000, MS Visual C++ v.6 rel.5です。
rubyはmswin32版を使用しました。cygwin, mingwで動くかはわかりません。

lzh形式で圧縮してあるファイルを適当なディレクトリーで展開してください。
まず、一番上のディレクトリーで、
ruby extconf.rb --with-qt2-dir=c:\qt
(Qtライブラリーがc:\qtにインストールされている場合）
によりMakefileを作成してnmake およびnmake installしてください。

Qtライブラリーのインストールしてある場所は--with-qt-dir=で指定してくださ
い。
以下に詳しいインストールの手順を示します。
a.Makefileの作成

>cd (...)qt
>ruby --with-qt2-dir=c:\qt

--with-qt2-dir=以下にQtライブラリーのインストールされているディレクトリ
ーを指定してください。
(例：QTDIRがc:\qtの場合)
c.コンパイル
>nmake

(ワーニングがでますが、無視してください。）

d.インストール（Windows2000のば場合はAdministrator権限が必要かもしれませ
ん。）

$nmake (DESTDIR=...) install

(qt2.soとqt2.rbが適切な場所、たとえば、c:\usr\local\lib\ruby\1.6\i586-li
nux
およびc:\usr\local\lib\ruby\1.6などにコピーされたことを確認してください
。
）


3.含まれているファイルそのほか
a.ディレクトリーに含まれているファイルは次の通りです。

extconf.rb...    Makefileを作るためのRuby script

moc_qrobject.cc  moc_rsignal.cc moc_rslot.cc ... Qt library
のmoc(metaobject compiler)によって作られたファイル

qrbfunction.cc qrbfunction.h qreventfilter.cc
qr2eventfilter.h　qrobject.cc　qrobject.h　
rsignal.cc rsignal.h rslot.cc qt_wrap.h
qrmovie.h qrmovie.cc etc.... Qt 拡張ライブラリー用の補助クラスなど

qt2_wrap.cc ... swigrubyにより作成したインターフェース部分を含むソース


lib/qt2.rb ... Qt拡張ライブラリーの補助関数を含むRuby script

b.Qt library の moduleについて
Qt libraryでは　openGL等に関連したクラスをmoduleとして提供しています。
通常は自動的に認識されて本体に組み込まれますが、OpenGLなどのlibraryを使
用していない場合には組み込まれません。
Ruby/Qtではmoduleとなっている部分を独立したlibraryとしてロードできるよう
にして、/modules以下のディレクトリーにまとめてあります。
それぞれのディレクトリーで
ruby extconf.rb --with-qt2-dir=/...
make
make install
としてインストールしてください。（使い方についてはそれぞれのexamples以下
の例を参照してください。）

Windowsの場合は、makeのかわりにnmake(Visual
C++のmake)を使用してください。

Windows98/Me/2000の場合、Openglに必要なライブラリーはOSに含まれています
。また、ヘッダーファイルはMS Visual C++に含まれています。

4.使い方など。
パッケージの中に、QtのtutorialおよびexampleをRuby/qtで書き直したものが含
まれていますので、参考にしてください。また、example/classbrows以下のqt2b
rows3.rbを実行するとQtモジュールに含まれるクラスと関数の一覧が表示されま
す。

* 注意点
QtをC++で使う場合との主な相違点は以下の通りです。

a.クラス名や関数名はほとんどQt-C++と同じですが、一部多重定義されているも
のについては、それぞれ別の名前を付けてあります。ただし、ver.0.13からは極
力別の名前を付けるのをやめ、Qt-C++と同じ名前の関数が使えるようにしてあり
ます。

b.C++で定義された関数のオーバーロードは基本的にできていません。ただし、R
ubyでのクラス定義のinitializeでcatchEventを実行すると、イベント関連の関
数についてはオーバーロードできるようになります。（例としては、
tutorialのt14.rbなどを見てください。）また一部のクラスでは、QRより始まる
クラスをC++で書くことにより、コールバックがかかるようにしています。(QRFi
leDialog クラスなど)
この制限は、基本的にはSWIGを用いて自動的にWrapper関数を生成しているため
です。SWIGでは、C++のクラスを含むようなコードは生成しないので、C++でのPr
otectedの関数やオーバーロードのようなクラス構造に依存するような機構は使
えません。イベント関数が使用できるのはQt
libraryの機能であるイベントフィルター関数を用いてイベントをフックしてrub
yの関数に渡しているためです。作者としてはこの部分が一番手抜かりだと思っ
ているので、将来的にはクラス構造を持つようなWrapper関数を書いて改善した
いと考えています。ただしそのためには、SWIGを用いないアプローチが必要なた
め少し大変かもしれません。因みにpythonのQt
bindingでは、SIPというpython独自のWrapper生成プログラムを用いてこの問題
を解決しているようです。

c.シグナルのコネクトは、Qt-C++でのシグナル、スロットとRubyで定義したシグ
ナル、スロット(Rubyのスロットとしては、パブリックな関数すべてを使うこと
ができます。)の間でできるようにしてあります。ただし、Qtで定義されている
ものはQSIGNAL,QSLOTで囲んで使ってください。また、Rubyでシグナルでの定義
がQtをC++で使う場合と異なります。これについては、example/signalやexample
/dclockの例を参考にしてください。


5.謝辞
RubyおよびSWIG,swigrubyの作者に感謝します。また、作成に当たり、ruby-list
が大変参考になりました。

なお、感想そのほかは以下にお願いします。
horie@smail.u-shizuoka-ken.ac.jp
また、ruby-list, ruby-extも見ておりますので、よろしくお願いします。

COPYING
see COPYING file.

QT-ruby requires the Qt library, which is copyright Troll Tech AS. Free
distributable programs may generally use At Free Edition free of
charge, see appropriate file for detail.

**************************************
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
