GettingStarted

iOS Tutorial

From Xojo Documentation

This iOS Tutorial is for people who are new to programming and new to Xojo. It is an introduction to the Xojo development environment and will lead you through the development of a real iOS app.

It should take you about an hour to complete this tutorial. If you would like a shorter introduction to Xojo for iOS, take a look at the iOS QuickStart.

If you have experience with other programming languages, you’ll also want to check out the User Guide and Reference Guide.

Getting Started

Launch Xojo. After it finishes loading, the Project Chooser window appears.

iOS Tutorial Project Chooser.png

Xojo lets you build several different types of apps (Desktop, Web, Console and iOS). For this Tutorial, you are building an iOS app, so click on iOS.

fa-info-circle-32.png
 You have to be using Xojo on a Mac in order to create iOS projects.

You should now see three fields that need values: Application Name, Company Name and Application Identifier.

  • Application Name is the name of your app. This will be the filename of the actual app file that gets created.
  • Company Name is the name of your company. You may choose to leave this blank.
  • Application Identifier is a unique identifier for this app. It will automatically populate using what you enter for the Application and Company Names, but you can also change it to whatever you want.

Enter "TaskManager" as the Application Name. You can leave Company Name as it is or change it. Click OK to open the main Xojo window (called the Workspace), where you will begin designing your app.

Workspace

Xojo opens the Workspace with the default View for your app selected in the Navigator and displayed in the Layout Editor.

iOS Tutorial Workspace.png

Navigator: The area on the top left shows you all the items in your project. By default you can see View1 (which is selected), the App object, the Screen objects and items for the App Icon and optional Launch Screen. You use the Navigator to navigate within your project.

Layout Editor: The center area is the Layout Editor. You use the Layout Editor to design the user interface for the Views in your app. It shows the View and previews how it looks when the app runs on an iOS device. In this image, the View is blank because you haven't yet added any user interface controls from the Library.

Library: The area on the right is the Library and shows the controls and interface elements that you can add to a View or to the project. You design the View by dragging controls from the Library to the View layout. You can also add a control to the View by double-clicking it. You can change how the controls display in the Library by clicking the small gear icon and choosing a different setting.

If the Library is not visible, click the Library button on the toolbar to show it.

Inspector: Not shown in the above image is the Inspector, which allows you to see and change the properties for the selected control. This area of the Workspace window is shared with the Library. You can show the Inspector by clicking the Inspector button on the toolbar. The Inspector shows information about the selected item in the Navigator or Editor. The contents of the Inspector changes as you click on different items. You change an Inspector value by entering a new value in the field to the right of the field label.

About the App

In this tutorial you will create an app to manage tasks. Not surprisingly it is called Task Manager.

iOS Tutorial Task Manager.png

Task Manager

For the Task manager app, you enter tasks in the text field and tap Add to add them to the table. You can tap on individual tasks in the table to delete them or mark them as complete.

Task Manager uses these controls:

  • TextField: An iOSTextField control is used to enter text. In this project, the task to add is entered into an iOSTextField at the top of the view.
  • Button: An iOSButton is used to trigger an action. This project uses an iOSButton to add a task to the table.
  • ToolButton: An iOSToolButton is also used to trigger an action, but this button is contained in the toolbar at the bottom of the view.
  • Table: An iOSTable is used to display a list of data. In this project, it is what displays the tasks entered in the TextField.

The next sections walk you through creating the user interface and adding the necessary code to make the app work.

Designing the User Interface

You should have Xojo running and View1 open in the Layout Editor. You are now going to add the controls to the View and position them.

Button

First add the Button that is used to add a task to the table.

  1. In the Library, click on Button and drag it to the View so that it is at the top right.

TextField

The Text Field is where the user types the Task to add to the list.

  1. In the Library, click on TextField and drag it to the View so that it is at the top left, next to the button.

Table

The Table displays the tasks.

  1. Add the Table: In the Control Library, click on the Table and drag it to the center of the Layout Editor below the Button and TextField. As you drag the Table onto the View, you will see alignment indicators that help you position the control. Drop the Listbox when you are happy with its position on the View.

