From 139600418b85482005d3beac5a0d22cf2742c0fe Mon Sep 17 00:00:00 2001 From: pubiqq Date: Mon, 5 Dec 2022 18:01:09 -0500 Subject: [PATCH] [TabLayout] Fix confusing documentation Resolves https://github.com/material-components/material-components-android/pull/3098 GIT_ORIGIN_REV_ID=200a9d2f97bffa86a2b8ee3c3746fc7b5718b7a5 PiperOrigin-RevId: 493122430 --- .../android/material/tabs/TabLayout.java | 68 +++++++++++-------- .../material/tabs/TabLayoutMediator.java | 7 +- 2 files changed, 43 insertions(+), 32 deletions(-) diff --git a/lib/java/com/google/android/material/tabs/TabLayout.java b/lib/java/com/google/android/material/tabs/TabLayout.java index 493734f3cec..52303d6d8f4 100644 --- a/lib/java/com/google/android/material/tabs/TabLayout.java +++ b/lib/java/com/google/android/material/tabs/TabLayout.java @@ -339,8 +339,8 @@ public class TabLayout extends HorizontalScrollView { public static final int INDICATOR_GRAVITY_TOP = 2; /** - * Indicator gravity used to stretch the tab selection indicator across the entire height and - * width of the {@link TabLayout}. This will disregard {@code tabIndicatorHeight} and the + * Indicator gravity used to stretch the tab selection indicator across the entire height + * of the {@link TabLayout}. This will disregard {@code tabIndicatorHeight} and the * indicator drawable's intrinsic height, if set. * * @see #setSelectedTabIndicatorGravity(int) @@ -717,36 +717,45 @@ public void setSelectedTabIndicatorHeight(int height) { } /** - * Set the scroll position of the tabs. This is useful for when the tabs are being displayed as - * part of a scrolling container such as {@link androidx.viewpager.widget.ViewPager}. + * Set the scroll position of the {@link TabLayout}. * - *

Calling this method does not update the selected tab, it is only used for drawing purposes. - * - * @param position current scroll position + * @param position Position of the tab to scroll. * @param positionOffset Value from [0, 1) indicating the offset from {@code position}. - * @param updateSelectedText Whether to update the text's selected state. + * @param updateSelectedTabView Whether to draw the tab at the specified position + positionOffset + * as selected. + *

Note that calling the method with {@code updateSelectedTabView = true} + * does not select a tab at the specified position, but only draws it + * as selected. This can be useful for when the TabLayout behavior needs to be linked to + * another view, such as {@link androidx.viewpager.widget.ViewPager}. * @see #setScrollPosition(int, float, boolean, boolean) */ - public void setScrollPosition(int position, float positionOffset, boolean updateSelectedText) { - setScrollPosition(position, positionOffset, updateSelectedText, true); + public void setScrollPosition(int position, float positionOffset, boolean updateSelectedTabView) { + setScrollPosition(position, positionOffset, updateSelectedTabView, true); } /** - * Set the scroll position of the tabs. This is useful for when the tabs are being displayed as - * part of a scrolling container such as {@link androidx.viewpager.widget.ViewPager}. - * - *

Calling this method does not update the selected tab, it is only used for drawing purposes. + * Set the scroll position of the {@link TabLayout}. * - * @param position current scroll position + * @param position Position of the tab to scroll. * @param positionOffset Value from [0, 1) indicating the offset from {@code position}. - * @param updateSelectedText Whether to update the text's selected state. - * @param updateIndicatorPosition Whether to set the indicator to the given position and offset. + * @param updateSelectedTabView Whether to draw the tab at the specified position + positionOffset + * as selected. + *

Note that calling the method with {@code updateSelectedTabView = true} + * does not select a tab at the specified position, but only draws it + * as selected. This can be useful for when the TabLayout behavior needs to be linked to + * another view, such as {@link androidx.viewpager.widget.ViewPager}. + * @param updateIndicatorPosition Whether to set the indicator to the specified position and + * offset. + *

