AppTaskController

Keeps the queue of UserTasks that the user needs to do.

A singleton. When an AppTask is triggered, its AppTaskExecutor is wrapped in a UserTask by a UserTaskFactory and enqueued here. The app shows userTaskQueue to the user (e.g., as a task list) and listens to userTaskEvents for changes.

Key points:

• Asks the NotificationManager to notify about each enqueued task, if notifications are enabled in initialize.
• Tasks from schedulable triggers are first buffered, then enqueueBufferedTasks schedules as many as the OS notification limit allows.
• Tasks whose AppTask.expire has passed are expired once an hour.
• The queue is restored from the PersistenceService on initialize.

See also UserTask, whose callbacks the app calls to start and finish a task.

Constructors

AppTaskController

AppTaskController()

Returns the singleton AppTaskController.

Properties

notificationManager

NotificationManager get notificationManager

The client's notification controller for sending notifications to the user.

notificationsEnabled

bool get notificationsEnabled

Whether this controller sends notifications to the user.

Set in initialize.

taskCompleted

int get taskCompleted

The number of done tasks in the userTaskQueue.

taskExpired

int get taskExpired

The number of expired tasks in the userTaskQueue.

taskPending

int get taskPending

The number of UserTaskState.enqueued tasks in the userTaskQueue.

taskTotal

int get taskTotal

The number of tasks in the userTaskQueue.

userTaskEvents

Stream<UserTask> get userTaskEvents

Emits a UserTask each time the controller changes it.

That is, when it is enqueued, dequeued, notified, done or expired. Other state changes (e.g. started) are only on UserTask.stateEvents.

Useful in a StreamBuilder to rebuild a task list.

userTaskQueue

List<UserTask> get userTaskQueue

The UserTasks whose trigger time has passed.

These are the tasks to show to the user. Includes done and expired tasks until they are dequeued.

userTasks

List<UserTask> get userTasks

All UserTasks, including those scheduled to trigger in the future.

Methods

buffer

void buffer(

1. AppTaskExecutor<AppTask> executor,
2. TaskControl taskControl, {
3. DateTime? triggerTime,
4. bool sendNotification = true,

})

Buffers executor from taskControl to be enqueued later.

The task triggers at triggerTime, default now.

Buffered tasks are enqueued by enqueueBufferedTasks.

dequeue

void dequeue(

1. String id

)

Removes the UserTask with id and cancels its notification.

dispose

void dispose()

Stops the expiry check and closes userTaskEvents.

No further app tasks can be enqueued afterwards.

done

void done(

1. String id, [
2. Data? result

])

Marks the UserTask with id as done, with an optional result.

A done task stays on the queue. Use dequeue to remove it. Usually called through UserTask.onDone.

enqueue

Future<UserTask?> enqueue(

1. AppTaskExecutor<AppTask> executor, {
2. DateTime? triggerTime,
3. bool sendNotification = true,

})

Creates a UserTask for the AppTask run by executor and enqueues it.

triggerTime is when the task becomes available; defaults to now. If sendNotification and notificationsEnabled are true, the NotificationManager is asked to show a notification now (if triggerTime is null) or to schedule one for triggerTime. It still skips tasks with AppTask.notification off and past trigger times.

Returns null if no UserTaskFactory is registered for the task's type.

enqueueBufferedTasks

Future<void> enqueueBufferedTasks()

Enqueues the tasks buffered with buffer, earliest first.

Only as many tasks are enqueued as there are free notification slots (NotificationManager.pendingNotificationLimit minus pending ones). The rest are discarded and buffered again on a later resume. Each enqueued task updates TaskControl.hasBeenScheduledUntil.

Called by the SmartphoneDeploymentExecutor when it resumes.

expire

void expire(

1. String id

)

Marks the UserTask with id as expired, unless it is done.

Also cancels its notification.

An expired task stays on the queue. Use dequeue to remove it.

getUserTask

UserTask? getUserTask(

1. String id

)

Returns the UserTask with id, or null if no task is found.

initialize

Future<void> initialize({

1. bool enableNotifications = true,

})

Restores the queue of UserTasks from persistent storage.

Also starts the hourly check for expired tasks.

If enableNotifications is true, a notification is shown when a task is enqueued.

Called by SmartPhoneClientManager.configure.

onNotification

void onNotification(

1. String id

)

Called when the user taps the OS notification of the UserTask with id.

If the task is enqueued or canceled, moves it to UserTaskState.notified and calls UserTask.onNotification.

registerUserTaskFactory

void registerUserTaskFactory(

1. UserTaskFactory factory

)

Registers factory for each AppTask.type in UserTaskFactory.types.

A later factory for the same type replaces an earlier one. A SensingUserTaskFactory is registered by default.

removeStudy

void removeStudy(

1. SmartphoneStudy study

)

Removes all tasks of study and cancels their notifications.