An Introduction to Desktop Apps with Ruby

by on September 29, 2010

An Introduction to Desktop Apps with Ruby

This guest post is contributed by Martin Sadler, who has over 10 years experience in the web development industry working with a range of successful high profile businesses, public sector organisations, and individuals. He is best known in the Ruby community as the creator of Working With Rails and is a keen advocate of the Ruby on Rails Framework.

Introduction

Martin Sadler In this article I’m going to show you how easy it is to create a nifty little cross-platform system tray/menu bar application using JRuby.

The application enables a user to take a screenshot of their desktop and then do something interesting with it!

"Screenshot Tray Application"

What’s covered in this article

Some of the key areas covered include:

  • Using Java Classes within Ruby
  • Refactoring
  • Blocks

Note: This tutorial assumes no prior Java knowledge and covers basic Ruby concepts only.

What is JRuby?

JRuby is a version of Ruby that runs on top of the JVM. It runs just the same as regular MRI Ruby except it’s about twice as fast and you get access to existing Java libraries.

Getting started with JRuby

It’s never been easier to try JRuby out. RVM is your friend here. Assuming you have RVM already installed it’s simply a case of doing the following inside your terminal session:

rvm install jruby

and then (where x.y.z is the version of JRuby)

rvm use jruby-x.y.z

From this point all your normal ruby commands will be using JRuby in the current terminal. Sweet.

Part 1: Taking a screenshot

Robot

Robot does for the Desktop what Selenium and other automation tools do for the browser. The main difference is that you have far more access to a users machine. You can move the mouse around, control keystrokes, manipulate other programs, and most usefully take a screenshot.

What is Robot? It’s a Java class and we going to make good use of it in our first script.

Our first JRuby script

example1.rb

#----------------------------------------------------------------
# Summary: Takes a screenshot of the desktop and saves to disk
#----------------------------------------------------------------

# this gives us direct access to Java classes in Ruby
include Java

# here we are importing Java classes, just like you might require 'yaml' or 'date'
import java.awt.Robot
import java.awt.Toolkit
import java.awt.Rectangle
import javax.imageio.ImageIO

# Taking the screenshot
# 1) Create a new instance of the Robot class
# 2) Use the Toolkit class to get the size of the screen
# 3) and pass those dimensions to the Robot instance for capture
robot     = Robot.new
toolkit   = Toolkit.get_default_toolkit
dim       = toolkit.get_screen_size
rectangle = Rectangle.new(0, 0, dim.get_width, dim.get_height)
image     = robot.create_screen_capture(rectangle)

# Save the file to disk
file = java::io::File.new('test.png')
ImageIO::write(image, "png", file)

Running the above script is a simple case of:

ruby example1.rb

The resulting screenshot gets saved to the same directory you are in as ‘test.png’. Result.

Tip: One question you might be asking by this point is how do you know what classes are available when you include Java? Java API docs have the answer.
Now, although helpful, it’s still pure Java so you’ll need to do a bit of translating to the equivalent JRuby calls. The tree view makes it easier to see how all the classes fit together.

So we’ve got a script to take a screenshot, it does the job, but we can make it better.

Refactoring into a re-usable Ruby Class

screenshot.rb

class Screenshot
  include Java

  import java.awt.Robot
  import java.awt.Toolkit
  import java.awt.Rectangle
  import javax.imageio.ImageIO

  def self.capture(filename = 'screenshot.png')
    robot     = Robot.new
    toolkit   = Toolkit.get_default_toolkit
    dim       = toolkit.get_screen_size
    rectangle = Rectangle.new(0, 0, dim.get_width, dim.get_height)
    image     = robot.create_screen_capture(rectangle)
    file  = java::io::File.new(filename)
    ImageIO::write(image, "png", file)
  end

end

now fire up a copy of irb and enter the following:

require 'screenshot'
Screenshot.capture('screenshot1.png')

By moving the code into a class method it’s much tidier and easier to use for the next part of the application.

Gotcha: File naming is really important here. The Ruby class defined in the file must be the CamelCase version of the filename for the require to work otherwise you’ll get errors like :
LoadError: use ‘java_import’ to load normal Java classes
Note, this is only the case in JRuby not regular MRI Ruby

Part 2: Creating the system tray application

Now we have a class for taking a screenshot lets create the system tray application:

example2.rb

#-----------------------------------------------------------------------------
# Summary: Runs a system tray application with ability to take a screenshot
#-----------------------------------------------------------------------------

require 'screenshot'

# Import the Java class libraries we wish to use
include Java
import java.awt.TrayIcon
import java.awt.Toolkit

# Setup our menu items
exititem        = java.awt.MenuItem.new("Exit")
screenshotitem  = java.awt.MenuItem.new("Take Screenshot...")
aboutitem       = java.awt.MenuItem.new("About")

