ORKTaskViewControllerDelegate Protocol Reference

Conforms to NSObject
Declared in ORKTaskViewController.h

The task view controller delegate is responsible for processing the results of the task, exerting some control over how the controller behaves, and providing auxiliary content as needed.

– taskViewController:didFinishWithReason:error: required method

Tells the delegate that the task has finished.

- (void)taskViewController:(ORKTaskViewController *)taskViewController didFinishWithReason:(ORKTaskViewControllerFinishReason)reason error:(nullable NSError *)error

Parameters

taskViewController

The ORKTaskViewControllerinstance that is returning the result.

reason

An ORKTaskViewControllerFinishReason value indicating how the user chose to complete the task.

error

If failure occurred, an NSError object indicating the reason for the failure. The value of this parameter is nil if result does not indicate failure.

Discussion

The task view controller calls this method when an unrecoverable error occurs, when the user has canceled the task (with or without saving), or when the user completes the last step in the task.

In most circumstances, the receiver should dismiss the task view controller in response to this method, and may also need to collect and process the results of the task.

Declared In

ORKTaskViewController.h

– taskViewController:recorder:didFailWithError:

Signals that an error has been detected by a recorder.

- (void)taskViewController:(ORKTaskViewController *)taskViewController recorder:(ORKRecorder *)recorder didFailWithError:(NSError *)error

Parameters

taskViewController

The calling ORKTaskViewController instance.

recorder

The recorder that detected the error. ORKStep and ORKRecorderConfiguration objects can be found in the recorder instance.

error

The error that was detected.

Discussion

Recorder errors can occur during active steps, typically because sensor data is unavailable or there isn’t enough disk space to record the results. You can use this method as an opportunity to respond to the error by, for example, logging and ignoring it.

Declared In

ORKTaskViewController.h

– taskViewControllerSupportsSaveAndRestore:

Asks the delegate if the state of the current uncompleted task should be saved.

- (BOOL)taskViewControllerSupportsSaveAndRestore:(ORKTaskViewController *)taskViewController

Parameters

taskViewController

The calling ORKTaskViewController instance.

Return Value

YES if save and restore should be supported; otherwise, NO.

Discussion

The task view controller calls this method to determine whether to offer a save option when the user attempts to cancel a task that is in progress.

If this method is not implemented, the task view controller assumes that save and restore are not supported. If this method returns YES, it’s recommended that you copy the value of the restorationData property of the task view controller and pass that data to initWithTask:restorationData: when it is time to create a new task view controller to continue from the point at which the user stopped.

Declared In

ORKTaskViewController.h

– taskViewController:hasLearnMoreForStep:

Asks the delegate if there is Learn More content for this step.

- (BOOL)taskViewController:(ORKTaskViewController *)taskViewController hasLearnMoreForStep:(ORKStep *)step

Parameters

taskViewController

The calling ORKTaskViewController instance.

step

The step for which the task view controller needs to know if there is Learn More content.

Return Value

NO if there is no Learn More content to display.

Discussion

The task view controller calls this method to determine whether a Learn More button should be displayed for the step.

The standard templates in ResearchKit for all types of steps include a button labeled Learn More (or a variant). In consent steps, this is internal to the implementations of the step and step view controller, but in all other steps, the task view controller asks its delegate to determine if Learn More content is available, and to request that it be displayed.

Declared In

ORKTaskViewController.h

– taskViewController:learnMoreForStep:

Tells the delegate that the user has tapped the Learn More button in the step.

- (void)taskViewController:(ORKTaskViewController *)taskViewController learnMoreForStep:(ORKStepViewController *)stepViewController

Parameters

taskViewController

The calling ORKTaskViewController instance.

stepViewController

The ORKStepViewController that reported the Learn More event to the task view controller.

Discussion

The standard templates in ResearchKit for all types of steps include a button labeled Learn More (or a variant). In consent steps this is internal to the implementations of the step and step view controller, but in all other steps, the task view controller asks its delegate to determine if Learn More content is available.

This method is called only if the delegate returns YES to taskViewController:hasLearnMoreForStep: for the current step, and the user subsequently taps on the Learn More button.

When this method is called, the app should respond to the Learn More action by presenting a dialog or other view (possibly modal) that contains the Learn More content.

Declared In

ORKTaskViewController.h

– taskViewController:viewControllerForStep:

Asks the delegate for a custom view controller for the specified step.

- (nullable ORKStepViewController *)taskViewController:(ORKTaskViewController *)taskViewController viewControllerForStep:(ORKStep *)step

Parameters

taskViewController

The calling ORKTaskViewController instance.

step

The step for which a view controller is requested.

Return Value

A custom view controller, or nil to request the default step controller for this step.

Discussion

If this method is implemented, the task view controller calls it to obtain a step view controller for the step.

In most circumstances, the task view controller can determine which view controller to instantiate for a step. However, if you want to provide a specific view controller instance, you can call this method to do so.

The delegate should provide a step view controller implementation for any custom step.

Declared In

ORKTaskViewController.h

– taskViewController:shouldPresentStep:

Asks the delegate if the task view controller should proceed to the specified step.

- (BOOL)taskViewController:(ORKTaskViewController *)taskViewController shouldPresentStep:(ORKStep *)step

Parameters

taskViewController

The calling ORKTaskViewController instance.

step

The step for which presentation is requested.

Return Value

YES if navigation should proceed to the specified step; NO if navigation should not proceed.

Discussion

The task view controller calls this method before creating a step view controller for the next or previous step.

Generally, when a step is available, the task view controller presents it when the user taps a forward or backward navigation button, but the results entered or other circumstances can make this action inappropriate. In these circumstances, you can implement this delegate method and return NO.

If you return NO, it’s often appropriate to present a dialog or take some other UI action to explain why navigation was denied.

Declared In

ORKTaskViewController.h

– taskViewController:stepViewControllerWillAppear:

Tells the delegate that a step view controller is about to be displayed.

- (void)taskViewController:(ORKTaskViewController *)taskViewController stepViewControllerWillAppear:(ORKStepViewController *)stepViewController

Parameters

taskViewController

The calling ORKTaskViewController instance.

stepViewController

The ORKStepViewController that is about to be displayed.

Discussion

The task view controller calls this method before presenting the step view controller.

This method gives you an opportunity to modify the step view controller before presentation. For example, you might want to modify the learnMoreButtonTitle or continueButtonTitle properties, or modify other button state. Another possible use case is when a particular step view controller requires additional setup before presentation.

Declared In

ORKTaskViewController.h

– taskViewController:didChangeResult:

Tells the delegate that the result has substantively changed.

- (void)taskViewController:(ORKTaskViewController *)taskViewController didChangeResult:(ORKTaskResult *)result

Parameters

taskViewController

The calling ORKTaskViewController instance.

result

The current value of the result.

Discussion

The task view controller calls this method when steps start or finish, or if an answer has changed in the current step due to editing or other user interaction.

Declared In

ORKTaskViewController.h