Fool's Ruby and Cocoa Workshop A weblog dedicated to development with RubyCocoa and MacRuby on OS X Mon, 07 Jul 2008 18:15:06 +0000 en A Few Other RubyCocoa Tutorials Thu, 19 Jun 2008 19:17:40 +0000 K. M. Lawson A few links to some RubyCocoa tutorials I found helpful in addition to the ones you can find on this weblog:

Bowled over by RubyCocoa

This is a wonderful tutorial that both teaches you some basic GUI programming with RubyCocoa while teaching you a testing approach. I don’t recommend it for complete beginners, however.

Selectable Toolbar Icons in RubyCocoa

Create nice selectable toolbar items for your prefs window. Two part tutorial.

RubyCocoa SpeakLine example

Shows you how to create an application that speaks a line you enter. Lots of comments in the code makes this one nice. Uses an example from Hillegass book.

Your First Few Days on RubyCocoa

A lot of people have mentioned this around the net but this is over a year old and I had trouble getting things to work in my newer XCode environment.

RubyCocoa MultipleNibTabView sample

Shows you how to use views housed in separate nibs. Just provides you with some code without much explanation.

Satoshi Nakagawa’s RubyCocoa Tutorials

I recently translated these tutorials from Japanese.

A much longer list of tutorials can be found here.

MacRuby Random Number Generator Tutorial Thu, 19 Jun 2008 18:08:36 +0000 K. M. Lawson There is a very popular book out there for learning Cocoa called Cocoa® Programming for Mac® OS X, Third Edition by Aaron Hillegass. A number of people have suggested that, even if I want to program using RubyCocoa or MacRuby and don’t care much for learning the Objective-C language, you can learn a lot by going through the Hillegass book and trying to turn the examples into Ruby.

Since my own Ruby writing skills are still relatively elementary and my Objective-C reading skills are poor to say the least, I’m not very confident I’ll be able to do this for all examples I come across in that book. However, I want to pass on whatever I can do to others who may be as new to this as I am.

For this purpose I made a new MacRuby screencast tutorial for the first example of the Hillegass book called RandomApp.1 I would recommend doing the earlier MacRuby tutorial first but this tutorial repeats many of the same basic steps involving the connecting of outlets and actions.

MacRuby Random Number Generator Screencast (6.23MB 3m:50s)

Here is the completed XCode project for you to play with:

MacRuby Random Number Generator XCode Project

See also a RubyCocoa version of this Hillegass example which doesn’t need Interface Builder over at RubyCocoa resources.

UPDATE: The credits at the end make it seem like this is a RubyCocoa example, which it isn’t. This is a MacRuby example. This works for RubyCocoa as well but you need a few modifications to the code.

  1. You can find this in Chapter 2, beginning page 9.
Browser Tutorial #1: Creating a Simple Web Browser in RubyCocoa Tue, 17 Jun 2008 18:58:19 +0000 K. M. Lawson The Webkit framework has made it ridiculously easy to create a browser as part of any OS X application and there are tutorials all over the web to show how this can be done in Cocoa applications. For the basics, it doesn’t require any code at all, so it comes as no surprise that this as easy in RubyCocoa applications as in other languages.

In the first of several tutorials (only some of which will be screencasts), I will show the basics of creating an extremely simple browser and then we’ll move on to add some Ruby code and other features in later episodes.

For a more advanced XCode project to play with that incorporates more features than we will get to in these tutorials, feel free to dive into the example that comes with RubyCocoa, which is located in the /Developer/Examples/RubyCocoa/MiniBrowser folder.

RubyCocoa Webkit Tutorial #1

RubyCocoa Webkit Tutorial XCode Project

Tutorial #1 Summary

In the first screencast I will go through the following simple steps:

1. Add controls for the browser, including the WebViewer control.
2. Connect these controls to Webkit methods associated with the WebViewer
3. Fix autosizing for the address field and the WebView browser component.
4. Add the Webkit framework to the Linked Frameworks folder.
5. Activate the “New” file menu item.

UPDATE: jp_tix on #ruby-osx kindly pointed out that you don’t have to change a Custom View into a WebView in Interface Builder, but can drag a WebView directly from the Library. I didn’t notice the availability of this control. Thanks! You can find this in the library and it looks like this:

Interface BuilderScreenSnapz002.jpg

Adding a Check Updates Feature for RubyCocoa and MacRuby Tue, 17 Jun 2008 08:13:13 +0000 K. M. Lawson Do you want to have a nice “Check for Updates…” feature in your new application without having to code it yourself? The Sparkle module provides a wonderful and free way of implementing this in your application.

This tutorial is essentially a modified version of the tutorial I created for using the Sparkle updates module on my Applescript Studio weblog. The steps for getting a nice “Check Updates…” feature in your RubyCocoa application using Sparkle are pretty much the same with one small change that seems to be specific to the current version of Sparkle.

The tuturial below should technically also work for MacRuby but, unlike RubyCocoa, MacRuby requires GC (Garbage Collection). There is a GC version of Sparkle which came with the release I used but it does not appear to be functional. When it does work, you’ll be able to follow the steps below with one modification in step 2, which is noted below.

1. First download the Sparkle module from its homepage. This tutorial uses Sparkle 1.5b1 and XCode 3.1.

2. This step will differ depending on whether you are using RubyCocoa or MacRuby (0.2 as of this tutorial):

RubyCocoa: Simple drag the Sparkle.framework inside the downloaded Sparkle folder into your XCode application into the folder “Linked Frameworks” of the “Frameworks” folder.

MacRuby: You need to use the “Sparkle-with-GC.framework” version of the framework and rename this to “Sparkle.framework” (after renaming or moving the original) before continuing with the steps below. NOTE: due to a problem with the current 1.5 beta release of Sparkle, this does not work yet. Let me know if you get it working with MacRuby in a future Sparkle release and I’ll note that here.


You should now see it in your linked frameworks folder.


3. Now, from the “Project” menu of XCode, choose “New Copy Files Build Phase” from the “New Build Phase” menu item.


A new window will appear looking like this:


NOTE: Make sure this says “Frameworks” and not “Resources” in order to prevent a potential build error.

4. Now, drag the Sparkle.framework from the “Linked Frameworks” folder and drop it onto the newly created “Copy Files” build phase listed under your application in the “Targets” section of your project.


5. Now in the Info.plist file of your project in XCode, you need to add a new key. This will designate a link to the RSS file you will eventually create, called an “AppCast” which will contain the information about updates to the application. For example:


In my version of XCode, you no longer have to enter this by hand coding the xml, and instead you simply click the “+” simple on the last visible key in the plist and enter in SUFeedURL in the first field and the URL in the second field. When you are done the added key at the bottom should look something this:


6. Now switch to the “Interface Builder” application and your “MainMenu.nib” file (open it from the “Resources” folder of your XCode project if it is not open.

From the File menu choose “Read Class Files”

Interface BuilderScreenSnapz004.jpg

Navigate to your folder and you should see the Sparkle.framework folder and inside that the “Headers” folder (or actually an alias to the folder, which is deep in the “Versions” folder). Select all the files in the “Headers” folder and add them.

Interface BuilderScreenSnapz005.jpg

7. Once you have added the class header files from Sparkle, add an “NSObject” which looks like a blue box from the library panel into the list of files in your MainMenu.nib.

Interface BuilderScreenSnapz006.jpg

8. Click on this object and in the “Information” tab looking like a white “I” on a blue circle, type “SUUpdater” into the “Class” field (it should auto complete if you read the class files correctly) and press enter. This will add the required Class Actions in the panel below it.

Interface BuilderScreenSnapz007.jpg

9. Now create your “Check for Updates…” menu item in the application menu by dragging an NSMenuItem into the appropriate place. After you add it, you can change the “Title” of your menu in the inspector in the first tab.

Interface BuilderScreenSnapz008.jpg

10. Now, you need to connect this menu to the new Sparkle object you created. Control-click on the menu item and a blue line will appear. Drag this line and drop it on the “Updater” object.

Interface BuilderScreenSnapz010.jpg

11. Everything you need to do in the project is set up. However, you still need to set up an AppCast RSS file. There is a sample of one in the Sparkle documentation PDF and also you can download the test file used found in the Demo application. I created my AppCast RSS file using the RSS application Feeder which actually has a template for creating Sparkle RSS files (if you use this, consider editing the template and turning on the extra field for “Release info”). The important things that must be included in your AppCast RSS feed are a link to the Sparkle namespace:


You then add a new RSS item each time you make a new update, and include an enclosure linking to your new release, which the documentation says should be named something like “Application Name”

Here is what my RSS feed looks like after I created it with the Sparkle template in Feeder. Some of these things are optional lines or extra information added by Feeder itself, but it should give you an idea of how this works:

<?xml version="1.0" encoding="utf-8"?>
<rss xmlns:atom="" xmlns:sparkle="" version="2.0">
    <title>Sparkle Sample</title>
    <description>A simple example AppCast for Sparkle</description>
    <generator>Feeder 1.5.3(378)</generator>
    <pubDate>Fri, 30 May 2008 11:35:15 +0900</pubDate>
    <lastBuildDate>Fri, 30 May 2008 11:35:15 +0900</lastBuildDate>
    <atom:link href="" rel="self" type="application/rss+xml"/>
      <title>Version 2.0 (No useful changes, upgrade for $100)</title>
      <pubDate>Sun, 01 Jun 2008 11:24:54 +0900</pubDate>
      <enclosure url=" Sparkle" length="561575" type="application/octet-stream" sparkle:version="2.0"/>
      <guid isPermaLink="false">version-20-no-useful-changes-upgrade-for-$100</guid>

12. In addition to the RSS file (in this case rubycocoasparkle.xml), you might also want to post some release notes on the new version, which you can see in the above RSS is linked with the “sparkle:releaseNotesLink” tag. If such a file exists, Sparkle will display this file, which is regular HTML, when a new update is found.

You can try all this and play with a sample application here:

RubyCocoa Sparkle Sample Project

Building this application and running should give you a chance to see how Sparkle works, as I have posted a “fake” 2.0 update. Note that the built application is labelled as “2.0″ in the Finder if you choose “Get Info” after downloading the update.

Sparkle SampleScreenSnapz001.jpg

There was no need to enter in any ruby code anywhere in order to make this work in its most basic form. To recap the steps are roughly as follows:

1. Add the framework to your project and follow the steps in Interface Builder above (steps 1-10)
2. Create an RSS feed (in my case rubycocoasparkle.xml) to announce new releases (step 11).
3. Create an HTML file for release notes so people know what they are getting (step 12).

MacRuby Tutorial Mon, 16 Jun 2008 03:15:47 +0000 K. M. Lawson There is a nice and simple tutorial that can be found towards the end of this page at the MacRuby site. I gave it a try but also wanted to test the way that MacRuby can seamlessly convert to and from Cocoa strings without conversion.

In the following screencast I create a simple MacRuby application that first goes through the tutorial on the MacRuby site. This tutorial simply outputs a line to the console when a button is clicked. I then add two text fields and change the action of the button to take the text from the input field and output it with some added text to the output field.

MacRuby Tutorial (4 minutes and 4 seconds, 20.5MB)

My voice is a bit off so I put some simple commentary as subtitles rather than adding a voiceover.

You can also download the XCode project created by this screencast:

MacRuby Tutorial XCode Project

The only real code by the end of the screen cast is the code for the controller class, which is:

class MyController &lt; NSWindowController
  ib_outlet :button, :inputfield, :outputfield
  ib_action :clicked do  |sender|
    @outputfield.stringValue="You entered: "+@inputfield.stringValue

UPDATE: Got some recommendations from lrz including changing setStringValue to simply StringValue. May redo this screencast and also use fixed rather than moving screen. I’m still new to the screencast world. I’ll figure things out.

UPDATE: I have completely redone the screencast and added a note at the end showing an easier way of changing the string value of a text field. Instead of setStringValue, you can use stringValue= as in the code above. The original line is below:

@outputfield.setStringValue("You entered: "+@inputfield.stringValue)

UPDATE: One more error pointed out by lrz: in the added note at the end of the tutorial I used “StringValue=” instead of setStringValue but this should be “stringValue” with a small s. I have updated this in the code, the above posting, and the screencast.

Translation of Satoshi Nakagawa’s RubyCocoa Tutorials Sun, 15 Jun 2008 11:58:46 +0000 K. M. Lawson Satoshi Nakagawa, a contributor to RubyCocoa’s development and the creator of the IRC chat client LimeChat has some great resources online that can help with learning RubyCocoa. They are mostly in Japanese so there are many who won’t be able to benefit from them.

I especially liked some really clear and simple tutorials for RubyCocoa that Mr. Nakagawa has made available.

I am almost finished with a translation of these Japanese language tutorials into English. You can read the English translation of these tutorials here:

Satoshi Nakagawa’s RubyCocoa Tutorials

Thanks to Mr. Nakagawa for writing the tutorials.

UPDATE: I finished the translation this evening. Enjoy

Missing MacRuby Project Template Sun, 15 Jun 2008 09:19:10 +0000 K. M. Lawson After installing MacRuby 0.2 I tried to follow the tutorial available online. However, I discovered XCode 3.1 didn’t display the “MacRuby Application” project template the way the tutorial indicated it should.

I spoke to MacRuby developer lrz on #ruby-osx yesterday, and he was kind enough to send me an empty MacRuby project that can be used if you are unable to get the project template to work. Note that when you rename the project you need to search through and replace all the old references to the project name with your own project name. You can download this blank project here:

New MacRuby Project

Today, however, user lachie on #ruby-osx was able to find a more direct fix for this problem. If you have XCode 3.1 and have trouble finding the project template he found that all you had to do was move the “MacRuby Application” folder from here:

/Library/Application Support/Developer/3.0/Xcode/Project Templates/Application/MacRuby Application

In my case this looked like this:

to here:

/Users/YOUR_USER_NAME/Library/Application Support/Developer/Shared/Xcode/Project Templates/Application/MacRuby Application

Which in my case looked like:


And when next booted up XCode 3.1 I found the “User Templates” category which listed the new option of “MacRuby Application” looking like this:


I’ll update this posting if I hear of any better ways of doing this or find that new releases of MacRuby remove the need to do this. My warm thanks to both lrz and lachie.

New Ruby and Cocoa Google Group Sun, 15 Jun 2008 08:44:42 +0000 K. M. Lawson There is a good mailing list out there for RubyCocoa and a development mailing list for MacRuby.

In order to create an online forum for discussing development with Ruby and Cocoa I created a new Google Group where people working with MacRuby, RubyCocoa, or RubyObjC can gather to discuss Ruby and Cocoa development issues:

Ruby and Cocoa Google Group

I just created this yesterday but I hope it will turn into a useful resource for anyone working in this environment. I’m glad to see we already have on board lrz who is a developer of MacRuby, and hope it will grow to include others in the Ruby and Cocoa development world.

New Ruby and Cocoa Weblog Sun, 15 Jun 2008 08:34:07 +0000 K. M. Lawson I’m not a programmer by trade. This weblog is maintained by a student of history who likes to tinker with coding on the side for OS X and some online websites. For a few weeks I have tried to rewrite an old OS 9 project using AppleScript Studio and posted some tips and tutorials on a separate weblog dedicated to that environment. My frustrations with the applescript language, however, and my appreciation for the beauty of Ruby has led me to start over and try to learn how to combine the power of the Ruby language with the ease of GUI design in Interface Builder and the broader world of Cocoa development.

I am no expert on Cocoa, XCode, Interface Builder, Ruby, or either RubyCocoa or MacRuby so this weblog is a window into one newbie’s attempt to learn all of them. I’ll post tips I found useful, tutorials I come across and one’s I create on my own. I will also collect useful links related to RubyCocoa and MacRuby and you can find them in the blogroll located in the sidebar.

I will start off trying to learn RubyCocoa but I’m excited by the new MacRuby project which is aiming to overcome some apparent weaknesses with the former. I may eventually shift to the latter as it becomes more mature and support for it grows.

There is also another Objective-C bridge RubyObjC, by Tim Burks who now focuses on a Lisp and Ruby influenced language called Nu but I won’t be mentioning that much here.

I am also interested in welcoming others to join as contributors to this weblog if you are interested in Ruby and Cocoa development and want to make postings useful to others who are new to the topic.