Introduction to OS X Tutorial: Core Controls and Swift Part 1/2

Get started with OS X core controls!

Update note: This tutorial was updated for OS X 10.10 Yosemite and Swift by Michael Briscoe. Original post by tutorial team member Ernesto García.

If you’re an iOS developer and you’re interested in learning about Mac development, you’re in luck – with your iOS skills, you’ll find it quite easy to learn!

Many of the Cocoa classes and design patterns you know and love like strings, dictionaries and delegates have direct equivalents in Mac development. You’ll feel right at home!

However, one big difference with Mac development are there are different controls. Gone are UIButton and UITextField – instead there are similar (but slightly different) Mac variants.

This tutorial will introduce you to some of the more common user interface controls of OS X — the foundation upon which most Mac apps are built. You’ll learn about these controls, as well as the methods and properties you’ll need to understand in order to get up and running as a developer! :]

In this tutorial, you’ll be creating a simple Mac application like the popular game Mad Libs. Mad Libs is a word game where you can insert different words in a block of text in order to create a story — which often has hilarious results!

Once you’ve completed both parts of this tutorial, you’ll have a fundamental understanding of the following controls:

• Labels and Text Fields
• Combo Boxes
• Popup Buttons
• Text Views
• Sliders
• Date Pickers
• Buttons
• Radio Buttons
• Check Buttons
• Image Views

Before you go through this tutorial, you should go through our How to Make a Simple Mac App Tutorial to learn the basics of Mac development.

The best way to learn any new programming platform is to dive right in and get started — so without further ado, here’s your introduction to Core Controls in Mac OS X! :]

Getting Started

Launch the latest version of Xcode 6, and choose File\New\Project. When the Choose a template dialog appears, select OS X\Application\Cocoa Application, which is the template you use to create an app with a GUI on the Mac. Then click Next.

In the project options dialog, enter MadLibs as the product name. Also enter a unique company identifier and make sure to choose Swift as the language:

Click Next. Finally, choose a location where you’d like to save your new project, and click Create.

Once Xcode has finished generating the project files, you’ll be presented with the main Xcode window. Go ahead and click Run in the toolbar. If all goes well, you should see the following:

You’ve built a working application — without any coding at all. The window is empty right now, but you’re going to fill it up with some controls and make it look amazing! :]

Click on MainMenu.xib in the project explorer, and you’ll see a window named “MadLibs” which already contains a view. You’re going to create a view controller that will be the owner of this view.

From the File menu choose New\File, or alternately you can use the keyboard shortcut Command + N. When the Choose a template dialog appears, select OS X\Source\Cocoa Class, as shown below:

Click Next to move on to the the file options dialog. Enter RootViewController as the Class and make it a subclass of NSViewController. Make sure Also create XIB file for user interface is NOT checked, and Swift is the language, then click Next.

Finally, click Create to save the new view controller.

Now you need to create an instance of your new view controller and associate the Main Window’s view with the view controller. Here, you have two choices — you can do it directly in code, or you can do it the quick and easy way: by using the Interface Builder within Xcode! :]

Select MainMenu.xib in the project explorer to open it in Interface Builder. In the lower right-hand corner of the window, you’ll find the the Object Library palette. In the Object Library palette, find View Controller and drag it to the Objects palette on the left-hand side of the window, like so:

By default, this view controller object is an instance of NSViewController, but you’ll need this to be an instance of your RootViewController class instead — you will change that right now.

To do this, click on the newly created view controller object, go to the utilities palette and then select the identity inspector tab. Rename the class to RootViewController, as in the screenshot below:

In order to make your newly created view controller the owner of the window’s content view, you’ll need to connect its view outlet to the main window’s content view.

To do that, select the main window in the Objects palette to display it on the screen, and then select your view controller object. Then, go back to the utilities palette and select the connections inspector tab. From the Outlets section, click and drag the view outlet to the main window. This sequence of events is illustrated in the screenshot below:

And that’s it! You’ve now configured your app to instantiate an instance of your RootViewController class, and you’ve made it the owner of the main window’s content view. And you still haven’t written a single line of code! :]

If you’ve followed the above instructions, then everything should be hooked up properly. But before you go any further, take a minute to ensure that everything’s working by following the steps below! :]

