In this article we will explain how to create a simple application using MacRuby.

Here is the user interface of the application we will build. We will call this application "StopWatch".

The "StopWatch" application has the following features.

1. Run the timer if the start button is clicked.
2. Stop the timer if the stop button is clicked.
3. The timer value is displayed in the text field.

Note that if you’re running Xcode 4.3.3, 4.4, 4.5.1 or 4.5.2, you may need to add /Library/Frameworks to the framework search path in your project. See https://github.com/MacRuby/MacRuby/issues/107 for more details.

When you launch Xcode, you may see a "Welcome to Xcode" dialog. If so, click on "Create a new Xcode project".

If you don't see the "Welcome to Xcode" dialog, select the File -> New -> Project... menu.

In both cases, the Xcode workspace window will open, and you will be presented with a sheet headed "Choose a template for your new project". In the sidebar under "OS X", select "Application"; then select the "MacRuby Application" icon; then click "Next".

The sheet will update to options for the new project. Fill them in:

• Product Name: StopWatch
• Company Identifier: Needs to be something valid, like "org.macruby" or "com.example". Note that if this were a real application, you would want to use an identifier which is different from anyone else's.

Finally, the file save sheet will be presented. Choose a directory in which the project will be created.

We will start by designing the user interface.

In the Xcode project, choose MainMenu.xib.

Select [Window - StopWatch] to display the window object.

Click on the following View toolbar item in order to display the object library.

Now we are ready to start designing the user interface. We can simply drag the controls from the object library to the window.

The "StopWatch" application sets the timer value in the text field. However, placing the text field on the window is not enough. We need to connect the text field with the actual application code. UI controls connected to code are called outlets.

In order to create an outlet, we need to write code. Select the AppDelegate.rb file, then add the attr_accessor :textField line inside the AppDelegate class.

class AppDelegate
  attr_accessor :window
  attr_accessor :textField # This creates an outlet named textField

Now we can go back to the MainMenu.xib file and connect the outlet. Maintain the control key and drag the App Delegate object to the text field.

A list of outlets will be displayed. You can select textField here.

Now, we can retrieve and update the value of the text field in our code by using the respective textField accessor methods.

At this point, if you click on the start or stop buttons, nothing happens. It's perfectly normal as we haven't written the code for these features.

Select the AppDelegate.rb file. We can define the startTimer and stopTimer methods as following.

class AppDelegate
  attr_accessor :window
  attr_accessor :textField # Outlet
  def applicationDidFinishLaunching(a_notification)
    # Insert code here to initialize your application
  end

  def startTimer(sender)
    # This method is called when the start button is clicked.
  end

  def stopTimer(sender)
    # This method is called when the stop button is clicked.
  end
end

These methods are called actions. Actions are special methods defined in code that are connected to UI controls, and called when something happens with the control.

Let's go back to the MainMenu.xib file to connect the actions. Just as you connected the outlet for the textfield, press the control key and drag the start button onto the App Delegate object.

From the list of actions that is displayed, select startTimer.

Connect the stop button to the App Delegate in the same way. After that, the methods will be called when the buttons will be clicked by the user.

stopTimer/startTimer are also known as the action method.

Important: when you are defining an action method, you must provide a sender argument. If the method does not have a sender argument, it won't be recognized as an action by Xcode.

The NSTimer class can be used in order to perform a certain action at a constant interval.

The following code creates and schedules a timer that will execute the timerHandler method repetitively each 0.1 seconds.

@timer = NSTimer
           .scheduledTimerWithTimeInterval(0.1,
                                           target: self,
                                           selector: "timerHandler:",
                                           userInfo: nil,
                                           repeats: true)

def timerHandler(userInfo)
  # Handler
end

Now, we can create the timer in startTimer, and stop the timer in stopTimer.

class AppDelegate
  attr_accessor :window
  attr_accessor :textField # Outlet
  def applicationDidFinishLaunching(a_notification)
    # Insert code here to initialize your application
  end

  def startTimer(sender)
    if @timer.nil?
      @time = 0.0
      @timer = NSTimer
                .scheduledTimerWithTimeInterval(0.1,
                                                target: self,
                                                selector: "timerHandler:",
                                                userInfo: nil,
                                                repeats: true)
    end
  end

  def stopTimer(sender)
    if @timer
      @timer.invalidate
      @timer = nil
    end
  end

  def timerHandler(userInfo)
    @time += 0.1
    string = sprintf("%.1f", @time)
    textField.setStringValue(string)
  end
end

The @timer.invalidate method is used to stop the timer. The textField.setStringValue(string) method is used to change the text field to a new string value.

Congratulations, our "Stopwatch" application is now complete!

We can change the scheme to "Deployment". After that, Click [Run]. "Stopwatch" application will be running!