Note that calling the method with {@code updateIndicatorPosition = true} + * does not select a tab at the specified position, but only updates the indicator + * position. This can be useful for when the TabLayout behavior needs to be linked to + * another view, such as {@link androidx.viewpager.widget.ViewPager}. * @see #setScrollPosition(int, float, boolean) */ public void setScrollPosition( int position, float positionOffset, - boolean updateSelectedText, + boolean updateSelectedTabView, boolean updateIndicatorPosition) { final int roundedPosition = Math.round(position + positionOffset); if (roundedPosition < 0 || roundedPosition >= slidingTabIndicator.getChildCount()) { @@ -765,7 +774,7 @@ public void setScrollPosition( scrollTo(position < 0 ? 0 : calculateScrollXForTab(position, positionOffset), 0); // Update the 'selected state' view as we scroll, if enabled - if (updateSelectedText) { + if (updateSelectedTabView) { setSelectedTabView(roundedPosition); } } @@ -976,7 +985,7 @@ protected boolean releaseFromTabPool(Tab tab) { } /** - * Returns the number of tabs currently registered with the action bar. + * Returns the number of tabs currently registered with the tab layout. * * @return Tab count */ @@ -1047,7 +1056,7 @@ public void removeTabAt(int position) { } } - /** Remove all tabs from the action bar and deselect the current tab. */ + /** Remove all tabs from the tab layout and deselect the current tab. */ public void removeAllTabs() { // Remove all the views for (int i = slidingTabIndicator.getChildCount() - 1; i >= 0; i--) { @@ -1125,7 +1134,7 @@ public int getTabGravity() { * (preferred), via the {@code tabIndicatorHeight} attribute (deprecated), or via {@link * #setSelectedTabIndicatorHeight(int)} (deprecated). Otherwise, the indicator will not be shown * unless gravity is set to {@link #INDICATOR_GRAVITY_STRETCH}, in which case it will ignore - * indicator height and stretch across the entire height and width of the {@link TabLayout}. This + * indicator height and stretch across the entire height of the {@link TabLayout}. This * defaults to {@link #INDICATOR_GRAVITY_BOTTOM} if not set. * * @param indicatorGravity one of {@link #INDICATOR_GRAVITY_BOTTOM}, {@link @@ -1950,7 +1959,7 @@ public void selectTab(@Nullable Tab tab) { * reselected, regardless of the value of {@code updateIndicator}. * * @param tab The tab to select, or {@code null} to select none. - * @param updateIndicator Whether to animate to the selected tab. + * @param updateIndicator Whether to update the indicator. * @see #selectTab(Tab) */ public void selectTab(@Nullable final Tab tab, boolean updateIndicator) { @@ -2222,10 +2231,10 @@ public Drawable getIcon() { } /** - * Return the current position of this tab in the action bar. + * Return the current position of this tab in the tab layout. * * @return Current position, or {@link #INVALID_POSITION} if this tab is not currently in the - * action bar. + * tab layout. */ public int getPosition() { return position; @@ -2390,7 +2399,7 @@ public int getTabLabelVisibility() { return this.labelVisibilityMode; } - /** Select this tab. Only valid if the tab has been added to the action bar. */ + /** Select this tab. Only valid if the tab has been added to the tab layout. */ public void select() { if (parent == null) { throw new IllegalArgumentException("Tab not attached to a TabLayout"); @@ -3517,16 +3526,17 @@ public void onPageScrolled( final int position, final float positionOffset, final int positionOffsetPixels) { final TabLayout tabLayout = tabLayoutRef.get(); if (tabLayout != null) { - // Only update the text selection if we're not settling, or we are settling after + // Only update the tab view selection if we're not settling, or we are settling after // being dragged - final boolean updateText = + final boolean updateSelectedTabView = scrollState != SCROLL_STATE_SETTLING || previousScrollState == SCROLL_STATE_DRAGGING; // Update the indicator if we're not settling after being idle. This is caused // from a setCurrentItem() call and will be handled by an animation from // onPageSelected() instead. final boolean updateIndicator = !(scrollState == SCROLL_STATE_SETTLING && previousScrollState == SCROLL_STATE_IDLE); - tabLayout.setScrollPosition(position, positionOffset, updateText, updateIndicator); + tabLayout.setScrollPosition( + position, positionOffset, updateSelectedTabView, updateIndicator); } } diff --git a/lib/java/com/google/android/material/tabs/TabLayoutMediator.java b/lib/java/com/google/android/material/tabs/TabLayoutMediator.java index d2b40622725..94e219ae024 100644 --- a/lib/java/com/google/android/material/tabs/TabLayoutMediator.java +++ b/lib/java/com/google/android/material/tabs/TabLayoutMediator.java @@ -220,16 +220,17 @@ public void onPageScrollStateChanged(final int state) { public void onPageScrolled(int position, float positionOffset, int positionOffsetPixels) { TabLayout tabLayout = tabLayoutRef.get(); if (tabLayout != null) { - // Only update the text selection if we're not settling, or we are settling after + // Only update the tab view selection if we're not settling, or we are settling after // being dragged - boolean updateText = + boolean updateSelectedTabView = scrollState != SCROLL_STATE_SETTLING || previousScrollState == SCROLL_STATE_DRAGGING; // Update the indicator if we're not settling after being idle. This is caused // from a setCurrentItem() call and will be handled by an animation from // onPageSelected() instead. boolean updateIndicator = !(scrollState == SCROLL_STATE_SETTLING && previousScrollState == SCROLL_STATE_IDLE); - tabLayout.setScrollPosition(position, positionOffset, updateText, updateIndicator); + tabLayout.setScrollPosition( + position, positionOffset, updateSelectedTabView, updateIndicator); } }