ToolButtons

ToolButtons work like buttons but they appear in the toolbar at the bottom of the view.

  1. Add the Complete button: In the Library, click on ToolButton and drag it to the bottom right of the view.
  2. Add a Flexible Space: In the Library, click on ToolButton and drag it to the bottom of the view just to the right of the Complete button. You will change this to an actual Flexible Space when you modify properties in the next section.
  3. Add the Delete button: In the Library, click on ToolButton and drag it to the bottom of the view just to the right of the Flexible Space button.

After adding all the controls, your View should now look like this:

iOS Tutorial Initial Layout.png

Properties

What is a Property?

A property is a value of a class. Changing property values allows you to change the behavior of the object. For this project, you want to change various properties for the view and the controls you added. Some of the things you need to do are:

  • Rename all controls (and the view) so that they describe their behavior and are easy to refer to in code.
  • Add a Caption to the Button and ToolButtons.
  • Set auto-layout properties so that the controls resize properly for different sized iOS devices.

Inspector

The Inspector is used to change view and control properties. It shares the same area on the right of the Workspace as the Library. In order to show the Inspector, click the Inspector button on the toolbar or press ⌘-I.

View Properties

If you haven’t already, display the Inspector by clicking the Inspector button on the toolbar. You need to change the Name, NavigationBarVisible and Title properties of View1:

  1. In the Layout Editor click anywhere on the background (or phone UI) to select the View (rather than a control). The Inspector now shows the properties of the view.
  2. In the Name field (located in the ID group), change the name from “View1” to “TaskManagerView”. Press Return to see the name change in the Navigator.
  3. Set the NavigatorBarVisible property to ON.
  4. In the Title field (located in the Behavior group), change the name from “Untitled” to “Task Manager”. Press Return to see the name change in the Navigation Bar of the view.

You may notice that some of the controls overlap the Navigation Bar area at the top. That is OK for now. You'll fix this when you adjust the auto-layout rules for the controls.

Button Properties

For the button you'll change the Name and Caption properties and Auto-Layout rules.

  1. Click the Button to select it. The Inspector now shows its properties.
  2. In the Name field of the Inspector, change the name from "Button1" to "AddButton". Press return to see the name change in the Navigator.
  3. In the Caption field, change the text from "Untitled" to "Add".

There are several auto-layout rules you'll want to change so that the button positions properly.

  1. In the Auto-Layout section, select the "Top" rule and and click the Edit button.
    1. Change Relative To to be "TopLayoutGuide".
    2. Change Edge to be "Bottom".
    3. Change Offset to "Standard".
    4. Click Done.
    5. The Add button is now positioned below the Navigation Bar.
  2. Click the "+" in the Auto-Layout section and choose "Right" from the list. This displays the Rule editor.
    1. Change Edge to "Right".
    2. Change Offset to "Standard".
    3. Click Done.
  3. Select the "Left" rule in the Auto-Layout section and then click the "-" button to remove it. With the "Right" rule in place, the left rule is not needed.
  4. Select the "Width" rule i the Auto-Layout section and click the Edit button.
    1. Change the Offset value to "50".
    2. Click Done.

This is how the auto-layout rules for the button should look:

iOS Tutorial Button Auto-Layout Settings.png

TextField Properties

The TextField is where the user types the task to add to the Table. You'll be changing the Name, Text and Placeholder properties and Auto-Layout rules.

  1. Click on the TextField to select it so that its properties are displayed in the Inspector.
  2. In the Name field of the Inspector, change the text from "TextField1" to "TaskField". Press Return to see the name change in the Navigator.
  3. In the PlaceHolder field, add the text "Enter a task".
  4. In the Text field, remove the text "Untitled" and leave the field blank.

