RubyCocoa Resources: Recent Changes

Michael Black: Put it to work

Mon, 25 Feb 2008 11:32:16 GMT

Our code-to-talk ratio has gotten dangerously low. Let’s fix that by putting our Apple Remote controller to work. Put the source from the previous two parts of this chapter into a Ruby file called “remote.rb”, start irb from the Terminal, and type the commands in the transcript below:

>> require 'remote'
=> true
>> d = AppleRemoteDelegate.alloc.init
=> #<AppleRemoteDelegate:0x3691e2 class='AppleRemoteDelegate' id=0x5734a0>
>> a = OSX::AppleRemote.alloc.initWithDelegate_(d)
=> #<OSX::AppleRemote:0x367c52 class='AppleRemote' id=0x5773c0>
>> a.startListening 0
=> nil
>> OSX::NSApplication.sharedApplication.run

Next, start pressing buttons on your remote. You should see something like the following listing. You can easily use this to find the codes for each button, or if you prefer, go back to Martin’s RemoteControl.h and look at the _RemoteControlEventIdentifier enum.

button 2, pressed 1
button 2, pressed 0
button 2, pressed 1
button 2, pressed 0
button 4, pressed 1
button 4, pressed 0
button 32, pressed 1
button 32, pressed 0

That’s it! There’s obviously some complicated stuff happening under the covers of the RubyCocoa bridge, and there’s probably also some ways it can be improved. But with the right understanding and incantations, the bridge works right now and can be used to do some dramatic things very quickly. Consider how much more difficult this would have been if Martin’s package was written in C or C++. We would have needed to either write the Ruby wrapper ourselves or use a tool like SWIG to generate wrapper glue code. With Objective-C and RubyCocoa, we were able to use Martin’s package with no glue code and no compilation. Everything we needed to do was done at runtime. Amazing?

Michael Black: Write a delegate

Mon, 25 Feb 2008 11:27:06 GMT

Next we need to write a delegate class. Here’s a simple one to get you started.

Provide a delegate [ruby]

class AppleRemoteDelegate < OSX::NSObject

addRubyMethod_withType('sendRemoteButtonEvent:pressedDown:remoteControl:', 'v@:ii@')  

  def sendRemoteButtonEvent_pressedDown_remoteControl(buttonIdentifier, pressedDown, remoteControl)
    puts "button #{buttonIdentifier}, pressed #{pressedDown}"
  end

end

Our delegate has one method of interest, sendRemoteButtonEvent_pressedDown_remoteControl, which simply prints the values passed to it by the controller. It’s preceeded by an interesting statement, the addRubyMethod_withType call. The purpose of this statement is to give the Objective-C runtime the correct signature to use for our delegate method. Its two arguments are the selector name (a string), and a string containing the encoded signature. In this case, the signature is six characters long. The first character indicates that the return value of the method is void. The next two are superfluous to us, but important to the Objective-C runtime. The ’@’ means that the message is to be sent to an object of Objective-C type id, and the ’:’ indicates that the message is described by a special Objective-C type called a selector. These two values are the same for all Cocoa messages. The next three characters give the types of the three arguments to the method, in this case they are two integers and an id type.

You can find a full listing of type codes on Apple’s Developer Connection web site. Look here.

But why, you may ask, did we need to go to this trouble? The answer to that is a bit complex. If you’d rather not get into it, just skip to the next section, but remember to look back here if you ever write Ruby code that gets called by Objective-C code that is not part of Cocoa.

Martin’s controller is written in Objective-C and uses the Objective-C runtime environment to send messages to its delegate. When the Objective-C runtime sends a message to an object, it does so with a low-level function that looks for a handler in the method table of the receiving object’s class. When the receiving object is an Objective-C wrapper for a RubyCocoa object, normally there’s no corresponding handler in its method table (with one exception to be explained later). When no handler is present, that low-level message sending function tries to package the message into an NSInvocation object which it resends to the target object with the forwardInvocation method. Then the target can pass the message along to an object capable of responding to it. In the case of RubyCocoa, this NSInvocation gets handled by bridge code that makes a corresponding Ruby method call, converts the Ruby return value into the appropriate Objective-C type, and returns control to the message sender. But for the sender to be able to construct the invocation, a special message must first be sent to the Objective-C wrapper object. This message is called methodSignatureForSelector: and its purpose is to provide the signature for the message to be sent.

