• Slides can be found here.
• Source and examples: here.

Download the fox gem. In order to compile it, you may need to download the ruby1.8-dev package:

gem install fxruby


Once this is done, open the old file where you should find something like:

require 'fox14'

#----- more stuff


You need to modify that to make it look something like:

require 'rubygems'
gem 'fxruby'
require 'fox16'

#----- more stuff


And that should make it.

Model-view-controller (MVC) is an architectural pattern used in software engineering. In complex computer applications that present a large amount of data to the user, a developer often wishes to separate data (model) and user interface (view) concerns, so that changes to the user interface will not affect data handling, and that the data can be reorganized without changing the user interface.

MVC is not only useful for web frameworks and applications, here is a simple example of the implementation of the MVC pattern for a Qt GUI application.

For this example the business data (Model) will consist of just a counter. The GUI (View) will have elements to increase and decrease this counter. Since this is a very small proof-of-concept application there is no need for a Controller component. You can have a look at the code before we start.

First the Model class:-

class Model < Qt::Object
  slots 'increase()', 'decrease()'
  signals 'modified()'
  
  attr :counter
  
  def initialize 
    super
    @counter = 0
  end
  
  def increase
    @counter += 1
    emit modified()
  end
  
  def decrease
    @counter -= 1
    emit modified()
  end
end

The Model extends Qt::Object so we can inherit the signals / slots functionality. Signals and slots will be the mechanisms used by our components to talk to each other. The class defines two slots: increase() and decrease(). If an external component wants to modify the data kept by the Model, the component will send a signal to one of these slots. In the same way, one the value of the counter is modified, the Model will emit the modified() signal.

The View class contains only two methods: the constructor and one slot. In the constructor we create the widgets of the interface and then connect the different signals and slots (more on this later). A single slot is defined in the class: counter_modified(). This slot will receive the signal sent by the Model each time the underlaying data is modified. Here is the code:-

class View < Qt::Widget
  slots 'counter_modified()'
  
  def initialize(model)
    super(nil)
    
    # keep a reference to the model
    @model = model
    
    # define widgets and layout
    grid = Qt::GridLayout.new
    @btn1 = Qt::PushButton.new('+1')
    @btn2 = Qt::PushButton.new('-1')
    @lcd = Qt::LCDNumber.new
    grid.addWidget(@btn1)
    grid.addWidget(@btn2)
    grid.addWidget(@lcd)
    self.setLayout(grid)
    
    # connect signals and slots between the Model and the View
    connect @btn1, SIGNAL('clicked()'), @model, SLOT('increase()')
    connect @btn2, SIGNAL('clicked()'), @model, SLOT('decrease()')
    connect @model, SIGNAL('modified()'), self, SLOT('counter_modified()')
  end
  

  def counter_modified
    @lcd.display(@model.counter)
  end
end

As mentioned earlier we are not using a Controller component for this example. However, the controller behaviour still exist but is included in the View class.

The Model has two slots and is able to emit a signal. We only need to bind this messages with the corresponding widgets in the user interface. The lines below connect the clicked() of the buttons with the different slots of the Model. Likewise, the modified() signal of the Model is connected to the counter_modified() slot of the View.

connect @btn1, SIGNAL('clicked()'), @model, SLOT('increase()')
connect @btn2, SIGNAL('clicked()'), @model, SLOT('decrease()')
connect @model, SIGNAL('modified()'), self, SLOT('counter_modified()')

When the Model emits the modified() signal, the View will update the value displayed in the Qt::LCDNumber widget.

More complex data models may require more complex patterns, but that is another story and shall be told another time.

#require Qt4 bindings for ruby
require 'Qt4'

class MenuWindow < Qt::MainWindow
end

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

Now that we have our main window we can start adding widgets. We begin with the menu bar and two top level menu items. We will override the default constructor of MenuWindow:

def initialize
    super

    # create the menu bar
    @menubar = Qt::MenuBar.new(self)
    @menubar.setObjectName('menubar')
    
    # create the top level menu items
    @menuFile = Qt::Menu.new(@menubar)
    @menuFile.setObjectName('menuFile')
    @menuFile.setTitle('File')
    @menuHelp = Qt::Menu.new(@menubar)
    @menuHelp.setObjectName('menuHelp')
    @menuHelp.setTitle('&Help')

    # add the top level menu items to the menu bar
    @menubar.addAction(@menuFile.menuAction())
    @menubar.addAction(@menuHelp.menuAction())

    # attach the bar to the window
    self.setMenuBar(@menubar)
  end

The only difference between these two elements is the ampersand (&) symbol in their title. For those new to GUI development and ampersand in the title of a menu will be painted as an underscore of the letter that follows. When the user presses the special combination Alt+H the Help menu will be highlighted. No special combination is associated to the File menu.

