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 *)errorParameters
taskViewController |
The |
|---|---|
reason |
An |
error |
If failure occurred, an |
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 *)errorParameters
taskViewController |
The calling |
|---|---|
recorder |
The recorder that detected the error. |
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 *)taskViewControllerParameters
taskViewController |
The calling |
|---|
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
– taskViewControllerShouldConfirmCancel:
Asks the delegate if the cancel action should be confirmed
- (BOOL)taskViewControllerShouldConfirmCancel:(ORKTaskViewController *)taskViewControllerParameters
taskViewController |
The calling |
|---|
Return Value
YES to confirm cancel action; NO to immediately discard the results.
Discussion
The task view controller calls this method to determine whether or not to confirm result save or discard when user attempts to cancel a task that is in progress.
If this method is not implemented, the task view controller assumes that cancel should be confirmed.
If this method returns YES, then cancel action will be confirmed.
If this method returns NO, then the results will immediately be discarded.
Declared In
ORKTaskViewController.h
– taskViewController:hasLearnMoreForStep:
Asks the delegate if there is Learn More content for this step.
- (BOOL)taskViewController:(ORKTaskViewController *)taskViewController hasLearnMoreForStep:(ORKStep *)stepParameters
taskViewController |
The calling |
|---|---|
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 *)stepViewControllerParameters
taskViewController |
The calling |
|---|---|
stepViewController |
The |
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 *)stepParameters
taskViewController |
The calling |
|---|---|
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 *)stepParameters
taskViewController |
The calling |
|---|---|
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 *)stepViewControllerParameters
taskViewController |
The calling |
|---|---|
stepViewController |
The |
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:stepViewControllerWillDisappear:navigationDirection:
Tells the delegate that a step will disappear.
- (void)taskViewController:(ORKTaskViewController *)taskViewController stepViewControllerWillDisappear:(ORKStepViewController *)stepViewController navigationDirection:(ORKStepViewControllerNavigationDirection)directionParameters
taskViewController |
The calling |
|---|---|
stepViewController |
The |
direction |
The |
Discussion
This is called in the ORKStepViewControllerDelegate method for stepViewController:didFinishWithNavigationDirection:
after saving the result of the step to the task view controller and before navigating to the next/previous step.
Declared In
ORKTaskViewController.h
– taskViewController:didChangeResult:
Tells the delegate that the result has substantively changed.
- (void)taskViewController:(ORKTaskViewController *)taskViewController didChangeResult:(ORKTaskResult *)resultParameters
taskViewController |
The calling |
|---|---|
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