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.

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.¹ 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.

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:

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:

<key>SUFeedURL</key>
<string>http://foolsworkshop.com/downloads/sparklesample.xml</string>

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”

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.

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.

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.

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.

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.

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:

xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle"

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 App_2.0.zip”

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="http://www.w3.org/2005/Atom" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
  <channel>
    <title>Sparkle Sample</title>
    <link>http://foolsworkshop.com/downloads/rubycocoasparkle.xml</link>
    <description>A simple example AppCast for Sparkle</description>
    <generator>Feeder 1.5.3(378) http://reinventedsoftware.com/feeder/</generator>
    <docs>http://blogs.law.harvard.edu/tech/rss</docs>
    <language>en</language>
    <pubDate>Fri, 30 May 2008 11:35:15 +0900</pubDate>
    <lastBuildDate>Fri, 30 May 2008 11:35:15 +0900</lastBuildDate>
    <atom:link href="http://foolsworkshop.com/downloads/rubycocoasparkle.xml" rel="self" type="application/rss+xml"/>
    <item>
      <title>Version 2.0 (No useful changes, upgrade for $100)</title>
      <pubDate>Sun, 01 Jun 2008 11:24:54 +0900</pubDate>
      <enclosure url="http://foolsworkshop.com/downloads/RubyCocoa Sparkle Tutorial_2.0.zip" length="561575" type="application/octet-stream" sparkle:version="2.0"/>
      <guid isPermaLink="false">version-20-no-useful-changes-upgrade-for-$100</guid>
      <sparkle:releaseNotesLink>http://foolsworkshop.com/downloads/sparklesample.html</sparkle:releaseNotesLink>
    </item>
  </channel>
</rss>

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.

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).

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 < NSWindowController
  ib_outlet :button, :inputfield, :outputfield
  ib_action :clicked do  |sender|
    @outputfield.stringValue="You entered: "+@inputfield.stringValue
  end
end

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.

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

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.

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.

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.