The next step is to add some actions for out menus. We are trying to have the following structure:

• File
  • Open
  • (separator)
  • Exit
• Help
  • About

Which can be accomplished by adding the following code to the constructor above:

# create menu actions
@actionOpen = Qt::Action.new(self)
@actionOpen.setObjectName('actionOpen')
@actionOpen.setText('Open')

@actionExit = Qt::Action.new(self)
@actionExit.setObjectName('actionExit')
@actionExit.setText('Exit')

@actionAbout = Qt::Action.new(self)
@actionAbout.setObjectName('actionAbout')
@actionAbout.setText('About')

# attach actions to top level menu items
@menuFile.addAction(@actionOpen)
@menuFile.addSeparator()
@menuFile.addAction(@actionExit)

@menuHelp.addAction(@actionAbout)

The results of the code can be seen in the following capture:-

There are three different properties that you may be interested in changing on a given menu action:

• The shortcut is a special combination of keys that when pressed effectively send the activated() signal of an action.
• The status bar message is the message that will be displayed in the status bar when the user hovers the pointer over the action.
• The icon that will be displayed on the left of the action’s text.

In order to show how the status bar message behaves we need to create and attach a status bar to our application. This can be done by adding the following code to the constructor of our main window:

# create and attach the status bar
@statusbar = Qt::StatusBar.new(self)
@statusbar.setObjectName('statusbar')
self.setStatusBar(@statusbar)

So now we can add a short message that will be displayed in the status bar to our actions, for example: @actionOpen.setStatusTip('Open a new file').

Almost as easy is to add a shortcut combination: @actionExit.setShortcut('Ctrl+X').

A combination of the two at work can be seen in the following capture:-

The most tricky of the three is the icon property. Resources (as images) in Qt can be loaded in three different ways:

• At run time
• By using a resource file
• Or by loading one of the built-in resources

The easiest way of adding an icon to an action is by loading the resource at run time: @actionOpen.setIcon(Qt::Icon.new('icons/fileopen.png')). This will try to load the given image from the file system at runtime.

If you do not want to distribute icons as separate files you can group them in Qt resource file. A resource file (usually with .qrc extension) is an XML file containing resource descriptions. You can see an example here:

<RCC>
    <qresource prefix="/" >
        <file>icons/help.png</file>
    </qresource>
</RCC>

This file needs to be compiled, we will cover that in a second, but provided that you have the file compiled, to use a resource of the file you just need something like this:

#require the compiled resources file
require 'resources'
[...]
  # inside the constructor
  @actionAbout.setIcon(Qt::Icon.new(':/icons/help.png'))
[...]

Notice the colon (:) before the path in the method call. A path is constructed by appending the prefix (/) to the file name of the resource (icons/help.png). Also note that before compiling the resources file you need a subdirectory called icons and a file named help.png inside it in order to produce the desired output.

In order to compile a .qrc file you will need the standard tool rbrcc whose syntax is as follows:

rbrcc resources.qrc -o resources.rb

That command will try to find all the referenced resources in the .qrc file and compile and compress them into the .rb file.
The third way to assign an icon to an action is by using one of the standard pixmaps built-in the Qt library. If you want to use one of these default resources, the code you need is the following: @actionExit.setIcon(self.style().standardIcon(PixmapCode)) where PixmapCode is defined in the QStyle class. Some of the values that can be used are listed below:

• QStyle::SP_DesktopIcon
• QStyle::SP_TrashIcon
• QStyle::SP_ComputerIcon
• QStyle::SP_TitleBarCloseButton
• QStyle::SP_FileIcon

I have left a tar file containing all the files required for this example. The three icon loading techniques shown above are used in the example. And remember that you will need to compile the .qrc file before running it.

In this case we are creating a graphical command line. The command line will consist mainly of a text input box (Qt::LineEdit). The widget will have memory, that is, every line entered by the user will be added to the internal history of the widget and will be accessible by means of Up and Down arrows as the standard *nix command line.

Here is the code:-

=begin
**
** commandline.rb
** 03/JUN/2007
** ETD-Software
**  - Daniel Martin Gomez <etd[-at-]nomejortu.com>
**
** Desc:
**   Qt custom widget that behaves as a standard command line. It keeps a 
** buffer of commands that can be accessed by pressing Up and Down keys.
**
** Version:
**  v1.0 [03/Jun/2007]: first released
**
** This file may be used under the terms of the GNU General Public
** License version 2.0 as published by the Free Software Foundation
** and appearing in the file LICENSE.GPL included in the packaging of
** this file.  Please review the following information to ensure GNU
** General Public Licensing requirements will be met:
** http://www.trolltech.com/products/qt/opensource.html
**
=end

require 'Qt4'

