Thought Into Motion

MacRuby

I was reading one of my favorite blogs to today (Thought Palace) and I came across this interesting post called MacRuby. It seems that Apple has created an open source project for porting the Ruby language to run on top of Objective-C. In essence this would eliminate the need for the scripting bridge called RubyCocoa.

After playing with RubyCocoa and building a couple of smaller applications in it, I think this is an excellent move by the apple guys. The power of ruby with the speed of Objective-C will only bring a new of developers to the mac platform.

For more information check out the post on Thought Palace or visit the offical apple website for the MacRuby project

Recreating The iCal Sounds Pull Down Menu

In a recent design session we were looking to recreate the sounds drop down menu from iCal. This menu is attached to an alarm within iCal. One of the interesting things about this menu is that as you change the sound name, the sound is played. Borrowing from this cocoa dev article, I dived into converting the sample code into RubyCocoa. During my conversion, I ran into some snags that I would like to point out before we get to my methods.

Tips & Tricks
1) I tried many times to get the fileExistsAtPath_isDirectory function to return a boolean in the "isDir" variable that is passed into the function, but in the end I could not get that function to work correctly. That is why I added the lines below it to get the attributes of the file to find out if it is a directory. This is an extra step, but in my testing it seemed to be a necessary one.

2) The NSSound class makes many references to playing sounds by their "name", but there is no mention to returning a list of available sound names. The functions below should help you keep a list of sound names without having to hardcode their "names"

3) Make sure to check the documentation for the NSFileManager class. This class has many different methods for parsing a directory, and some return a list of file names, while others return file objects.

Functions:
The function below loops through some system directories and finds folders named "Sounds". Once a folder has been located it will loop through the files and load them into the NSMutableDictionary with the key being the name of the file without the extension. For instance Basso.aiff will become Basso. Once we have a list of sounds stored in a dictionary, I created simple wrapper methods to help retrieve the sound files and a list of the sound names.

Method To Create A Sounds Dictionary

def generateSoundsList()
  @soundsList = OSX::NSMutableDictionary.alloc.init
  knownSoundTypes = OSX::NSSound.soundUnfilteredFileTypes()

  libs = OSX::NSSearchPathForDirectoriesInDomains(OSX::NSLibraryDirectory, OSX::NSUserDomainMask | OSX::NSLocalDomainMask | OSX::NSSystemDomainMask, true);

  fm = OSX::NSFileManager.defaultManager()
  libs.each { | dir |
    fileExists = nil
    isDir = nil
    error = nil

    (fileExists, isDir) = fm.fileExistsAtPath_isDirectory(dir, isDir)
    attrs = fm.attributesOfItemAtPath_error(dir, nil)
    if (fm.fileExistsAtPath(dir))
      attrs = fm.attributesOfItemAtPath_error(dir, nil)
      if ((attrs["NSFileType"] == "NSFileTypeDirectory"))
        fm.contentsOfDirectoryAtPath_error(dir, error).each { | fileName |
          if (fileName == "Sounds")
            fm.enumeratorAtPath(dir + "/" + fileName).allObjects.each { | file |
              if (knownSoundTypes.containsObject(file.pathExtension))
                @soundsList.setValue_forKey(dir + "/" + fileName + "/" + file, file.stringByDeletingPathExtension)
              end
            }
          end
        }
      end
    end
  }
end

Method To Get A Sound By Name

def getSound(name)
  return @soundsList.objectForKey(name)
end

Method To Create A Sounds Dictionary

def getSoundNames()
  return @soundsList.keysSortedByValueUsingSelector ("caseInsensitiveCompare:")
end

Hopefully these methods will help you in your next rubycocoa project.

NSGradient Class... Who Knew?

My company has started building a new time tracking applications for mac users, focusing mostly on freelancers. During one of our mock up sessions I commented that it might be nice to put a gradient background behind the view. So I took it upon myself to figure out how I would add a gradient background using RubyCocoa.

First off, I did a quick google search for "cocoa gradient background custom view", and I found a couple of interesting sites:

1) Cocoa Background Tutotorial 1.1

2) Pimp My Code: Part 3 Gradient Table Views

I decided to focus on the second post since this was more inline with what I was trying to do, and it didn't hurt that it was written by Wil Shipley. As a side note, if you have never checked out his blog Call Me Fishmeal you really should.

Now that I had my example and I knew what I wanted to do it was time to port the code over to RubyCocoa so I could start playing with it. Well after 3 hours of looking at API's and c functions, I only made it about 1/2 way before I had to call it a night. About an hour into my coding the next morning, I was looking at an API when I ran across a link to the companion document, the "Cocoa Drawing Guide". I figured I had nothing to lose so I took a quick look. Upon perusing the contents in the left side, I couldn't believe my eyes. Right there in the "Related Reference" section was a link to the NSGradient class.

After some swearing, crying and general shock that I had missed this in my searching, I felt excitied and ready to code. Below is the RubyCocoa code for my first quick test project using the NSGradient class.

Rounded Textured Button With A Gradient Fill: My Custom Draw Method

def drawRect(rect)
  newSize = OSX::NSRect.new([(rect.x + 2), (rect.y+1)],[(rect.width - 4),(rect.height-3)])

  clipShape = OSX::NSBezierPath.bezierPathWithRoundedRect_xRadius_yRadius(newSize,6,(rect.height/2))
  aGradient = OSX::NSGradient.alloc.initWithStartingColor_endingColor(OSX::NSColor.whiteColor,OSX::NSColor.grayColor)
  aGradient.drawInBezierPath_angle(clipShape,90);
  self.attributedTitle.drawInRect(newSize)

end

Class References:
NSGradient
NSBezierPath

Lastly some things that I ran across when making this example:

1. Make sure you are looking at the latest api's from apple. At one point I wasted about 20 min looking at an older version of the NSBezierPath api.

2. Make sure to read the Cocoa Drawing Guide

3. Once you get a base example working, play with it and try to change things like the text color or the path's line width.

Retriving CoreData Objects Using RubyCocoa

If you are like me then you followed all the core data tutorials and you created your cocoa applications without any problem. But very quickly into creating your own application, you start to move outside the confines of the tutorials and need to get into the code and figure out what to do. This is normally a struggling point for anyone learning a new language, but when you throw in the fact that to tutorials, guides and documentation are in a separate language from the one your are writing in your task become harder. This is how I felt when I tried to retrieve core data objects through code in my brand new RubyCocoa application.

There are plenty of tutorials out there for core data and even some for RubyCocoa, but in my experience most of these tutorials show you how to interface with your object model using bindings. Most of the time this is the way I would prefer to handle my data interactions. But then again sometimes you just have to dive into the code and get your hands dirty. Below is a little snippet of code I wrote to retrieve a list of "Projects" from my core data model. After the code, I will go through and point out a coupe of spots that caused me a little grief in hopes of sharing my knowledge. Of course this posting assumes that you have read the CoreData Programming Guide from apple and are familiar with the concepts of the core data framework.

The Code:
managedObjectContext = self.managedObjectContext() entity = OSX::NSEntityDescription.entityForName_inManagedObjectContext("Project",managedObjectContext)

# Create Fetch Request
request = OSX::NSFetchRequest.alloc.init
request.entity = entity

# Create Predicate (where clause)
predicate = OSX::NSPredicate.predicateWithFormat("(isActive = true)")
request.predicate = predicate

# Add Sorting
sort = OSX::NSSortDescriptor.alloc.initWithKey_ascending("name",true)
request.sortDescriptors = [sort]

rows = managedObjectContext.executeFetchRequest_error(request)
rows.each { | row |
  case (row.class.to_s())
  when /NSError/i
    OSX::NSLog("Error Retriving Data: %@", row)
    break;
  when /Array/i
    row.each { | dataRow |
      OSX::NSLog("Item: %@ Class: %@", dataRow, dataRow.class)
      ... your code here ...
    }
  end
}

The Breakdown:
These lines of code establish the link to the managedObjectContext and create an entity description for the model you would like to retrieve. Later we will use this description in our fetch request, but for now this just creates the pointer.

managedObjectContext = self.managedObjectContext()
entity = OSX::NSEntityDescription.entityForName_inManagedObjectContext("Project",managedObjectContext)

Next we create our fetch request and assign our entity description to the fetch request. One of the things that had me stumped for alittle whlie is the "alloc.init" part of the code. In most of the RubyCocoa tutorials I have scene, I have not run accross this construct, but for my core data programming this is required to create and initialize the cocoa objects.

request = OSX::NSFetchRequest.alloc.init
request.entity = entity

Now that our fetch request has been created and our entity is assigned, we can add a predicate to our request to limit our results. In this examples I was looking for all projects that have the attribute "isActive" set to true. Predicate programming is similar to SQL where clauses, but there are subtle differences, so make sure to check the Predicate Programming Guide if you are having problems.

predicate = OSX::NSPredicate.predicateWithFormat("(isActive = true)")
request.predicate = predicate