Now you can change the auto-layout rules so that the TextField is positioned and sized properly.

  1. In the Auto-Layout section, select the Top rule and click the Edit button. If there is no Top rule, you can add it.
    1. Change Relative To to be "TopLayoutGuide".
    2. Change Edge to be "Bottom".
    3. Change Offset to "Standard".
    4. Click Done.
  2. Click the "+" in the Auto-Layout section and choose "Right" from the list. This displays the Rule editor.
    1. Change Relative To from "Parent" to "AddButton".
    2. Change Edge to "Left".
    3. Change Offset to "Standard".
    4. Click Done.
  3. Select the "Width" rule in the Auto-Layout section and then click the "-" button to remove it. With both "Left" and "Right" rules in place, the "Width" rule is not needed.

This is how the auto-layout rules for the TextField should look:

iOS Tutorial TextField Auto-Layout Settings.png

Table Properties

The table displays the tasks and will also show a check mark next to ones marked as completed. You will change the Name property and adjust the auto-layout rules.

  1. Click on the table to select it and display its properties in the Inspector.
  2. In the Name field of the Inspector, change the text from "Table1" to "TaskTable". Press Return to see the name change in the Navigator.

Now you can change the auto-layout rules so that the table will use up as much space as is available on the device:

  1. In the Auto-Layout section, select the Top rule and click the Edit button. If there is no Top rule, you can add it.
    1. Set Relative To to "TaskField".
    2. Set Edge to "Bottom".
    3. Set Offset to "Standard".
    4. Click Done.
  2. Now select the Bottom rule and click Edit. If there is no Bottom rule, add it using the "+" button.
    1. Set Relative To to "BottomLayoutGuide".
    2. Set Edge to "Top".
    3. Set Offset to 0.
    4. Click Done.
  3. If there is a Height rule, select it and click the "-" button to remove it.
  4. The Left and Right rules should be set to Parent.Left and Parent.Right respectively which you should be able to do by now.

This is what the table auto-layout rules should look like:

iOS Tutorial Table Auto-Layout Settings.png

ToolButton Properties

The last items to adjust are the ToolButtons. Select the first ToolButton (Button2) to display its properties in the Inspector. You may need to select it in the Inspector if it is not visible in the Layout Editor. You will change the Name, Caption and Type properties. Because these buttons are on the toolbar you do not have to specify any auto-layout rules.

Complete Button
  1. Click Button2 to display its properties in the Inspector. You may need to click it in the Navigator if it is not visible in the Layout Editor.
  2. In the Name field of the Inspector, change the text from "Button2" to "CompleteButton". Press Return to see the name change in the Navigator.
  3. In the Caption field, change the text from "Untitled" to "Complete". Press Return to see the name change in the Layout Editor.
Flexible Space
  1. Click Button3 (the middle one) to display its properties in the Inspector. You will change this from an actual button to a special control called a Flexible Space. A Flexible Space will essentially provide enough space to force the next button (the one for Delete) to be on the right side of the layout.
  2. In the Type field of the Inspector, change the value from "Plain Style" to "Flexible Space". You will see the control change to a dotted line with arrows.
Delete Button
  1. Click Button4 to display its properties in the Inspector.
  2. In the Name field of the Inspector, change the text from "Button4" to "DeleteButton". Press Return to see the name change in the Navigator.
  3. In the Caption field, change the text from "Untitled" to "Delete". Press Return to see the name change in the Layout Editor.

Final Layout

This is what your layout should now look like after adjusting all the properties and auto-layout rules:

iOS Tutorial Final Layout.png

Running the App

Your user interface layout is now complete, so it’s time to try it out. But before you go further, you should first save your work.

  1. Save the project by choosing File ↠ Save.
  2. Name the project “iOSTaskManager” and click Save.


To test the app you use the iOS Simulator. To get the iOS Simulator from Apple you'll have to first download, install and run Xcode once so it install its components. You do not need to keep Xcode running or otherwise use it when developing with Xojo. To learn more about Xcode and the iOS Simulator, refer to the Xcode Setup and iOS Simulator topics.

Now you can test your app:

  1. Click the Run button in the toolbar to run the project. This builds your app and runs it in the iOS Simulator.
  2. When Task Manager is displayed, you can interact with the buttons by clicking on them or you can type in the TextField.
  3. Quit the iOS Simulator to return to the Xojo Layout Editor.


