org.researchstack.backbone.task

Class Task

java.lang.Object

org.researchstack.backbone.task.Task

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

OrderedTask

public abstract class Task
extends java.lang.Object
implements java.io.Serializable

A task to be carried out by a participant in a research study.

To present the ResearchStack framework UI in your app, instantiate an object that extends the Task class (such as OrderedTask) and provide it to a ViewTaskActivity.

Implement this protocol to enable dynamic selection of the steps for a given task. By default, OrderedTask implements this protocol for simple sequential tasks.

Each Step in a task roughly corresponds to one screen, and represents the primary unit of work in any task. For example, a QuestionStep object corresponds to a single question presented on screen, together with controls the participant uses to answer the question. Another example is FormStep, which corresponds to a single screen that displays multiple questions or items for which participants provide information, such as first name, last name, and birth date.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Task.InvalidTaskException Runtime exception that is thrown by Task subclasses in validateParameters().
static class	Task.TaskProgress A structure that represents how far a task has progressed.
static class	Task.ViewChangeType

Constructor Summary

Constructors

Constructor and Description
Task(java.lang.String identifier) Class constructor specifying a unique identifier.

Method Summary

Modifier and Type	Method and Description
java.lang.String	getIdentifier() Gets the unique identifier for this task.
abstract Task.TaskProgress	getProgressOfCurrentStep(Step step, TaskResult result) Returns the progress of the current step.
abstract Step	getStepAfterStep(Step step, TaskResult result) Returns the step after the specified step, if there is one.
abstract Step	getStepBeforeStep(Step step, TaskResult result) Returns the step that precedes the specified step, if there is one.
abstract Step	getStepWithIdentifier(java.lang.String identifier) Returns the step that matches the specified identifier, if there is one.
java.lang.String	getTitleForStep(android.content.Context context, Step step) Gets the title to display in the toolbar for a given step.
void	onViewChange(Task.ViewChangeType type, ViewTaskActivity activity, Step currentStep) Function that can be overridden in order to access the low level changes in the view.
abstract void	validateParameters() Validates the task parameters.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Task

public Task(java.lang.String identifier)

Class constructor specifying a unique identifier.

Parameters:

identifier - the task identifier, see getIdentifier()

Method Detail

getIdentifier

public java.lang.String getIdentifier()

Gets the unique identifier for this task.

The identifier should be a short string that identifies the task. The identifier is copied into the TaskResult objects generated for this task. You can use a human-readable string for the task identifier or a UUID; the exact string you use depends on your app.

In the case of apps whose tasks come from a server, the unique identifier for the task may be in an external database.

The task identifier is used when constructing the task result. The identifier can also be used during UI state restoration to identify the task that needs to be restored.

Returns:

the task identifier

getTitleForStep

public java.lang.String getTitleForStep(android.content.Context context,
                                        Step step)

Gets the title to display in the toolbar for a given step.

Override this method to return a custom title, such a text representation of the current progress instead of the step's title.

The default implementation gets the title from string resources if it exists, otherwise it returns an empty string.

Parameters:

context - for fetching resources

step - the current step

Returns:

the title to display

getStepAfterStep

public abstract Step getStepAfterStep(Step step,
                                      TaskResult result)

Returns the step after the specified step, if there is one.

This method lets you use a result to determine the next step.

The ViewTaskActivity calls this method to determine the step to display after the specified step. The ViewTaskActivity can also call this method every time the result updates, to determine if the new result changes which steps are available.

If you need to implement this method, take care to avoid creating a confusing sequence of steps. As much as possible, use OrderedTask instead.

Parameters:

step - The reference step. Pass null to specify the first step.

result - A snapshot of the current set of results.

Returns:

The step that comes after the specified step, or null if there isn't one.

getStepBeforeStep

public abstract Step getStepBeforeStep(Step step,
                                       TaskResult result)

Returns the step that precedes the specified step, if there is one.

The ViewTaskActivity calls this method to determine the step to display before the specified step. The ViewTaskActivity can also call this method every time the result changes, to determine if the new result changes which steps are available.

If you need to implement this method, take care to avoid creating a confusing sequence of steps. As much as possible, use OrderedTask instead. Returning null prevents the user from navigating back to a previous step.

Parameters:

step - The reference step. Pass null to specify the last step.

result - A snapshot of the current set of results.

Returns:

The step that precedes the reference step, or null if there isn't one.

getStepWithIdentifier

public abstract Step getStepWithIdentifier(java.lang.String identifier)

Returns the step that matches the specified identifier, if there is one.

Parameters:

identifier - The identifier of the step to retrieve.

Returns:

The step that matches the specified identifier.

getProgressOfCurrentStep

public abstract Task.TaskProgress getProgressOfCurrentStep(Step step,
                                                           TaskResult result)

Returns the progress of the current step.

During a task, the ViewTaskActivity can display the progress (that is, the current step number out of the total number of steps) in the navigation bar. Implement this method to control what is displayed; if you don't implement this method, the progress label does not appear.

If the returned Task.TaskProgress object has a count of 0, the progress is not displayed.

Parameters:

step - The current step.

result - A snapshot of the current set of results.

Returns:

The current step's index and the total number of steps in the task, as an TaskProgress object.

validateParameters

public abstract void validateParameters()

Validates the task parameters.

The implementation of this method should check that all the task parameters are correct. An invalid task is considered an unrecoverable error: the implementation should throw an exception on parameter validation failure. For example, the OrderedTask implementation makes sure that all its step identifiers are unique, throwing an exception otherwise.

This method is usually called by ViewTaskActivity when its task is set.

Throws:

Task.InvalidTaskException

onViewChange

public void onViewChange(Task.ViewChangeType type,
                         ViewTaskActivity activity,
                         Step currentStep)

Function that can be overridden in order to access the low level changes in the view. The function is called at Activity lifecycle events (creation, pause, resume, stop and whenever the content of the activity is changed, according to the step.

Parameters:

type - lifecycle event

activity - current activity

currentStep - the current step being shown