ORKTaskViewController Class Reference

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

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

`– initWithTask:taskRunUUID:`

Returns a newly initialized task view controller.

- (instancetype)initWithTask:(nullable id<ORKTask>)task taskRunUUID:(nullable 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

`– 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

`– initWithNibName:bundle:`

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

- (instancetype)initWithNibName:(nullable NSString *)nibNameOrNil bundle:(nullable 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

`– initWithTask:restorationData:delegate:`

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

- (instancetype)initWithTask:(nullable id<ORKTask>)task restorationData:(nullable NSData *)data delegate:(nullable 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

`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.

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

`taskRunUUID`

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

@property (nonatomic, copy) 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)

@property (nonatomic, copy, readonly) 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.

@property (nonatomic, copy, readonly, nullable) 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

`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

`– 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

`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

`– 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)

@property (nonatomic, readonly) UINavigationBar *navigationBar

Discussion

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

Declared In

ORKTaskViewController.h

ORKActiveTaskSupport Methods

`– 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.

Declared In

ORKTaskViewController_Private.h