In this section you will extend the Objective-C delegates and tie into the framework to create a clean and simple RubyMotion application! Delegates/messages are the key to dealing with iOS development.

It's time to understand the app structure from a RubyMotion perspective. To generate your first ever RubyMotion app, jump into the console and type the following command:

$ motion create –-template=ios HelloWorld

The motion create command then generates a project for you (much like Rails) with the same name you pass the command. In this case, we're creating a project named HelloWorld. Your output should look like the following screenshot:

Let's take a look at what files are created in this new HelloWorld project folder.

Here's a breakdown of the generated files:

A short editorial about MacBacon

As stated, MacBacon is a small Rspec clone, and is therefore geared toward behavior-driven development. MacBacon claims less than 350 LoC and allows for an extensive amount of testing. If you come from the Ruby world, you may have your own testing preferences, but in RubyMotion, you'll have to exist with this one alone (for now). It's geared to handle all iOS you'll be throwing at it.

You're almost done, but before you close out this section on the app structure, take a look at the generated app_delegate.rb file in the app folder. When you open this file, you're presented with a very simple five-line Ruby file. Let's review the structure of the generated file.

Line one give us the class that the rake command will be looking for the app delegate, and as you can clearly see they have initialized it with a single method. This method might appear confusing to any Ruby developer who has not familiarized themselves with the named parameter syntax, introduced in Ruby 2.0, but for all intents and purposes this is how RubyMotion has matched the expected Cocoa delegate. At this point Cocoa will run any code placed in here when the application has finished launching. In this case, that code is simply returning true.

To keep with our conductor analogy, the conductor has indicated that the application is ready to start and those who have music in front of them for this portion should begin. Our "music" is to return true... might not even have to learn our scales for that!

Note

If you're not familiar with named parameters don't fret! This is the perfect opportunity for you to become accustomed to using them. Additionally, MacRuby/RubyMotion has been emulating named parameters via hash since before Ruby 2.0 was officially released. This means your new knowledge is instantly backwards compatible in this realm of development (though order must be enforced to match method signatures). At the time of writing, RubyMotion was based on Ruby 1.9, but has announced their intention to move toward Ruby 2.0 compliance.

Now we have a completely functional application out the box. It doesn't do much; it doesn't even have a window. Let's take a quick moment to look at how to test and run this empty shell program.

If you're familiar with red/green/refactor test-driven development (TDD), we need to see the tests fail before we fix them. We'll be following the red/green/refactor methodology for the projects in this book. All tests will be written first, and will fail because there is no corresponding code. We'll write as much code as needed to get our test Green, aka passed, and then touch up our code with the Refactory cycle. More information on red/green/refactor can be found at http://www.jamesshore.com/Blog/Red-Green-Refactor.html.

As previously stated, our default test is verifying a window exists, and this should fail as there's no code for a window. To run the MacBacon specifications, we simply need to type the following command into the terminal:

$ rake spec

The preceding command will open a small window and run the tests. The parameter is necessary, unlike Rails. Your test runs the actual application in the simulator while the console gives you output relatively similar to the following:

There's more to the screen, but this and the summary at the end of the tests are the important parts. We've failed our test, which means the test is working (not to be confused with an error in our tests!). We're officially at red in the life cycle.

To add a window to the app, we'll need to edit the app_delegate.rb file and add a single line. Take a look at the following code, where we add line three:

This single line shouldn't take much explaining. We created an instance variable to hold our created window. We use the iOS window class UIWindow and we instantiate an instance using alloc.initWithFrame.

This initializer is called initWithFrame and as a parameter we're passing in the full screen's bounds:

Quite simply we've used Ruby to give us access to native Objective-C objects. You'll see this quite often as Ruby brushes up against the framework verbosity.

Once the preceding line is saved, re-running our tests yields a passing grade! Our code is now considered Green!

The last step is to refactor. There's not much we can do here, since we've got a shell application, but we can go just a little further into what the application probably should do. I've added the following line to our app_delegate, on the line with @window.makeKeyAndVisible.

What does this line do? Well you can tell it's an Objective-C function, since it's CamelCased. In iOS, the key window receives the keyboard input. The makeKeyAndVisible method brings the focus to this window as the main window, and assures that the keyboard input should be directed to it. Not much of a refactor but it's a necessary step for most applications, so we'll have it here. You're likely to have this line in just about every application you write.

At this point you can run the actual application, not simply the tests. This can be done by running the rake command with no parameters. By default this will usually run in a very small non-retina window. At the very least, I will usually run a simulator of the 4S retina:

$ rake retina=4     #runs iPhone 5 simulator
$ rake retina=3.5   #runs the iPhone 4S and older simulator

Upon running the code, your window stays open this time, and the console gives you a prompt that simply says (main)>. The prompt is one of the most impressive features of RubyMotion. Your empty shell application is running and you have direct access to your application in what's known as the REPL (Read-Evaluate-Print Loop). Via this command line you can interact directly with your running applications. We'll cover more about how to use this in the Top 3 features you need to know about section.

If you've ever opened a computer programming book, you're surely familiar with the classic "Hello World" application. The classic Hello World program simply displays the text from your application. Let's get started!

Since we're driving our application with desired behavior and tests, let's start there and see if we can add another feature and can get to stage Red. Our goal is to add our custom code to the running application window. Following the framework for iOS, this means we'll need to set the window's rootViewController with our own controller. I can think of two simple tests that would verify this. First, to check if the root view is set at all, and second, we can verify that the root view is set to our custom controller, which will be HelloWorldController.

I've written the tests in the supplied test file for simplicity. The tests will make your main_spec.rb file look like the following screenshot:

The preceding code adds one line to the before block, and the two additional specifications we discussed previously. Those familiar with before blocks know it helps keep variables current, and even better you don't have to repeat any setup, so your code is DRY (Don't Repeat Yourself).

In line four, we're adding an instance variable to simplify our tests. We'll use this @window variable to both of our follow up tests.

Starting at line 11 we add a check to verify that rootViewController is set, and on line 15 we check its class to see if it's been set to the correct class. By looking at the code, there is little coding explanation needed. MacBacon reads very similar to English! Just like the checking of a window size, these tests are quite constrained and basic, but that's where we're at with our application, so it's nice to see the code to verify these aspects.

Running the specifications at this point will fail, giving us the correct Red status of our development pattern.

We're going to start by making a file to be our controller and placing it inside the app folder. We'll name the file hello_world_controller.rb, so that it can be a class called HelloWorldController, which will satisfy our requirement. Additionally, it will need to have a subclass UIViewController in order to be our rootViewController. Your shell controller should look as such:

This is just your normal Ruby class definition subclassing on the iOS class we will be inheriting from.

Now modify our app_delegate.rb file to set our new class to rootViewController, as shown in the following code:

On line four we've set the controller to our custom controller. The .new code is generally a shortcut for .alloc.init. Since we didn't have any special initialization, the .new code will work perfectly here. If you're looking to strictly keep Cocoa with clear Cocoa conventions, and delineate clearly between any RubyMotion usages, you may elect to keep using .alloc.init instead.

At this point we've created our controller and set it where we are supposed to. This should be more than enough to pass our tests, so running rake spec will show us that we're now Green! No room to refactor on this round, so the cycle is complete.

The good news is that our controller is in place so we're breaking away from the lifeless shell application and moving towards a true "Hello World" app. We won't need to deal with our AppDelegate any longer.

Now we can start placing code in our controller. Remember when I said that this is a framework that calls into our code at given points, here's where we choose one of those points in time to hook into, and we'll choose one of the most common UIViewController methods, viewDidLoad. So, create a method called viewDidLoad, and let's put the following code inside:

Running your application at this point (by typing rake in the console) will cause your application to output "Hello World" to the application's standard output (the command line in this case). There's nothing too special happening here, we're using the traditional Ruby puts method to give us some feedback on the console.

Running this does start the simulator. To quit the simulator, you can use command + Q or from the console window, press Ctrl + D or Ctrl + C.

Since our phone doesn't really have a console to receive the standard output message, let's take this up a notch by adding a label to the application and configuring it to be a more traditional "Hello World" on the device. So, we plan on making a label that will have the text "Hello World", correct? Let's create the test for that.

We'll start by making a new file in our spec folder called hello_world_controller_spec.rb and we'll make it look like the following:

Let's inspect the testing code from the previous image. Everything looks similar to the other code but, as you can see, there's no need to make a before block, since we are able to access the controller by simply stating the controller we're testing on the second line. This shortcut works for any ViewController you're testing!

The actual testing and use for the variable starts with our specification. We grab the label so we can apply our two requirements on the following lines. We check the text value, and verify that the label has been added to the view. This might seem quite nebulous without knowing what we're testing, but the logic is simple. We want to make sure there's a label that says "Hello World" and we want it to be visible. Running these tests will fail, which puts us on track to write the actual "Hello World" portion.

You should add the following code to your project's hello_world_controller.rb file:

There it is! We've finally written a real Hello World application! Let's break this into each line and see how it was done. Line three is like our normal puts method to the console, but I've upgraded it to p, which is shorter to type, and actually calls the .inspect method on the parameter. This way you receive a human-readable representation of whatever object you've passed. This helps for outputting all kinds of objects as well as strings!

On line five, I get rid of the lifeless black background, and replace it with white. The view object you see referenced is the view of the controller. In the testing code, you see us reference this same view by controller.view, which points to the same object. On this view object, I'm setting the backgroundColor property (the available property on the UIView classes) to UIColor.

Properties of UIView can be found in the Apple Documentation (http://developer.apple.com/library/ios/#documentation/UIKit/Reference/UIView_Class/UIView/UIView.html).

We create a UILabel, which we intend to add to view. @label.text sets the text property, and next line sets the frame. Line 9 uses a RubyMotion shortcut for the frame. Normally, you would need to use Objective-C's CGRectMake with Cartesian coordinates as well as width and height, but instead you can pass in the array as we have it in the previous code example. The format is [[x coordinate, y coordinate],[width, height]]. Where the first array portion is the origin and the second is the size. We actually already dealt with a frame when we sent the bounds value to initWithFrame in the AppDelegate class. The last line of the method takes this object we've been working on and places it on view!

Line 8 satisfies the first requirement of our specification test that the text matches "Hello World". Line 10 satisfies our second requirement, by verifying the label is added. Running specification tests with the preceding code yields a passing result! Actually running the application shows the following app:

Yeah, it's nothing you'd show your friends, but it's definitely something to be proud of because it's a complete application for your iPhone!

Now we can refactor our code. At a simple glance we can tell that our "Hello World" text is anything but centered. Let's grab the position of the view and center ourselves neatly!

We'll add sweet symmetry to our app with the following code:

Voila! We've quickly modified our original application to handle the frame dynamically.

We calculate the center coordinate along the horizontal (x) by grabbing our current main view frame width and dividing by 2. Likewise, we do the same for the vertical (y). On line 11, we call the UIView class's sizeToFit method. This sizes the frame around all contents and subviews, essentially making the label frame exactly the size of the text. Then, lastly, on line 12, we set the label's center to the calculated center from lines 6 and 7. This yields the aesthetic result of a completely horizontally and vertically centered label!

Additionally, if you're keen enough, you may have realized the great ancillary benefit to this method. Your application will now center the text on any device, even an iPad!

Why not try it out? Let's make our app so it can render on an iPad. All we have to do is add device_family to our Rakefile:

By the preceding line 8, we've added the ability of our app to go on the iPad. The order of the parameters in this array will adjust which device is default. To build our app specifically for the iPad we run the following:

$ rake device_family=ipad

And there you go! Your application is now an iPad application, and your label is still centered! You may need to clean and rebuild if your application is not switched to iPad. This can be done with a quick call to rake clean.

All the code of the Hello World project can be found at https://github.com/GantMan/HelloWorld or http://www.packtpub.com/support.

Congratulations on your first RubyMotion application! You deserve it!