Unit 1: Getting Started|Introduction

So far in this unit, you've learned the basics of Xcode and Interface Builder. You'll now apply your knowledge of these tools by building a project.

By the end of this Guided Project, you'll have created an app, called Light, that changes the screen from black to white, and back again, whenever the user taps a button. To successfully build the light, you'll need to use Xcode documentation, set breakpoints, and create outlets and actions.

This project will involve modifying some code—even though you're relatively new to the Swift language. Don't be discouraged if you struggle with the code-specific pieces of the project. Just keep at it!

Part One — Create a Button and an Action

Create a new Xcode project using the Single View App template that you've used in previous lessons. Name the project "Light". When you build and run the project, you'll notice there's nothing for the user to interact with. You'll be changing that soon.

Select Main.storyboard in the project navigator to open your storyboard in Interface Builder.

Selecting storyboard from Project Navigator

The initial interface created by Xcode includes an instance of ViewController. ViewController is a subclass of UIViewController that comes predefined as part of the Single View App template and is listed in the project navigator. You can click the Show Document Outline button Square icon with a stripe along its left edge 1 to reveal all the view controllers defined in Main.storyboard.

View Controller in Document Outline

Select View Controller in the document outline,1 then click the Identity inspector button at the top of the utilities area, to confirm that this particular view controller is of type ViewController.

Custom class of type ViewController

If you're using Simulator, use the "View as" button at the bottom of the canvas to adjust the size of the canvas. Set the canvas size to the iPhone 11 Pro configuration, and select the iPhone 11 Pro simulator from the menu toward the left end of the Xcode toolbar.

If you're using your own device for this project, the size of the view controller may not be identical to the size of your screen. Use the "View as" button at the bottom of the canvas to adjust the size of the canvas to match your device, but leave it in portrait orientation.

Changing canvas size

Changing Simulator size

Select the view controller's view, then select the Attributes inspector , which will allow you to customize the attributes of any interface element. The background color for this view has already been set to white. That's the desired state of your app on launch, so you don't need to change anything right now.

Next, add a button that’ll be used to change the view's background color, simulating a light turning on and off. Press the + button at the top right of the toolbar to open the Library. As you learned in an earlier lesson, this library includes a list of common objects you can add to a storyboard. Scroll through the list, or use the search filter at the top of the library area.

Object Library, filtering buttons

Find the "Button" object in the library and drag it over on top of the view. When you release the cursor, the document outline should indicate that the button has been added as a subview.1

Button added to canvas

Move the button to the upper-left corner of the view. Margin-alignment guides will help snap the object into the correct position.1

Button alignment with margin guides

Give your button an action to perform when it's clicked or tapped. Add an assistant editor using the Adjust Editor Options button and choose Assistant Editor1 to split the Xcode workspace into two parts: Interface Builder and its corresponding code.

Assistant Editor Option

Assistant editor split screen active

Now Control-drag (or right-click) the button into an available area within the ViewController class definition. As you drag, a blue line extends from the button and a blue horizontal bar will display below your cursor, indicating a valid place to create a connection.1

When you release the mouse cursor, you will be prompted to create an outlet or define an action. Change Connection to Action, then set Name to "buttonPressed".1 When you click the Connect button, Xcode will create a new method that will be called whenever the button is tapped. You may notice the @IBAction keyword right before the buttonPressed(_:) method. @IBAction signals to Xcode that a relationship can be created between a visual element in a storyboard and the function.

Proper selections in popup for creating an action to the button

Build and run the app. When you press the button, nothing happens, because there's no code within the buttonPressed(_:) method to execute. To verify that the method is being called, you can place a breakpoint within the method definition. Now press the button and the breakpoint will be triggered.1

Xcode breakpoint trigger

Now that you've verified that the action is working correctly, you can add some code to change the background color. Remove the breakpoint before proceeding.

Part Two - Change the Background

If the light is on (that is, if the background color is white) then the light should be switched off. Otherwise, if the light is off (the background is black), then the light should be switched on. The statement, "The light is on", is either a true or false statement, so it would make sense to use a Boolean to determine how to change the background color.

Near the top of the ViewController class definition, create a variable called lightOn and set the initial value to true, since the screen starts off with a white background.

var lightOn = true

Each time the button is tapped, the value should change from true to false, or from false to true. Swift booleans have a method, toggle(), that does precisely this. Since the buttonPressed(_:) method is called whenever the tap is executed, make the change there.

@IBAction func buttonPressed(_ sender: Any) {
    lightOn.toggle()
}