# Event handling
exititem.add_action_listener {java.lang.System::exit(0)}
screenshotitem.add_action_listener {Screenshot.capture}

# Add the items to the popup menu itself
popup = java.awt.PopupMenu.new
popup.add(aboutitem)
popup.add(screenshotitem)
popup.add(exititem)

# Give the tray an icon and attach the popup menu to it
image    = java.awt.Toolkit::default_toolkit.get_image("screenshot.gif")
tray_icon = TrayIcon.new(image, "Screenshot!", popup)
tray_icon.image_auto_size = true

# Finally add the tray icon to the tray
tray = java.awt.SystemTray::system_tray
tray.add(tray_icon)

Before you run this script make sure you have an icon named screenshot.gif in the same directory. Short of creating one you can use Google to find an icon.

On running the application you’ll see the menu appear in your system tray. Click the screenshot menu item and the screenshot gets saved to disk!

"Screenshot Tray Application"

Refactor

The application is neat but it feels quite bulky, lets condense it down in to a much tighter API:

example3.rb

require 'tray_application'; require 'screenshot';
app = TrayApplication.new("Deskshot")
app.icon_filename = 'screenshot.png'
app.item('Take Screenshot')  {Screenshot.capture}
app.item('Exit')              {java.lang.System::exit(0)}
app.run

Not bad for an application of 6 lines! Where did all that code go?

tray_application.rb

class TrayApplication

  include Java
  import java.awt.TrayIcon
  import java.awt.Toolkit

  attr_accessor :icon_filename
  attr_accessor :menu_items

  def initialize(name = 'Tray Application')
    @menu_items = []
    @name       = name
  end

  def item(label, &block)
    item = java.awt.MenuItem.new(label)
    item.add_action_listener(block)
    @menu_items << item
  end

  def run
    popup = java.awt.PopupMenu.new
    @menu_items.each{|i| popup.add(i)}

    # Give the tray an icon and attach the popup menu to it
    image    = java.awt.Toolkit::default_toolkit.get_image(@icon_filename)
    tray_icon = TrayIcon.new(image, @name, popup)
    tray_icon.image_auto_size = true

    # Finally add the tray icon to the tray
    tray = java.awt.SystemTray::system_tray
    tray.add(tray_icon)
  end

end

A similar pattern of refactoring was carried out here as per the Screenshot class.

Probably the most interesting point is the way you can use Ruby to capture a block of code. In the case of the Screenshot application there are certain actions we only want to be executed when the user clicks a menu item. You can see these as code surrounded by curly braces. Alternatively they could have been written as follows:

app.item('Take Screenshot') do
  Screenshot.capture
end

Which does more or less the same job. Usually the do/end format is preferred for multi-line code blocks.

What is handy for us is that we can capture these code blocks using the &block parameter in the method definition. This makes the block available as a local variable inside the method and it can be simply pushed onto an array (@menu_items) for later recall.

Curious as to how a block is executed once stored? Here is a simple example:

def hello(&block)
  block.call # execute the contents of the hello block using call
end

hello do
  p "hello there"
end

Tip: Always try to keep your code tidy as you go along. Look for patterns and bake them into classes if need be. Think about how the end product will look like and work out how to get there. See also: Readme Driven Development.

Part 4: One further improvement

So now we have a tray application that takes a screenshot and saves to disk. How about we get it to open in an image browser too. No problem.

Lets make a small addition by making use of the Desktop Java Class.

screenshot.rb (revisited)

class Screenshot
  include Java

  import java.awt.Desktop # added Desktop to import
  import java.awt.Robot
  import java.awt.Toolkit
  import java.awt.Rectangle
  import javax.imageio.ImageIO

  def self.capture(filename = 'screenshot.png')
    robot     = Robot.new
    toolkit   = Toolkit.get_default_toolkit
    dim       = toolkit.get_screen_size
    rectangle = Rectangle.new(0, 0, dim.get_width, dim.get_height)
    image     = robot.create_screen_capture(rectangle)

    file  = java::io::File.new(filename)
    ImageIO::write(image, "png", file)

    # Open the file in the users default application for the given file type
    desktop = Desktop.get_desktop
    desktop.open(file)
   end
  end

end

So now when you click ‘Take Screenshot..’ up pops Preview (on Mac) with your Desktop image.

Beyond the screenshot

So we have put together the foundations of a screenshot tray application and in the process built a skeleton GUI JRuby framework. So where could we go from here?

  • Send the screenshot to a web service

    This would make for a handy utility for a support web app. Take the file and post it via http to your app for processing.

  • Add an About Box

    Sadly the amount of code to show this here would have detracted from the main article. However it is still pretty straight forward. JFrame is your friend.

  • HotKey for taking the screenshot

  • Package! Rawr. Distribute

    So currently you’ll need JRuby in order to run this application. One of the main benefits of JRuby is it compiles down to Java bytecode and will run on any Java enabled platform. Mac, Windows, and Unix support in one go!

  • Variations on the theme

    Why stop at screenshots? Here are few more ideas:

    • Drag and drop copy and upload of files to a web service
    • A notification service e.g. new support messages, tweets
    • System analytics tool
    • Copy and Paste share bin