You’re going to override awakeFromNib in your RootViewController class, since this method is part of an object’s life cycle when it’s instantiated from a XIB file. If everything has been connected correctly, then this method will be called when the application runs, and the view controller should have a view associated with it.

Open RootViewController.swift and add the following:

override func awakeFromNib() {
  println("View controller instance with view: \(self.view)")
}

This will simply output some debug code to the console to indicate that (a) this code is called, and (b) that the associated view is valid.

Buld and run your app. In the Output pane of the Debug area, you should a message similar to the following:

View controller instance with view: <NSView: 0x60000012cd00>

If you see the line above (the NSView hex address will be different), then you’ve verified that both the view and the view controller have been instantiated, and the two are connected properly!

Now that the basic framework has been laid down, you can now move on to the main focus of this tutorial — adding controls to your app! :]

Each of the remaining steps in this tutorial will focus on a single, different control. You’ll learn the basics of each control, and then implement each one in the Mad Libs app to try it out.

NSControl – The Building Block of Controls

NSControl is the foundation upon which all other controls are built. NSControl provides three features which are pretty fundamental for user interfaces: drawing controls on the screen, responding to user events, and sending action messages.

As NSControl is an abstract superclass, it’s entirely possible that you’ll never need to use it directly within your own apps. All of the common controls are descendants of NSControl, and therefore inherit the properties and methods defined in NSControl.

The most common methods used for a control are getting and setting the value of that control, as well as enabling or disabling the control itself. Have a look at the details behind these methods below:

Setting The Control’s Value

If you need to display information using a control, you’ll usually do this by changing the control’s value. Depending on your needs, the value can be a string, a number or even an object. In most circumstances you’ll use a value which matches the type of information being displayed, but NSControl allows you to go beyond this and set several different value types!

The methods for getting and setting a control’s value are:

// getting & setting a string
let myString = myControl.stringValue
myControl.stringValue = myString
 
// getting & setting an integer
let myInteger = myControl.integerValue
myControl.integerValue = myInteger
 
// getting & setting a float
let myFloat = myControl.floatValue
myControl.floatValue = myFloat
 
// getting & setting a double
let myDouble = myControl.doubleValue
myControl.doubleValue = myDouble
 
// getting & setting an object
let myObject: AnyObject! = myControl.objectValue
myControl.objectValue = myObject

You can see how the different setters and getters fit with the type-safety of Swift.

Enabling & Disabling a Control

Enabling or disabling a control based on the current state of an app is a very common UI task. When a control is disabled, it will not respond to mouse and keyboard events, and will usually update its graphical representation to provide some visual cues that it is disabled, such as drawing itself in a lighter “greyed out” color.

The methods for enabling and disabling a control are:

// disable a control
myControl.enabled = false
 
// enable a control
myControl.enabled = true
 
// get a control's enabled state
let isEnabled = myControl.enabled

Okay, that seems pretty easy — and the great thing is that these methods are common to all controls; they’ll all work the same way for any control you use in your UI.

Now it’s time to take a look at the more common user interface controls of OS X! :]

Field of Dreams – NSTextField

One of the most common controls in any UI is a field that can be used to display or edit text. Almost any modern application will need to display some sort of text, such as a RSS reader, a Twitter client, or an address book, and almost all applications require some sort of text enty to log in, change settings, or to provide other inputs to the app.

The control responsible for this functionality in OS X is NSTextField.

NSTextField is used for both displaying and editing text. You’ll notice this is quite different than iOS, where UILabel is used to display text, and UITextField to edit it. In OS X, these two controls are combined into one, and the behaviour of the control is modified via setting the control’s properties.

If you want a text field to be a label, you simply set it as non-editable. To make the text field editable — yup, you simply set the control to be editable! These properties can either be modified programmatically or from Interface Builder.

To make your coding life just a little easier, Interface Builder actually provides several pre-configured controls for displaying and editing text which are all based on NSTextField. These pre-configured controls can be found in the Object Library, and are described in the graphic below:

So now that you’ve learned about the function of NSTextField, you can now add one to your Mad Libs application! :]

Living in the Past — A Past Tense Verb

In the Mad Libs application you’ll be building, you will add various UI controls which will allow the user to blindly construct a funny sentence, without knowing the final result. Once the user has finished, your app will combine all the different parts and display the result, hopefully with some comedic value. The more creative the user is, the more fun they’ll have! :]