After the value has been changed, you can use the new value to determine how to change the background color. If the light is supposed to be off, change it to black. Or if it's supposed to be on, change it to white. You can write this logic using a simple if-statement.

@IBAction func buttonPressed(_ sender: Any) {
    lightOn.toggle()
    if lightOn {
      view.backgroundColor = .white
    } else {
      view.backgroundColor = .black
    }
}

Build and run your application, and the background should successfully change on each press. Great job!

As your application’s size continues to grow, make sure that your code stays organized. Rather than put the if-statement directly inside the buttonPressed(_:) method, you can move it to a new method that handles updating the entire user interface.

Extract to Method

Select the entire if-statement,1 and then choose Editor > Refactor > Extract to Method.2

Extract to Method Renaming

Xcode moves the code out of place into a new method and enters a special editing mode that allows you to set the new method's name and update where it’s called at the same time. Type updateUI and press the Return key to set the name.1

Xcode moved the selected code into a new method named updateUI(), and then added a call to updateUI() where the code once lived.

The result should look like the following:

fileprivate func updateUI() {
  if lightOn {
    view.backgroundColor = .white
  } else {
    view.backgroundColor = .black
  }
}

@IBAction func buttonPressed(_ sender: Any) {
    lightOn.toggle()
    updateUI()
}

Notice the fileprivate keyword that Xcode used in front of the method name. Swift uses this special access modifier to specify where the method can be called from. If you use the Xcode refactor feature and need to call your method outside of the file it’s defined in, remove the fileprivate keyword in front of it.

This is a small change for a small app. You will see this pattern persist throughout this book, and you will find it much easier to debug interface issues if the code that updates the view is all contained in a single method.

Part Three — Update the Button Text

You've now successfully set the button to change the background color of the view, but the title of the button text remains the same no matter the state of the light. At the moment, there's no way to reference your newly created button in code. You must first create an outlet to the button. Control-drag the button in Interface Builder to an empty space at the top of the view controller's definition in the editor area. In the popover, verify that Outlet is selected under Connection, and enter "lightButton" in the Name field.

The popover menu should look like this:1

Proper selections in popup for creating an outlet to the button

Click Connect.

As you learned in an earlier lesson, you're able to see these details of the outlet, from left to right:

Circle — The filled circle indicates that the outlet is connected. The circle would be empty if the property isn't connected to anything.
@IBOutlet — This keyword signals to Xcode that the property on this line is an outlet.
var lightButton — This declares a property called "lightButton."
UIButton! — The type of the property is UIButton!. The exclamation point warns you that the program will crash if you try to access this property and the outlet isn't connected. You'll learn more about the exclamation point when you learn about optionals in a later unit.

Having created the outlet, you can now make changes to the button programmatically. Start by finding the right place for updating the button's title and the right action for it to perform.

Add a breakpoint to the first line of the buttonPressed(_:) method, then build and run your app. As you might expect, when you press the button to change the color, the corresponding action, buttonPressed(_:), will be executed. But since you added a breakpoint, the code will pause before executing the line with the breakpoint.1

Triggering breakpoint in function

Click the "Step over" button Step Over button 2 to run the first line. Now your app is paused just before running the updateUI() method. Click the "Step into" button Step Into button .3 Now the app is paused just before executing the first line of updateUI.

Code for the updateUI function

Take a moment to try and read the body of the updateUI() method. 1 Since Swift is a very readable programming language, you can probably interpret the lines to say: "If the light is on, the view's background color should be white, or else the view's background color should be black."

Now consider how the button's title should be decided. If the light is on, the button's title should read "Off," or else the button's title should read "On." It makes sense that the button's title should be updated in a similar way to the view's background color.

You've now found a reasonable place to update the text—in the updateUI() method. But what's the actual function for doing so? As you learned earlier, Xcode documentation is always available to support you. So whenever you're unsure of something, it's a good habit to look to the documentation for answers.

To learn how to set the title of lightButton, start by reading the documentation on its type, UIButton. You can access the documentation directly using Window > Developer Documentation from the Xcode menu. This opens a separate window with the documentation viewer.

Xcode documentation reference window

Start entering UIButton in the documentation search field. Autocompletion quickly suggests options. As soon as you see UIButton in the menu, go ahead and select it.1

Searching for UIButton in documentation window

Scroll down to the Symbols section to find a list called "Configuring the Button." There you'll find a function to set the title: func setTitle(String?, for: UIControl.State).

