Revision as of 07:05, 15 August 2009

Developing Ruby QT Applications using QT Designer and Ruby on Ubuntu

These instructions are tested with Ubuntu Jaunty Jackalope 9.04 . We will create a simple application to display a list of items (pieces of text) and move them up and down. Ground breaking in the extreme!

Install the appropriate packages

From a command line terminal run

sudo aptitude install libkorundum4-ruby1.8
sudo aptitude qt4-designer
sudo aptitude libqt4-ruby1.8-dev
sudo aptitude install libqt4-ruby1.8-examples
sudo aptitude install qt4-doc qt4-doc-html qt4-demos
sudo aptitude install qt-creator (you may not need this)

Create a simple Form with QT4 Designer

Create a folder on disk for your project, for example, my_first_project
Start up QT4 Designer

Select QT 4 Designer from the Applications->Programming menu or...
From a command line terminal run: designer-qt4

The default form is a Dialog with Buttons Right. Stick with that and click Create
Drag a List View from the Item Widgets (Item-Based) selection of widgets on the left onto the form. Be careful NOT to choose the List View from the Item Widgets (Model-Based)
Right-click the List View that is now dragged on the form

Select Edit Items
Click the green plus icon on the left to add an item
Enter the text: First line
Click the green plus icon on the left to add an item
Enter the text: Second line
Click OK to finish editing items

In the Property Editor on the right, scroll down to the section QAbstractItemView
Keep scrolling down a little more to the Property DragDropMode and change it's value to internal. This will let us move items up and down in the list easily
Save what we've done by selecting Save As in the File Menu

Navigate to the folder you created earlier, my_first_project
Choose the filename dashboard.ui for your file and click save
This file contains and XML representation of the form you just created

If you want to take a quick look at your form select Preview from the Form menu
But we're done with GUI stuff now! Let's get hacking...

Creating the basic application structure

Now that we've got a user interface, we need to run a command (rbuic4) that creates a Ruby class that we can use based on the interface
From the command line terminal

Navigate to the my_first_project folder you created earlier using the cd command
Run the command 'rbuic4 dashboard.ui -x -o dashboard_ui.rb'
The '-o dashboard_ui.rb' bit of the command says dump the resulting ruby code into a file called dashboard_ui.rb
The '-x' bit of the command says to create a little stub (like a main function in C/C++ or public static void main in Java) that kicks off the application. Otherwise your application would have no entry point.
We need to rerun this command every time we change the form using QT4 Designer. Usually we won't add the '-x' flag
For instant gratification run the command 'ruby dashboard_ui.rb'
Woaa!!! You should see your beautiful form before you very eyes. But when the excitement dies down, be aware that if you were to add any code to your dashboard_ui.rb file it would get blown away every time we run rbuic4 on this file to pick up the latest changes we made to the UI using QT4 Designer. But it needn't be this way...

Separating generated code from our 'real' code

In QT4, this is achieved by subclassing the dashboard_ui.rb file. Using a text editor create a new file in your my_first_project folder called dashboard.rb. The comments should explain what's going on

We pull in the file containg the class containing the generated code

require 'dashboard_ui'

We inherit from the class containing the generated code.

class Dashboard < Ui::Dialog

   # We are then free to put our own code into this class without fear
   # of it being overwritten. Here we add a setup_ui function which
   # can be used to customise how the form looks on startup

   def setup_ui(dialog)
       super
       # We'll be putting some code here real soon...
   end

end

We now need to make see how we can control the look of the form using code

Create a new file in the my_first_project folder called main.rb
Move the following code from the dashboard_ui.rb file to main.rb

if $0 == __FILE__

   a = Qt::Application.new(ARGV)
   u = Ui_Dialog.new
   w = Qt::Dialog.new
   u.setupUi(w)
   w.show
   a.exec

end

Because we have our own main file now

There is no need for the opening 'if $0 == __FILE__' line, so delete that line and it's enclosing 'end' statement
We can move the inclusion of the Qt framework (require 'Qt') from the dashboard_ui.rb file to main.rb. Actually, we have to do this because in future we will run rbuic4 without the '-x' parameter; this would mean that the autogenerated code won't contain require 'Qt' so we'd run into problems
We need to include our dashboard.rb file containing the 'real' code at the top the file

This is done using 'require 'dashboard'
You may have guessed by now that you don't need to add the '.rb' extension when including a ruby file. The Ruby interpreter is clever enough to figure out that it should look for a .rb file

We can change the line 'u = Ui_Dialog.new' to 'u = Dashboard.new' as we want to call our shiny new Dashboard class as opposed to the autogenerated class. NNB: This is the most likely place for you to go wrong. I often forget this :-)
We need to change the line 'u.setup_ui(w)' to 'u.setup_ui(w)'

The latter is more Rubyesque. If you look in the autogenerated file dashboard_ui.rb, you will that the funtion sampleUi() is wrapped by another function sample_ui()
This is just aesthetics. Syntactic sugar, but important syntactic sugar nonetheless!
If you continue to follow this article you have to make this change as we will override the setup_ui function shortly

This gives us a main.rb file that looks like

require 'Qt' require 'dashboard' a = Qt::Application.new(ARGV)

u = Dashboard.new w = Qt::Dialog.new u.setupUi(w) w.show a.exec

Note: Don't forget to remove the require 'Qt' (or it might be require 'Qt4' for you) from the top of the dashboard_ui.rb

Now currently all the code to insert the items into the Item List is controlled in the autogenerated file dashboard_ui.rb. Let's take the power back

From the the setupUi function in dashboard_ui.rb file to our own dashboard.rb file's setup_ui function, move the lines

Qt::ListWidgetItem.new(@listWidget) Qt::ListWidgetItem.new(@listWidget)

From the the retranslateUi function in dashboard_ui.rb file to a new retranslate_ui function in our own dashboard.rb file's, move the lines

@listWidget.item(0).text = Qt::Application.translate("Dialog", "First Line", nil, Qt::Application::UnicodeUTF8) @listWidget.item(1).text = Qt::Application.translate("Dialog", "Second Line", nil, Qt::Application::UnicodeUTF8)

This gives us a dashboard.rb file that looks like

We pull in the file containg the class containing the generated code

require 'dashboard_ui'

We inherit from the class containing the generated code.

class Dashboard < Ui::Dialog

   # We are then free to put our own code into this class without fear
   # of it being overwritten. Here we add a setup_ui function which
   # can be used to customise how the form looks on startup

   def setup_ui(dialog)
      super
      # We'll be putting some code here real soon...
   
      # As promised...
      Qt::ListWidgetItem.new(@listWidget)
      Qt::ListWidgetItem.new(@listWidget)
   
   end
   
   def retranslate_ui(dialog)
   
      #And also...
      @listWidget.item(0).text = Qt::Application.translate("Dialog", "First Line", nil, Qt::Application::UnicodeUTF8)
      @listWidget.item(1).text = Qt::Application.translate("Dialog", "Second Line", nil, Qt::Application::UnicodeUTF8)
   end

end