Archive:Development/Languages/Ruby (zh TW)

Development/Languages/Ruby

Languages: عربي | Asturianu | Català | Česky | Kaszëbsczi | Dansk | Deutsch | English | Esperanto | Español | Eesti | فارسی | Suomi | Français | Galego | Italiano | 日本語 | 한국어 | Norwegian | Polski | Português Brasileiro | Română | Русский | Svenska | Slovenčina | Slovenščina | српски | Türkçe | Tiếng Việt | Українська | 简体中文 | 繁體中文

非常完整的綁定包括 KDE API 和 Qt API。Korundum 套件包括 QtRuby，以及完整結合 Qt/KDE。QtRuby 套件僅包含 Qt 綁定並不相依 KDE。

Korundum/QtRuby - Ruby-KDE/Qt 綁定

The book Rapid GUI Development with QtRuby (for Qt version 3.x) is available.

作為基於 Smoke 的綁定，意味著他們提供完整使用大多數 KDE 4.x 和 Qt 4.x 的類別。

QtRuby

Hello world 範例：

1. !/usr/bin/ruby -w

require 'Qt4' a = Qt::Application.new(ARGV) hello = Qt::PushButton.new("Hello World!") hello.resize(100, 30) hello.show a.exec

更'Rubyish'方式的 Hello Qt 範例：

require 'Qt4'

Qt::Application.new(ARGV) do

   Qt::Widget.new do

       self.window_title = 'Hello QtRuby v1.0'
       resize(200, 100)
   
       button = Qt::PushButton.new('Quit') do
           connect(SIGNAL :clicked) { Qt::Application.instance.quit }
       end

       label = Qt::Label.new('Hello Qt in the Ruby way!')
       
       self.layout = Qt::VBoxLayout.new do
           add_widget(label, 0, Qt::AlignCenter)
           add_widget(button, 0, Qt::AlignRight)
       end
       
       show
   end
   
   exec

end

目前 API 範圍概覽

可用呼叫

You can call all Qt public and protected methods, and all friend methods such as bitBlt() etc

虛擬方法

All virtual methods can be overridden, not just event handlers

屬性

'foobar = 5' is a synonym for 'setFooBar(5)'

Use either CamelCase or lowercase with underscore naming

Any underscores in method names are removed, and the following character is capitalised. For example, you can use either of these two forms to call the same method:

      create_standard_status_bar_action()
      createStandardStatusBarAction()

運算子重載

The full range of Qt operator methods is available, for example:

      p1 = Qt::Point.new(5,5)   => (5, 5)
      p2 = Qt::Point.new(20,20) => (20, 20)
      p1 + p2                   => (25, 25)

宣告訊號（Signals）和槽（Slots）

Signals and slots are declared as list of strings like this:

      slots 'setColor(QColor)', 'slotLoad(const QString&)'..
      signals 'clicked()'..

For slots and signals without arguments you can use Ruby symbols:

      slots :slotLoad
      signals :clicked
       

Currently C++ type signatures must be used, a future version of QtRuby will allow ruby type signatures instead.

Connect slots and signals like this:

      Qt::Object.connect( @colormenu, SIGNAL( "activated(int)" ),
                        self, SLOT( "slotColorMenu(int)" ) )

Or you can connect signal to a block:

      quit_button.connect(SIGNAL :clicked) { $qApp.quit }

And emit signals like this:

      emit colorChanged( black )

建構子

You can call constructors in the conventional style:

      quit = Qt::PushButton.new("Quit", self, "quit")

Or you can pass a block if you prefer:

      w = MyWidget.new { setCaption("foobar") }

The block will be called in the context of the newly created instance.

Ordinary arguments can be provided as well as a block at the end:

      w = MyWidget.new(nil) { setCaption("foobar") }

They are run in the context of the new instance.

And there's more! You can also pass an arg to the block, and it will be run in the context of the arg:

      w = MyWidget.new { |theWidget| theWidget.setCaption "foobar" }

垃圾回收

When a ruby instance is garbage collected, the underlying C++ instance will only be deleted if it isn't 'owned' by a parent object. Normally this will 'just work', but there are occasions when you need to delete the C++ ahead of garbage collection, and whether or not it has a parent. Use the dispose(), isDisposed() and disposed? methods like this:

      item2.dispose
      if item2.disposed?
      	puts "item2 is disposed"
      end

C++ 'int*' 和 'int&' 參數型態

Ruby passes numeric values by value, and so they can't be changed when passed to a method. The Qt::Integer class provides a mutable numeric type which does get updated when passed as an argument. For example, this C++ method 'findByFileContent()':

      # static Ptr findByFileContent( const QString &fileName, 
      #                               int *accuracy=0 );

      acc = Qt::Integer.new(0)
      fc = KDE::MimeType.findByFileContent("mimetype.rb", acc)

It supports the arithmetic operators, and so expressions such as 'acc + 3' will work.

C++ 'bool*' 和 'bool&' 參數型態

There is a similar problem for bool arg types, and the mutable Qt::Boolean class can be used like this:

      # QFont getFont(bool * ok, const QFont&initial, 
      #               QWidget* parent = 0, const char *name = 0);		
		
      ok = Qt::Boolean.new
      font = Qt::FontDialog.getFont(ok, 
                          Qt::Font.new("Helvetica [Cronyx]", 10), 
                          self)
      if !ok.nil? 
      	# font is set to the font the user selected
      else 
      	# the user canceled the dialog
      end

Use 'nil?' to test the value returned in the Boolean

C++ (const )(unsigned )char* 參數型態

In some cases Qt/KDE object "takes ownership" over Ruby String passed as char* argument type. Programmer needs to make sure that Ruby String is not being garbage collected or changed for the time it's being used by Qt/KDE object. It is also quite possible that Qt/KDE object will change and eventually free it(memory used internally by Ruby String to store its data). Be very careful when you call this kind of methods and make sure that there is no overloaded version witch accepts QString or QByteArray first!

C++ unsigned char* 函式

Very few functions (as QImage::bits()) return a uchar* to directly manipulate data. These functions are not supported in Ruby and will throw an ArgumentError. More information on the mail list.

除錯

If a method call can't be matched in the Smoke library giving a 'method_missing' error, first check that you are passing correct class instance that is properly initialized (with super method called in constructors of custom Qt classes descendants). You can also turn on debugging to trace the matching process:

      a = Qt::Application.new(ARGV)
      Qt.debug_level = Qt::DebugLevel::High
      a.loadLibrary("foo")  # Non existent method

Will give the following output:

      classname    == QApplication
      :: method == loadLibrary$
      -> methodIds == []
      candidate list:
      Possible prototypes:
          static QWidget* QApplication::widgetAt(int, int, bool)
			...

Here, the list of candidate methods 'methodIds' is empty

Another debugging mechanism allows various trace 'channels' to be switched on.

You can trace virtual method callbacks:

      Qt::Internal::setDebug(Qt::QtDebugChannel::QTDB_VIRTUAL)

Or trace QtRuby garbage collection:

      Qt::Internal::setDebug(Qt::QtDebugChannel::QTDB_GC)

字串 i18n

QtRuby supports $KCODE values of 'u', 'e' and 's' or the corresponding '-K' options from the command line. Qt Designer .ui files have UTF-8 strings so if you use any 8 bit UTF-8 characters, you will need to set $KCODE='u' or use the -Ku command line option.

Other capabilities and offerings

Qt Designer

A 'rbuic4' tool is included in qtruby/tools/rbuic to compile .ui files into ruby code. As described above, Qt Designer uses UTF-8. In addition to the options in the original uic C++ utility an '-x' flag has been added. This will generate a top level stub in the code:

      $ rbuic mainform.ui -x -o mainform.rb

Will add this to the end of the generated code:

      if $0 == __FILE__
          a = Qt::Application.new(ARGV)
          w = MainForm.new
          w.show
          a.exec
      end

Then you can test the example code straight away:

      $ ruby mainform.rb

Use the '-kde' option to require the 'korundum4' extension rather than the 'Qt4' one. If the '-x' option is used in conjunction, it generates a KDE top level. For example:

      $ rbuic4 -x -kde knotifywidgetbase.ui -o knotifywidgetbase.rb

Will generate this top level code:

      if $0 == __FILE__
      	about = KDE::AboutData.new("knotifywidgetbase", 
		                           "KNotifyWidgetBase", "0.1")
      	KDE::CmdLineArgs.init(ARGV, about)
        a = KDE::Application.new()
    	w = KNotifyWidgetBase.new
    	w.show
    	a.exec
      end