In RubyCocoa, there’s a methodSignatureForSelector defined for Objective-C wrapper objects, but it only knows about selectors associated with Cocoa classes—the RubyCocoa build process extracts them from Cocoa headers and hard-codes them into the RubyCocoa source files. (If you’d like to see them for yourself, look at framework/src/objc/DummyProtocolHandler.m in the RubyCocoa source distribution.)

Martin’s controller uses a protocol that is unknown to the RubyCocoa bridge. So when RubyCocoa’s methodSignatureForSelector gets called, it returns a default signature that assumes that all arguments and the return value are of type id (Objective-C objects). One desperate way to fix this problem is to explicitly add the protocol to DummyProtocolHandler.m and rebuild the RubyCocoa sources, but in most cases, the addRubyMethod_withType makes that unnecessary.

The addRubyMethod_withType method doesn’t do anything to change methodSignatureForSelector. Instead, it resolves the problem by adding a message handler with the specified signature directly to the Objective-C wrapper class (there’s a unique Objective-C wrapper class for each wrapped Ruby class). When it is used to set the correct signature, messages are sent and handled correctly. If it is used incorrectly or omitted, all kinds of havoc will follow.

Whew. That’s a lot of writing to explain one line of code. But without that line, the invocation would be sent with the wrong signature and our program would behave mysteriously—and possibly crash.

Earlier in this section I wrote that there’s an exception to the general rule that bridged method calls are handled by invocations. We actually just saw one exception, when we used addRubyMethod_withType to put an entry into the wrapper class’s method table. But the exception I was indicating is ns_overrides, the mysterious function that must be called when any Objective-C method is overridden in a RubyCocoa class. It is necessary because when messages are sent to RubyCocoa’s Objective-C wrapper objects, any message handler defined on a superclass will handle the message and prevent it from being wrapped in an NSInvocation and sent to the RubyCocoa class. ns_overrides prevents this by adding an entry to the wrapper class’s method table.

Michael Black: Rebuild it as a Framework

Mon, 25 Feb 2008 11:13:39 GMT

Let’s begin by creating a framework containing Martin’s AppleRemote controller. First, in the Groups & Files pane, expand the Targets item, click on the AppleRemote target to select it, and press the delete key to delete it. We’re going to replace it with a new build target with the same name. To add the new target, first select the Project->New Target… menu item. You’ll then see a dialog box with a list of different project types. Choose the Cocoa->Framework type and press the Next button. Name the target “AppleRemote” (don’t type the quotes) and click the Finish button.

Now you’ll need to add some files to the new target. Back in the Groups & Files pane, expand the AppleRemote target to reveal the build steps. Then expand the Base Classes and Devices folder near the top of the pane and drag RemoteControl.h, HIDRemoteControlDevice.h and AppleRemote.h to the Copy Headers step and RemoteControl.m, HIDRemoteControlDevice.m and AppleRemote.m to the Compile Sources step. Then expand the Frameworks folder and drag the IOKit.framework and Carbon.framework to the Link Binary With Libraries step.

Under the Project menu, set the Active Build Configuration to Release.

Next, build the framework. Here is a picture of my Xcode project window just after my build completed.

Finally, move the result (AppleRemote.framework) from the build/Release directory to /Library/Frameworks.

Michael Black: A quick introduction

Mon, 25 Feb 2008 11:09:56 GMT

Recently I was planning a presentation on RubyCocoa. I had prepared a demo application to show during my talk and decided that it would be fun to show my presentation slides from my demo app. I quickly found that Keynote could export my slides as .png files, and it didn’t take long to get them loaded into a custom image viewer that used an NSImageView to display the slides. But one thing was missing: with Keynote, I could control my presentation with my new Apple Remote. I wanted to be able to do the same thing from Ruby.

Thanks to Google, Martin Kahr, Objective-C, and RubyCocoa, less than 30 minutes later I had exactly what I wanted. A search for ‘Apple Remote Objective-C’ took me directly to Martin’s source code page, where I found the source for his small demo application.

Let’s switch from past to present and do the rest together.

Download the source from Martin’s web site. As I write this, here is the current version of his demo application. Inside the archive, you’ll find an Xcode project. Build and run it. The result will be an application window like the one below.

Pressing buttons on your remote will cause red circles to appear on the corresponding parts of the image. In the window shown, I’m holding the right “forward” button down.

