Class TabLayout

All Implemented Interfaces:
Drawable.Callback, ViewManager, ViewParent

public class TabLayout extends HorizontalScrollView
TabLayout provides a horizontal layout to display tabs.

Population of the tabs to display is done through TabLayout.Tab instances. You create tabs via newTab(). From there you can change the tab's label or icon via TabLayout.Tab.setText(java.lang.CharSequence) and TabLayout.Tab.setIcon(icyllis.modernui.graphics.drawable.Drawable) respectively. To display the tab, you need to add it to the layout via one of the addTab(Tab) methods. For example:

 TabLayout tabLayout = ...;
 tabLayout.addTab(tabLayout.newTab().setText("Tab 1"));
 tabLayout.addTab(tabLayout.newTab().setText("Tab 2"));
 tabLayout.addTab(tabLayout.newTab().setText("Tab 3"));
 
You should add a listener via addOnTabSelectedListener(OnTabSelectedListener) to be notified when any tab's selection state has been changed.

ViewPager integration

If you're using a ViewPager together with this layout, you can call setupWithViewPager(ViewPager) to link the two together. This layout will be automatically populated from the PagerAdapter's page titles.

This view also supports being used as part of a ViewPager's decor, and can be added directly to the ViewPager.

For more information, see the component developer guidance and design guidelines.

  • Field Details

    • MODE_SCROLLABLE

      public static final int MODE_SCROLLABLE
      Scrollable tabs display a subset of tabs at any given moment, and can contain longer tab labels and a larger number of tabs. They are best used for browsing contexts in touch interfaces when users don't need to directly compare the tab labels.
      See Also:
    • MODE_FIXED

      public static final int MODE_FIXED
      Fixed tabs display all tabs concurrently and are best used with content that benefits from quick pivots between tabs. The maximum number of tabs is limited by the view's width. Fixed tabs have equal width, based on the widest tab label.
      See Also:
    • MODE_AUTO

      public static final int MODE_AUTO
      Auto-sizing tabs behave like MODE_FIXED with GRAVITY_CENTER while the tabs fit within the TabLayout's content width. Fixed tabs have equal width, based on the widest tab label. Once the tabs outgrow the view's width, auto-sizing tabs behave like MODE_SCROLLABLE, allowing for a dynamic number of tabs without requiring additional layout logic.
      See Also:
    • TAB_LABEL_VISIBILITY_UNLABELED

      public static final int TAB_LABEL_VISIBILITY_UNLABELED
      If a tab is instantiated with TabLayout.Tab.setText(CharSequence), and this mode is set, the text will be saved and utilized for the content description, but no visible labels will be created.
      See Also:
    • TAB_LABEL_VISIBILITY_LABELED

      public static final int TAB_LABEL_VISIBILITY_LABELED
      This mode is set by default. If a tab is instantiated with TabLayout.Tab.setText(CharSequence), a visible label will be created.
      See Also:
    • GRAVITY_FILL

      public static final int GRAVITY_FILL
      Gravity used to fill the TabLayout as much as possible. This option only takes effect when used with MODE_FIXED on non-landscape screens less than 600dp wide.
      See Also:
    • GRAVITY_CENTER

      public static final int GRAVITY_CENTER
      Gravity used to lay out the tabs in the center of the TabLayout.
      See Also:
    • GRAVITY_START

      public static final int GRAVITY_START
      Gravity used to lay out the tabs aligned to the start of the TabLayout.
      See Also:
    • INDICATOR_GRAVITY_BOTTOM

      public static final int INDICATOR_GRAVITY_BOTTOM
      Indicator gravity used to align the tab selection indicator to the bottom of the TabLayout. This will only take effect if the indicator height is set via the custom indicator drawable's intrinsic height (preferred). Otherwise, the indicator will not be shown. This is the default value.
      See Also:
    • INDICATOR_GRAVITY_CENTER

      public static final int INDICATOR_GRAVITY_CENTER
      Indicator gravity used to align the tab selection indicator to the center of the TabLayout. This will only take effect if the indicator height is set via the custom indicator drawable's intrinsic height (preferred). Otherwise, the indicator will not be shown.
      See Also:
    • INDICATOR_GRAVITY_TOP

      public static final int INDICATOR_GRAVITY_TOP
      Indicator gravity used to align the tab selection indicator to the top of the TabLayout. This will only take effect if the indicator height is set via the custom indicator drawable's intrinsic height (preferred). Otherwise, the indicator will not be shown.
      See Also:
    • INDICATOR_GRAVITY_STRETCH

      public static final int INDICATOR_GRAVITY_STRETCH
      Indicator gravity used to stretch the tab selection indicator across the entire height of the TabLayout. This will disregard tabIndicatorHeight and the indicator drawable's intrinsic height, if set.
      See Also:
    • INDICATOR_ANIMATION_MODE_LINEAR

      public static final int INDICATOR_ANIMATION_MODE_LINEAR
      Indicator animation mode used to translate the selected tab indicator between two tabs using a linear motion.

      The left and right side of the selection indicator translate in step over the duration of the animation. The only exception to this is when the indicator needs to change size to fit the width of its new destination tab's label.

      See Also:
    • INDICATOR_ANIMATION_MODE_ELASTIC

      public static final int INDICATOR_ANIMATION_MODE_ELASTIC
      Indicator animation mode used to translate the selected tab indicator by growing and then shrinking the indicator, making the indicator look like it is stretching while translating between destinations.

      The left and right side of the selection indicator translate out of step - with the right decelerating and the left accelerating (when moving right). This difference in velocity between the sides of the indicator, over the duration of the animation, make the indicator look like it grows and then shrinks back down to fit it's new destination's width.

      See Also:
    • INDICATOR_ANIMATION_MODE_FADE

      public static final int INDICATOR_ANIMATION_MODE_FADE
      Indicator animation mode used to switch the selected tab indicator from one tab to another by sequentially fading it out from the current destination and in at its new destination.
      See Also:
  • Constructor Details

  • Method Details

    • setSelectedTabIndicatorColor

      public void setSelectedTabIndicatorColor(@ColorInt int color)
      Sets the tab indicator's color for the currently selected tab.

      If the tab indicator color is not Color.TRANSPARENT, the indicator will be wrapped and tinted right before it is drawn by View.draw(Canvas). If you'd like the inherent color or the tinted color of a custom drawable to be used, make sure this color is set to Color.TRANSPARENT to avoid your color/tint being overridden.

      Parameters:
      color - color to use for the indicator
    • setScrollPosition

      public void setScrollPosition(int position, float positionOffset, boolean updateSelectedTabView)
      Set the scroll position of the TabLayout.
      Parameters:
      position - Position of the tab to scroll.
      positionOffset - Value from [0, 1) indicating the offset from position.
      updateSelectedTabView - Whether to draw the tab at the specified position + positionOffset as selected.

      Note that calling the method with 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 ViewPager.

      See Also:
    • setScrollPosition

      public void setScrollPosition(int position, float positionOffset, boolean updateSelectedTabView, boolean updateIndicatorPosition)
      Set the scroll position of the TabLayout.
      Parameters:
      position - Position of the tab to scroll.
      positionOffset - Value from [0, 1) indicating the offset from position.
      updateSelectedTabView - Whether to draw the tab at the specified position + positionOffset as selected.

      Note that calling the method with 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 ViewPager.

      updateIndicatorPosition - Whether to set the indicator to the specified position and offset.

      Note that calling the method with 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 ViewPager.

      See Also:
    • addTab

      public void addTab(@NonNull TabLayout.Tab tab)
      Add a tab to this layout. The tab will be added at the end of the list. If this is the first tab to be added it will become the selected tab.
      Parameters:
      tab - Tab to add
    • addTab

      public void addTab(@NonNull TabLayout.Tab tab, int position)
      Add a tab to this layout. The tab will be inserted at position. If this is the first tab to be added it will become the selected tab.
      Parameters:
      tab - The tab to add
      position - The new position of the tab
    • addTab

      public void addTab(@NonNull TabLayout.Tab tab, boolean setSelected)
      Add a tab to this layout. The tab will be added at the end of the list.
      Parameters:
      tab - Tab to add
      setSelected - True if the added tab should become the selected tab.
    • addTab

      public void addTab(@NonNull TabLayout.Tab tab, int position, boolean setSelected)
      Add a tab to this layout. The tab will be inserted at position.
      Parameters:
      tab - The tab to add
      position - The new position of the tab
      setSelected - True if the added tab should become the selected tab.
    • onInterceptTouchEvent

      public boolean onInterceptTouchEvent(MotionEvent event)
      Description copied from class: ViewGroup
      Implement this method to intercept all touch screen motion events. This allows you to watch events as they are dispatched to your children, and take ownership of the current gesture at any point.

      Using this function takes some care, as it has a fairly complicated interaction with View.onTouchEvent(MotionEvent), and using it requires implementing that method as well as this one in the correct way. Events will be received in the following order:

      1. You will receive the down event here.
      2. The down event will be handled either by a child of this view group, or given to your own onTouchEvent() method to handle; this means you should implement onTouchEvent() to return true, so you will continue to see the rest of the gesture (instead of looking for a parent view to handle it). Also, by returning true from onTouchEvent(), you will not receive any following events in onInterceptTouchEvent() and all touch processing must happen in onTouchEvent() like normal.
      3. For as long as you return false from this function, each following event (up to and including the final up) will be delivered first here and then to the target's onTouchEvent().
      4. If you return true from here, you will not receive any following events: the target view will receive the same event but with the action MotionEvent.ACTION_CANCEL, and all further events will be delivered to your onTouchEvent() method and no longer appear here.
      Overrides:
      onInterceptTouchEvent in class HorizontalScrollView
      Parameters:
      event - The motion event being dispatched down the hierarchy.
      Returns:
      Return true to steal motion events from the children and have them dispatched to this ViewGroup through onTouchEvent(). The current target will receive an ACTION_CANCEL event, and no further messages will be delivered here.
    • onTouchEvent

      public boolean onTouchEvent(@NonNull MotionEvent event)
      Description copied from class: View
      Implement this method to handle touch screen motion events.

      If this method is used to detect click actions, it is recommended that the actions be performed by implementing and calling View.performClick(). This will ensure consistent system behavior.

      Overrides:
      onTouchEvent in class HorizontalScrollView
      Parameters:
      event - the touch event
      Returns:
      true if the event was handled by the view, false otherwise
    • addOnTabSelectedListener

      public void addOnTabSelectedListener(@NonNull TabLayout.OnTabSelectedListener listener)
      Add a TabLayout.OnTabSelectedListener that will be invoked when tab selection changes.

      Components that add a listener should take care to remove it when finished via removeOnTabSelectedListener(OnTabSelectedListener).

      Parameters:
      listener - listener to add
    • removeOnTabSelectedListener

      public void removeOnTabSelectedListener(@NonNull TabLayout.OnTabSelectedListener listener)
      Parameters:
      listener - listener to remove
    • clearOnTabSelectedListeners

      public void clearOnTabSelectedListeners()
      Remove all previously added TabLayout.OnTabSelectedListeners.
    • newTab

      @NonNull public TabLayout.Tab newTab()
      Create and return a new TabLayout.Tab. You need to manually add this using addTab(Tab) or a related method.
      Returns:
      A new Tab
      See Also:
    • getTabCount

      public int getTabCount()
      Returns the number of tabs currently registered with the tab layout.
      Returns:
      Tab count
    • getTabAt

      @Nullable public TabLayout.Tab getTabAt(int index)
      Returns the tab at the specified index.
    • getSelectedTabPosition

      public int getSelectedTabPosition()
      Returns the position of the current selected tab.
      Returns:
      selected tab position, or -1 if there isn't a selected tab.
    • removeTab

      public void removeTab(@NonNull TabLayout.Tab tab)
      Remove a tab from the layout. If the removed tab was selected it will be deselected and another tab will be selected if present.
      Parameters:
      tab - The tab to remove
    • removeTabAt

      public void removeTabAt(int position)
      Remove a tab from the layout. If the removed tab was selected it will be deselected and another tab will be selected if present.
      Parameters:
      position - Position of the tab to remove
    • removeAllTabs

      public void removeAllTabs()
      Remove all tabs from the tab layout and deselect the current tab.
    • setTabMode

      public void setTabMode(int mode)
      Set the behavior mode for the Tabs in this layout. The valid input options are:
      • MODE_FIXED: Fixed tabs display all tabs concurrently and are best used with content that benefits from quick pivots between tabs.
      • MODE_SCROLLABLE: Scrollable tabs display a subset of tabs at any given moment, and can contain longer tab labels and a larger number of tabs. They are best used for browsing contexts in touch interfaces when users don't need to directly compare the tab labels. This mode is commonly used with a ViewPager.
      Parameters:
      mode - one of MODE_FIXED, MODE_SCROLLABLE or MODE_AUTO.
    • getTabMode

      public int getTabMode()
      Returns the current mode used by this TabLayout.
      See Also:
    • setTabGravity

      public void setTabGravity(int gravity)
      Set the gravity to use when laying out the tabs.
      Parameters:
      gravity - one of GRAVITY_CENTER, GRAVITY_FILL or GRAVITY_START.
    • getTabGravity

      public int getTabGravity()
      The current gravity used for laying out tabs.
      See Also:
    • setSelectedTabIndicatorGravity

      public void setSelectedTabIndicatorGravity(int indicatorGravity)
      Set the indicator gravity used to align the tab selection indicator in the TabLayout. You must set the indicator height via the custom indicator drawable's intrinsic height (preferred). Otherwise, the indicator will not be shown unless gravity is set to INDICATOR_GRAVITY_STRETCH, in which case it will ignore indicator height and stretch across the entire height of the TabLayout. This defaults to INDICATOR_GRAVITY_BOTTOM if not set.
      Parameters:
      indicatorGravity - one of INDICATOR_GRAVITY_BOTTOM, INDICATOR_GRAVITY_CENTER, INDICATOR_GRAVITY_TOP, or INDICATOR_GRAVITY_STRETCH
    • getTabIndicatorGravity

      public int getTabIndicatorGravity()
      Get the current indicator gravity used to align the tab selection indicator in the TabLayout.
      Returns:
      one of INDICATOR_GRAVITY_BOTTOM, INDICATOR_GRAVITY_CENTER, INDICATOR_GRAVITY_TOP, or INDICATOR_GRAVITY_STRETCH
    • setTabIndicatorAnimationMode

      public void setTabIndicatorAnimationMode(int tabIndicatorAnimationMode)
      Set the mode by which the selection indicator should animate when moving between destinations.

      Defaults to INDICATOR_ANIMATION_MODE_LINEAR. Changing this is useful as a stylistic choice.

      Parameters:
      tabIndicatorAnimationMode - one of INDICATOR_ANIMATION_MODE_LINEAR or INDICATOR_ANIMATION_MODE_ELASTIC
      See Also:
    • getTabIndicatorAnimationMode

      public int getTabIndicatorAnimationMode()
      Get the current indicator animation mode used to animate the selection indicator between destinations.
      Returns:
      one of INDICATOR_ANIMATION_MODE_LINEAR or INDICATOR_ANIMATION_MODE_ELASTIC
      See Also:
    • setTabIndicatorFullWidth

      public void setTabIndicatorFullWidth(boolean tabIndicatorFullWidth)
      Enable or disable option to fit the tab selection indicator to the full width of the tab item rather than to the tab item's content.

      Defaults to true. If set to false and the tab item has a text label, the selection indicator width will be set to the width of the text label. If the tab item has no text label, but does have an icon, the selection indicator width will be set to the icon. If the tab item has neither of these, or if the calculated width is less than a minimum width value, the selection indicator width will be set to the minimum width value.

      Parameters:
      tabIndicatorFullWidth - Whether or not to fit selection indicator width to full width of the tab item
      See Also:
    • isTabIndicatorFullWidth

      public boolean isTabIndicatorFullWidth()
      Get whether or not selection indicator width is fit to full width of the tab item, or fit to the tab item's content.
      Returns:
      whether or not selection indicator width is fit to the full width of the tab item
      See Also:
    • setInlineLabel

      public void setInlineLabel(boolean inline)
      Set whether tab labels will be displayed inline with tab icons, or if they will be displayed underneath tab icons.
      See Also:
    • isInlineLabel

      public boolean isInlineLabel()
      Returns whether tab labels will be displayed inline with tab icons, or if they will be displayed underneath tab icons.
      See Also:
    • setUnboundedRipple

      public void setUnboundedRipple(boolean unboundedRipple)
      Set whether this TabLayout will have an unbounded ripple effect or if ripple will be bound to the tab item size.

      Defaults to false.

      See Also:
    • hasUnboundedRipple

      public boolean hasUnboundedRipple()
      Returns whether this TabLayout has an unbounded ripple effect, or if ripple is bound to the tab item size.
      See Also:
    • setTabTextColors

      public void setTabTextColors(@Nullable ColorStateList textColor)
      Sets the text colors for the different states (normal, selected) used for the tabs.
      See Also:
    • getTabTextColors

      @Nullable public ColorStateList getTabTextColors()
      Gets the text colors for the different states (normal, selected) used for the tabs.
    • setTabTextColors

      public void setTabTextColors(int normalColor, int selectedColor)
      Sets the text colors for the different states (normal, selected) used for the tabs.
    • setTabIconTint

      public void setTabIconTint(@Nullable ColorStateList iconTint)
      Sets the icon tint for the different states (normal, selected) used for the tabs.
      See Also:
    • getTabIconTint

      @Nullable public ColorStateList getTabIconTint()
      Gets the icon tint for the different states (normal, selected) used for the tabs.
    • getTabRippleColor

      @Nullable public ColorStateList getTabRippleColor()
      Returns the ripple color for this TabLayout.
      Returns:
      the color (or ColorStateList) used for the ripple
      See Also:
    • setTabRippleColor

      public void setTabRippleColor(@Nullable ColorStateList color)
      Sets the ripple color for this TabLayout.

      When running on devices with KitKat, we draw this color as a filled overlay rather than a ripple.

      Parameters:
      color - color (or ColorStateList) to use for the ripple
      See Also:
    • getTabSelectedIndicator

      @NonNull public Drawable getTabSelectedIndicator()
      Returns the selection indicator drawable for this TabLayout.
      Returns:
      The drawable used as the tab selection indicator, if set.
      See Also:
    • setSelectedTabIndicator

      public void setSelectedTabIndicator(@Nullable Drawable tabSelectedIndicator)
      Sets the selection indicator for this TabLayout. By default, this is a line along the bottom of the tab. If tabIndicatorColor is specified via the TabLayout's style or via setSelectedTabIndicatorColor(int) the selection indicator will be tinted that color. Otherwise, it will use the colors specified in the drawable.

      Setting the indicator drawable to null will cause TabLayout to use the default, ShapeDrawable line indicator.

      Parameters:
      tabSelectedIndicator - A drawable to use as the selected tab indicator.
      See Also:
    • setupWithViewPager

      public void setupWithViewPager(@Nullable ViewPager viewPager)
      The one-stop shop for setting up this TabLayout with a ViewPager.

      This is the same as calling setupWithViewPager(ViewPager, boolean) with auto-refresh enabled.

      Parameters:
      viewPager - the ViewPager to link to, or null to clear any previous link
    • setupWithViewPager

      public void setupWithViewPager(@Nullable ViewPager viewPager, boolean autoRefresh)
      The one-stop shop for setting up this TabLayout with a ViewPager.

      This method will link the given ViewPager and this TabLayout together so that changes in one are automatically reflected in the other. This includes scroll state changes and clicks. The tabs displayed in this layout will be populated from the ViewPager adapter's page titles.

      If autoRefresh is true, any changes in the PagerAdapter will trigger this layout to re-populate itself from the adapter's titles.

      If the given ViewPager is non-null, it needs to already have a PagerAdapter set.

      Parameters:
      viewPager - the ViewPager to link to, or null to clear any previous link
      autoRefresh - whether this layout should refresh its contents if the given ViewPager's content changes
    • shouldDelayChildPressedState

      public boolean shouldDelayChildPressedState()
      Description copied from class: ViewGroup
      Return true if the pressed state should be delayed for children or descendants of this ViewGroup. Generally, this should be done for containers that can scroll, such as a List. This prevents the pressed state from appearing when the user is actually trying to scroll the content.

      The default implementation returns false. Subclasses that do scroll should override this method and return true.

      Overrides:
      shouldDelayChildPressedState in class HorizontalScrollView
    • onAttachedToWindow

      protected void onAttachedToWindow()
      Description copied from class: View
      This is called when the view is attached to a window. At this point it has a Surface and will start drawing. Note that this function is guaranteed to be called before View.onDraw(Canvas), however it may be called any time before the first onDraw -- including before or after View.onMeasure(int, int).
      Overrides:
      onAttachedToWindow in class View
      See Also:
    • onDetachedFromWindow

      protected void onDetachedFromWindow()
      Description copied from class: View
      This is called when the view is detached from a window. At this point it no longer has a surface for drawing.
      Overrides:
      onDetachedFromWindow in class View
      See Also:
    • addView

      public void addView(@NonNull View child)
      Description copied from class: ViewGroup

      Adds a child view. If no layout parameters are already set on the child, the default parameters for this ViewGroup are set on the child.

      Note: do not invoke this method from View.draw(Canvas), View.onDraw(Canvas), ViewGroup.dispatchDraw(Canvas) or any related method.

      Overrides:
      addView in class HorizontalScrollView
      Parameters:
      child - the child view to add
      See Also:
    • addView

      public void addView(@NonNull View child, int index)
      Description copied from class: ViewGroup
      Adds a child view. If no layout parameters are already set on the child, the default parameters for this ViewGroup are set on the child.

      Note: do not invoke this method from View.draw(Canvas), View.onDraw(Canvas), ViewGroup.dispatchDraw(Canvas) or any related method.

      Overrides:
      addView in class HorizontalScrollView
      Parameters:
      child - the child view to add
      index - the position at which to add the child
      See Also:
    • addView

      public void addView(@NonNull View child, @NonNull ViewGroup.LayoutParams params)
      Description copied from class: ViewGroup
      Adds a child view with the specified layout parameters.

      Note: do not invoke this method from View.draw(Canvas), View.onDraw(Canvas), ViewGroup.dispatchDraw(Canvas) or any related method.

      Specified by:
      addView in interface ViewManager
      Overrides:
      addView in class HorizontalScrollView
      Parameters:
      child - the child view to add
      params - the layout parameters to set on the child
    • addView

      public void addView(@NonNull View child, int index, @NonNull ViewGroup.LayoutParams params)
      Description copied from class: ViewGroup
      Adds a child view with the specified layout parameters.

      Note: do not invoke this method from View.draw(Canvas), View.onDraw(Canvas), ViewGroup.dispatchDraw(Canvas) or any related method.

      Overrides:
      addView in class HorizontalScrollView
      Parameters:
      child - the child view to add
      index - the position at which to add the child or -1 to add last
      params - the layout parameters to set on the child
    • onDraw

      protected void onDraw(@NonNull Canvas canvas)
      Description copied from class: View
      Draw the content of this view, implement this to do your drawing.

      Note that (0, 0) will be the top left of the bounds, and (width, height) will be the bottom right of the bounds.

      Overrides:
      onDraw in class View
      Parameters:
      canvas - the canvas to draw content
    • onMeasure

      protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec)
      Description copied from class: View
      Measure the view and its content to determine the measured width and the measured height. This method is invoked by View.measure(int, int) and should be overridden by subclasses to provide accurate and efficient measurement of their contents.

      CONTRACT: When overriding this method, you must call View.setMeasuredDimension(int, int) to store the measured width and height of this view. Failure to do so will trigger an IllegalStateException, thrown by View.measure(int, int). Calling super.onMeasure() is a valid use.

      The base class implementation of measure defaults to the background size, unless a larger size is allowed by the MeasureSpec. Subclasses should override the base one to provide better measurements of their content.

      Overrides:
      onMeasure in class HorizontalScrollView
      Parameters:
      widthMeasureSpec - width measure specification imposed by the parent MeasureSpec
      heightMeasureSpec - height measure specification imposed by the parent MeasureSpec
    • selectTab

      public void selectTab(@Nullable TabLayout.Tab tab)
      Selects the given tab.
      Parameters:
      tab - The tab to select, or null to select none.
      See Also:
    • selectTab

      public void selectTab(@Nullable TabLayout.Tab tab, boolean updateIndicator)
      Selects the given tab. Will always animate to the selected tab if the current tab is reselected, regardless of the value of updateIndicator.
      Parameters:
      tab - The tab to select, or null to select none.
      updateIndicator - Whether to update the indicator.
      See Also: