Allow generating page content to be asynchronous

[grahamsmith]

I open this to feedback.

Premise

I've been building some complicated PDFs and it would be great if we could generate the list of widgets per page asynchronously. Things like maps, data from other services etc. The change would allow for example GraphPage to build its own content and handle its errors etc.

Example

Future<Uint8List> generate() async {
    logger.i('Generating PDF report with ${pages.length} pages');

    final pdf = Document();

    for (final page in pages) {
      await page.preProcessor();

      try {
        final pdfPage = MultiPage(
          pageTheme: pageTheme,
          maxPages: 8000,
          build: (context) => await page.generate(context), //we can create the content async here
        );

        pdf.addPage(pdfPage);
      } on TooManyPagesException catch (e) {
        logger.e('Too many pages when generating page ${page.pageName} with ${e.message}');
      } catch (e, stackTrace) {
        logger.e('Error generating page ${page.pageName}, stackTrace: $stackTrace');
      }
    }

    return pdf.save();
  }

We could get all the data and pass it all in, but this also means we can't have nice component style pages that deal with what they need to do in order to get their content and lay it out.

What about existing users?

Hoping to minimise any disruption to current users via FutureOr<>. You don't have to be async unless you want to be.

Fallout

The built in charts legend now has a seperate tyedef to save the asynchronous code propagating further than it need to.

[grahamsmith]

@DavBfr let me know your thoughts. Appreciate you are busy.

[DavBfr]

I don't see any reason for async build methods. There is no interaction, so everything can be calculated before generating the PDF document.
We don't want to encourage people to do network image fetch during PDF creation each time the document is rebuilt using Printing.layoutPdf() Changing the printer, the page format, color type, etc. re-triggers a new Pdf creation.