There are three significant Objective-C classes in the demo application, each with its own pair of header and source files. RemoteFeedbackView provides the contents of the application window, AppleRemote handles communication with the remote control, and MainController brings the two together. If you look at its source in MainController.m, you’ll see that Martin has designed a very easy to use interface that uses a common Objective-C pattern: delegation. In its awakeFromNib method, the MainController gets a singleton object representing the Apple Remote (using another common Objective-C pattern, the shared object). Then the controller sets itself as the delegate of the [AppleRemote sharedRemote]. It then waits for button presses, which cause the Apple Remote handler to send an appleRemoteButton:pressedDown: message to the delegate, which displays a status message and forwards the button press information to the view.

Feel free to read through the code in AppleRemote.m; it contains some mysterious calls to Apple’s HID (human interface device) manager that could easily take hours to fully understand. But by now we already know enough to use Martin’s Apple Remote interface from Ruby.

Michael Black: A quick introduction

Mon, 25 Feb 2008 11:04:58 GMT

Let’s switch from past to present and do the rest together.

Pressing buttons on your remote will cause red circles to appear on the corresponding parts of the image. In the window shown, I’m holding the right “forward” button down.

Michael Black: Rebuild it as a Framework

Mon, 25 Feb 2008 10:34:24 GMT

Now you’ll need to add some files to the new target. Back in the Groups & Files pane, expand the AppleRemote target to reveal the build steps. Then expand the Base Classes folder near the top of the pane and drag RemoteControl.h to the Copy Headers step and RemoteControl.m to the Compile Sources step. Then expand the Frameworks folder and drag the IOKit.framework to the Link Binary With Libraries step.

Under the Project menu, set the Active Build Configuration to Release.

Next, build the framework. Here is a picture of my Xcode project window just after my build completed.

Finally, move the result (AppleRemote.framework) from the build/Release directory to /Library/Frameworks.

Michael Black: A quick introduction

Mon, 25 Feb 2008 10:32:50 GMT

Let’s switch from past to present and do the rest together.

Pressing buttons on your remote will cause red circles to appear on the corresponding parts of the image. In the window shown, I’m holding the right “forward” button down.

Michael Black: A RubyCocoa console

Mon, 25 Feb 2008 10:04:32 GMT

The code for our console is below. To use it, download it from this link, put it in your project directory and restart your application (be sure to also remove the code for the dummy console from the previous chapter). I’ll discuss the console’s implementation in the following section, but if you want to play with it first, just go on to the next chapter.

console.rb (final version) [ruby]

require 'irb'

class ConsoleWindowController < OSX::NSObject
  attr_accessor :window, :textview, :console
  def initWithFrame(frame)
    init
    styleMask = OSX::NSTitledWindowMask + OSX::NSClosableWindowMask +
    OSX::NSMiniaturizableWindowMask + OSX::NSResizableWindowMask
    @window = OSX::NSWindow.alloc.initWithContentRect_styleMask_backing_defer(
    frame, styleMask, OSX::NSBackingStoreBuffered, false)
    @textview = OSX::NSTextView.alloc.initWithFrame(frame)
    @console = RubyConsole.alloc.initWithTextView @textview
    with @window do |w|
      w.setContentView scrollableView(@textview)
      w.setTitle "RubyCocoa Console"
      w.setDelegate self
      w.center
      w.makeKeyAndOrderFront(self)
    end
    self
  end

  def run
    @console.performSelector_withObject_afterDelay("run:", self, 0)
  end

  def windowWillClose(notification)
    OSX::NSApplication.sharedApplication.terminate(self)
  end

  def windowShouldClose(notification)
    @alert = OSX::NSAlert.alloc.init
    with @alert do |a|
      a.setMessageText(
      "Do you really want to close this console?\nYour application will exit.")
      a.setAlertStyle(OSX::NSCriticalAlertStyle)
      a.addButtonWithTitle("OK")
      a.addButtonWithTitle("Cancel")
      a.beginSheetModalForWindow_modalDelegate_didEndSelector_contextInfo(
      window, self, "alertDidEnd:returnCode:contextInfo:", nil)
    end
    false
  end

  def alertDidEnd_returnCode_contextInfo(alert, code, contextInfo)
    window.close if (code == 1000)
  end
end

def with(x)
  yield x if block_given?; x
end if not defined? with

