Flutter Gallery Documentation

Codeviewer is a command-line tool used to highlight Dart source code before compilation to prevent delays during app runtime. It scans files in the lib/demos/ folder and writes the highlighted widgets to lib/codeviewer/code_segments.dart.

To generate code segments, run these commands from the gallery/ directory:

1. Ensure grinder is installed: flutter pub get
2. Run the update command: flutter pub run grinder update-code-segments

To mark a specific block of code for highlighting, wrap it with // BEGIN yourDemoName and // END comments.

When processed, the highlighter automatically includes the code within the markers, as well as any copyright notices and imports at the start of the file. The result is stored as a static method: static TextSpan yourDemoName(BuildContext context) inside gallery/lib/codeviewer/code_segments.dart.

To display the highlighted code in the gallery, you must register it in gallery/lib/data/demos.dart by adding the code property to your GalleryDemoConfiguration object:

code: CodeSegments.yourDemoName,

To add new strings to the application, use intl_en.arb as the template. Each new entry must follow a specific format consisting of a Dart getter variable name and a metadata object containing a description. The dartGetterVariableName will be the name used to access the string in your Dart code via the localizations delegate.

Once added to intl_en.arb, you can use the English version immediately in your code after regenerating the GalleryLocalizations delegate, even before other languages are translated.

  "dartGetterVariableName": "english translation of the message",
  "@dartGetterVariableName": {
    "description": "description that the localizations delegate will use."
  },

To see how Material 3 features are implemented in the Flutter Material library, use the Material 3 Demo.

• Web Demo: https://flutter.github.io/samples/web/material_3_demo/
• Source Code: https://github.com/flutter/samples/tree/main/material_3_demo

To run these performance tests, follow the instructions provided in the official Flutter repository's macrobenchmarks documentation. The Gallery benchmarks are integrated into the Flutter web_benchmarks workflow.

Refer to the following external guide for detailed execution steps: https://github.com/flutter/flutter/tree/master/dev/benchmarks/macrobenchmarks#web-benchmarks

If this is the first time building the Flutter Gallery, localized code will not be present in the project directory. After running the application for the first time, a synthetic package is generated containing the app's localizations via package:flutter_gen/gen_l10n/. To generate them manually, run the following commands:

flutter pub get
flutter pub run grinder l10n

Codeviewer supports joining multiple blocks into a single segment or handling nested/overlapping blocks.

Joining Blocks

If you use multiple BEGIN and END markers with different suffixes (e.g., #1, #2), the segments are joined in the order of their suffix number. For example:

// BEGIN yourDemo#2
a();
// END
b();
// BEGIN yourDemo#1
c();
// END

Results in:

c();
a();

Nested and Overlapping Blocks

Blocks can be nested or overlap. When nesting, ensure you specify which file/block to END correctly.

Example of nesting:

// BEGIN demoOne
a();
// BEGIN demoTwo
b();
// END demoOne
c();
// END demoTwo

This produces two segments:

• demoOne: a(); b();
• demoTwo: b(); c();

The Flutter Samples collection provides open source samples that illustrate best practices for Flutter development.

• Samples: https://flutter.github.io/samples
• Source Code: https://github.com/flutter/samples

When an intentional UI change causes golden tests (screenshot tests) to fail, you must update the saved golden images.

Important: Due to rendering differences across platforms (especially regarding text), these tests are designed to run on macOS in GitHub Actions. If you update goldens on Linux or Windows, they will likely fail in the CI environment.

If you are not on macOS, the recommended workflow is:

1. Locate the failed GitHub Actions job.
2. Download the goldens folder from the Artifacts section at the bottom of the Summary page.
3. Use the downloaded images (which include the golden image, the test image, and the difference) within your branch.

flutter test --update-goldens test_goldens