The first control you’ll add is a text field where the user can enter a verb to be added to the sentence, as well as a label to inform the user what the text field is for.

Select MainMenu.xib in the project explorer to open it in Interface Builder, and then select the Main Window. In the Object Library palette, locate the Label control and drag it onto the window. Double-click the label to edit the default text, and change it to Past Tense Verb:.

Next, locate the Text Field control and drag it onto the window, placing it to the right of the label.

You should now have something similar to this:

Later on, you’re going to need to interact with the text field, and to do this you’ll need an outlet on the view controller.

To create this property and connect it so that you can work with it, open the assistant editor — making sure that RootViewController.swift is selected — and Ctrl-Drag the text field to the class interface to create a new property, like shown below:

In the popup window that appears, name the Outlet pastTenseVerbTextField, and click Connect, as shown in the image below:

And that’s it! You now have an NSTextField property in your view controller that is connected to the text field in the main window.

You know, it would be great to display some sample default text when the app launches, in order to give the user an idea of what to put in the field. Since everyone loves to eat, and food related Mad Libs are always the most entertaining, the word ate would be a tasty choice here! :]

A good place to put this is inside awakeFromNib. To change the text field’s default value, simply set the stringValue property you learned about earlier.

Add the following code to the end of awakeFromNib:

// Set the default text for the pastTenseVerbTextField property
pastTenseVerbTextField.stringValue = "ate"

Build and run your app. You should see the two controls you’ve just added, and the text field should display the word ate, as below:

Okay, that takes care of a single input with a default value. But what if you want to provide a list of values that the user can select from?

Combo Boxes to the rescue! :]

The Value Combo – NSComboBox

A combo box is interesting — and quite handy — as it allows the user to choose one value from an array of options, as well as enter their own text.

It looks similar to a text field in which the user can type freely, but it also contains a button that allows the user to display a list of selectable items. You can find a solid example of this in OS X’s Date & Time preferences panel:

Here, the user can select from a predefined list, or enter their own server name, if they wish.

The control responsible for this in OS X is NSComboBox.

NSComboBox has two distinct components: the text field where the user can type, and the list of options which appear when the embedded button is clicked. You’re able to control the data in both parts separately.

To get or set the value in the text field, simply use the stringValue property covered earlier. Hooray for keeping things simple and consistent! :]

Providing options for the list is a little more involved, but still relatively straightforward. You can call methods directly on the control to add elements in a manner similar to NSMutableArray, or you can use a data source — anyone familiar with iOS programming and UITableViewDataSource will feel right at home!

Method 1 – Calling Methods Directly On The Control

NSComboBox contains an internal list of items, and exposes several methods that allow you to manipulate this list, as follows:

// Add an object to the list
myComboBox.addItemWithObjectValue(anObject)
 
// Add an array of objects to the list
myComboBox.addItemsWithObjectValues([objectOne, objectTwo, objectThree])
 
// Remove all objects from the list
myComboBox.removeAllItems()
 
// Remove an object from the list at a specific index
myComboBox.removeItemAtIndex(2)
 
// Get the index of the currently selected object
let selectedIndex = myComboBox.indexOfSelectedItem
 
// Select an object at a specific index
myComboBox.selectItemAtIndex(1)

That’s relatively straightforward, but what if you don’t want your options hardcoded in the app — such as a dynamic list that is stored outside of the app? That’s when using a datasource comes in really handy! :]

Method 2 – Using A Data Source

When using a data source to populate the combo box, the control will query the data source for the items it needs to display as well, as any necessary metadata, such as the number of items in the list.

To use a data source, you’ll need to implement the NSComboBoxDataSource protocol in your class. From there, it’s a two-step process to configure the combo box to use the data source.

First, set the control’s dataSource property, passing an instance of the class implementing the protocol; usually “self”. Then set the control’s usesDataSource property to “true”.

myComboBox.dataSource = self
myComboBox.usesDataSource = true

In order to conform to the protocol, you’ll need to implement the following two methods:

// Returns the number of items that the data source manages for the combo box
func numberOfItemsInComboBox(aComboBox: NSComboBox!) -> Int {
  // anArray is an NSArray variable containing the objects
  return anArray.count
}
 
