Scope

Shares a value with the widgets below it.

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

// Share a value owned elsewhere:
Scope(project, child: const ProjectPath())

// Create and own a model for this subtree:
Scope.create(Cart.new, child: const ShopScreen())

// Read the nearest one in a descendant's build (it rebuilds on change):
final cart = context.scope<Cart>();

Details

Provide a value once with Scope(model, child: ...), then read the nearest scope with context.scope<Model>() or a ScopeBuilder<Model> — the same read, as a call or as a widget. Widgets between the provider and its readers need not pass the value along. The declared type is the lookup key; an inner scope of that type overrides an outer one.

Readers rebuild when an ordinary value changes according to ==, when a Listenable is replaced by a different instance, or when it notifies. Mutable models extend Notifier and call Notifier.notify after a change. A scope listens on its readers’ behalf, so they need no additional builder.

Scope.create creates and owns a value. Scope.createWithContext also supplies the scope’s own context to a factory that needs ancestor scopes. A reader stays subscribed until it leaves the tree; see BuildContext.scope for where a scope can be read. A value needed in dispose should be saved earlier, before the element leaves the tree.

Constructors

`Scope()`

Shares value without taking ownership or disposing it.

Parameter	Type	Default	Description
`value`	`T`	required	The value exposed to descendant readers under the declared type `T`.
`child:`	`Widget`	required	The subtree that can read this value.

`Scope.create()`

Creates a value once when this scope mounts and owns its lifetime.

Rebuilding retains the value and its original dispose callback. A Notifier is disposed automatically unless a custom callback is supplied. Other resources can be cleaned up with dispose. Children unmount first. Switching from a supplied value to an owned scope also runs create.

Parameter	Type	Default	Description
`create`	`T Function()`	required	Creates the value when this scope begins owning it.
`dispose:`	`void Function(T value)?`	—	Optional cleanup, replacing automatic disposal for a `Notifier`.
`child:`	`Widget`	required	The subtree that can read this value.

`Scope.createWithContext()`

Creates an owned value with access to ancestor scopes.

create receives this scope’s own context and may use context.scope to read ancestors. Its lifetime and disposal follow Scope.create.

Parameter	Type	Default	Description
`create`	`T Function(BuildContext context)`	required	Creates the value with this scope’s context for ancestor lookups.
`dispose:`	`void Function(T value)?`	—	Optional cleanup, replacing automatic disposal for a `Notifier`.
`child:`	`Widget`	required	The subtree that can read this value.

Source

Scope is defined in packages/fleury/lib/src/widgets/framework.dart.

Category: State & async · All widgets

Example · editable

class _ProjectScreenState extends State<ProjectScreen> {
  var project = const Project('Atlas');

  void switchProject() => setState(() {
    project = project.name == 'Atlas'
        ? const Project('Beacon')
        : const Project('Atlas');
  });

  @override
  Widget build(BuildContext context) => Scope(
    project,
    child: Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        const ProjectTitle(),
        const ProjectPath(),
        Button(text: 'Switch project', onPressed: switchProject),
      ],
    ),
  );
}

class ProjectTitle extends StatelessWidget {
  const ProjectTitle({super.key});

  @override
  Widget build(BuildContext context) => ScopeBuilder<Project>(
    builder: (context, project) => Text('Project: ${project.name}'),
  );
}

class ProjectPath extends StatelessWidget {
  const ProjectPath({super.key});

  @override
  Widget build(BuildContext context) {
    final project = context.scope<Project>();
    return Text('Path: ${project.path}');
  }
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs