THE RUBY WAY, Third Edition (2015)

Chapter 12. Graphical Interfaces for Ruby

There is nothing worse than a sharp image of a fuzzy concept.

—Ansel Adams

There is no denying that we are in the age of the graphical user interface (GUI). For as far into the future as we can see, some form of graphical interface is going to be the preferred way to interact with a computer.

I don’t see the command line going away anytime soon; it definitely has its place in the world. But even the old-time hackers (who would rather use cp -R than a mouse) still enjoy a GUI when it is appropriate.

However, there are new difficulties when it comes to programming graphically. The first problem, of course, is designing a meaningful, usable “front end” for a program. In interface design, a picture is not always worth a thousand words. This book can’t address these issues; our topic here is not ergonomics, aesthetics, or psychology.

The second problem is that graphical programming is more complex. We have to worry about the sizes, shapes, locations, and behaviors of all the controls that can be displayed and manipulated with mouse, keyboard, or finger.

The third difficulty is that various computing subcultures have differing ideas of what a windowing system is and how it should be implemented. The disparity between these systems has to be experienced to be fully appreciated; many a programmer has attempted to produce a cross-platform tool only to find that the impedance mismatch between the GUIs was the hardest part to deal with.

This chapter can’t help much with these problems. The most I can do is give a gentle introduction to a few popular GUI systems (as they relate to Ruby) and offer a few hints and observations.

The bulk of this chapter is devoted to Shoes, Tk, GTK, and Qt. Whatever your background, there is a good chance you are asking, “Why wasn’t (insert name of favorite GUI) included here?”

There could be several reasons. One reason is limited space, because this book is not primarily about graphical interfaces. Another reason might be that your favorite system doesn’t have a mature set of Ruby bindings yet (in which case you are encouraged to create them). Finally, not all GUI systems are created equal. This chapter tries to cover the most mature and widely used options, and give the rest a passing mention.

12.1 Shoes 4

Shoes is a uniquely “Rubyesque” GUI system—and at present the most widely used way to create graphical programs in Ruby. Shoes provides an extremely simple and straightforward graphics API, and has been used for both teaching and building applications. It was originally created by _why the lucky stiff_ for his teaching tool Hackety Hack, and after _why disappeared, the project was adopted by Steve Klabnik.

The latest version of Shoes runs on JRuby, which is a Ruby interpreter written in Java. It allows Ruby programs to run on the Java Virtual Machine (JVM) with easy access to any Java library. Although it has not always been true, JRuby today is stable, mature, and sometimes even faster than MRI (the main Ruby interpreter).

Today, the team of volunteers working on Shoes 4 is led by Tobias Pfeiffer and Jason R. Clark. They are working to complete _why’s original vision of making it easy for children to create graphical and interactive programs using Ruby.

12.1.1 Starting Out with Shoes

Installing JRuby for Shoes is probably the hardest part of using it. You’ll need to install JRuby, following whatever instructions are appropriate for your current platform. For detailed instructions, see the JRuby website at jruby.org. Another option is to use a Ruby version manager, which is discussed in Section 21.6, “Ruby Version Managers,” of Chapter 21, “Ruby Development Tools.”

Once JRuby is installed and running, installing Shoes is just one command:

gem install shoes -v "~> 4.0.pre"

The version requirement ~> 4.0 tells Rubygems to install Shoes 4.0 or greater, but less than 5.0, whereas the .pre allows prerelease versions.

With the gem installed, Shoes programs can be run with the shoes command. To run a Shoes program saved into the file program.rb, you would run the command shoes program.rb.

The simplest possible Shoes program just creates an empty window when launched:

Shoes.app

The size of the window can be changed by passing height: and width: arguments to the app method. Elements inside the application window are created by passing a block to the app method that declares those elements. There are ten basic elements, and they can be used to create GUI programs containing buttons, text, graphics, text, forms, and links.

12.1.2 An Interactive Button

Buttons in shoes are extremely straightforward to create: Call the button method, and supply the text of the button as the first argument. If a block is passed, it will be run whenever the button is clicked. Here is a small application with a button that will display an alert when clicked:

Shoes.app(height: 30, width: 125) do
button "Declaim poem" do
alert "O freddled gruntbuggly thy micturations " \
"are to me\n As plurdled gabbleblotchits on a " \
"lurgid bee."
end
end

The alert method simply takes a string and displays it in a modal dialog box with an “OK” button. Figure 12.1 displays the application window and the alert that appears when the button is clicked.

Figure 12.1 Shoes application with alert dialog box

12.1.3 Text and Input

Text can be inserted into the window by passing a string to the para method. After the string, options can be given, including size and stroke (which changes the color of the text). Additional methods are provided as shortcuts for certain sets of options. Larger text can be inserted usingbanner, title, subtitle, and other methods, whereas styled text can be added with the em, strong, and code, among others.

By saving a reference to a text element, it becomes possible to update the contents of that element later. Here, we create a title element as well as a button that, when clicked, changes the text of that title element, as shown in Figure 12.2.

Shoes.app(height: 75, width: 225) do
@book = title "The Urby Way"
button "Correct spelling" do
@book.text = "The Ruby Way"
end
end

Figure 12.2 Styled title text in Shoes

The title element is saved as @book so that the contents of the title can be updated later, when the button is clicked. Notice that the instance variable @book is available inside both the Shoes.app block and the button block. Each block is run using instance_eval on the instance of the App class that is currently running. This provides the same set of instance variables to every block, no matter which method the block was given to.

Text input is supplied by the edit_line and edit_box methods, which create single-line and multiple-line text entry areas, respectively. If a block is given, it will be called when the field is changed and then passed the field as an argument. Here, we take any string that is entered into the field and display it in reverse, as shown in Figure 12.3.

Shoes.app do
edit_line do |line|
@name.text = line.text.reverse
end
@name = para "", margin: 10
end

Figure 12.3 Edit line with reversed text

The para containing the reversed text starts out empty (like the edit_field) but updates as each letter is typed into the field.

12.1.4 Layout

As you probably noticed in the last example (especially if you typed a lot of text into the edit_field), new elements fill up the available space left to right and then top to bottom, just like text in a paragraph. In Shoes, this kind of layout is called a flow, and the main Shoes.app block provides a flow for you. The other type of layout is called a stack. Inside a stack, each new element is added underneath the previous element.

Predictably, stacks and flows are created by passing blocks to the methods stack and flow. By combining them together, it is easy to create screens with elements laid out naturally, even with multiple columns. In this example, we create a form with columns containing text, fields, and buttons:

Shoes.app width: 500, height: 240 do
stack width: 220, margin: 10 do
caption "Name"
@name = edit_line

caption "Nation"
@nation = edit_line

caption "Home"
@home = edit_line

caption "Destination"
@destination = edit_line

button "Compose", margin_top: 10 do
@result.clear
@result.append do
caption "#{@name.text} is my name,"
caption "and #{@nation.text} is my nation."
caption "#{@home.text} is my dwelling place,"
caption "#{@destination.text} my destination."
end
end
end

@result = stack width: -220, margin: 20
end

The first stack has a fixed width of 220 pixels. The negative width on the second stack indicates that it should fill the entire width except 220 pixels. Because the main app block creates a flow, the two stacks are placed next to one another to create two columns.

Rather than use the edit_line blocks to create a live-updating result, we create a button that removes all elements (if any) from the right column and adds several text elements. Because the right column is also a stack, each element is stacked onto a new line.

The ultimate effect is one of a form on the left and text on the right, created when the button is clicked. Figure 12.4 shows what using the program might look like.

Figure 12.4 Quatrain generator

12.1.5 Images and Shapes

Shoes also provides straightforward graphical elements. Adding images to a Shoes window is as simple as calling the image method with the path to an image. The path can point to a local file or to an image hosted on the internet.

Graphics can be constructed using the basic arc, line, oval, and rect methods. Arbitrary shapes can be constructed as well, using the shape method. Colors can be set by calling stroke to set the outline color and fill to set the interior color before creating the shape. In this example, we simply draw a green oval and then a black rectangle at a 30-degree angle. The result is shown in Figure 12.5.

Shoes.app width: 250, height: 125 do
fill green
nostroke
oval top: 25, left: 125, width: 45, height: 65

rotate 30
rect top: 30, left: 30, width: 60, height: 40
end

Figure 12.5 Shapes

The stroke and fill are be cleared by nostroke and nofill, whereas the stroke thickness can be set with strokewidth. For more details about drawing and manipulating shapes, see the Shoes manual at shoesrb.com.

12.1.6 Events

We’ve already seen how clicking buttons and changing text fields can cause blocks to run. Shoes provides a few other events that can also be given blocks:

• keypress—Calls the given block with each key pushed while your app is running.

• motion—Runs when the mouse moves, and passes the left and top location of the mouse.

• hover—Runs when the mouse enters a stack or flow.

• click—Runs when the mouse clicks the element.

• release—Runs when the mouse is released after having clicked the element.

• leave—Runs when the mouse exits the stack or flow.

Note that keypress always applies to the entire Shoes app, whereas the other events apply only to the stack or flow that contains them. Using events, we can move shapes whenever someone interacts with our program:

Shoes.app do
@circle = oval top: 5, left: 5, radius: 30

motion do |left, top|
if @track
@circle.left, @circle.top = left - 15, top - 15
else
@circle.left = (width - left)
@circle.top = (height - top)
end
end

click { @track = true }
release { @track = false }
end

In this program, a circle will react to mouse movement, moving to the opposite side of the window. While the mouse is held down, however, the circle will follow the cursor exactly. A screenshot is simply unable to capture the experience, so I encourage you to try it out for yourself.

12.1.7 Other Notes

Any program written in Shoes can be packaged into a standalone executable that can be distributed and run on Windows, Mac OS X, and Linux computers. Work is ongoing on different backends, allowing Shoes to run inside Qt and GTK, which are both examined later in this chapter.

Although Shoes is not very much like other GUI toolkits, its extreme simplicity and its focus on being easy to use with Ruby make it the most popular way to create GUI Ruby applications today. For the latest news and more documentation, including a hand-drawn manual and API reference, see the Shoes website at shoesrb.com.

12.2 Ruby/Tk

The roots of Tk go back as far as 1988, if you count prerelease versions. It has a long association with the Tcl programming language, but now has bindings for many other languages, including Perl and Ruby.

In 2001, Tk was probably the most common GUI in use with Ruby. It was the first one made available and has long been part of the standard Ruby installation. Though it is not as popular as it was then, it is still in use.

Although Ruby/Tk is included in the Ruby standard library, most would say that Tk is showing its age; for those who like clean, object-oriented interfaces, it may be something of a disappointment. However, it still has the advantages of being well known, portable, and stable. The examples shown in this section will work with Ruby on Windows, Mac OS X, and Linux.

12.2.1 Overview

Any Ruby/Tk application must use require to load the tk extension. Following that, the application’s interface is built up piecemeal, starting with some kind of container and the controls that populate it. Finally, a call to Tk.mainloop is made; this method captures all the events, such as mouse movements and button presses, and acts on them accordingly.

require "tk"
# Launch the app...
Tk.mainloop

As with most or all windowing systems, Tk graphical controls are called widgets, and these widgets are typically grouped together in containers. The top-level container is called the root. Although it is not always necessary to specify an explicit root, doing so is a good idea.

Every widget class is named according to its name in the Tk world (by appending Tk to the front). Thus, the Frame widget corresponds to the TkFrame class.

Widgets are naturally instantiated using the new method. The first parameter specifies the container into which the widget is placed; if it is omitted, the root is assumed.

The options used to instantiate a widget may be specified in two ways. The first way is to pass in a hash of attributes and values. (Recall that it is a quirk of Ruby syntax that a hash passed in as the last or only parameter may have its braces omitted.)

my_widget = TkSomewidget.new(borderwidth: 2,
height: 40, justify: "center")

The other way is to pass a block to the constructor that will be evaluated with instance_eval. Within this block, we can call methods to set the attributes of the widget (using methods that are named the same as the attributes). Bear in mind that the code block is evaluated in the context of the object, not the caller. This means, for instance, that the caller’s instance variables cannot be referenced inside this block. This code will create a widget with the exact same settings as the previous example will:

my_widget = TkSomewidget.new do
borderwidth 2
height 40
justify "center"
end

Three geometry managers are available with Tk; they all serve the purpose of controlling the relative size and placement of the widgets as they appear onscreen. The first (and most commonly used) is pack; the other two are grid and place. The grid manager is sophisticated but somewhat prone to bugs; the place manager is the most simpleminded of all because it requires absolute values for the positioning of widgets. We will only use pack in our examples.

12.2.2 A Simple Windowed Application

Here, we’ll demonstrate the simplest possible application—a simple calendar app that displays the current date. For good form, we’ll begin by explicitly creating a root and placing a Label widget inside it:

require "tk"

root = TkRoot.new() { title "Today's Date" }
str = Time.now.strftime("Today is \n%B %d, %Y")
lab = TkLabel.new(root) do
text str
pack("padx" => 15, "pady" => 10,
"side" => "top")
end
Tk.mainloop

After creating the root itself, we create a string containing the date. Then, while creating the label, we set the text to be the value of str and call pack to arrange everything neatly. We tell pack to use a padding of 15 pixels horizontally and 10 pixels vertically, and we ask that the text be centered on the label.

Figure 12.6 shows what the application looks like.

Figure 12.6 A simple Tk application

As we mentioned, the creation of the label could also be done in this way:

lab = TkLabel.new(root) do
text str
pack(padx: 15, pady: 10, side: "top")
end

The units for screen measurement (as used in this example for padx and pady) are in pixels by default. We can also work in another unit by appending a suffix onto the number; the value now becomes a string, of course, but because Ruby/Tk doesn’t care about that, we don’t care either. The available units are centimeters (c), millimeters (m), inches (i), and points (p). All of these are valid padx calls:

pack(padx: "80m")
pack(padx: "8c")
pack(padx: "3i")
pack(padx: "12p")

The side attribute doesn’t actually contribute anything in this case because we have set it to its default. If you resize the application window, you will notice that the text “sticks” to the top part of the area in which it lives. Other possible values are right, left, and bottom, as you might expect.

The pack method has other options that govern the placement of widgets onscreen. We’ll look at just a few.

The fill option specifies whether a widget fills its allocation rectangle (in the horizontal and/or vertical directions). Possible values are x, y, both, and none (the default being none).

The anchor option will anchor the widget inside its allocation rectangle using a “compass point” notation; the default is center, and the other possible values are n, s, e, w, ne, nw, se, and sw.

The in option will pack the widget with respect to some container other than its parent. The default, of course, is the parent.

The before and after options can be used to change the packing order of the widgets in any way desired. This is useful because widgets may not be created in any particular order as compared to their locations onscreen.

All in all, Tk is fairly flexible about placing widgets onscreen. Search the documentation and try things out.

12.2.3 Working with Buttons

One of the most common widgets in any GUI is the pushbutton (or simply button). As you would expect, the TkButton class enables the use of buttons in Ruby/Tk applications.

In any nontrivial application, we usually create frames to contain the various widgets we’ll be placing onscreen. Button widgets can be placed in these containers.

A button will ordinarily have at least three attributes set:

• The text of the button

• The command associated with the button (to be executed when it is clicked)

• The packing of the button within its container

Here is a little example of a button:

btn_ok = TkButton.new do
text "OK"
command { puts "The user says OK." }
pack(side: "left")
end

Here we create a new button and assign the new object to the btn_OK variable; we pass in a block to the constructor, although we could use a hash if we chose. In this case, we use the multiline form (which we prefer), though in practice you can cram as much code onto a single line as you want. Recall, by the way, that the block is executed using instance_eval so that it is evaluated in the context of the object (in this case, the new TkButton object).

The text specified as a parameter to the text method will simply be placed on the button. It can be multiple words or even multiple lines.

The pack method we have already seen. It is nothing interesting, though it is essential if the widget is going to be visible at all.

The interesting part here is the command method, which takes a block and runs the block when the button is clicked.

The action we’re performing here is rather silly. When the user clicks the button, a (nongraphical) puts will be done; the output will go to the command-line window from which the program was started or perhaps an auxiliary console window.

We now offer a better example. Listing 12.1 is a fake thermostat application that will increment and decrement the displayed temperature (giving us at least the illusion that we are controlling the heating or cooling and making ourselves more comfortable). An explanation follows the code.

Listing 12.1 A Simulated Thermostat