// 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: // 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({ Key key }) : super(key: key); /// @override /// _MyTabbedPageState createState() => _MyTabbedPageState(); /// } /// /// class _MyTabbedPageState extends State<MyTabbedPage> with SingleTickerProviderStateMixin { /// final List<Tab> myTabs = <Tab>[ /// Tab(text: 'LEFT'), /// Tab(text: 'RIGHT'), /// ]; /// /// 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} 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, @required this.length, @required TickerProvider vsync }) : assert(length != null && length >= 0), assert(initialIndex != null && initialIndex >= 0 && (length == 0 || initialIndex < length)), _index = initialIndex, _previousIndex = initialIndex, _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._({ int index, int previousIndex, AnimationController animationController, @required this.length, }) : _index = index, _previousIndex = previousIndex, _animationController = animationController; /// Creates a new [TabController] with `index`, `previousIndex`, and `length` /// 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({ int index, int length, int previousIndex }) { return TabController._( index: index ?? _index, length: length ?? this.length, animationController: _animationController, previousIndex: previousIndex ?? _previousIndex, ); } /// 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; /// 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 != null); 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) { _indexIsChangingCount += 1; notifyListeners(); // Because the value of indexIsChanging may have changed. _animationController .animateTo(_index.toDouble(), duration: duration, curve: curve) .whenCompleteOrCancel(() { _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 = kTabScrollDuration, Curve curve = Curves.ease }) { _changeIndex(value, duration: duration, 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 != null); 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({ Key key, this.controller, this.enabled, Widget child, }) : super(key: key, child: 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. /// /// [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 { /// final 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: 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({ Key key, @required this.length, this.initialIndex = 0, @required this.child, }) : assert(initialIndex != null), assert(length >= 0), assert(length == 0 || (initialIndex >= 0 && initialIndex < length)), super(key: key); /// 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; /// The widget below this widget in the tree. /// /// Typically a [Scaffold] whose [AppBar] includes a [TabBar]. /// /// {@macro flutter.widgets.child} final Widget child; /// The closest instance of this class that encloses the given context. /// /// {@tool snippet} /// Typical usage is as follows: /// /// ```dart /// TabController controller = DefaultTabController.of(context); /// ``` /// {@end-tool} static TabController of(BuildContext context) { final _TabControllerScope scope = context.dependOnInheritedWidgetOfExactType<_TabControllerScope>(); return scope?.controller; } @override _DefaultTabControllerState createState() => _DefaultTabControllerState(); } class _DefaultTabControllerState extends State<DefaultTabController> with SingleTickerProviderStateMixin { TabController _controller; @override void initState() { super.initState(); _controller = TabController( vsync: this, length: widget.length, initialIndex: widget.initialIndex, ); } @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, index: newIndex, previousIndex: previousIndex, ); } } }