blob: bcbd1bdf9a068338f640c63c07ac196625094470 [file] [log] [blame]
// Copyright 2014 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import 'dart:math' as math;
import 'package:flutter/widgets.dart';
import 'constants.dart';
// Examples can assume:
// late BuildContext context;
/// Coordinates tab selection between a [TabBar] and a [TabBarView].
///
/// The [index] property is the index of the selected tab and the [animation]
/// represents the current scroll positions of the tab bar and the tab bar view.
/// The selected tab's index can be changed with [animateTo].
///
/// A stateful widget that builds a [TabBar] or a [TabBarView] can create
/// a [TabController] and share it directly.
///
/// When the [TabBar] and [TabBarView] don't have a convenient stateful
/// ancestor, a [TabController] can be shared by providing a
/// [DefaultTabController] inherited widget.
///
/// {@animation 700 540 https://flutter.github.io/assets-for-api-docs/assets/material/tabs.mp4}
///
/// {@tool snippet}
///
/// This widget introduces a [Scaffold] with an [AppBar] and a [TabBar].
///
/// ```dart
/// class MyTabbedPage extends StatefulWidget {
/// const MyTabbedPage({ super.key });
/// @override
/// State<MyTabbedPage> createState() => _MyTabbedPageState();
/// }
///
/// class _MyTabbedPageState extends State<MyTabbedPage> with SingleTickerProviderStateMixin {
/// static const List<Tab> myTabs = <Tab>[
/// Tab(text: 'LEFT'),
/// Tab(text: 'RIGHT'),
/// ];
///
/// late TabController _tabController;
///
/// @override
/// void initState() {
/// super.initState();
/// _tabController = TabController(vsync: this, length: myTabs.length);
/// }
///
/// @override
/// void dispose() {
/// _tabController.dispose();
/// super.dispose();
/// }
///
/// @override
/// Widget build(BuildContext context) {
/// return Scaffold(
/// appBar: AppBar(
/// bottom: TabBar(
/// controller: _tabController,
/// tabs: myTabs,
/// ),
/// ),
/// body: TabBarView(
/// controller: _tabController,
/// children: myTabs.map((Tab tab) {
/// final String label = tab.text!.toLowerCase();
/// return Center(
/// child: Text(
/// 'This is the $label tab',
/// style: const TextStyle(fontSize: 36),
/// ),
/// );
/// }).toList(),
/// ),
/// );
/// }
/// }
/// ```
/// {@end-tool}
///
/// {@tool dartpad}
/// This example shows how to listen to page updates in [TabBar] and [TabBarView]
/// when using [DefaultTabController].
///
/// ** See code in examples/api/lib/material/tab_controller/tab_controller.1.dart **
/// {@end-tool}
///
class TabController extends ChangeNotifier {
/// Creates an object that manages the state required by [TabBar] and a
/// [TabBarView].
///
/// The [length] must not be null or negative. Typically it's a value greater
/// than one, i.e. typically there are two or more tabs. The [length] must
/// match [TabBar.tabs]'s and [TabBarView.children]'s length.
///
/// The `initialIndex` must be valid given [length] and must not be null. If
/// [length] is zero, then `initialIndex` must be 0 (the default).
TabController({ int initialIndex = 0, Duration? animationDuration, required this.length, required TickerProvider vsync})
: assert(length >= 0),
assert(initialIndex >= 0 && (length == 0 || initialIndex < length)),
_index = initialIndex,
_previousIndex = initialIndex,
_animationDuration = animationDuration ?? kTabScrollDuration,
_animationController = AnimationController.unbounded(
value: initialIndex.toDouble(),
vsync: vsync,
);
// Private constructor used by `_copyWith`. This allows a new TabController to
// be created without having to create a new animationController.
TabController._({
required int index,
required int previousIndex,
required AnimationController? animationController,
required Duration animationDuration,
required this.length,
}) : _index = index,
_previousIndex = previousIndex,
_animationController = animationController,
_animationDuration = animationDuration;
/// Creates a new [TabController] with `index`, `previousIndex`, `length`, and
/// `animationDuration` if they are non-null.
///
/// This method is used by [DefaultTabController].
///
/// When [DefaultTabController.length] is updated, this method is called to
/// create a new [TabController] without creating a new [AnimationController].
TabController _copyWith({
required int? index,
required int? length,
required int? previousIndex,
required Duration? animationDuration,
}) {
if (index != null) {
_animationController!.value = index.toDouble();
}
return TabController._(
index: index ?? _index,
length: length ?? this.length,
animationController: _animationController,
previousIndex: previousIndex ?? _previousIndex,
animationDuration: animationDuration ?? _animationDuration,
);
}
/// An animation whose value represents the current position of the [TabBar]'s
/// selected tab indicator as well as the scrollOffsets of the [TabBar]
/// and [TabBarView].
///
/// The animation's value ranges from 0.0 to [length] - 1.0. After the
/// selected tab is changed, the animation's value equals [index]. The
/// animation's value can be [offset] by +/- 1.0 to reflect [TabBarView]
/// drag scrolling.
///
/// If this [TabController] was disposed, then return null.
Animation<double>? get animation => _animationController?.view;
AnimationController? _animationController;
/// Controls the duration of TabController and TabBarView animations.
///
/// Defaults to kTabScrollDuration.
Duration get animationDuration => _animationDuration;
final Duration _animationDuration;
/// The total number of tabs.
///
/// Typically greater than one. Must match [TabBar.tabs]'s and
/// [TabBarView.children]'s length.
final int length;
void _changeIndex(int value, { Duration? duration, Curve? curve }) {
assert(value >= 0 && (value < length || length == 0));
assert(duration != null || curve == null);
assert(_indexIsChangingCount >= 0);
if (value == _index || length < 2) {
return;
}
_previousIndex = index;
_index = value;
if (duration != null && duration > Duration.zero) {
_indexIsChangingCount += 1;
notifyListeners(); // Because the value of indexIsChanging may have changed.
_animationController!
.animateTo(_index.toDouble(), duration: duration, curve: curve!)
.whenCompleteOrCancel(() {
if (_animationController != null) { // don't notify if we've been disposed
_indexIsChangingCount -= 1;
notifyListeners();
}
});
} else {
_indexIsChangingCount += 1;
_animationController!.value = _index.toDouble();
_indexIsChangingCount -= 1;
notifyListeners();
}
}
/// The index of the currently selected tab.
///
/// Changing the index also updates [previousIndex], sets the [animation]'s
/// value to index, resets [indexIsChanging] to false, and notifies listeners.
///
/// To change the currently selected tab and play the [animation] use [animateTo].
///
/// The value of [index] must be valid given [length]. If [length] is zero,
/// then [index] will also be zero.
int get index => _index;
int _index;
set index(int value) {
_changeIndex(value);
}
/// The index of the previously selected tab.
///
/// Initially the same as [index].
int get previousIndex => _previousIndex;
int _previousIndex;
/// True while we're animating from [previousIndex] to [index] as a
/// consequence of calling [animateTo].
///
/// This value is true during the [animateTo] animation that's triggered when
/// the user taps a [TabBar] tab. It is false when [offset] is changing as a
/// consequence of the user dragging (and "flinging") the [TabBarView].
bool get indexIsChanging => _indexIsChangingCount != 0;
int _indexIsChangingCount = 0;
/// Immediately sets [index] and [previousIndex] and then plays the
/// [animation] from its current value to [index].
///
/// While the animation is running [indexIsChanging] is true. When the
/// animation completes [offset] will be 0.0.
void animateTo(int value, { Duration? duration, Curve curve = Curves.ease }) {
_changeIndex(value, duration: duration ?? _animationDuration, curve: curve);
}
/// The difference between the [animation]'s value and [index].
///
/// The offset value must be between -1.0 and 1.0.
///
/// This property is typically set by the [TabBarView] when the user
/// drags left or right. A value between -1.0 and 0.0 implies that the
/// TabBarView has been dragged to the left. Similarly a value between
/// 0.0 and 1.0 implies that the TabBarView has been dragged to the right.
double get offset => _animationController!.value - _index.toDouble();
set offset(double value) {
assert(value >= -1.0 && value <= 1.0);
assert(!indexIsChanging);
if (value == offset) {
return;
}
_animationController!.value = value + _index.toDouble();
}
@override
void dispose() {
_animationController?.dispose();
_animationController = null;
super.dispose();
}
}
class _TabControllerScope extends InheritedWidget {
const _TabControllerScope({
required this.controller,
required this.enabled,
required super.child,
});
final TabController controller;
final bool enabled;
@override
bool updateShouldNotify(_TabControllerScope old) {
return enabled != old.enabled || controller != old.controller;
}
}
/// The [TabController] for descendant widgets that don't specify one
/// explicitly.
///
/// {@youtube 560 315 https://www.youtube.com/watch?v=POtoEH-5l40}
///
/// [DefaultTabController] is an inherited widget that is used to share a
/// [TabController] with a [TabBar] or a [TabBarView]. It's used when sharing an
/// explicitly created [TabController] isn't convenient because the tab bar
/// widgets are created by a stateless parent widget or by different parent
/// widgets.
///
/// {@animation 700 540 https://flutter.github.io/assets-for-api-docs/assets/material/tabs.mp4}
///
/// ```dart
/// class MyDemo extends StatelessWidget {
/// const MyDemo({super.key});
///
/// static const List<Tab> myTabs = <Tab>[
/// Tab(text: 'LEFT'),
/// Tab(text: 'RIGHT'),
/// ];
///
/// @override
/// Widget build(BuildContext context) {
/// return DefaultTabController(
/// length: myTabs.length,
/// child: Scaffold(
/// appBar: AppBar(
/// bottom: const TabBar(
/// tabs: myTabs,
/// ),
/// ),
/// body: TabBarView(
/// children: myTabs.map((Tab tab) {
/// final String label = tab.text!.toLowerCase();
/// return Center(
/// child: Text(
/// 'This is the $label tab',
/// style: const TextStyle(fontSize: 36),
/// ),
/// );
/// }).toList(),
/// ),
/// ),
/// );
/// }
/// }
/// ```
class DefaultTabController extends StatefulWidget {
/// Creates a default tab controller for the given [child] widget.
///
/// The [length] argument is typically greater than one. The [length] must
/// match [TabBar.tabs]'s and [TabBarView.children]'s length.
///
/// The [initialIndex] argument must not be null.
const DefaultTabController({
super.key,
required this.length,
this.initialIndex = 0,
required this.child,
this.animationDuration,
}) : assert(length >= 0),
assert(length == 0 || (initialIndex >= 0 && initialIndex < length));
/// The total number of tabs.
///
/// Typically greater than one. Must match [TabBar.tabs]'s and
/// [TabBarView.children]'s length.
final int length;
/// The initial index of the selected tab.
///
/// Defaults to zero.
final int initialIndex;
/// Controls the duration of DefaultTabController and TabBarView animations.
///
/// Defaults to kTabScrollDuration.
final Duration? animationDuration;
/// The widget below this widget in the tree.
///
/// Typically a [Scaffold] whose [AppBar] includes a [TabBar].
///
/// {@macro flutter.widgets.ProxyWidget.child}
final Widget child;
/// The closest instance of [DefaultTabController] that encloses the given
/// context, or null if none is found.
///
/// {@tool snippet} Typical usage is as follows:
///
/// ```dart
/// TabController? controller = DefaultTabController.maybeOf(context);
/// ```
/// {@end-tool}
///
/// Calling this method will create a dependency on the closest
/// [DefaultTabController] in the [context], if there is one.
///
/// See also:
///
/// * [DefaultTabController.of], which is similar to this method, but asserts
/// if no [DefaultTabController] ancestor is found.
static TabController? maybeOf(BuildContext context) {
return context.dependOnInheritedWidgetOfExactType<_TabControllerScope>()?.controller;
}
/// The closest instance of [DefaultTabController] that encloses the given
/// context.
///
/// If no instance is found, this method will assert in debug mode and throw
/// an exception in release mode.
///
/// Calling this method will create a dependency on the closest
/// [DefaultTabController] in the [context].
///
/// {@tool snippet} Typical usage is as follows:
///
/// ```dart
/// TabController controller = DefaultTabController.of(context);
/// ```
/// {@end-tool}
///
/// See also:
///
/// * [DefaultTabController.maybeOf], which is similar to this method, but
/// returns null if no [DefaultTabController] ancestor is found.
static TabController of(BuildContext context) {
final TabController? controller = maybeOf(context);
assert(() {
if (controller == null) {
throw FlutterError(
'DefaultTabController.of() was called with a context that does not '
'contain a DefaultTabController widget.\n'
'No DefaultTabController widget ancestor could be found starting from '
'the context that was passed to DefaultTabController.of(). This can '
'happen because you are using a widget that looks for a DefaultTabController '
'ancestor, but no such ancestor exists.\n'
'The context used was:\n'
' $context',
);
}
return true;
}());
return controller!;
}
@override
State<DefaultTabController> createState() => _DefaultTabControllerState();
}
class _DefaultTabControllerState extends State<DefaultTabController> with SingleTickerProviderStateMixin {
late TabController _controller;
@override
void initState() {
super.initState();
_controller = TabController(
vsync: this,
length: widget.length,
initialIndex: widget.initialIndex,
animationDuration: widget.animationDuration,
);
}
@override
void dispose() {
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return _TabControllerScope(
controller: _controller,
enabled: TickerMode.of(context),
child: widget.child,
);
}
@override
void didUpdateWidget(DefaultTabController oldWidget) {
super.didUpdateWidget(oldWidget);
if (oldWidget.length != widget.length) {
// If the length is shortened while the last tab is selected, we should
// automatically update the index of the controller to be the new last tab.
int? newIndex;
int previousIndex = _controller.previousIndex;
if (_controller.index >= widget.length) {
newIndex = math.max(0, widget.length - 1);
previousIndex = _controller.index;
}
_controller = _controller._copyWith(
length: widget.length,
animationDuration: widget.animationDuration,
index: newIndex,
previousIndex: previousIndex,
);
}
if (oldWidget.animationDuration != widget.animationDuration) {
_controller = _controller._copyWith(
length: widget.length,
animationDuration: widget.animationDuration,
index: _controller.index,
previousIndex: _controller.previousIndex,
);
}
}
}