Of course, Task Manager doesn’t do anything yet! For that you need to add some code, which is what you'll do next.

If you want to change the type of iOS device that the iOS Simulator runs your project in, go to the Navigator and click on the Shared item in the Build Settings. In the Inspector change the value for the Simulator Device property to another available iOS device in the list.

Adding Code

TaskManagerView

You will add a property to store the row number that was last tapped so that it can be used when it comes time to either complete or delete a task in the table.

  1. Select TaskManagerView in the Navigator.
  2. Click the "+" button in the command bar (that's the smaller toolbar immediately above the layout) and choose "Property". This adds a new property. You'll use the Inspector to change its name.
  3. In the Inspector for the newly added property, change its name from "Untitled" to "CurrentRow".
  4. Also change the Default property to -1 to indicate that no row is selected by default.
  5. Since this property is used to store a row number, its type is Integer and there is need to change it.

TaskTable

In TaskTable you will add two events. One to initialize the sections and one to assign the last tapped row to the CurrentRow property you just created.

  1. On the TaskManagerView, double-click the TaskTable control (or select TaskTable and click the "+" button in the command bar -- that's the smaller toolbar immediately above the layout and choose "Event Handler"). The Add Handler window appears with a list of availble events. The Open event is generally used for initialization so select that and click OK to display the Code Editor. Also notice that the Navigator updates to show the Open event below TaskTable.
  2. Now you can add a line of code to initialize the TaskTable with a section by calling the AddSection method like this:
    Me.AddSection("")
    The "Me" part of that line of code means that you are referring to the TaskTable itself (since that is where the Open event is). The "AddSection" part refers to the method call to add a section to a table. In this case only a default section is needed so no name is necessary.
  3. Now add the next event. Click the "+" button in the command bar and choose "Event Handler" again. This time you are looking for the Action event. It is called when the user taps on a row in the table. Select the Action event and click OK to display its Code Editor.
  4. The Action event has two parameters that provide the section and row that was tapped. Since this table only has a single section that can be ignored. But the row is needed later when completing or deleting rows. The best way to remember the row number is to store it in the CurrentRow property you previously created. The code looks like this:
    CurrentRow = row

Add Button

The Add button adds tasks to the table. The code you add to the button needs to take what was typed in TaskField and add it as a new row to the table. Follow these steps to add the code:

  1. On the TaskManagerView, double-click the AddButton control, labelled “Add”. The Add Event Handler window appears. (You could also click on the Add button and use the "+" button in the command bar as you did above with TaskManagerView.) When a user clicks on an iOSButton in the running app, the Action event handler is called. This means you want to add your code to the Action event handler, so select Action from the Event Handler list and click OK. This displays the Code Editor. Also notice the Navigator updates to show the Action event underneath the AddButton control.
  2. Now you need to get the task that was typed into the Task field. You might think you could get the task just by referring to the name of the field, TaskField. That is close, but not quite what you want. What you instead need is a property of TaskField. When you need to refer to a property of an object, you use the name of the object, followed by a dot, followed by the name of the property. In other words, you use this syntax: ObjectName.PropertyName. This is something called “dot” notation and is commonly used in object-oriented programming. In this case the object is TaskField and the property you want is Text (use the Language Reference to find out about all the properties available to iOSTextFields). The syntax looks like this:
    TaskField.Text
  3. To actually add a row to a Listbox, you use the AddRow method. You already know how to get the text in the Task field from step 2. As you have seen before, objects can have properties. And as you now see with TaskList, objects can also have methods. AddRow is one of many methods available to Listboxes. The first parameter is the section, but since this table does not use sections is can be 0. The second column contains the text to display, which in this case is the name of the task. Lastly, after adding the task to the table you can clear the field by setting its property to an empty value. Here is the code:
    TaskTable.AddRow(0, TaskField.Text) // Add text to the table
    TaskField.Text = "" // Clear the text in the field
  4. Save the project by choosing File ↠ Save.
  5. Run the app to test it out. Type tasks in the task field and click the Add button to see them appear in the task list. Close the browser tab or window to return to the Code Editor.

Complete and Delete Buttons

When the user clicks the Complete button, the selected task in the Listbox should be marked as completed. This is indicated by showing a checkmark (✓) after the task. When the user clicks the Delete button, the task should be removed from the table. Follow these steps to add the code:

  1. Because the Complete and Delete buttons are toolbar buttons, the event to handle their taps is actually on the View itself. So select the TaskManagerView by clicking on a blank part of the background.
  2. In the command bar, select "+" and choose "Event Handler" to display the Event Handler window. When a user clicks on a toolbar button, the ToolbarPressed event is called with a parameter indicating which toolbar button was pressed. So select ToolbarPressed and click OK to display its Code Editor.
  3. The code uses the supplied button parameter to determine which button was pressed and then does the necessary steps to display a checkmark or remove the row. Here is the code:
    Select Case button
    Case CompleteButton
    Var cell As iOSTableCellData
    cell = TaskTable.RowData(0, CurrentRow)
    cell.AccessoryType = iOSTableCellData.AccessoryTypes.Checkmark
    TaskTable.ReloadRow(0, CurrentRow)

    Case DeleteButton
    TaskTable.RemoveRow(0, CurrentRow)

    End Select
    CurrentRow = -1
    The Select Case command is used to determine what was pressed. In the CompleteButton section the code gets the cell information for the selected row and then sets the AccessoryType property to be a checkmark. The DeleteButton code removes the selected row. Finally, the CurrentRow property is set to -1 to indicate that a row is no longer selected.
  4. Run the app and add a few sample tasks. Now click on a task and tap the Complete button. A checkmark appears in the Completed column.
  5. Select a task and tap on the Delete button to remove it.
  6. Close the iOS Simulator to return to the Code Editor.

Debugging

Finding Bugs is part of creating apps. A bug is when your code or app does something unexpected, often leading to a crash. Although your app works just fine, there is one bug that need addressing. Have you figured out what it is?

Here’s a hint: What happens if you you click on the Complete or Delete buttons but have not selected a task? Try it.

  1. Run the app and click on the Complete button without doing anything else. Your app will switch to the Debugger with a line of code highlighted. Your code has generated an OutOfBoundsException and you are now in the debugger. The error occurred because you attempted to remove (or complete) a row that does not exist. When no row is selected in the Table, the CurrentRow property is set to -1. Since -1 is not a valid row in the Table, the RowData method raises an OutOfBoundsException in the ToolbarPressed event.
  2. Click the Resume button in the debugger toolbar and your app will terminate back to the Code Editor.

Nobody wants buggy code. Luckily it is easy to prevent this bug from occurring. Essentially, you want to make sure a row is selected before you attempt to Delete or Complete a task.

  1. Go to the code for the ToolbarPressed event.
  2. You will add code to not attempt to complete or delete a task if the CurrentRow is not valid. To do this add this one line to the beginning of the code:
    If CurrentRow < 0 Then Return
  3. So now the full code for the ToolbarPressed event should look like this:
    If CurrentRow < 0 Then Return

    Select Case button
    Case CompleteButton
    Var cell As iOSTableCellData
    cell = TaskTable.RowData(0, CurrentRow)
    cell.AccessoryType = iOSTableCellData.AccessoryTypes.Checkmark
    TaskTable.ReloadRow(0, CurrentRow)

    Case DeleteButton
    TaskTable.RemoveRow(0, CurrentRow)

    End Select
    CurrentRow = -1
  4. Save the project by choosing File ↠ Save.
  5. Run the project again and click the Complete button without selecting a row in the task table. No more bug!

Finishing the App

Testing

Just because your app seems to work, doesn’t mean you are finished with it. A good developer always thoroughly tests their apps to look for possible problems.

You already found and fixed one problem (clicking Complete or Delete when no row was selected). Do you think there are other problems to fix? Run the app and play around with it a bit. Make a note of things you want to change. In the next section, you will add some improvements to Task Manager.

Improvements

Did you notice that there are times when the buttons in Task Manager probably should not do their action? For example, the Complete button should not try to mark a task as completed if one is not selected and the Delete button should not try to delete a task if one is not selected. Right now (with your bug fix) you can tap them, but nothing happens. Also, you are not going to want to add a task to the list if nothing has been entered in the task field.

There are several ways to accomplish this, but one way is to disable the buttons when they should not be used.

Follow these steps to add this improvement:

  1. On TaskManagerView, select CompleteButton, labeled “Complete”. In the Inspector, turn the Enabled property to Off.
  2. Also selct DeleteButton and turn its Enabled property to Off.
  3. Go to the Action event on the TaskTable to show the code. Here you can add code to enable those two buttons when a row is tapped. The complete code for the Action event now looks like this:
    CurrentRow = row

    CompleteButton.Enabled = True
    DeleteButton.Enabled = True
  4. Next go to the ToolbarPressed event to show its code.Here you also want to disable the buttons after completing or removing a row since this also clears the selection. At the very end you can add the two lines to do that so that the code now looks like this:
    If CurrentRow < 0 Then Return

    Select Case button
    Case CompleteButton
    Var cell As iOSTableCellData
    cell = TaskTable.RowData(0, CurrentRow)
    cell.AccessoryType = iOSTableCellData.AccessoryTypes.Checkmark
    TaskTable.ReloadRow(0, CurrentRow)

    Case DeleteButton
    TaskTable.RemoveRow(0, CurrentRow)

    End Select

    CurrentRow = -1
    CompleteButton.Enabled = False
    DeleteButton.Enabled = False
  5. Save the project and run it. You will now see those two buttons start out as disabled. Add a task and tap on it to see the buttons become enabled. Delete a task to see the buttons again get disabled.

For the last improvement you can make it so that the Add button is only enabled when the user has entered text in the TaskField.

  1. Select AddButton, labeled “Add”. In the Inspector, turn the Enabled property (in the Appearance group) to Off.
  2. Now you will add code to enable the Add button when there is text in the Task Field. Select the TaskField control, click the "+" in the command bar and choose "Add Handler" to open the Add Handler window. Here you are seeing yet another list of event handlers. Every control type has its own specific list of event handlers. In this case, you want to disable AddButton when there is no text in the task field and enable it when there is text. The TextChange event is called whenever the text in the task field is changed, either by the user typing or by your code changing the Text property. Select TextChange from the Event Handler list and click OK. Notice the Navigator on the left updates to show the TextChange event underneath the TaskField control and the code editor displays.
  3. You now need code that checks the Text property of the TextField (Me.Text) to see if anything is there. If there is text there, then the AddButton is enabled by setting its Enabled property to True. If there is no text, then it is disabled by setting its Enabled property to False. This is the code:
    If Me.Text <> "" Then
    AddButton.Enabled = True
    Else
    AddButton.Enabled = False
    End If
  4. Lastly you also want to disable the Add button after it is clicked by adding code to the end:
    TaskTable.AddRow(0, TaskField.Text) ' Add text to the table
    TaskField.Text = "" // Clear the text in the field
    Me.Enabled = False
  5. Save the project and Run the app to test it out. Notice that you cannot tap the Add button until after you enter some text. And if you remove all the text from the Task field, you will again be unable to tab the button.

Deploying

There are several ways to deploy a Xojo iOS app. You can build your app with Xojo and manually copy it to an iOS device using Xcode. Or you can build your app with Xojo and submit it to the App Store. Both of these options require you to create certificates, IDs and distributions profiles with Apple and use Xcode to install them. You can find more information here:

Next Steps

Congratulations, you have successfully completed the iOS Tutorial and now have a fully functional app. To continue on your journey of learning Xojo, you should next move on to the User Guide, which covers Xojo in its entirety. You will also want to refer to the iOS Language Reference, which covers the specifics of language elements, classes and other details of Xojo.

Download the completed TaskManager project.

Retrieved from "http://docs.xojo.com/index.php?title=GettingStarted:iOS_Tutorial&oldid=68937"