class CommandLine < Qt::LineEdit
  slots 'clear_history()'

  def initialize(parent=nil)
    super(parent)
    #initialize internal history buffer
    @history = []
    @pointer = 0
  end

  #override some event handlers
  def keyPressEvent(event)
    case event.key 
      when Qt::Key_Up:
        if ((@history.size > 0) && (@pointer >= 0) )
          if (@pointer == @history.size)
            @history << self.text 
          end
          @pointer -= 1 if @pointer > 0
          self.text = @history[@pointer]
        end
        return

      when Qt::Key_Down:
        if ((@history.size > 0) && (@pointer < @history.size) )
          @pointer += 1 if @pointer < @history.size - 1
          self.text = @history[@pointer]
        end
        return

      #add a new element to the local @history
      when Qt::Key_Return:

        #keep an eye on the last entry to avoid empty entries in the list
        if ((@history.size > 0) && (@history.last.strip.size == 0) )
          @history.pop
        end

        if self.text.strip.size > 0
          @history << self.text
          @pointer = @history.size
          self.clear
        else
          return
        end
    end

    super
  end


  def clear_history()
    @history.clear
  end

  def last_command()
    @history.last
  end
end

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

As you can see, out widget inherits from standard Qt LineEdit widget:-
class CommandLine < Qt::LineEdit

When instancing a copy of the widget we set up two variables to handle the internal history:-

def initialize(parent=nil)
  super(parent)
  #initialize internal history buffer
  @history = []
  @pointer = 0
end

@history array contains the list of commands typed by the user. @pointer is a pointer to the element of the list that will be displayed when Up or Down keys are pressed.

All the widget's functionality is coded in the keyPressEvent of the class. This method is called everytime the user introduces a new letter in the box. We are adding special functionality for three letters: Qt::Key_Up, Qt::Key_Down and Qt::Key_Return.

when Qt::Key_Up:
  if ((@history.size > 0) && (@pointer >= 0) )
    if (@pointer == @history.size)
      @history << self.text 
    end
    @pointer -= 1 if @pointer > 0
    self.text = @history[@pointer]
  end
  return

If the @history contains elements and the Qt::Key_Up is pressed we move the pointer to the correct place in the @history list and then replace the current text of the box. However, if the user decides to press the Up arrow in the middle of a new line, we add this new line to the @history before continuing.

when Qt::Key_Down:
  if ((@history.size > 0) && (@pointer < @history.size) )
    @pointer += 1 if @pointer < @history.size - 1
    self.text = @history[@pointer]
  end
  return

Likewise, if the Down arrow is pressed we move the @pointer down the list and replace the text.

The last case when we intercept the KeyPress event is when the user hits the Return key. The first if gets rid of the last element of the @history if it is empty. Reme,ber when we added the current line to the history in the Qt::Key_Up case? This if removes that element if it was an empty line.

when Qt::Key_Return:
  #keep an eye on the last entry to avoid empty entries in the list
  if ((@history.size > 0) && (@history.last.strip.size == 0) )
    @history.pop
  end

  if self.text.strip.size > 0
    @history << self.text
    @pointer = @history.size
    self.clear
  else
    return
  end

We then check that the current line is not empty. We add the text to the widget's history and clear the box. If the line is empty we return, so no keyPressed() signal is raised.

The script contains helper code to test it by creating a Qt application and showing the widget.

The TreeWidget can be used not only to display information hierarchically but also to add multiple columns to the data model.

We are going to use a simple example in which we will populate our TreeWidget with filesystem information.

Below is a screen capture of what we want to accomplish:-

Here is the code:-

=begin
**
** treedemo.rb
** 02/JUN/2007
** Daniel Martin Gomez
**
** Desc:
**  This script shows how to use the Qt::TreeWidget object. It populates a tree
**  using filesystem directory information. Please note that this should only
**  be used as an usage example of the widget. See Qt::DirModel for
**  implementing directory tree behaviour.
**
** Version:
**  v1.0 [02/Jun/2007]: first released
**
** This file may be used under the terms of the GNU General Public
** License version 2.0 as published by the Free Software Foundation
** and appearing in the file LICENSE.GPL included in the packaging of
** this file.  Please review the following information to ensure GNU
** General Public Licensing requirements will be met:
** http://www.trolltech.com/products/qt/opensource.html
**
=end

#require Qt4 bindings for ruby
require 'Qt4'

$DEFAULT_PATH = '/home/etd'


#populate the tree
def populate(tree, path, parent=nil)
  Dir["#{path}/*"].each do |file|
    #fill item information
    item = Qt::TreeWidgetItem.new()
    item.setText(0, File.basename(file))
    item.setText(1, File.mtime(file).strftime("%Y-%m-%d %I:%M:%S %p"))
    item.setText(2, (File.size(file).to_s + ' bytes'))
    item.setText(3, File.dirname(file) + '/')
    item.setIcon(0, Qt::Icon.new(File.ftype(file)) )

    #add item to the tree
    if (parent == nil)
      tree.addTopLevelItem(item)
    else
      parent.insertChild(parent.childCount, item)
    end

    if (File.ftype(file) == 'directory')
      populate(tree, file, item)
    end
  end