def scrollableView(content)
  scrollview = OSX::NSScrollView.alloc.initWithFrame(content.frame)
  clipview = OSX::NSClipView.alloc.initWithFrame(scrollview.frame)
  scrollview.setContentView(clipview)
  scrollview.setDocumentView(content)
  clipview.setDocumentView(content)
  content.setFrame(clipview.frame)
  scrollview.setHasVerticalScroller(1)
  scrollview.setHasHorizontalScroller(1)
  scrollview.setAutohidesScrollers(1)
  resizingMask = OSX::NSViewWidthSizable + OSX::NSViewHeightSizable
  content.setAutoresizingMask(resizingMask)
  clipview.setAutoresizingMask(resizingMask)
  scrollview.setAutoresizingMask(resizingMask)
  scrollview
end

class RubyCocoaInputMethod < IRB::StdioInputMethod
  def initialize(console)
    super() # superclass method has no arguments
    @console = console
    @history_index = 1
    @continued_from_line = nil
  end

  def gets
    m = @prompt.match(/(\d+)[>*]/)
    level = m ? m[1].to_i : 0
    if level > 0
      @continued_from_line ||= @line_no
    elsif @continued_from_line
      mergeLastNLines(@line_no - @continued_from_line + 1)
      @continued_from_line = nil
    end
    @console.write @prompt+"  "*level
    string = @console.readLine
    @line_no += 1
    @history_index = @line_no + 1
    @line[@line_no] = string
    string
  end

  def mergeLastNLines(i)
    return unless i > 1
    range = -i..-1
    @line[range] = @line[range].map {|l| l.chomp}.join("\n")
    @line_no -= (i-1)
    @history_index -= (i-1)
  end

  def prevCmd
    return "" if @line_no == 0
    @history_index -= 1 unless @history_index <= 1
    @line[@history_index]
  end

  def nextCmd
    return "" if (@line_no == 0) or (@history_index >= @line_no)
    @history_index += 1
    @line[@history_index]
  end
end

# this is an output handler for IRB 
# and a delegate and controller for an NSTextView
class RubyConsole < OSX::NSObject
  attr_accessor :textview, :inputMethod

  def initWithTextView(textview)
    init
    @textview = textview
    @textview.setDelegate self
    @textview.setRichText(false)
    @textview.setContinuousSpellCheckingEnabled(false)
    @inputMethod = RubyCocoaInputMethod.new(self)
    @context = Kernel::binding
    @startOfInput = 0
    self
  end

  def run(sender = nil)
    @textview.window.makeKeyAndOrderFront(self)
    IRB.startInConsole(self)
    OSX::NSApplication.sharedApplication.terminate(self)
  end

  def write(object)
    string = object.to_s
    @textview.textStorage.insertAttributedString_atIndex(
      OSX::NSAttributedString.alloc.initWithString(string), @startOfInput)
    @startOfInput += string.length
    @textview.scrollRangeToVisible([lengthOfTextView, 0])
    handleEvents if OSX::NSApplication.sharedApplication.isRunning
  end

  def moveAndScrollToIndex(index)
    range = OSX::NSRange.new(index, 0)
    @textview.scrollRangeToVisible(range)
    @textview.setSelectedRange(range)
  end

  def lengthOfTextView
    @textview.textStorage.mutableString.length
  end

  def currentLine
    text = @textview.textStorage.mutableString
    text.substringWithRange(
      OSX::NSRange.new(@startOfInput, text.length - @startOfInput)).to_s
  end

  def readLine
    app = OSX::NSApplication.sharedApplication
    @startOfInput = lengthOfTextView
    loop do
      event = app.nextEventMatchingMask_untilDate_inMode_dequeue(
        OSX::NSAnyEventMask, 
        OSX::NSDate.distantFuture(), 
        OSX::NSDefaultRunLoopMode, 
        true)
      if (event.oc_type == OSX::NSKeyDown) and 
         event.window and 
         (event.window.isEqual? @textview.window)
        break if event.characters.to_s == "\r"
        if (event.modifierFlags & OSX::NSControlKeyMask) != 0:
          case event.keyCode
          when 0:  moveAndScrollToIndex(@startOfInput)     # control-a
          when 14: moveAndScrollToIndex(lengthOfTextView)  # control-e
          end
        end
      end
      app.sendEvent(event)
    end
    lineToReturn = currentLine
    @startOfInput = lengthOfTextView
    write("\n")
    return lineToReturn + "\n"
  end

  def handleEvents
    app = OSX::NSApplication.sharedApplication
    event = app.nextEventMatchingMask_untilDate_inMode_dequeue(
      OSX::NSAnyEventMask,
      OSX::NSDate.dateWithTimeIntervalSinceNow(0.01),
      OSX::NSDefaultRunLoopMode,
      true)
    if event
      if (event.oc_type == OSX::NSKeyDown) and
        event.window and
        (event.window.isEqualTo @textview.window) and
        (event.charactersIgnoringModifiers.to_s == 'c') and
        (event.modifierFlags & OSX::NSControlKeyMask)
        raise IRB::Abort, "abort, then interrupt!!" # that's what IRB says...
      else
        app.sendEvent(event)
      end
    end
  end

  def replaceLineWithHistory(s)
    range = OSX::NSRange.new(@startOfInput, lengthOfTextView - @startOfInput)
    @textview.textStorage.replaceCharactersInRange_withAttributedString(
    range, OSX::NSAttributedString.alloc.initWithString(s.chomp))
    @textview.scrollRangeToVisible([lengthOfTextView, 0])
    true
  end

  # delegate methods
  def textView_shouldChangeTextInRange_replacementString(
        textview, range, replacement)
    return false if range.location < @startOfInput
    replacement = replacement.to_s.gsub("\r","\n")
    if replacement.length > 0 and replacement[-1].chr == "\n"
      @textview.textStorage.appendAttributedString(
        OSX::NSAttributedString.alloc.initWithString(replacement)
      ) if currentLine != ""
      @startOfInput = lengthOfTextView
      false # don't insert replacement text because we've already inserted it
    else
      true  # caller should insert replacement text
    end
  end

  def textView_willChangeSelectionFromCharacterRange_toCharacterRange(
       textview, oldRange, newRange)
    return oldRange if (newRange.length == 0) and
                       (newRange.location < @startOfInput)
    newRange
  end

  def textView_doCommandBySelector(textview, selector)
    case selector
    when "moveUp:"
      replaceLineWithHistory(@inputMethod.prevCmd)
    when "moveDown:"
      replaceLineWithHistory(@inputMethod.nextCmd)
    else
      false
    end
  end
