ORKNavigableOrderedTask Class Reference

Inherits from ORKOrderedTask : NSObject
Declared in ORKNavigableOrderedTask.h

The ORKNavigableOrderedTask class adds conditional step navigation to the behavior inherited from the ORKOrderedTask class.

For implementing conditional task navigation, you must instantiate concrete subclasses of ORKStepNavigationRule and ORKSkipStepNavigationRule and attach them to trigger steps by using the setNavigationRule:forTriggerStepIdentifier: and setSkipNavigationRule:forStepIdentifier: methods.

For example, if you want to display a survey question only when the user answered Yes to a previous question you can use ORKPredicateStepNavigationRule; or if you want to define an arbitrary jump between two steps you can use ORKDirectStepNavigationRule. You can also optionally omit steps by using ORKPredicateSkipStepNavigationRule objects.

Note that each step in the task can have at most one attached navigation rule and one attached skip navigation rule.

Navigable ordered tasks support looping over previously visited steps. Note, however, that results for steps that are visited more than once will be ovewritten when you revisit the step on the loop. Thus, going over a loop will produce duplicate results within the task results for the steps that are seen more than once, but all the duplicate step results will point to the same result instance: the one corresponding to the last time you visited the step.

The same applies when navigating backwards over looped steps: only your last valid answer is shown every time you encounter a revisited step.

Other Methods

– setNavigationRule:forTriggerStepIdentifier:

Adds a navigation rule for a trigger step identifier.

- (void)setNavigationRule:(ORKStepNavigationRule *)stepNavigationRule forTriggerStepIdentifier:(NSString *)triggerStepIdentifier

Parameters

stepNavigationRule

The step navigation rule to be used when navigating forward from the trigger step. A strong reference to the rule is kept by the task.

triggerStepIdentifier

The identifier of the step that triggers the rule.

Discussion

The rule will be used to obtain a new destination step when the participant goes forward from the trigger step. You cannot add two different navigation rules to the same trigger step identifier; only the most recently added rule is kept.

Declared In

ORKNavigableOrderedTask.h

– navigationRuleForTriggerStepIdentifier:

Returns the step navigation rule associated with a trigger step identifier, or nil if there is no rule associated with that step identifier.

- (nullable ORKStepNavigationRule *)navigationRuleForTriggerStepIdentifier:(NSString *)triggerStepIdentifier

Parameters

triggerStepIdentifier

The identifier of the step whose rule you want to retrieve.

Return Value

A step navigation rule, or nil if the trigger step identifier has none.

Declared In

ORKNavigableOrderedTask.h

– removeNavigationRuleForTriggerStepIdentifier:

Removes the navigation rule, if any, associated with the specified trigger step identifier.

- (void)removeNavigationRuleForTriggerStepIdentifier:(NSString *)triggerStepIdentifier

Parameters

triggerStepIdentifier

The identifier of the step whose rule is to be removed.

Declared In

ORKNavigableOrderedTask.h

  stepNavigationRules

A dictionary of step navigation rules in the task, keyed by trigger step identifier.

@property (nonatomic, copy, readonly) NSDictionary<NSString*ORKStepNavigationRule*> *stepNavigationRules

Discussion

Each object in the dictionary should be a ORKStepNavigationRule subclass.

Declared In

ORKNavigableOrderedTask.h

– setSkipNavigationRule:forStepIdentifier:

Adds a skip step navigation rule for a step identifier.

- (void)setSkipNavigationRule:(ORKSkipStepNavigationRule *)skipStepNavigationRule forStepIdentifier:(NSString *)stepIdentifier

Parameters

skipStepNavigationRule

The skip step navigation rule to be used to determine if the step should be skipped. A strong reference to the rule is kept by the task.

stepIdentifier

The identifier of the step that is checked against the skip rule.

Discussion

The rule will be used to decide if the identified step needs to be skipped. You cannot add two different skip navigation rules to the same step identifier; only the most recently added rule is kept.

Declared In

ORKNavigableOrderedTask.h

– skipNavigationRuleForStepIdentifier:

Returns the skip step navigation rule associated with a step identifier, or nil if there is no skip rule associated with that step identifier.

- (nullable ORKSkipStepNavigationRule *)skipNavigationRuleForStepIdentifier:(NSString *)stepIdentifier

Parameters

stepIdentifier

The identifier of the step whose skip rule you want to retrieve.

Return Value

A skip step navigation rule, or nil if the step identifier has none.

Declared In

ORKNavigableOrderedTask.h

– removeSkipNavigationRuleForStepIdentifier:

Removes the skip step navigation rule, if any, associated with the specified step identifier.

- (void)removeSkipNavigationRuleForStepIdentifier:(NSString *)stepIdentifier

Parameters

stepIdentifier

The identifier of the step whose rule is to be removed.

Declared In

ORKNavigableOrderedTask.h

  skipStepNavigationRules

A dictionary of step navigation rules in the task, keyed by trigger step identifier.

@property (nonatomic, copy, readonly) NSDictionary<NSString*ORKSkipStepNavigationRule*> *skipStepNavigationRules

Discussion

Each object in the dictionary should be a ORKStepNavigationRule subclass.

Declared In

ORKNavigableOrderedTask.h

– setStepModifier:forStepIdentifier:

Adds a step modifier for a step identifier.

- (void)setStepModifier:(ORKStepModifier *)stepModifier forStepIdentifier:(NSString *)stepIdentifier

Parameters

stepModifier

The step modifier associated with this step

stepIdentifier

The identifier of the step that is checked against the skip rule.

Declared In

ORKNavigableOrderedTask.h

– stepModifierForStepIdentifier:

Returns the step modifier associated with a step identifier, or nil if there is no step modifier associated with that step identifier.

- (nullable ORKStepModifier *)stepModifierForStepIdentifier:(NSString *)stepIdentifier

Parameters

stepIdentifier

The identifier of the step to be modified

Return Value

A step modifier, or nil if the step identifier has none.

Declared In

ORKNavigableOrderedTask.h

– removeStepModifierForStepIdentifier:

Removes the step modifier, if any, associated with the specified step identifier.

- (void)removeStepModifierForStepIdentifier:(NSString *)stepIdentifier

Parameters

stepIdentifier

The identifier of the step whose rule is to be removed.

Declared In

ORKNavigableOrderedTask.h

  stepModifiers

A dictionary of step modifiers in the task, keyed by trigger step identifier.

@property (nonatomic, copy, readonly) NSDictionary<NSString*ORKStepModifier*> *stepModifiers

Discussion

Each object in the dictionary should be a ORKStepModifier subclass.

Declared In

ORKNavigableOrderedTask.h

  shouldReportProgress

Determines whether the task should report its progress as a linear ordered task or not. The default value of this property is NO.

@property (nonatomic) BOOL shouldReportProgress

Declared In

ORKNavigableOrderedTask.h

ORKPredefinedActiveTask Methods

+ holePegTestTaskWithIdentifier:intendedUseDescription:dominantHand:numberOfPegs:threshold:rotated:timeLimit:options:

Returns a predefined task that measures the upper extremity function.

+ (ORKNavigableOrderedTask *)holePegTestTaskWithIdentifier:(NSString *)identifier intendedUseDescription:(nullable NSString *)intendedUseDescription dominantHand:(ORKBodySagittal)dominantHand numberOfPegs:(int)numberOfPegs threshold:(double)threshold rotated:(BOOL)rotated timeLimit:(NSTimeInterval)timeLimit options:(ORKPredefinedTaskOption)options

Parameters

identifier

The task identifier to use for this task, appropriate to the study.

intendedUseDescription

A localized string describing the intended use of the data collected. If the value of this parameter is nil, the default localized text will be displayed.

dominantHand

The participant dominant hand that will be tested first.

numberOfPegs

The number of pegs to place in the pegboard.

threshold

The threshold value used for the detection area.

rotated

A test variant that also requires peg rotation.

timeLimit

The duration allowed to validate the peg position.

options

Options that affect the features of the predefined task.

Return Value

An active hole peg test task that can be presented with an ORKTaskViewController object.

Discussion

In a hole peg test task, the participant is asked to fill holes with pegs.

A hole peg test task can be used to assess arm and hand function, especially in patients with severe disability.

Data collected in this task is in the form of an ORKHolePegTestResult object.

Declared In

ORKNavigableOrderedTask.h