// Returns the object that corresponds to the item at the specified index in the combo box
func comboBox(aComboBox: NSComboBox!, objectValueForItemAtIndex index: Int) -> AnyObject! {
  return anArray[index]
}

Finally, whenever you need to reload the data in a combo box which is using a data source, simply call reloadData().

Which Method To Use?

If your list of items is relatively small and you don’t expect it to change that often, adding items once to the internal list is probably the best choice. But if your list of items is large or dynamic, it can often be more efficient to handle it yourself using a data source. For this tutorial you’ll be using method 1.

Now that you’ve covered the fundamentals of the combo box, move on to implement one in your app! :]

The Singles Bar — A Singular Noun

In this section you’ll add a combo box to your Mad Libs application, to allow the user to enter a singular noun. They can either choose from a list or enter their own.

To do this, first add a Label to the app so that the user knows what the control is for. Select the MainMenu.xib in the project explorer to open it in Interface Builder, and then select the Main Window.

In the Object Library palette, locate the Label control and drag it onto the window. Double-click it to edit it’s default text, changing it to Singular Noun:.

Next, add the combo box that will provide the users with the list of choices. Locate the Combo Box control and drag it onto the window, placing it to the right of the label.

Your window should now look like this:

Now you need to add an NSComboBox outlet to the view controller so you can populate the default items, and later access it via code to read the user’s selection.

To do this, use the same technique you used for the text field: select the assistant editor (making sure RootViewController.swift is selected) and Ctrl-Drag the combo box to the RootViewController.swift to create a new property, just like in the screenshot below:

In the popup window that appears, name the property singularNounCombo.

Now the NSComboBox property is connected to the combo box control! Now, if you only had some data to populate the list! :] Time to add some.

Open RootViewController.swift in the code editor and add the following property declaration directly below the singularNounCombo property:

var singularNouns: [String]!

Inside awakeFromNib, add this to the bottom:

// Setup the combo box with singular nouns
singularNouns = ["dog", "muppet", "ninja", "fat dude"]
singularNounCombo.removeAllItems()
singularNounCombo.addItemsWithObjectValues(singularNouns)
singularNounCombo.selectItemAtIndex(2)

The first line initializes an array with four strings. The second line removes any items added by default. Next items are added to the combo box using one of the methods covered earlier. Finally, the combo box is asked to select the item at index 2 so that “ninja” is the default value.

Build and run the application to see your combo box in action!

Great — it looks as though everything is working just right. If you click on the combo box, you can then view and select any of the other items.

Now what if you want to present the user with a list of choices, but not allow them to enter their own text? Read on — there’s a control for that as well! :]

Pop Goes the Weasel — NSPopupButton

The pop up button allows the user to choose from an array of options, but without giving the user the option of entering their own value in the control. The control responsible for this in OS X is NSPopupButton.

Pop up buttons are incredibly common in OS X, and you can find them in almost every application — including the one that you’re using right now: Xcode! :] You’re using the pop up button to set many of the properties on the controls you’re using in this tutorial, as in the screenshot below:

Filling the Spaces — Adding Items To Pop Up Buttons

As you might expect, adding items to NSPopUpButton is similar to adding items to NSComboBox — except that NSPopUpButton doesn’t support using a data source for the content of the control. NSPopUpButton maintains an internal list of items and exposes several methods allowing you to manipulate it:

// Add an item to the list
myPopUpbutton.addItemWithTitle("Pop up buttons rock")
 
// Add an array of items to the list
myPopUpbutton.addItemsWithTitles(["Item 1", "Item 2", "Item 3"])
 
// Remove all items from the list
myPopUpbutton.removeAllItems()
 
// Get the index of the currently selected item
let selectedIndex = myPopUpbutton.indexOfSelectedItem
 
// Select an item at a specific index
myPopUpbutton.selectItemAtIndex(1)

Pretty straightforward, isn’t it? That’s the beauty of the core controls — there are a lot of similarities between them in terms of the methods used to manipulate the controls.

Time to implement a pop up button in your app! :]

The More the Merrier — A Plural Noun

You’ll now add a pop up button to your Mad Libs application which will allow the user to choose between different plural nouns to populate your comical sentence.

Select MainMenu.xib in the project explorer to open it in Interface Builder, and then select the Main Window. In the Object Library palette, locate the Label control and drag it onto the window just beneath the Singular Noun label.

Double-click the control to edit its default text, and change it to Plural Noun:. Next, locate the Pop Up Button control and drag it onto the window, placing it to the right of the label.

Your window should now look like this:

Now you need to add an NSPopUpButton outlet to the view controller. You’ll use the same technique as before, which should be fairly familiar by now: open the assistant editor, make sure RootViewController.swift is selected, and then Ctrl-Drag the pop up button to the RootViewController.swift to create a new property. This is illustrated in the screenshot below:

In the popup window that appears, name the property pluralNounPopup:

Okay, now the outlet is connected to the pop up button control. Now you just need some data to populate it!

Open RootViewController.swift in the code editor and add the following property declaration directly below the pluralNounPopup property.

var pluralNouns: [String]!

Add the following code to the bottom of awakeFromNib:

// Setup the pop up button with plural nouns
pluralNouns = ["tacos", "rainbows", "iPhones", "gold coins"]
pluralNounPopup.removeAllItems()
pluralNounPopup.addItemsWithTitles(pluralNouns)
pluralNounPopup.selectItemAtIndex(0)

The first line in the code above initializes an array with four strings. The second line removes any existing items from the pop up button. The third line adds the array of items to the pop up button using some of the methods covered earlier. Finally, the pop up button is instructed to select the first item in the list as the default.

Build and run the application to see the result:

Once the app has launched, note that the pop up button shows the initial item, tacos, and if you click on the pop up button, you’ll see all the other items in the list.

Okay, so you now have two controls that allow the user to select from lists, as well as a control that allows the user to enter a single line of text. But what if you need the user to enter more than a few words in a text field?

Read on to learn about text views! :]

Text is Next – NSTextView

Text views, unlike text fields, are usually the control of choice for displaying rich text. Some implementations even allow for more advanced features such as displaying inline images.

The control responsible for this on OS X is NSTextView.

A great example of an application using all of what NSTextView has to offer is TextEdit, as shown in the screenshot below:

NSTextView is so feature rich that to cover everything would warrant a tutorial of its own, so here you’ll just see a few of the basic features in order to get you up and running! (Did you just breathe a sigh of relief?) :]

Here are the basic methods you’ll need to work with text views:

// Get the text from a text view
let text = myTextView.string
 
// Set the text of a text view
myTextView.string = "Text views rock too!"
 
// Set the background color of a text view
myTextView.backgroundColor = NSColor.whiteColor()
 
// Set the text color of a text view
myTextView.textColor = NSColor.blackColor()

Relatively simple — nothing too shocking here! :]

The String’s the Thing — Attributed Strings

NSTextView has built-in support for NSAttributedString. If you pass an attributed string to a text view, the string will be displayed correctly using all the appropriate attributes such as font, font size, and font color.

NSTextView has a property called textStorage, whose type is NSTextStorage. NSTextStorage is a semi-concrete subclass of NSMutableAttributedString, which is a fancy way of saying “you can put formatted text in it, and change it later.”

In order to have NSTextView display an attributed string, you actually set the attributed string on the NSTextStorage instance returned by the textStorage property, as shown in the code below:

// Setting an attributed string on the NSTextStorage instance owned by our NSTextView
var myAttributedstring = NSMutableAttributedString(string: "Red Green")
myAttributedstring.addAttribute(NSForegroundColorAttributeName, value: NSColor.redColor(), range: NSMakeRange(0, 3))
myAttributedstring.addAttribute(NSForegroundColorAttributeName, value: NSColor.greenColor(), range: NSMakeRange(4, 5))
 
myTextView.textStorage.setAttributedString(myAttributedstring)

So that’s how to set the text view’s (attributed) string!

The Phrase that Pays – Adding a Text View

Looks like you have everything you need in order to add a text view to your Mad Libs application! This text view will allow the user to enter a multi-word phrase that will be used in the final rendered Mad Lib.

To add the text view to your application, open MainMenu.xib and then select the Main Window. In the Object Library palette, locate the Label control and drag it onto the window just beneath the Plural Noun label (or duplicate an existing label, as mentioned earlier).