end

module IRB
  def IRB.startInConsole(console)
    IRB.setup(nil)
    @CONF[:PROMPT_MODE] = :DEFAULT
    @CONF[:VERBOSE] = false
    @CONF[:ECHO] = true
    irb = Irb.new(nil, console.inputMethod)
    @CONF[:IRB_RC].call(irb.context) if @CONF[:IRB_RC]
    @CONF[:MAIN_CONTEXT] = irb.context
    trap("SIGINT") do
      irb.signal_handle
    end
    old_stdout, old_stderr = $stdout, $stderr
    $stdout = $stderr = console
    catch(:IRB_EXIT) do
      loop do
        begin
          irb.eval_input
        rescue Exception
          puts "Error: #{$!}"
        end
      end
    end
    $stdout, $stderr = old_stdout, old_stderr
  end
  class Context
    def prompting?
      true
    end
  end
end

class ApplicationDelegate < OSX::NSObject
  def applicationDidFinishLaunching(sender)
    $consoleWindowController = ConsoleWindowController.alloc.
       initWithFrame([50,50,600,300])
    $consoleWindowController.run
  end
end

# set up the application delegate
$delegate = ApplicationDelegate.alloc.init
OSX::NSApplication.sharedApplication.setDelegate($delegate)

Michael Black: Do this and your software will thank you

Mon, 25 Feb 2008 09:43:01 GMT

The first step is to convert our Objective-C Cocoa application into a RubyCocoa application. Our application will need to have a Ruby interpreter and the RubyCocoa bridge code built into it. To get them, make the following changes:

Add the RubyCocoa framework to your project.
- In the ‘Groups & Files’ section on the left side of the Project window, expand the ‘Frameworks’ group,
- Right-click (or Ctrl-click) on the ‘Linked Frameworks’ group, and choose ‘Add -> Existing Frameworks…’
- Find and add ’/System/Frameworks/RubyCocoa.framework’

Replace main.m with the following code:

main.m [Objective-C]

#import <RubyCocoa/RBRuntime.h>

int main(int argc, const char *argv[])
{
    return RBApplicationMain("rb_main.rb", argc, argv);
}

