flutter_queue_it 0.10.1
flutter_queue_it: ^0.10.1 copied to clipboard
Flutter integration for QueueIt. Provides a widget that automatically rebuilds when the queue is updated.
flutter_queue_it #
Flutter integration with queue_it.
Provides the QueueItWidget widget that listens to the queue and automatically
rebuilds on changes, and the QueueItListener widget that lets you react to every change
without rebuilding.
Getting started #
flutter pub add flutter_queue_it
flutter_queue_it exports queue_it, so it's the only package you need to add and import. It requires Dart 3.5 and Flutter 3.24 or later.
Example #
This app processes "uploads" two at a time and lists them with their status:
// lib/main.dart
import 'package:flutter/material.dart';
import 'package:flutter_queue_it/flutter_queue_it.dart';
void main() => runApp(const MaterialApp(home: UploadsPage()));
class UploadsPage extends StatefulWidget {
const UploadsPage({super.key});
@override
State<UploadsPage> createState() => _UploadsPageState();
}
class _UploadsPageState extends State<UploadsPage> {
/// Keep the queue in your `State`, so it survives rebuilds
final _queue = QueueIt<String>(
parallel: 2,
itemHandler: (item) async {
/// Fake upload time
await Future<void>.delayed(const Duration(seconds: 1));
},
);
var _count = 0;
@override
void dispose() {
/// The widgets never dispose of the queue, so do it here
_queue.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Uploads')),
body: QueueItWidget<String>(
queue: _queue,
builder: (context, snapshot) {
/// `builder` will be called each time the queue updates
final items = _queue.items().toList();
return Column(
children: [
/// The progress of the current batch: the uploads added since the
/// queue last ran out of work
if (_queue.isProcessing)
LinearProgressIndicator(
value: _queue.currentBatchItems.progress,
),
Expanded(
child: ListView.builder(
itemCount: items.length,
itemBuilder: (context, index) {
final item = items[index];
return ListTile(
title: Text(item.data),
subtitle: Text('Item status: ${item.status.name}'),
);
},
),
),
],
);
},
),
floatingActionButton: FloatingActionButton(
/// Add an item and start the queue. The queue stops by itself once every
/// item is processed, and starting it while it's running does nothing
onPressed: () => _queue
..add('photo_${++_count}.jpg')
..start(),
tooltip: 'Add upload',
child: const Icon(Icons.add),
),
);
}
}
Rebuilding less often #
Use buildWhen to only rebuild for the updates you care about:
QueueItWidget(
queue: _queue,
/// Only rebuild when the queue starts or stops
buildWhen: (snapshot) =>
snapshot.event == QueueEvent.startedQueue ||
snapshot.event == QueueEvent.stoppedQueue,
builder: (context, snapshot) {
return Text(_queue.isStarted ? 'Running' : 'Stopped');
},
);
Reacting to every update #
builder isn't the place to show a message or log something, because it can skip updates and
Flutter can call it at other times. Use QueueItListener instead:
QueueItListener(
queue: _queue,
listener: (context, snapshot) {
/// `listener` will be called once for every update, without rebuilding.
/// Processing also stops when the queue is stopped, so check that no
/// uploads are left
if (snapshot.event == QueueEvent.stoppedProcessing &&
snapshot.items.pending.isEmpty) {
ScaffoldMessenger.of(context).showSnackBar(
const SnackBar(content: Text('All uploads processed')),
);
}
},
child: const UploadList(),
);
The listener can call the queue too. It's called as soon as the queue sends an update. Updates sent
while Flutter is building or disposing widgets, for example from a widget's initState or
dispose, reach the listener right after that frame, so it can still show a SnackBar. Once the
widget is being removed, the listener isn't called any more.
Good to know #
- The first build gets a null
snapshot. The queue doesn't replay updates sent before the widget started listening, so read the current state from the queue itself:queue.items(),queue.isStartedandqueue.isProcessingare always up to date. - Updates sent in the same frame cause a single rebuild with the latest snapshot. Updates sent
while Flutter is building, for example from a widget's
initStateordispose, rebuild the widget right after that frame. snapshot.eventtells you what happened, andsnapshot.eventItemis a copy of the item the update is about, taken at that moment.snapshot.itemsholds the queue's own items, so they show each item's current status (and leave out the ones removed since), unless the queue was created withdeepCopyItemsInSnapshot: true.- The widgets never start, stop or dispose of the queue. Keep the queue somewhere that outlives
rebuilds, like a
State, and calldispose()on it when you're done. - Any number of widgets can listen to the same queue, such as a list and a counter in the app bar.
- If a rebuild passes a different queue, the widgets switch to it. Until the new queue changes,
builderstill gets the old queue's last snapshot. Updates from the old queue that were still waiting for the end of the frame don't reachlistener.
Migrating from 0.9 #
- flutter_queue_it now exports queue_it, so you can remove the
package:queue_it/queue_it.dartimport (the analyzer reports it as unnecessary) and thequeue_itdependency. If you keep the dependency, update it to 0.10.0. - queue_it 0.10.0 has a few breaking changes of its own. Check out the migration notes in its README.
- flutter_queue_it now requires Dart 3.5 and Flutter 3.24 or later.
For a more in-depth example, check out the example project.