Reference

Attribution

In Summary

I hope you found this article valuable and that it gives you an insight into the world of possibilities with JRuby and desktop applications. Feel free to ask questions and give feedback in the comments section of this post. Thanks!

Do read these awesome Guest Posts:

Technorati Tags: , , , , ,

Posted by Martin Sadler

Follow me on Twitter to communicate and stay connected

{ 12 comments… read them below or add one }

Rick September 29, 2010 at 6:52 am

This is an awesome tutorial! There should be more articles on building native desktop apps using Java (for cross platform) or MacRuby (for apple).

Reply

Martin Sadler September 29, 2010 at 12:31 pm

@rick thanks, glad you like it.

Other related resources you might also want to check out:

* Ruby Koans http://github.com/edgecase/ruby_koans – now also includes a JRuby section.
* Redcar Editor http://redcareditor.com/ – made entirely using JRuby.
* JRuby Conf http://jrubyconf.com/ – at the start of Oct, hopefully lots of great material will follow.

Reply

drew September 29, 2010 at 9:44 pm

Great writeup, thanks for this. I never knew about rawr before and it strikes me as totally awesome!

Reply

Luiz September 29, 2010 at 11:32 pm

a long time ago, i saw jruby with swt. can you provide some like that?

Reply

Martin Sadler September 30, 2010 at 12:56 pm

Sure, Dan Lucraft, creator of Redcar has published an example on GitHub: http://github.com/danlucraft/jruby-swt-cookbook

Reply

Jared Miller September 30, 2010 at 8:58 am

Hey Martin, thanks for the awesome guide. Curious, though, to run the ruby script I have to run it as:

jruby example1.rb

Is there some reason I can’t run it as ruby example1.rb, as you do in your tutorial, or was that a typo?

Reply

Martin Sadler September 30, 2010 at 12:47 pm

Hi Jared,

If you are using RVM it creates a ‘ruby’ symlink to jruby (see ~/.rvm/rubies/jruby-1.5.2/). I’m guessing in your case you installed JRuby by itself which won’t have created the symlink.

Martin.

Reply

roger September 30, 2010 at 9:53 pm

I too have enjoyed using jruby for its GUI attributes recently (redcar, desktop apps).

A few points to clarify.
1) jruby is twice as fast as MRI 1.8, but not twice as fast as 1.9.2 [1]
2) I don’t think that “gotcha” is accurate…it seems to work fine for me without having a fixed naming convention.

Also it might be nice to have a “full fledged” implementation somewhere, like github (with an about box).

Cheers!
-r
[1] http://programmingzen.com/2010/07/19/the-great-ruby-shootout-july-2010/

Reply

Martin Sadler September 30, 2010 at 11:07 pm

Hi Roger,

Thanks for your comments.

Good point about Ruby MRI 1.9.2, significant speed improvements have been made and shouldn’t be ignored as more developers move over from 1.8.7.

In regards to the ‘gotcha’ it was certainly an error I experienced when originally putting together this tutorial. If it’s no longer the case then that’s great.

Martin.

Reply

John January 5, 2011 at 9:16 pm

Hey Martin,

I am having a great time with JRuby and your listings just added to that.

But I cannot seem to get the last part with the preview to work on windows.

Also, I like using swing but I fear that not knowing java is hurting me, I have a hard time translating the java api to what ruby will work with. And I have an even harder finding anyone who KNOWs or is willing to help.

Most say just look at the javadocs, which I do. But if your coming from non-ruby, non-java background it makes it interesting.

Great article, please write more. I would be an avid fan.

John

Reply

Leo Gallucci July 3, 2013 at 12:36 am

There’s seem to be an extra `end`, just remove that if you are getting a

SyntaxError: G:/lnk/testcode/tray_app/screenshot_and_open.rb:26: syntax error, unexpected kEND

Works for me on:
- Windows 8 x64
- JRE build 1.7.0_25-b16
- JRuby 1.7.4 (1.9.3p392) 2013-05-16

Reply

ragu September 28, 2012 at 1:58 pm

Enjoyed this article. In fact, this gives me confidence that I don’t have to learn Python for developing GTK applications which I intend to port later to windows/mac. This article uses `awt`. It would be great if there is a `swt` version of this article.

I particularly liked the approach of presentation. You showed a naive implementation and refactored it into more object oriented and in ruby style. Nice!

Reply

Leave a Comment

{ 80 trackbacks }

Previous post:

Next post: