summaryrefslogtreecommitdiffstats
path: root/qtruby/README
diff options
context:
space:
mode:
Diffstat (limited to 'qtruby/README')
-rw-r--r--qtruby/README259
1 files changed, 259 insertions, 0 deletions
diff --git a/qtruby/README b/qtruby/README
new file mode 100644
index 00000000..22dee743
--- /dev/null
+++ b/qtruby/README
@@ -0,0 +1,259 @@
+/***************************************************************************
+ * (C) 2003 Richard Dale All rights reserved. *
+ * *
+ * This program is free software; you can redistribute it and/or modify *
+ * it under the terms of the GNU General Public License as *
+ * published by the Free Software Foundation; either version 2 of the *
+ * License, or (at your option) any later version. *
+ * *
+ ***************************************************************************/
+
+Here is a Ruby SMOKE adaptor for Qt
+
+Why ruby? From the rubytalk list
+
+On 8/28/03 8:56 PM, "Scott Thompson" wrote:
+
+>> : Can anyone give me a good reason why I would want to use Ruby over
+>> Python?
+>>
+>> Ruby smells better than Python. Also, it has cuter girls.
+>>
+>> Python sometimes tastes better if you prepare it right.
+>
+> I hadn't noticed the odor thing. It does have a faintly floral aroma
+> doesn't it.
+>
+> Of course it is no surprise that you can get more and cuter girls with
+> Rubies than you can with Pythons.
+>
+> Scott
+
+So there you have it! :)
+
+Here is 'Hello World' in QtRuby:
+
+#!/usr/bin/ruby -w
+
+require 'Qt'
+
+a = Qt::Application.new(ARGV)
+hello = Qt::PushButton.new("Hello World!", nil)
+hello.resize(100, 30)
+a.setMainWidget(hello)
+hello.show()
+a.exec()
+
+Ruby 1.8 is unfortunately implicitly required as with 1.6.x it is not possible to:
+
+ Make dynamic constants available (thus forcing syntax such as Qt.RichText rather than Qt::RichText)<br>
+ Call super in the initialize method thus making subclassing of non trivial classes impossible
+
+QtRuby features a very complete coverage of the Qt api:
+
+ - You can call all Qt public and protected methods, and all friend methods
+ such as bitBlt() etc
+
+ - Virtual methods
+ All virtual methods can be overriden, not just event handlers
+
+ - Properties
+ 'fooBar = 5' is a synonym for 'setFooBar(5)'
+
+ - Predicates
+ 'if foo?' is a synonym for 'if isFoo()' or 'if hasFoo()'
+
+ - Use underscore naming for method names instead of camel case if you
+ prefer. 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()
+
+ - Operator overloading
+ 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)
+
+ - Declare signals and slots
+ Signals and slots are declared as list of strings like this:
+
+ slots 'setColor(QColor)', 'slotLoad(const QString&)'..
+ 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 )" ) )
+
+ And emit signals like this:
+
+ emit colorChanged( black )
+
+ - Constructors
+ 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" }
+
+ - Garbage Collection
+ 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() and isDisposed() methods like this:
+
+ item2.dispose
+ if item2.isDisposed
+ puts "item2 is disposed"
+ end
+
+ - C++ 'int*' and 'int&' argument types
+ 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*' and 'bool&' argument types
+ 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
+
+ - Debugging
+ If a method call can't be matched in the Smoke library giving a 'method_missing'
+ error, you can 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)
+
+ - String 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.
+
+ - Qt Designer
+ A 'rbuic' tool is included in qtruby/rubylib/designer/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
+ a.setMainWidget(w)
+ w.show
+ a.exec
+ end
+
+ Then you can test the example code straight away:
+
+ $ ruby mainform.rb
+
+ - Loading .ui files at runtime with QWidgetFactory
+ You can load a Qt Designer .ui file at runtime with the qui extension,
+ for example:
+
+ require 'Qt'
+ require 'qui'
+
+ 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
+
+ - QtRuby shell
+ You can use the QtRuby shell in bin/rbqtsh to create widgets
+ interactively from the command line.
+
+ - API reference
+ Use the bin/rbqtapi tool to discover which methods are available in
+ the QtRuby api.
+
+ - Example programs
+ The best way to start programming QtRuby is to look at some existing
+ code and start messing with it..
+ The are various samples under qtruby/rubylib/examples.
+
+ - Optional QScintilla text editing widget support
+ Great for building your own ruby IDE..
+
+Have Fun!
+
+-- Richard