end

if $0 == __FILE__
  #parse command line
  if (ARGV.size > 0)
    path = ARGV[0]
  else
    path = $DEFAULT_PATH
  end

  app = Qt::Application.new(ARGV)
  tree = Qt::TreeWidget.new
  tree.windowTitle = "Simple Tree Example"
  
  #set view headers
  tree.setHeaderLabels(['File Name', 'Last Modified', 'Size', 'Path'])
  populate(tree,path)
  
  tree.show
  app.exec
end

Interesting bits and pieces of the code above include the import of the Qt4 library for ruby:-

require 'Qt4'

And the main Qt application execution:-

app = Qt::Application.new(ARGV)
tree = Qt::TreeWidget.new
tree.windowTitle = "Simple Tree Example"
 
#set view headers
tree.setHeaderLabels(['File Name', 'Last Modified', 'Size', 'Path'])
populate(tree,path)
  
tree.show
app.exec

Every Qt Application needs to create a Qt::Application object. In our simple example only one widget is used (the TreeWidget). Because we are calling to the widget’s default constructor it will be drawn in it’s own window. If we want to draw the widget inside a parent window, we should pass that parent window in the widget’s constructor.

We then set the headers of the table and populate the tree (see below).

By calling to tree.show we let Qt know that from now on the widget must be drawn. The last line transfers the execution control to the Qt engine.

To populate the tree we are using a recursive function. For every row we want to add to the view we create a Qt::TreeWidgetItem, populate its properties (mainly the text to be displayed in each column) and add it to the TreeWidget object. The code that handles the hierarchy is shown here:-

#add item to the tree
if (parent == nil)
  tree.addTopLevelItem(item)
else
  parent.insertChild(parent.childCount, item)
end

if (File.ftype(file) == 'directory')
  #recursively browse through the filesystem
  populate(tree, file, item)
end

Where we are using TreeWidget.addTopLevelItem or TreeWidgetItem.insertChild depending on whether we want to add a top level element or a child to a given item.

One last notice, the call:-
item.setIcon(0, Qt::Icon.new(File.ftype(file)))
Sets the icon for the item’s first column. In this version the pictures are loaded from the filesystem, so you will need to have directory.png and file.png in the execution directory.

References

• Summary of Qt4 classes
• QTreeWidget API
• QTreeWidgetItem API

This is an easy one. Although you can perform background auto change from KDE control center, it may be usefull to have a script to do the task. You can use this script to create a link in your desktop to change the background image when you want.

The KDE applications can be controlled by scripts via the DCOP mechanism. From the Wikipedia:

DCOP, which stands for Desktop COmmunication Protocol, is a light-weight interprocess and software componentry communication system. The main point of this system is to allow applications to interoperate, and to share complex tasks. Essentially, DCOP is a ‘remote control’ system, which allows an application or a script to enlist the help of other applications. It is built on top of the X Window System’s Inter-Client Exchange protocol.

Let’s begin with the script, here is the code:

#!/bin/bash
dcop kdesktop KBackgroundIface changeWallpaper

Now, you have to create a list of backgrounds using KDE’s control center. First open kcontrol, browse to Appearance & Themes > Background and select Slide Show. Click on Settings

Just create the list, and the script is ready to go.

• signature.txt: you should point your mail client to this one
• signature.tpl: here is the common text to display, something like “xmms is now playing:“
• signature.sh: the script first copies the contents of the template file to the final signature file, and then adds the current song as a new line.

Download signature.sh:

#!/bin/sh
cat /home/etd/scripts/signature.tpl > /home/etd/scripts/signature.txt
echo $1 >> /home/etd/scripts/signature.txt

you only need to call the script using the change song xmms builtin plugin.

From this page:

To refresh the backdrop with a new random image from the list just run the xfdesktop command again, e.g. from a terminal or the run dialog, or xfdesktop [-reload].

What we have to do now is to create a shell script that runs xfdesktop -reload and to add a cron job to run it.

Let’s begin with the script, here is the code:

#!/bin/bash

#check if we are under xfce
for foo in  `ps aux | grep xfdesktop | awk '{print $11}'`;
do
        if [ $foo == "xfdesktop" ];
        then
                #reload xfdesktop
                export DISPLAY=:0
                xfdesktop -reload
        fi;
done;

Now we need to add a line in the crontab, run the script every 25 minutes:
*/25 * * * * /home/etd/scripts/xfdesktop-reload

NOTE: If someone finds an easier way to check wether the user is running Xfce or not, please let me know.