ORKTaskViewController Class Reference

Inherits from UIViewController
Conforms to ORKStepViewControllerDelegate
UIViewControllerRestoration
Declared in ORKTaskViewController.h
ORKTaskViewController.m

Overview

The ORKTaskViewController class is the primary entry point for the presentation of the ResearchKit framework UI. Note that a task view controller usually presents an ORKOrderedTask instance, but it can present any object that implements ORKTask.

The task view controller is intended for modal presentation, which lets the user cancel participation in the task at any time. Typically, the task view controller displays a navigation bar and conducts right-to-left navigation for each step as the user progresses through the task.

The task view controller supports UI state restoration, which allows users to continue a long task when they resume your app. To enable state restoration, set the restoration identifier and take the appropriate action to restore the task view controller when your app restarts or resumes.

The task view controller also lets users save their progress in the middle of a task. To support this scenario in your app, implement [ORKTaskViewControllerDelegate taskViewControllerSupportsSaveAndRestore:] in your task view controller delegate, and return YES. If the task completes with the status ORKTaskViewControllerFinishReasonSaved, copy and store the value of the restorationData property. When the user resumes the task, create a new task view controller using the initWithTask:restorationData: initializer, and present it.

It is possible to configure the task view controller to prefill surveys with data from another source, such as a previous run of the same task. Set the defaultResultSource property to use this feature.

When conducting active tasks which may produce file results, always set the outputDirectory property. Files generated during active steps are written to the output directory that you specify, and references to these files are returned by ORKFileResult objects in the result hierarchy.

Other Methods

– initWithNibName:bundle:

Returns a newly initialized task view controller using the nib file in the specified bundle.

- (instancetype)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil

Parameters

nibNameOrNil

The name of the nib file from which to instantiate the task view controller.

nibBundleOrNil

The name of the bundle in which to search for the nib file.

Return Value

A new task view controller.

Discussion

This method is a designated initializer.

Declared In

ORKTaskViewController.h

– initWithCoder:

Returns a new task view controller initialized from data in the given unarchiver.

- (instancetype)initWithCoder:(NSCoder *)aDecoder

Parameters

aDecoder

The coder from which to initialize the task view controller.

Return Value

A new task view controller.

Discussion

This method lets you instantiate a task view controller from a storyboard, although this is an atypical use case. This method is a designated initializer.

Declared In

ORKTaskViewController.h

– initWithTask:taskRunUUID:

Returns a newly initialized task view controller.

- (instancetype)initWithTask:(id<ORKTask>)task taskRunUUID:(NSUUID *)taskRunUUID

Parameters

task

The task to be presented.

taskRunUUID

The UUID of this instance of the task. If nil, a new UUID is generated.

Return Value

A new task view controller.

Discussion

This method is the primary designated initializer.

Declared In

ORKTaskViewController.h

– initWithTask:restorationData:delegate:

Creates a new task view controller from the specified restoration data.

- (instancetype)initWithTask:(id<ORKTask>)task restorationData:(NSData *)data delegate:(id<ORKTaskViewControllerDelegate>)delegate

Parameters

task

The task to be presented.

data

Data obtained from the restorationData property of a previous task view controller instance.

delegate

The delegate for the task view controller.

Return Value

A new task view controller.

Discussion

Call this method to restart a task when you have restoration data stored for a previous run of the task, in which the user canceled their current task and saved their progress.

This method restores the presentation of the task to the point at which the user stopped. If the restoration data is not valid, an exception may be thrown.

Declared In

ORKTaskViewController.h

– taskRunUUID

A unique identifier (UUID) for this presentation of the task.

- (NSUUID *)taskRunUUID

Discussion

The task run UUID is a unique identifier for this run of the task view controller. All results produced by this instance are tagged with this UUID.

The task run UUID is preserved across UI state restoration, or across task save and restore.

Note: It is an error to set the value of taskRunUUID after the first time the task view controller is presented.

Declared In

ORKTaskViewController.h

– result

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

- (ORKTaskResult *)result

Discussion

Use this property to obtain or inspect the results of the task. The results are hierarchical; the children of result are ORKStepResult instances, one for each step that the user visited during the task.

If the user uses the Back button to go back through the steps, the results of steps that are ahead of the currently visible step are not included in the result.

Declared In