Click the function name to see its declaration and a list of its parameters.1 The first parameter is the desired text, and the second parameter is a UIControl.State. UIControl.State represents the different potential states of a button, for example: if it is sitting idle, if the user has begun tapping it, or if the button is disabled. Click UIControl.State in the Declaration section.

Selecting UIControl.State to view its documentation

In this new list of symbols, the Constants section contains a normal constant,1 which corresponds to the state of the button when it's enabled and sitting idle on the screen. This is the correct state for setting the button's title.

Finding the constant in UIControl.State's documentation

With your new knowledge of the updateUI() method, you can remove the breakpoints you added earlier and adjust the method to look like the following:

func updateUI() {
  if lightOn {
    view.backgroundColor = .white
    lightButton.setTitle("Off", for: .normal)
  } else {
    view.backgroundColor = .black
    lightButton.setTitle("On", for: .normal)
  }
}

Build and run your app. Clicking or tapping the button should now change both the background color and the button text. But there's a bug: Before the button is clicked, the text still reads "Button," not "On" or "Off." How can you update the code to resolve this issue?

Your project already has code that will make sure the button's text matches the on or off state of the light: updateUI(). You just need to call it when the view first loads—so that the button is updated when the view appears, instead of when the user first taps the button. You can run setup code in the viewDidLoad() function, which is already defined in your view controller subclass and is called when the view controller is ready to appear on the screen.

Call updateUI() within this method, as shown in the following example:

override func viewDidLoad() {
    super.viewDidLoad()
    updateUI()
}

Build and run your app again. On launch, the text of the button should now read "On."

Part Four–Improve the User Experience

You have an app that works. That's a great start. Now take a moment to think about its design and how the user experiences the app. What could be improved?

Looking at the button, you might realize that the text feels extraneous. It's pretty clear whether the light is currently on or off—the background color indicates that. Does the user need to see the text at all?

Does it matter where on the screen the button is located? And isn't it a little odd that most of the screen isn't tappable?

It may be better to remove the text from the button and to make the button fill the entire screen. That way, the user can tap anywhere on the screen to turn the light on and off. An important part of building any app is considering the little details and trying to build an intuitive, simple, powerful user interface. In this case, it makes sense for the user to be able to tap anywhere on the screen to toggle the background color.

To begin, you'll need to resize the button to fill the screen. Select the button in Interface Builder, then drag its top-left and bottom-right corners, extending the button to cover the entire white view.1

Full-sized button

Remove the title text for the button. The tappable area of the button will still perform as expected, but it will now appear as though only the white view exists on the canvas.1

Fullscreen button with no text

With the text gone, you can remove the lines of code in updateUI() that make changes to the button's title.

func updateUI() {
    if lightOn {
        view.backgroundColor = .white
    } else {
        view.backgroundColor = .black
    }
}

In this updated design, the button's properties don't need to change while someone is using the app. That means the outlet—which you created at the beginning of the project—is no longer needed. As a developer, you want to keep your code as clean as possible, so it's a good idea to clear out the IBOutlet.

First, sever the connection between the button and its outlet. To do so, select the button in Interface Builder, then show the Connections inspector . Here you can see all the events and outlets connected to a particular object. In this case, you can see that the button is tied to the buttonPressed: action and to the lightButton outlet. Click the X next to the outlet to remove it.1

Removing button's outlet to lightButton variable

Since there are no longer any objects connected to lightButton, the little circle next to @IBOutlet is no longer filled in.1

Hollow circle indicating no connections to this outlet

It's now safe to delete the declaration of lightButton. Build and run your app one last time to test your new design improvements. You should now be able to tap or click anywhere on the screen to change its background color.

Because both lines in the if-else statement do the same thing (set the backgroundColor), the updateUI() method might look cleaner if you use a ternary operator instead of an if-else statement.

func updateUI() {
  view.backgroundColor = lightOn ? .white : .black
}

Build and run your application once more to verify that the ternary operator works as intended.

Wrap-up

You've successfully created an app that changes the screen from black to white, and back, at the tap of a button—something like a flashlight. You've simplified the design of the app as well, making conscious decisions to improve the user experience by removing the button title and filling the screen with a tappable area. Even though you have limited knowledge of Swift, you were able to step through lines of code and refer to the documentation to complete this project.

Did you find it difficult to navigate Xcode or use Interface Builder? If so, revisit the previous lessons that discussed them in more detail. You'll find that the more you build, the more familiar it becomes.

As you move onto the next unit, keep the developer documentation handy. Developers are only as good as the tools and resources they use.