ORKStepViewController Class Reference

Inherits from	UIViewController
Declared in	ORKStepViewController.h

The ORKStepViewController class is a base class for view controllers that are presented by an ORKTaskViewController object for the steps in a task.

In the ResearchKit framework, each step collects some information or data from the user. Typically, the task view controller instantiates the step view controller before presenting the next step (ORKStep) in the task.

When you create a new type of step, you usually have to subclass ORKStepViewController to manage the step. For examples of subclasses, see ORKQuestionStepViewController and ORKFormStepViewController. In contrast, the view controller for an active step is typically a subclass of ORKActiveStepViewController, because active steps include the concept of life cycle.

If you are simply trying to change some of the runtime behaviors of ORKStepViewController, it’s usually not necessary to subclass it. Instead, implement the [ORKTaskViewControllerDelegate taskViewController:stepViewControllerWillAppear:] method in the ORKTaskViewControllerDelegate protocol, and modify the appropriate properties of the step view controller. For example, to change the title of the Learn More or Next buttons, set the learnMoreButtonTitle or continueButtonTitle properties in your implementation of this delegate method.

`– initWithStep:`

Returns a new step view controller for the specified step.

- (instancetype)initWithStep:(nullable ORKStep *)step

Parameters

`step`	The step to be presented.

Return Value

A newly initialized step view controller.

Declared In

ORKStepViewController.h

`– initWithStep:result:`

Returns a new step view controller for the specified step.

- (instancetype)initWithStep:(ORKStep *)step result:(ORKResult *)result

Parameters

`step`	The step to be presented.
`result`	The current step result for this step.

Return Value

A newly initialized step view controller.

Declared In

ORKStepViewController.h

`step`

The step presented by the step view controller.

@property (nonatomic, strong, nullable) ORKStep *step

Discussion

If you use a storyboard to initialize the step view controller, initWithStep: isn’t called, so you need to set the step property directly before the step view controller is presented.

Setting the value of step after the controller has been presented is an error that generates an exception. Modifying the value of step after the controller has been presented is an error that has undefined results.

Subclasses that override the setter of this property must call super.

Declared In

ORKStepViewController.h

`delegate`

The delegate of the step view controller.

@property (nonatomic, weak, nullable) id<ORKStepViewControllerDelegate> delegate

Discussion

The delegate is usually the ORKTaskViewController object that presents the step view controller. If you need to intercept the delegate methods, you can assign an intermediary object as the delegate and forward the messages to the task view controller.

Declared In

ORKStepViewController.h

`continueButtonTitle`

A localized string that represents the title of the Continue button.

@property (nonatomic, copy, nullable) NSString *continueButtonTitle

Discussion

Most steps display a button that enables forward navigation. This button can have titles such as Next, Continue, or Done. Use this property to override the forward navigation button title for the step.

Declared In

ORKStepViewController.h

`learnMoreButtonTitle`

A localized string that represents the title of the Learn More button.

@property (nonatomic, copy, nullable) NSString *learnMoreButtonTitle

Discussion

Many steps have a button that lets users view more information about the step than can fit on the screen. Use this property to override the title of the Learn More button for the step.

Declared In

ORKStepViewController.h

`skipButtonTitle`

A localized string that represents the title of the “Skip” button.

@property (nonatomic, copy, nullable) NSString *skipButtonTitle

Discussion

Many steps are optional and can be skipped. Set this property to override the title of the Skip button for the step. Note that setting this property has no effect if the Skip button is not visible, which is the case in a required question step.

Declared In

ORKStepViewController.h

`backButtonItem`

The back button item.

@property (nonatomic, strong, nullable) UIBarButtonItem *backButtonItem

Discussion

The back button item controls the Back button displayed in the navigation bar when the step view controller is current. This property lets you control the appearance and target of the Back button at runtime.

When the value of the property is nil, the Back button is not displayed; otherwise, the title, target, and action associated with the Back button item are used (other properties of UIBarButtonItem are ignored).