Loading .ui files at runtime with Qt::UILoader

Warning

This section needs improvements: Please help us to

cleanup confusing sections and fix sections which contain a todo

Remove example that does not work

You can load a Qt Designer .ui file at runtime with the 'quiloader' extension, for example:

      require 'Qt4'
      require 'quiloader'

      a = Qt::Application.new(ARGV)
      if ARGV.length == 0
        exit
      end

      if ARGV.length == 2
        QUI::WidgetFactory.loadImages ARGV[0]
        w = QUI::WidgetFactory.create ARGV[1]
        if w.nil?
          exit
        end
        w.show()
        a.connect(a, SIGNAL('lastWindowClosed()'), a, SLOT('quit()'))
        a.exec()
      end

With new version API changed a little.

      require 'Qt4'
      require 'qtuitools'

      a = Qt::Application.new(ARGV)
      if ARGV.length == 0
        exit
      end

      if ARGV.length == 1
        file = Qt::File.new(ARGV[1])
        file.open(Qt::File::ReadOnly)

        loader = Qt::UiLoader.new
        window = loader.load(file, nil)
        file.close

        if (window.nil?)
          print "Error. Window is nil.\n"
          exit
        end
        window.show
        a.connect(a, SIGNAL('lastWindowClosed()'), a, SLOT('quit()'))
        a.exec
      end

API 參考

Use the bin/rbqtapi tool to discover which methods are available in the QtRuby api. This command:

	  $ rbqtapi Qt::TextEdit

Will list all the methods in the Qt::TextEdit class

	  $ rbqtapi -rsetCaption 

Lists all methods whose names contain the string 'setCaption'

範例程式

The best way to start programming QtRuby is to look at some existing code and start messing with it.. The are various samples under qtrubyexamples and korundum/examples.

KDE 的特定資訊

KDE 程式不是用 require 'Qt4'，而是用 require 'korundum4'

The KDE K* classes such as KApplication are renamed as KDE::Application. The other KDE classes are in the KParts::, KIO:: or DOM:: namespaces, with the same names as their C++ counterparts.

Use the 'rbkdeapi' script to introspect the Korundum api from the command line. For example:

      $ rbkdeapi KDE::Action

Will list all the methods in the KDE::Action class. There are currently (as at KDE 3.3 beta 2) 977 classes/30841 methods in the Smoke library runtime, so the coverage of the Qt/KDE api is pretty complete.

建構依賴

• ruby 1.8 或更高版本 (svn trunk works with 1.9.1)
• cmake 2.6 或更高版本
• Qt 4.0 或更高版本
• KDE 4.1 或更高版本（korundum 需要）

教學

There is a ruby translation of Qt Tutorial #1, and the corresponding ruby code is in qtruby/rubylib/tutorial/t1 to t14.

相同的教學的Qt4版本，由 Darshan Ishaya 翻譯為 Ruby，Qt4 教學 #1

Qt Tutorial #2, a Charting Application with ruby code in qtruby/rubylib/examples/qt-examples/chart.

The Qt Designer Color Tool Tutorial, with ruby code in qtruby/rubylib/designer/examples/colortool.

Paul Lutus has written a tutorial on how to get started with Ruby GUI programming with Qt

For KDE, there is a ruby translation of this KDE 3.0 tutorial originally written for C++ by Antonio Larrosa Jiménez. The sources are in korundum/rubylib/tutorials/p1 to p9.

The book Rapid GUI Development with QtRuby is now available.

下載

您可以從 RubyForge 的QtRuby/Korundum 網站取得最新的 SVN 快照。

更多協助

在FreeNode有兩個 IRC 頻道（#qtruby and #kde-ruby）。如果你偏好電子郵件，您可以使用 kde-bindings 郵件列表（低流量），或者在 ruby-talk 郵件列表提問（您可以使用 Ruby 論壇 gateway，從網頁發表文章到 ruby-talk）。

更多資訊

ruby Qt 的系列文章（靈感來自dradis專案的工作）：

• ruby workshop: the way of the Qt samurai
• ruby Qt: model / view / controller
• ruby Qt：選單列、狀態列和資源
• ruby Qt 自定 widget 範例
• ruby Qt::TreeWidget 範例
• Very usefull link how to create your first Qt window dialog