ORKTaskViewController.h

– restorationData

Snapshot data that can be used for future restoration.

- (NSData *)restorationData

Discussion

When the user taps Cancel during a task and selects the Save option, the [ORKTaskViewControllerDelegate taskViewController:didFinishWithReason:error:] method is called with ORKTaskViewControllerFinishReasonSaved. When that happens, use restorationData to obtain restoration data that can be used to restore the task at a later date.

Use initWithTask:restorationData: to create a new task view controller that restores the current state.

Declared In

ORKTaskViewController.h

– suspend

Suspends the task.

- (void)suspend

Discussion

Call this method to suspend an active step. To resume later, call resume. Not all active steps will respond to suspend / resume, so test thoroughly to verify correct behavior in your tasks.

This method will disable any background audio prompt session, and suspend any active step in progress.

Declared In

ORKTaskViewController_Private.h

– resume

Resumes any current active step.

- (void)resume

Discussion

Call this method to force resuming an active step may call this method. Should be paired with a call to suspend.

This method re-enables background audio prompts, if needed, and resumes any active step. If not in an active step, it has no effect.

See also: suspend

Declared In

ORKTaskViewController_Private.h

– goForward

Forces navigation to the next step.

- (void)goForward

Discussion

Call this method to force forward navigation. This method is called by the framework if the user takes an action that requires navigation, or if the step is timed and the timer completes.

Declared In

ORKTaskViewController.h

– goBackward

Forces navigation to the previous step.

- (void)goBackward

Discussion

Call this method to force backward navigation. This method is called by the framework if the user takes an action that requires backward navigation.

Declared In

ORKTaskViewController.h

– stepViewControllerWillAppear:

Tells the delegate that the step view controller’s view is about to appear.

- (void)stepViewControllerWillAppear:(ORKStepViewController *)viewController

Parameters

stepViewController

The step view controller providing the callback.

Discussion

This method is called from the step view controller’s viewWillAppear: method. You can use this method to customize the appearance of the step view controller without subclassing it.

Declared In

ORKStepViewController.h

– stepViewController:didFinishWithNavigationDirection:

Tells the delegate when the user has done something that requires navigation, such as tap the Back or a Next button, or enter a response to a nonoptional survey question.

- (void)stepViewController:(ORKStepViewController *)stepViewController didFinishWithNavigationDirection:(ORKStepViewControllerNavigationDirection)direction

Parameters

stepViewController

The step view controller providing the callback.

direction

Direction of navigation requested.

Declared In

ORKStepViewController.h

– stepViewControllerDidFail:withError:

Tells the delegate when a step fails due to an error.

- (void)stepViewControllerDidFail:(ORKStepViewController *)stepViewController withError:(NSError *)error

Parameters

stepViewController

The step view controller providing the callback.

error

The error detected.

Discussion

A step view controller can use this method to report its failure to the task view controller. The task view controller sends the error to its delegate indicating that the task has failed (using ORKTaskViewControllerFinishReasonFailed). Note that recorder errors are reported by calling the ORKStepViewControllerDelegate method stepViewController:recorder:didFailWithError:.

Declared In

ORKStepViewController.h

– stepViewControllerResultDidChange:

Tells the delegate when a substantial change has occurred to the result.

- (void)stepViewControllerResultDidChange:(ORKStepViewController *)stepViewController

Parameters

stepViewController

The step view controller providing the callback.

Discussion

The result is always available in the step view controller. Although the result is continuously changing while the step view controller is active (because the time stamp in the result property is different each time it’s called), this method is called only when a substantive change to the result occurs, such as when the user enters a survey answer or completes an active step.

In your implementation of this delegate method, you can collect the value of result from the step view controller.

Declared In

ORKStepViewController.h

– stepViewControllerHasPreviousStep:

Asks the delegate whether there is a previous step.

- (BOOL)stepViewControllerHasPreviousStep:(ORKStepViewController *)stepViewController

Parameters

stepViewController

The step view controller providing the callback.

Return Value

YES if a Back button should be visible; otherwise, NO.

Discussion

If there is a previous step, the step view controller adds a Back button to its navigation item; if not, no Back button is added to the navigation item.

Declared In

ORKStepViewController.h

– stepViewControllerHasNextStep:

Asks the delegate whether there is a next step.