The back button item is updated during view loading and when the value of the step property is changed, but they are safe to set in the taskViewController:stepViewControllerWillAppear: delegate callback.

Subclasses can safely modify this property any time after calling viewWillAppear: on super.

Declared In

ORKStepViewController.h

`cancelButtonItem`

The cancel button item.

@property (nonatomic, strong, nullable) UIBarButtonItem *cancelButtonItem

Discussion

The cancel button item controls the Cancel button displayed in the navigation bar when the step view controller is current. This property lets you control the appearance and target of the Cancel button at runtime.

When the value of the property is nil, the Cancel button is not displayed; otherwise, the title, target, and action associated with the Cancel button item are used (other properties of UIBarButtonItem are ignored).

The cancel button item is updated during view loading and when the value of the step property is changed, but is safe to set in the taskViewController:stepViewControllerWillAppear: delegate callback.

Subclasses can safely modify this property any time after calling viewWillAppear: on super.

Declared In

ORKStepViewController.h

`result`

The current state of the result. (read-only)

@property (nonatomic, copy, readonly, nullable) ORKStepResult *result

Discussion

The task view controller uses this property to get the results for the step, and to collate them into the task result.

The current step result and any subsidiary results representing data collected so far are available in this property. You can detect significant changes to the result, such as when the user enters a new answer, using the stepViewControllerResultDidChange: delegate callback.

Subclasses must use this property to return the current results. Subclasses may call super to obtain a clean, empty result object appropriate for the step, to which they can attach appropriate child results.

The implementations of this method in the ResearchKit framework currently create a new result object on every call, so do not call this method unless it is actually necessary.

Declared In

ORKStepViewController.h

`– addResult:`

Add a result to the step view controller’s ORKStepResult. By default, the property for the step view controller’s result will instantiate a copy of the result each time it is called. Therefore, the result cannot be mutated by adding a result to its result array.

- (void)addResult:(ORKResult *)result

Parameters

`result`	The result to add to the step results.

Discussion

This method can be called by a delegate to add a result to a given step in a way that will be retained by the step.

Declared In

ORKStepViewController.h

`– hasPreviousStep`

Returns a Boolean value indicating whether there is a previous step.

- (BOOL)hasPreviousStep

Return Value

YES if there is a previous step; otherwise, NO.

Discussion

This method is a convenience accessor that subclasses can call to make a delegate callback to determine whether a previous step exists. Subclasses can also override this method if the step view controller should always behave as if backward navigation is disabled.

See also: stepViewControllerHasPreviousStep:

Declared In

ORKStepViewController.h

`– hasNextStep`

Returns a Boolean value indicating whether there is a next step.

- (BOOL)hasNextStep

Return Value

YES if there is a next step; otherwise, NO.

Discussion

This method is a convenience method that subclasses can call to make a delegate callback to determine whether a next step exists.

See also: stepViewControllerHasNextStep:

Declared In

ORKStepViewController.h

`taskViewController`

The presenting task view controller. (read-only)

@property (nonatomic, weak, readonly, nullable) ORKTaskViewController *taskViewController

Declared In

ORKStepViewController.h

`– goForward`

Navigates forward to the next step.

- (void)goForward

Discussion

When a user taps a Next button, the information passes through this method. You can use this method as an override point or a target action for a subclass.

Declared In

ORKStepViewController.h

`– goBackward`

Navigates backward to the previous step.

- (void)goBackward

Discussion

When a user taps the Back button, the information passes through this method. You can use this method as an override point or a target action for a subclass.

Declared In

ORKStepViewController.h

`– skipForward`

This method is called when the user taps the skip button. By default, it calls goForward.

- (void)skipForward

Declared In

ORKStepViewController.h

`hasBeenPresented`

A Boolean value indicating whether the view controller has been presented before.

@property (nonatomic, readonly) BOOL hasBeenPresented

Declared In

ORKStepViewController.h