An object that creates and manages the contents of a single-column table interface.
- iOS 8.2+
- watchOS 2.0+
You use a table object to set the number and type of rows and to configure the data objects for those rows. Take the following steps to configure a table object and fill it with data:
Define one or more row controller types in your storyboard.
Define a custom data class to manage the contents of each row type.
Tell the table object how many rows (and of what type) to display at runtime.
Use instances of your custom data class to configure each row’s contents.
Do not subclass or create instances of this class yourself. Instead, define outlets in your interface controller class and connect them to the corresponding objects in your storyboard file. For example, to refer to a table object in your interface, define a property with the following syntax in your interface controller class:
During the initialization of your interface controller, WatchKit creates a new instance of this class and assigns it to your outlet. At that point, you can use the object in your outlet to make changes to the table.
Defining Your Table’s Rows
After adding a table object to your storyboard, configure the row controller that comes with the table. A row controller defines the appearance of a specific type of row. A table comes with one row type initially and you can add more later. Each row controller in your table requires some minimal configuration to be usable at runtime.
Each row controller must have a name, which you set using the Identifier property in the Attributes inspector. You use this name to create rows of that type later.
Each row controller must have an associated class, which you set in the Identity inspector. At runtime, the table creates instances of your row controller classes for each row in the table.
To configure the contents of a row controller, drag elements from the library and drop them onto the row’s group. For most rows, you will want to use a group object as the top-level object. You can also nest group objects to create vertical and horizontal arrangements for your interface objects. To that group, add the objects needed to display the row’s contents. Figure 1 shows how a configured row appears in Xcode.
Each row controller needs a class to manage the contents of the row at runtime. The class acts as a proxy for the row in your code and stores the outlets you need to configure the contents of the row. Listing 2 shows the definition of a custom
My class that could be used for the row controller in Figure 1.
Setting the Number of Rows at Runtime
To fill a table interface object with data, use the
set method. These methods specify the type (and number) of rows to add to the table. If all rows are of the same type, use the
set method. If you use more than one row controller in your table, use the
set method. The row type string corresponds to the name you entered into the Identifier property for that row controller in your storyboard.
When you add rows to a table, WatchKit creates the rows in your Watch app and instantiates the classes corresponding to those rows in your WatchKit extension. The newly instantiated classes are stored internally by the table object and made available to you through the
row method. Use that method to retrieve each row controller object and configure the contents of the row.
Listing 3 shows an example of how to configure a table object from your interface controller. The
todo property referenced by the method is a custom property that contains the
WKInterface object being configured. After getting the data for the rows, the method calls the
set method to create the rows. It then iterates over the newly created row controller objects, configuring each one’s label with the text for the to-do item.
When you want to update the contents of a table, call
set again with the new row type information. Calling these methods again forces the table to discard the old rows and create new ones. To insert new rows without removing the old ones, use the
Responding to Taps in Table Rows
In your storyboard, create a segue between a row controller and a destination interface controller. When the user taps on a row of that type, the system automatically pushes the destination interface controller onto the screen. To pass data to the destination controller, override your current interface controller’s
context method, and return context data based on the selected row.
Alternatively, you can explicitly respond to taps in a table row by implementing your interface controller’s
table(_: method. Use that method to present a different interface controller or to perform any other relevant tasks.
Supporting Item Pagination
Item Pagination lets users easily navigate through lists of items. When the user selects an item from the table, the app displays a detailed view for the item. The user can then scroll up and down to navigate between other sibling items from that table. For example if the user selects a stock symbol in the Stocks app, it will load the details for that stock. They can then scroll vertically to navigate to other stocks.
Item Pagination is disabled by default. To enable it, perform the following steps:
In the storyboard, enable the table’s Item Pagination option in the Attributes inspector.
In the storyboard, define segues for all of the table’s row controllers. Your table must use segues to drive its navigation.
If you programmatically navigate through a table’s items (for example, when launching from a complication to a specific interface controller), be sure to use the table’s
performmethod, instead of the interface controller’s
Controller(with Name: context:)
performmethod lets watchOS know which table and which row initiated the segue. The system needs this information to provide the correct sibling items as the user scrolls.
Interface Builder Configuration Options
Xcode lets you configure information about your table interface object in your storyboard file. Table 1 lists the attributes you can configure in your storyboard and their meaning.
The number of row controllers supported by the table. Change the value to add or remove new row controller objects to the storyboard file.
The amount of spacing (in points) between rows.
The background image to display behind the table’s items. Do not set an image if you want the background color or image of the underlying interface controller to be visible.
The background color for the table. Set the color to clear if you want the background color or image of the underlying interface controller to be visible.
A checkbox that determines whether Item Pagination is enabled. For more information on Item Pagination, see Supporting Item Pagination.
For each row controller in your table, Table 2 lists the attributes you can configure and their meaning.
A checkbox indicating whether rows of this type are enabled and tappable. When this option is disabled, tapping the row does not highlight the row or report the action to the table.