ORKStep Class Reference
ORKStep is the base class for the steps that can compose a task for presentation
ORKTaskViewController object. Each
ORKStep object represents one logical piece of data
entry or activity in a larger task.
A step can be a question, an active test, or a simple instruction. An
subclass is usually paired with an
ORKStepViewController subclass that displays the step.
To use a step, instantiate an
ORKStep object and populate its properties. Add the step to a task,
such as an
ORKOrderedTask object, and then present the task using a task view controller (an
To implement a new type of step, subclass
ORKStep and add your additional
properties. Separately, subclass
ORKStepViewController and implement
your user interface. Note that if your step is timed or requires sensor data collection,
you should consider subclassing
Returns a new step initialized with the specified identifier.
- (instancetype)initWithIdentifier:(NSString *)identifier
The unique identifier of the step.
A new step.
This method is the primary designated initializer.
Returns a new step initialized from data in the given unarchiver.
- (instancetype)initWithCoder:(NSCoder *)aDecoder
Coder from which to initialize the step.
A new step.
Returns a copy of this step initialized with the specified identifier.
- (instancetype)copyWithIdentifier:(NSString *)identifier
The unique identifier for the new step to be returned.
A new step.
A short string that uniquely identifies the step within the task.
@property (nonatomic, copy, readonly) NSString *identifier
The identifier is reproduced in the results of a step. In fact, the only way to link a result
ORKStepResult object) to the step that generated it is to look at the value of
identifier. To accurately identify step results, you need to ensure that step identifiers
are unique within each task.
In some cases, it can be useful to link the step identifier to a unique identifier in a database; in other cases, it can make sense to make the identifier human readable.
A Boolean value indicating whether a task can be restored to the step during state restoration. (read-only)
@property (nonatomic, readonly, getter=isRestorable) BOOL restorable
By default, the value of this property is
YES, but subclasses of
ORKStep might use
If a task cannot be restored to the step, the task is typically restored to the last restorable step in the task, or to the first step, if no restorable steps are available.
A Boolean value indicating whether the user can skip the step without providing an answer.
@property (nonatomic, getter=isOptional) BOOL optional
The default value of this property is
YES. When the value is
NO, the Skip button does not
appear on this step.
This property may not be meaningful for all steps; for example, an active step might not provide a way to skip, because it requires a timer to finish.
The primary text to display for the step in a localized string.
@property (nonatomic, copy, nullable) NSString *title
Additional text to display for the step in a localized string.
@property (nonatomic, copy, nullable) NSString *text
The additional text is displayed in a smaller font below
title. If you need to display a
long question, it can work well to keep the title short and put the additional content in
The task that contains the step.
@property (nonatomic, weak, nullable) id<ORKTask> task
The value of
task is usually set when a step is added to the
Although it’s a good idea to set this property when you implement a custom task, it’s important
to note that the use of this property is a convenience, and should not be relied
upon within the ResearchKit framework.
The set of access permissions required for the step. (read-only)
@property (nonatomic, readonly) ORKPermissionMask requestedPermissions
The permission mask is used by the task view controller to determine the types of access to request from users when they complete the initial instruction steps in a task. If your step requires access to APIs that limit access, include the permissions you require in this mask.
By default, the property scans the recorders and collates the permissions required by the recorders. Subclasses may override this implementation.
The set of HealthKit types the step requests for reading. (read-only)
@property (nonatomic, readonly, nullable) NSSet<HKObjectType*> *requestedHealthKitTypesForReading
The task view controller uses this set of types when constructing a list of all the HealthKit types required by all the steps in a task, so that it can present the HealthKit access dialog just once during that task.
By default, the property scans the recorders and collates the HealthKit types the recorders require. Subclasses may override this implementation.
Checks the parameters of the step and throws exceptions on invalid parameters.
This method is called when there is a need to validate the step’s parameters, which is typically
the case when adding a step to an
ORKStepViewController object, and when presenting the
step view controller.
Subclasses should override this method to provide validation of their additional properties, and must call super.
Returns the class that the task view controller should instantiate to display this step.
Instantiates a step view controller for this class.
- (ORKStepViewController *)instantiateStepViewControllerWithResult:(ORKResult *)result
The result associated with this step
A newly initialized step view controller.
This method is called when a step is about to be presented. The default implementation returns
a view controller that is appropriate to this step by allocating an instance of
stepViewControllerClass method and initializing that instance by calling
on the provided
ORKStepViewController class instance.
Override this method if you need to customize the behavior before presenting the step or if the view controller is presented using a nib or storyboard.