Lastly ever request must have a sort description added to our request, even if this is just a blank array. Unlike our predicate example above the sortDescriptors property is added as an array. You will notice below I create my sort description object and then just add it to an array while setting the descriptor on the request object. Not setting a sort descriptor will cause a runtime error, so if you don't need one just set this request property to a blank array. Also pay attention to the "alloc.init" syntax again. In this case we want to sort our data by the projects name.

sort = OSX::NSSortDescriptor.alloc.initWithKey_ascending("name",true)
request.sortDescriptors = [sort]

Now that we have created the fetch request, it is time to execute our fetch and return our rows. Once we have our rows, we have to loop through the results to retrieve the list of objects. The object returned is an array of objects. I first expected this to be an array of data but quickly found out that it can be an error or an array of data. The case clause helps figure out if the request worked correctly. Within the case statemnt you will notice that I using a regular expression to check the object type. I found this to be the easiest way for myself to parse the results, but feel freel to change this to the style that most suites you. Finally once we have our data array, it is time to loop through the objects and do what we need to with them.

rows = managedObjectContext.executeFetchRequest_error(request)
rows.each { | row |
  case (row.class.to_s())
  when /NSError/i
    OSX::NSLog("Error Retriving Data: %@", row)
    break;
  when /Array/i
    row.each { | dataRow |
      OSX::NSLog("Item: %@ Class: %@", dataRow, dataRow.class)
      ... your code here ...
    }
  end
}

I hope this example helps you out with your RubyCocoa project. I will be posting other quick examples when I find something that has caused me a little bit of a headache, so check back soon. My next post will be about a custom formater class that I created for an NSTableView cell.

RubyCocoa: 5 Things To Get Started

RubyCocoa is a promising technology for those of us who like ruby and have always wanted to build OSX applications but never wanted to learn Objective-C.  Now that the framework is included in Leopard (OSX:10.5), I have started building my own application using rubycocoa.  Below are the top 5 things I wish I had known when I started out, so I have compiled them to save you some time.

1) Get familiar with the rubycocoa and apple developer websites.

www.rubycocoa.com is the most complete website for information regarding the framework.  Before you get to far into your application make sure to read through some of the excellent tutorials and comments.   There is a wealth of information on this site, and most of my simplier problems were resolved pretty quickly by checking out some of the examples.

 The cocoa development is a great place for information regarding the cocoa language.  While all the examples are written in Objective-C the examples will point you in the right direction and the tutorials are very complete.  Furthermore since this is apple, this is the place to look for information when you are trying to figure out what is wrong.

2) Get the API's

The Cocoa API's are included with XCode so you won't have to worry about those, but rubycocoa api's are not included with Leopard.   The rubycocoa web site will tell you the api is installed in /Developer/Documentation/RubyCocoa/Frameworks. This assumes that you have built the project from source and have installed the documentation locally.  Before you get into actual coding of your application I would highly suggest building a local version of the source just to have the API.   Also if you are building the API from the source, make sure to build the examples as well.  These are the "ruby" versions of the Objective-C tutorials included with XCode.

When looking through the cocoa API's get used to checking out the ruby ones as well.  Compare the methods and you will quickly see how the wrapper is working it's magic.  In no time you will be able to read the Objective-C code and figure out what the rubycocoa equivalent is.

3)  Hit The Books

The book Cocoa Programming For Mac OSX Second Edition is a great book for beginners looking to jump into OSX development.  While this book is written for Objective-C and XCode 2.0, it provides an excellent introduction into cocoa programming, and servers as a good reference for when you want to venture into your own ideas.  Rubycocoa is just the language, and without the understanding of how to build a cocoa application you will get frustrated very quickly.   

4)  Build The Tutorials

XCode and Interface builder, along with the excellent tutorials on the net will allow you to start fast.  You can get an application up and running pretty quickly without really knowing how things are working on the backend and if you are like me, then you will jump right into your application, draw your interface and then get stuck with the details of how to make things happen.   Take some time to build the sample applications and really look at the tutorials. 

5)  Join The Lists

The apple developer network is extensive, and has plenty of great people willing to help you out.  Most of the development lists focus on Objective-C techniques and code, but once you get used to how the rubycocoa wrapper works then these mailing lists will be a great source of information for you.

Lastly I just want to point out that building an OSX application is very unlike any of the development you have done on other platforms.  While the rubycocoa framework is a great alternative for those of use who don't want to learn Objective-C it is only a small portion of what it takes to build your application.  Take the time to learn the cocoa fundamentals and the tools, they will come in handy when you are stuck later down the line.