Again, double-click it to edit the default text, changing it to Phrase:. Next, locate the Text View control and drag it onto the window, placing it beside the the label you just created.

Your window should now look like this:

Now you need to add an NSTextView outlet to the view controller. Again, the same familiar technique is similar to before, but there’s a twist.

Important: Since text views are contained inside scroll views, it’s important you make sure you’ve actually selected the text view before creating the outlet. To do so, simply click twice on the text view or select it from the Object navigator on the left. You can check the text view has been selected by inspecting the Type in the popup window.

Once you’re sure you have the text view selected, as before select the assistant editor, make sure RootViewController.swift is selected, and Ctrl-Drag the text view to the RootViewController.swift. The result is shown below:

In the popup window, name the property phraseTextView, as shown here:

Now that the NSTextView property is connected to the text view control, you can set a default text phrase in the control to again give the user an idea of what to enter here.

Add the following code to the end of awakeFromNib:

// Setup the default text to display in the text view
phraseTextView.string = "Me coding Mac Apps!!!"

Build and run the application to see the result! :]

Superb! The Mad Libs application is really starting to take shape now! :]

Pushing Your Buttons — NSButton

Buttons are controls designed to send a message to an app whenever they’re clicked by a user. An app associates an action with the button which is executed whenever the button is clicked.

The control responsible for this on OS X is NSButton.

On OS X there are many different styles of buttons which are viewable Interface Builder’s Object Library. They all work in much the same way, the only difference being their visual representation. The different types of Buttons are shown in the image below:

You should use the style of button that best suits your application’s design — refer to the OS X Human Interface Guidelines for advice and guidance on best design practices for your app.

Typically, when working with a button, you’ll simply need to associate an action with the button and set its title. However, there may be times when you need to disable the button, or change its appearance. The following methods allow you to perform these actions on your button:

// disable a button
myButton.enabled = false
 
// enable a button
myButton.enabled = true
 
// getting & setting a button's title
let theTitle = myButton.title
myButton.title = theTitle
 
// getting & setting a button's image
let theImage = myButton.image
myButton.image = theImage

Looks fairly simple — adding a button to your app in the next section should be a breeze!

Buttoning Things Down — Adding a Button

Find the Push Button in the Object Library palette and drag it onto the window, changing its title to Go!, like so:

Since you’re not going to manipulate the button in any way beyond letting the user click it, you don’t need to create an outlet for the button. However, you do need to create an action and associate it with the button, so that your app knows what to do when the button is pushed! :]

Just as before, Ctrl+Drag the button to the RootViewController.swift file and release just above awakeFromNib, as in the screenshot below:

In the popup window that appears, make sure that the connection is set to Action. Name the action goButton.

The goButton method will be invoked by the app whenever the user clicks on the button. For now you’ll add some debug code — just to make sure everything’s working!

Add the following code to goButton::

// Past tense verb
let pastTenseVerb = pastTenseVerbTextField.stringValue
 
// Singular noun
let singularNoun = singularNounCombo.stringValue
 
// Plural noun
let pluralNoun = pluralNouns[pluralNounPopup.indexOfSelectedItem]
 
// Phrase
let phrase = phraseTextView.string ?? ""
 
// Create the mad lib sentence
println("A \(singularNoun) \(pastTenseVerb) \(pluralNoun) and said, \(phrase)!")

Note that for the text view, the string property is actually an optional so it could be nil. To guard against that case, you’re using the nil coalescing operator ?? so if string is nil, you’ll get the empty string "" instead.

That’s all the code you need for now — build and run your app! :] It should look like the screenshot below:

Every time you click the button, you should see a short and silly sentence appear in Xcode’s console.

Where to Go From Here?

Here’s the example project containing all the source code from this tutorial up to this point.

In the second part of this tutorial, you’ll learn about more of the core controls in OS X, including sliders, date pickers, radio buttons, check boxes and image views — each of which will be added to your Mad Libs application in order to complete it!

In the meantime, if you have any questions or comments about what you’ve done so far, join in the forum discussion below!

Introduction to OS X Tutorial: Core Controls and Swift Part 1/2 is a post from: Ray Wenderlich

The post Introduction to OS X Tutorial: Core Controls and Swift Part 1/2 appeared first on Ray Wenderlich.