Add a new file to your project named rb_main.rb. Give it the following contents:

rb_main.rb [ruby]

require 'osx/cocoa'

def rb_main_init
  path = OSX::NSBundle.mainBundle.resourcePath.fileSystemRepresentation
  rbfiles = Dir.entries(path).select {|x| /\.rb\z/ =~ x}
  rbfiles -= [ File.basename(__FILE__) ]
  rbfiles.each do |path|
    require( File.basename(path) )
  end
end

if $0 == __FILE__ then
  rb_main_init
  OSX.NSApplicationMain(0, nil)
end

Now build and test your application. Everything should work just as before, but your application now has a hidden and very special power—it can run Ruby code. We’ll use this in the next three chapters to convert the three classes Controller, CustomWindow, and CustomView one-by-one into Ruby, and then in the next chapter to make some fun and easy enhancements. We’ll convert the classes one at a time so that we can catch any problems that appear along the way.

Michael Black: Set up the document nib file

Mon, 25 Feb 2008 08:59:58 GMT

Open Game.nib from within Xcode. Interface Builder will open the file. In the document window, delete the “Your document contents here” message and replace it with a CustomView object from the palette.

Select the Window object in the Game.nib main view and then use Command-3 to inspect its size properties. Set its width and height to 800×600 and click the “lock” checkbox. Then go to the window inspector with Command-1 and uncheck the “Zoom (and resize)” box (see the image at right). This will give the game world a fixed size. Now size the CustomView object so that it fills the window.

Hang in there! In my opinion, this is the most tedious part of the whole tutorial, so don’t get discouraged. Cocoa and NeXTSTEP mavens like to talk about how great it is to use Interface Builder (and compared with their previous alternatives, they’re probably right). But like Carl Jung, most of them have never used Ruby.

With the CustomView still selected, use Command-6 to bring up its Identity inspector. Change the class to GameView and add an outlet to your GameView class named game.

In the main Interface Builder window, select the File’s Owner object and use Command-6 to verify that its class is Game. Connect the GameView’s game outlet to the File’s Owner object.

Save the nib and exit Interface Builder. Run the application. You should now get an empty window and a warning message in the run log:

Unknown class ‘GameView’ in nib file, using `NSView’ instead.

It’s time to create the GameView. And from here on, it’s all Ruby.

Michael Black: Set up the document nib file

Mon, 25 Feb 2008 08:58:06 GMT

With the CustomView still selected, use Command-6 to bring up its class inspector. Change the class to GameView and add an outlet to your GameView class named game.

Save the nib and exit Interface Builder. Run the application. You should now get an empty window and a warning message in the run log:

Unknown class ‘GameView’ in nib file, using `NSView’ instead.

It’s time to create the GameView. And from here on, it’s all Ruby.

Michael Black: Set up the document nib file

Mon, 25 Feb 2008 08:47:29 GMT

We need to tell Interface Builder about two classes. We’ll call them Game and GameView. Game represents our document and GameView is the view. In the Classes view, find MyDocument (it’s a subclass of NSDocument) and rename it to Game. Then find NSView (it’s a subclass of NSResponder) and create a subclass called GameView (right- or control-click on NSView for a pop-up menu). Add an outlet to your GameView class named game.

Go back to the window object and select the CustomView. Use Command-6 to bring up its class inspector. Change the class to GameView.

Save the nib and exit Interface Builder. Run the application. You should now get an empty window and a warning message in the run log:

Unknown class ‘GameView’ in nib file, using `NSView’ instead.

It’s time to create the GameView. And from here on, it’s all Ruby.

Michael Black: Create the Xcode project

Mon, 25 Feb 2008 08:35:44 GMT

In Xcode, use File->New Project… to create a new project. In the dialog that appears, select “Cocoa-Ruby Document-based Application” as the project type. Name the project “rubyrocks”.

The project tempate specifies that the application’s document class is MyDocument. Let’s change that to Game. In the Groups & Files pane on the left side of the project window, open the Classes and Resources groups. Make these changes:

Rename MyDocument.nib to Game.nib.

Rename MyDocument.rb to RubyRocks.rb (we’ll put all of our Ruby code in this file). In RubyRocks.rb, change the name of the MyDocument class to Game. Find the windowNibName function; change it to return Game.

Now build and run your project. You should get an error: an alert box should appear with the message “No document could be created.” This is because the application is still looking for a class named MyDocument. To change this, find the Targets group in your Xcode main project window. Click on the triangle to its left to expose the rubyrocks target. Double-click on the target icon to edit the target’s build properties. In the Document Types table, double-click the value in the Class column and change it from MyDocument to Game.

Now when you run your project, you should see a new window appear with the words “Your document contents here.” That’s your document view. To get it ready, we need to make some changes to Game.nib.

Administrator: Background

Wed, 19 Dec 2007 11:36:47 GMT

Ruby is a powerful language and is loaded with features, but for some applications, Ruby programmers face a limitation. It might be a performance problem caused by the slowness of interpreted languages. Or it might be that a critical function or API is only available in a lower-level language like C or C++. To address this, Ruby provides a way for developers to write extensions of Ruby in C.

The extension process is described in the pickaxe book. It is simpler than the processes required by some other scripting languages, but it still requires programmers to write custom “glue code” for every C function or C++ object that we need to make available to Ruby.

There is a popular tool called SWIG that can help generate this code. SWIG reads C and C++ source files and automatically writes the glue code that wraps C functions for Ruby (and lots of other languages). Wrapping C++ objects is also possible, but is more tricky due to the complexity of C++.

At some point, one eventually wonders “why is all this glue code necessary?” The answer to that lies in the C and C++ compilation process, which converts a lot of very high level information about objects and functions into lots more very low level information, mainly the machine instructions that directly implement each function. But all the high level information that Ruby needs about objects, types, methods, and interfaces is discarded in the compilation of C and C++ programs (and sometimes recovered by SWIG).

This is where Ruby programmers begin to love Objective-C. The tables that Objective-C uses for dynamic message handling contain exactly the information that is needed to interface with Ruby. Because they are kept in the compiled object files, they are available at runtime. As a result, to interface Objective-C objects with Ruby, no custom glue code is needed! All the translation that we need is in handlers that are built right into the RubyCocoa framework.

This gives us direct access to Cocoa and a lot more: any Objective-C classes and objects can be accessed through RubyCocoa. What’s more, RubyCocoa also contains a bridge that makes certain kinds of Ruby objects available in Objective-C code. We’ll go into detail about all this in the rest of this chapter.

Administrator: Downloading and Installing RubyCocoa

Wed, 19 Dec 2007 11:33:27 GMT

RubyCocoa distributions are downloadable from this page on SourceForge.

The current version is 0.13 (released November 24, 2007). It’s a universal binary that works great on Intel iMacs and Mac Books. If you’re using the Apple-installed ruby (the one at /usr/bin/ruby), then you probably want to download and install the disk image—it’s the file whose name ends in ”.dmg”. After downloading it, double click on it and the installation will begin.

If you have built a newer version of ruby and installed it somewhere else (probably /usr/local/bin/ruby), then you’ll need to instead download the source code distribution and build RubyCocoa yourself. To do so, download the file ending in ”.tgz”. To build, simply run the following in the unpacked directory:

ruby install.rb config
ruby install.rb setup
sudo ruby install.rb install

Administrator: Building and Installing RubyCocoa from Subversion

Wed, 19 Dec 2007 11:32:19 GMT

To keep up with the latest developments and bug fixes, you can download and build RubyCocoa directly from the subversion repository. The latest versions of RubyCocoa can be checked out with the following subversion command:

svn co https://rubycocoa.svn.sourceforge.net/svnroot/rubycocoa/trunk rubycocoa

Recently (Fall 2006), there have been a lot of bleeding-edge changes on a branch that you can check out with this:

svn co https://rubycocoa.svn.sourceforge.net/svnroot/rubycocoa/branches/apple-unstable rubycocoa

If you get an error message like the following, you probably are running with an old version of subversion:

% svn co https://rubycocoa.svn.sourceforge.net/svnroot/rubycocoa/trunk rubycocoa
svn: SSL is not supported

Download and install a new subversion client from Matthew Porter’s archive on metissian.com. Be sure to use version 1.3.1 or later to get a universal binary and SSL support.

Administrator: rubycocoa-talk

Wed, 19 Dec 2007 11:17:00 GMT

rubycocoa-talk is an email list for discussion of RubyCocoa. It currently is also the official channel for discussing bugs and submitting patches. rubycocoa-talk is archived at SourceForge.