- (BOOL)stepViewControllerHasNextStep:(ORKStepViewController *)stepViewController

Parameters

stepViewController

The step view controller providing the callback.

Return Value

YES if there is a step following the current one; otherwise, NO.

Discussion

Depending on the result of the step, the step view controller can adjust the language for the Next button.

Declared In

ORKStepViewController.h

– stepViewController:recorder:didFailWithError:

Tells the delegate when a recorder error has been detected during the step.

- (void)stepViewController:(ORKStepViewController *)stepViewController recorder:(ORKRecorder *)recorder didFailWithError:(NSError *)error

Parameters

stepViewController

The step view controller providing the callback.

recorder

The recorder that detected the error.

error

The error detected.

Discussion

Recorder errors can occur during active steps, usually due to the unavailability of sensor data or disk space in which to record results.

Declared In

ORKStepViewController.h

– setNavigationBarHidden:animated:

Shows or hides the navigation bar, with optional animation.

- (void)setNavigationBarHidden:(BOOL)hidden animated:(BOOL)animated

Parameters

hidden

YES to hide the navigation bar; otherwise, NO.

animated

YES to animate the show or hide operation; otherwise, NO.

Declared In

ORKTaskViewController.h

– navigationBar

The navigation bar for the task view controller. (read-only)

- (UINavigationBar *)navigationBar

Discussion

You can use this method to customize the appearance of the task view controller’s navigation bar.

Declared In

ORKTaskViewController.h

Other Methods

  delegate

The delegate for the task view controller.

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

Discussion

There are many optional methods in the task view controller protocol, but the delegate must support completion. When the task view controller completes its task, it is the delegate’s responsibility to dismiss it.

See also: [ORKTaskViewControllerDelegate taskViewController:didFinishWithReason:error:].

Declared In

ORKTaskViewController.h

  task

The task for this task view controller.

@property (nonatomic, strong, nullable) id<ORKTask> task

Discussion

The task functions as the data source for an ORKTaskViewController object, providing the steps that the user must complete in order to complete the task. It is an error to change the task after presenting the task view controller.

Declared In

ORKTaskViewController.h

  defaultResultSource

A source that the task view controller can consult to obtain default answers for questions provided in question steps and form steps.

@property (nonatomic, strong, nullable) id<ORKTaskResultSource> defaultResultSource

Discussion

The source can provide default answers, perhaps based on previous runs of the same task, which will be used to prefill question and form items. For example, an ORKTaskResult object from a previous run of the task can function as an ORKTaskResultSource object, because ORKTaskResult implements the protocol.

Declared In

ORKTaskViewController.h

  outputDirectory

File URL for the directory in which to store generated data files.

@property (nonatomic, copy, nullable) NSURL *outputDirectory

Discussion

Active steps with recorders (and potentially other steps) can save data to files during the progress of the task. This property specifies where such data should be written. If no output directory is specified, active steps that require writing data to disk, such as those with recorders, will typically fail at runtime.

In general, set this property after instantiating the task view controller and before presenting it.

Before presenting the view controller, set the outputDirectory property to specify a path where files should be written when an ORKFileResult object must be returned for a step.

Declared In

ORKTaskViewController.h

  showsProgressInNavigationBar

A Boolean value indicating whether progress is shown in the navigation bar.

@property (nonatomic, assign) BOOL showsProgressInNavigationBar

Discussion

Setting this property to YES does not display progress if you don’t also implement the progress method of ORKTask.

The default value of this property is YES. To disable the display of progress in the navigation bar, set the value to NO.

Declared In

ORKTaskViewController.h

  currentStepViewController

The current step view controller.

@property (nonatomic, strong, readonly, nullable) ORKStepViewController *currentStepViewController

Discussion

The task view controller instantiates and presents a series of step view controllers. The current step view controller is the one that is currently visible on screen.

The value of this property may be nil if the task view controller has not yet been presented.

Declared In

ORKTaskViewController.h

  navigationBarHidden

A Boolean value indicating whether the navigation bar is hidden.

@property (nonatomic, getter=isNavigationBarHidden) BOOL navigationBarHidden

Discussion

By default, the task view controller includes a visible navigation bar. To disable the display of the navigation bar, set this property to NO.

Declared In

ORKTaskViewController.h